Give bare `dict`, `set` and `frozenset` return annotations structured output
Fixes #3725
A bare -> dict now gets the same structured output as -> dict[str, Any], and a bare -> set / -> frozenset is wrapped in {"result": ...} like their parameterized forms. A bare -> list / -> tuple deliberately stays unstructured, and structured_output=True now wraps it instead of raising.
Motivation and Context
Bare builtins fell through to the "other class" branch of _create_output_model, where get_type_hints(dict) is {}, so the tool silently got no outputSchema and no structuredContent. With structured_output=True it raised return type <class 'dict'> is not serializable, which reads as if a dict weren't serializable.
| Annotation | Before | After |
|---|---|---|
-> dict | no schema | {"type": "object", "additionalProperties": true}, unwrapped |
-> set, -> frozenset | no schema | wrapped, {"type": "array", "uniqueItems": true, "items": {}} |
-> list, -> tuple | no schema | no schema (on purpose); wrapped with structured_output=True |
Why bare list / tuple stay unstructured
_convert_to_content renders content blocks found in a list or tuple as blocks, and _returns_content already opts list[ImageContent] and friends out of structured output so the image isn't also echoed into structuredContent. A bare list says nothing about its items, so it may hold blocks too: a -> list tool returning [Image(...), {...}] would send the image twice, once as a block and once as base64 in structuredContent. Some clients then render the JSON instead of the picture, others put the base64 in the model's context. set / frozenset can't hold content blocks (they aren't hashable), so wrapping them is safe.
FastMCP made the same call (function_parsing.py: bare list/tuple produce no output schema for this reason, while bare dict and set get one). list[X] and structured_output=True remain the explicit opt-ins.
How Has This Been Tested?
- Bare
list/tupleadded totest_content_block_return_annotation_yields_no_output_schema. test_structured_output_true_wraps_a_bare_list,test_a_bare_list_inside_a_union_keeps_its_schema,test_a_bare_dict_is_structured_like_dict_str_anyandtest_a_bare_set_is_wrappedsnapshot bothoutput_schemaand the fullCallToolResult.- Full suite passes; coverage 100%,
strict-no-cover, ruff and pyright clean.
Breaking Changes
Tools annotated with a bare dict, set or frozenset start publishing an outputSchema and validating their result against it, exactly as dict[str, Any] / set[Any] do today. Values that used to be dumped as text with to_json(..., fallback=str) and now fail as a tool error (is_error=True):
- a bare-
dicttool returning non-strkeys, e.g.{1: "a"}; - a
Nonereturn from a-> dict/-> settool; - a value pydantic can't serialize to JSON, e.g. an instance of an arbitrary class inside the dict or set.
Bare list / tuple tools are unchanged unless they pass structured_output=True, which used to raise. Only a bare list / tuple as the whole annotation is opted out; nested ones (list | None, dict | list, list[list]) keep the wrapped schema they publish today.
Types of changes
- Bug fix (non-breaking change which fixes an issue)
- New feature (non-breaking change which adds functionality)
- Breaking change (fix or feature that would cause existing functionality to change)
- Documentation update
Checklist
- I am assigned to the linked issue (or it is labeled
help wanted, or I'm a maintainer) - I have disclosed any AI assistance and can explain the change in my own words
- I have read the MCP Documentation
- My code follows the repository's style guidelines
- New and existing tests pass locally
- I have added appropriate error handling
- I have added or updated documentation as needed
Additional context
This differs from the branch proposed in #3725, which also wraps bare list / tuple; the reason is the double-send above. Unparameterized typing.List / typing.Tuple are unchanged (still wrapped like list[Any]).
AI Disclaimer
This PR was developed with the assistance of either Claude or Codex. I've reviewed and verified the changes.