dict[str, T] tool return types lose Annotated/Field metadata in output schema #2935

Activity

1. zlucas03 commented on Jun 22, 2026

   

   zlucas03

   on Jun 22, 2026

   Author

   More actions

   Thanks for jumping on this, @anneheartrecord — this is the same approach I'd landed on (routing original_annotation through to _create_dict_model instead of the stripped type_expr), so +1 on the direction. One thing I confirmed while testing locally: un-annotated dict[str, str] and dict[str, Any] output schemas come out byte-for-byte identical, so it's safe as a non-breaking change.
2. anneheartrecord commented on Jun 23, 2026

   

   anneheartrecord

   on Jun 23, 2026

   More actions

   Thanks @zlucas03, good to have that confirmed independently. The byte-for-byte match on un-annotated dict[str, str] and dict[str, Any] is exactly why I threaded original_annotation through instead of touching the stripped type_expr — existing schemas stay identical, only the annotated case changes. Fix is up in #2939.
3. maxisbey

   added

   bugSomething isn't workingSomething isn't working

   P3Nice to haves, rare edge casesNice to haves, rare edge cases

   v2Affects the v2 line (2.x on main)Affects the v2 line (2.x on main)

   on Aug 14, 2026
4. anneheartrecord commented on Oct 8, 2026

   

   anneheartrecord

   on Oct 8, 2026

   More actions

   Since #2939 was closed in the backlog sweep, I re-checked this on v2.3.0: still reproduces. The dict[str, T] branch of _create_output_model builds the schema from the stripped type_expr, and the TODO right above it already notes the lost Annotated metadata:

   python-sdk/src/mcp/server/mcpserver/utilities/func_metadata.py

   Lines 509 to 511 in 91941ed

   	# TODO: should we use the original annotation? We are losing any potential `Annotated`
   	# metadata for Pydantic here:
   	model = Annotated[type_expr, Field(title=f"{func_name}DictOutput")]

   from typing import Annotated
   from pydantic import Field
   from mcp.server.mcpserver import MCPServer
   
   server = MCPServer("repro")
   
   @server.tool()
   def counts() -> Annotated[dict[str, int], Field(description="counts per key")]:
       return {"a": 1}
   
   print(server._tool_manager.get_tool("counts").output_schema)
   # {'additionalProperties': {'type': 'integer'}, 'title': 'countsDictOutput', 'type': 'object'}
   # -> no "description"

   Use case is the one from the original report: the description a tool author puts on a dict return never reaches outputSchema, so clients get the shape but not what it means.

   The fix is still the one-liner from #2939, Annotated[original_annotation, Field(title=...)] in that branch. I ran it against the 2.3.0 install: un-annotated dict[str, int] output stays byte-identical, the annotated case gains "description": "counts per key". Happy to rebase #2939 onto v2 if you'd rather reopen it than redo it.
5. inanna-malick commented on Oct 14, 2026

   

   inanna-malick

   on Oct 14, 2026

   More actions

   Additional evidence for the metadata-loss path identified in this report: it also drops validation constraints, beyond the description loss already demonstrated.

   For Annotated[dict[str, int], Field(min_length=1)], the generated schema omits minProperties and SDK output conversion accepts an empty dictionary. Pydantic's TypeAdapter for that exact annotation rejects {}. The corresponding annotated list retains minItems: 1 and SDK conversion rejects [], so the observed difference is specific to the direct dictionary path.

   from typing import Annotated
   import pytest
   from pydantic import Field, TypeAdapter, ValidationError
   from mcp.server.mcpserver.utilities.func_metadata import func_metadata
   
   def produce() -> Annotated[dict[str, int], Field(min_length=1)]:
       return {}
   
   with pytest.raises(ValidationError):
       TypeAdapter(Annotated[dict[str, int], Field(min_length=1)]).validate_python({})
   
   with pytest.raises(ValidationError):  # Fails: DID NOT RAISE
       func_metadata(produce).convert_result(produce())

   The deterministic failing test is on this test-only branch, with no production changes. Its first assertion checks the Pydantic control; the second fails because the SDK accepts the invalid output. Existing generic output tests pass in both environments.

   uv run --frozen pytest tests/server/mcpserver/test_func_metadata.py::test_direct_dict_output_rejects_results_below_annotated_minimum_length -q

   Python 3.14.7; Pydantic 2.12.5; MCP 2.3.0 (tag v2.3.0, 2118f14f8a19bc158d8a1cf90af58d85d187f849). Also reproduced using main source at 754254c08fe1c3eda18b69da3d336106fe8d72d6.

   AI-assisted investigation and test reproduction, with a human in the loop.