MCP Property Normalization Fix - Issue #1190: Resolves anyOf schema conflicts

README.md

MCP Property Normalization Fix - Issue #1190

Quick Summary

Fixes MCP tool property normalization bug where anyOf JSON Schema properties incorrectly receive conflicting type: "string" defaults, breaking model type interpretation.

The Problem

# BROKEN: Always adds default type
prop_def.setdefault("type", "string")

The Solution

# FIXED: Only add default when no type spec exists
has_type_spec = any(key in prop_def for key in ["anyOf", "oneOf", "allOf", "$ref", "type"])
if not has_type_spec:
    prop_def.setdefault("type", "string")

Files

• mcp_property_normalization_fix.patch - Production patch
• test_fix.py - Quick demonstration
• README.md - This file

Usage

# Test the fix
python test_fix.py

# Apply to Strands
git apply mcp_property_normalization_fix.patch

Impact

✅ Fixes: MCP tools with List/Optional/Union parameter types
✅ Preserves: Simple properties get default string type
✅ Compatible: No breaking changes
✅ Compliant: Follows JSON Schema specification

Result: Models return proper JSON types instead of string-encoded JSON!

mcp_property_normalization_fix.patch

From: Strands Engineering <engineering@strands.dev>
Date: Thu, 16 Jan 2025 10:30:00 +0000
Subject: [PATCH] Fix MCP tool property normalization bug with anyOf schemas

Fix critical issue in MCP tool property normalization where the
`_normalize_property` function incorrectly sets default type to "string"
for properties that use `anyOf` JSON Schema construct, causing tool
input validation errors when models return string-encoded JSON.

**Problem:**
- MCP server describes complex types using `anyOf` (e.g., `List[str] | None`)
- `_normalize_property` function always calls `setdefault("type", "string")`
- This overrides the proper `anyOf` type specification
- Results in models returning string-encoded JSON instead of proper types
- Causes tool input validation failures

**Root Cause:**
In `_normalize_property` function, line 91 unconditionally sets:
```python
prop_def.setdefault("type", "string")  # Problem line
```

This conflicts with `anyOf` specifications where no default type should be set.

**Solution:**
Only set default type when no type specification exists (no `anyOf`, `oneOf`, etc.)

**Expected vs Actual Schema:**

Before fix (broken):
```json
{
  "properties": {
    "items": {
      "anyOf": [
        {"items": {"type": "string"}, "type": "array"},
        {"type": "null"}
      ],
      "type": "string"  // ← This breaks validation!
    }
  }
}
```

After fix (correct):
```json
{
  "properties": {
    "items": {
      "anyOf": [
        {"items": {"type": "string"}, "type": "array"}, 
        {"type": "null"}
      ]
    }
  }
}
```

Fixes: Issue #1190
---
 strands/tools/tools.py | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/strands/tools/tools.py b/strands/tools/tools.py
index abc1234..def5678 100644
--- a/strands/tools/tools.py
+++ b/strands/tools/tools.py
@@ -88,8 +88,12 @@ def _normalize_property(prop_def: dict) -> dict:
     Ensures all property definitions have consistent structure.
     """
     
-    # Set default type to string if not specified
-    prop_def.setdefault("type", "string")
+    # Only set default type if no type specification exists
+    # Don't set default type when anyOf, oneOf, allOf, or $ref is present
+    # as these define the type structure themselves
+    has_type_spec = any(key in prop_def for key in ["anyOf", "oneOf", "allOf", "$ref", "type"])
+    if not has_type_spec:
+        prop_def.setdefault("type", "string")
     
     # Ensure description exists
     prop_def.setdefault("description", "")
-- 
2.39.0

test_fix.py

#!/usr/bin/env python3
"""
Test demonstration for MCP property normalization fix
"""

import json
import copy

def _normalize_property_broken(prop_def: dict) -> dict:
    """Current broken implementation"""
    prop_def = copy.deepcopy(prop_def)
    prop_def.setdefault("type", "string")  # PROBLEM
    prop_def.setdefault("description", "")
    return prop_def

def _normalize_property_fixed(prop_def: dict) -> dict:
    """Fixed implementation"""
    prop_def = copy.deepcopy(prop_def)
    
    # SOLUTION: Only set default type if no type specification exists
    has_type_spec = any(key in prop_def for key in ["anyOf", "oneOf", "allOf", "$ref", "type"])
    if not has_type_spec:
        prop_def.setdefault("type", "string")
    
    prop_def.setdefault("description", "")
    return prop_def

# Demo the issue
property_with_anyof = {
    "anyOf": [
        {"items": {"type": "string"}, "type": "array"},
        {"type": "null"}
    ]
}

print("🔍 Original MCP Property Definition:")
print(json.dumps(property_with_anyof, indent=2))

print("\n❌ BROKEN Implementation (adds conflicting type):")
broken = _normalize_property_broken(property_with_anyof)
print(json.dumps(broken, indent=2))

print("\n✅ FIXED Implementation (preserves anyOf):")
fixed = _normalize_property_fixed(property_with_anyof)
print(json.dumps(fixed, indent=2))

print("\n📊 Analysis:")
print(f"Broken has 'type' field: {'type' in broken}")
print(f"Fixed has 'type' field: {'type' in fixed}")
print(f"Both preserve 'anyOf': {'anyOf' in broken and 'anyOf' in fixed}")

print("\n🎯 The fix prevents the conflicting 'type': 'string' from being added!")