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.