MCP tool argument type coercion and schema resolution

Fixes on record

Merged to main. A stamp counts the issues a fix is linked to.

• #14811 fix(mcp): coerce stringified arrays/objects in tool args (salvage #12640)

  merged to main

  files: model_tools.py, scripts/release.py, tests/run_agent/test_tool_arg_coercion.py

  Show the diff

  • model_tools.py

    @@ -418,6 +418,31 @@ def _coerce_value(value: str, expected_type):
             return _coerce_number(value, integer_only=(expected_type == "integer"))
         if expected_type == "boolean":
             return _coerce_boolean(value)
    +    if expected_type == "array":
    +        return _coerce_json(value, list)
    +    if expected_type == "object":
    +        return _coerce_json(value, dict)
    +    return value
    +
    +
    +def _coerce_json(value: str, expected_python_type: type):
    +    """Parse *value* as JSON when the schema expects an array or object.
    +
    +    Handles model output drift where a complex oneOf/discriminated-union schema
    +    causes the LLM to emit the array/object as a JSON string instead of a native
    +    structure.  Returns the original string if parsing fails or yields the wrong
    +    Python type.
    +    """
    +    try:
    +        parsed = json.loads(value)
    +    except (ValueError, TypeError):
    +        return value
    +    if isinstance(parsed, expected_python_type):
    +        logger.debug(
    +            "coerce_tool_args: coerced string to %s via json.loads",
    +            expected_python_type.__name__,
    +        )
    +        return parsed
         return value
     
     

  • scripts/release.py

    @@ -167,6 +167,7 @@
         "[redacted:email]": "socrates1024",
         "[redacted:email]": "Salt-555",
         "[redacted:email]": "satelerd",
    +    "[redacted:email]": "danklynn",
         "[redacted:email]": "nummanali",
         "[redacted:email]": "whitehatjr1001",
         "[redacted:email]": "0xNyk",

  • tests/run_agent/test_tool_arg_coercion.py

    @@ -134,6 +134,31 @@ def test_union_with_string_preserves_original(self):
             """A non-numeric string in [number, string] should stay a string."""
             assert _coerce_value("hello", ["number", "string"]) == "hello"
     
    +    def test_array_type_parsed_from_json_string(self):
    +        """Stringified JSON arrays are parsed into native lists."""
    +        assert _coerce_value('["a", "b"]', "array") == ["a", "b"]
    +        assert _coerce_value("[1, 2, 3]", "array") == [1, 2, 3]
    +
    +    def test_object_type_parsed_from_json_string(self):
    +        """Stringified JSON objects are parsed into native dicts."""
    +        assert _coerce_value('{"k": "v"}', "object") == {"k": "v"}
    +        assert _coerce_value('{"n": 1}', "object") == {"n": 1}
    +
    +    def test_array_invalid_json_preserved(self):
    +        """Unparseable strings are returned unchanged."""
    +        assert _coerce_value("not-json", "array") == "not-json"
    +
    +    def test_object_invalid_json_preserved(self):
    +        assert _coerce_value("not-json", "object") == "not-json"
    +
    +    def test_array_type_wrong_shape_preserved(self):
    +        """A JSON object passed for an 'array' slot is preserved as a string."""
    +        assert _coerce_value('{"k": "v"}', "array") == '{"k": "v"}'
    +
    +    def test_object_type_wrong_shape_preserved(self):
    +        """A JSON array passed for an 'object' slot is preserved as a string."""
    +        assert _coerce_value('["a"]', "object") == '["a"]'
    +
     
     # ── Full coerce_tool_args with registry ───────────────────────────────────
     
    @@ -212,6 +237,32 @@ def test_preserves_non_string_values(self):
                 assert result["items"] == [1, 2, 3]
                 assert result["config"] == {"key": "val"}
     
    +    def test_coerces_stringified_array_arg(self):
    +        """Regression for #3947 — MCP servers using z.array() expect lists, not strings."""
    +        schema = self._mock_schema({
    +            "messageIds": {"type": "array", "items": {"type": "string"}},
    +        })
    +        with patch("model_tools.registry.get_schema", return_value=schema):
    +            args = {"messageIds": '["abc", "def"]'}
    +            result = coerce_tool_args("test_tool", args)
    +            assert result["messageIds"] == ["abc", "def"]
    +
    +    def test_coerces_stringified_object_arg(self):
    +        """Stringified JSON objects get parsed into dicts."""
    +        schema = self._mock_schema({"config": {"type": "object"}})
    +        with patch("model_tools.registry.get_schema", return_value=schema):
    +            args = {"config": '{"max": 50}'}
    +            result = coerce_tool_args("test_tool", args)
    +            assert result["config"] == {"max": 50}
    +
    +    def test_invalid_json_array_preserved_as_string(self):
    +        """If the string isn't valid JSON, pass it through — let the tool decide."""
    +        schema = self._mock_schema({"items": {"type": "array"}})
    +        with patch("model_tools.registry.get_schema", return_value=schema):
    +            args = {"items": "not-json"}
    +            result = coerce_tool_args("test_tool", args)
    +            assert result["items"] == "not-json"
    +
         def test_extra_args_without_schema_left_alone(self):
             """Args not in the schema properties are not touched."""
             schema = self._mock_schema({"limit": {"type": "integer"}})