modelcontextprotocol / modelcontextprotocol/python-sdk

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

Open Beginner friendly
#2,935 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

bug P3 v2
Dominant language
Python
Stars
24.3k
Forks
4k
Avg merge
1d 1h
Merged PRs (30d)
31

Description

Initial Checks
Description

Tools that return a string-keyed dict (dict[str, T]) lose any Annotated/Field metadata on the return type when the output schema is generated. A Field(description=...) on the return annotation shows up in the output schema for every other return type, but for dict[str, T] it's dropped.

I'd expect the description to be preserved, the same as other return types. Looks like the dict[str, T] branch in _try_create_model_and_schema builds the model from the Annotated-stripped type instead of the original annotation (there's an existing TODO on that line).

Have a simple, tested fix ready to go. Love the project and would love to contribute if possible!

Example Code
from typing import Annotated
from pydantic import Field
from mcp.server.mcpserver.utilities.func_metadata import func_metadata

def get_config() -> Annotated[dict[str, int], Field(description="Configuration values")]:
    return {"timeout": 30}

print(func_metadata(get_config).output_schema)
# {'type': 'object', 'additionalProperties': {'type': 'integer'}, 'title': 'get_configDictOutput'}
# expected to also include: 'description': 'Configuration values'
Python & MCP Python SDK
Python 3.14.5
mcp: main branch (mcpserver / V2)

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start in mcp.server.mcpserver.utilities.func_metadata at _try_create_model_and_schema, focusing on the dict[str, T] branch and its existing TODO. Review the provided get_config example and the surrounding schema-generation tests, then verify that an Annotated Field description appears in the output schema for string-keyed dictionary returns.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
api
Issue type
Bug
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Quiet
Clarity
Clearly specified
Newbie friendliness
78/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.