Give bare `dict`, `set` and `frozenset` return annotations structured output

Merged
KL
1mo ago
+123-9

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.

AnnotationBeforeAfter
-> dictno schema{"type": "object", "additionalProperties": true}, unwrapped
-> set, -> frozensetno schemawrapped, {"type": "array", "uniqueItems": true, "items": {}}
-> list, -> tupleno schemano 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 / tuple added to test_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_any and test_a_bare_set_is_wrapped snapshot both output_schema and the full CallToolResult.
  • 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-dict tool returning non-str keys, e.g. {1: "a"};
  • a None return from a -> dict / -> set tool;
  • 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.