Why does FastMCP tool JSON schema omit parameter descriptions from docstrings?
Using FastMCP from the modelcontextprotocol/python-sdk (issue opened 2025-02-21), func_metadata(...).arg_model.model_json_schema() returns properties with only title and type, even when the function has a Google-style docstring with per-argument descriptions. Why are docstring descriptions not included in the generated tool JSON schema, and what can I do until FastMCP supports it?
Originally asked on GitHub: https://github.com/modelcontextprotocol/python-sdk/issues/226
5 answers
Status: still open in the thread as of the last update (2026-06-15). FastMCP builds tool parameter schemas from pydantic metadata and does not currently parse the Args section of Google/NumPy/Sphinx docstrings into per-parameter descriptions. A maintainer said the library should infer the docstring format automatically, pointed to pydantic AI's implementation as a starting point, and welcomed a PR. The issue now consolidates #1134 (use inspect.getdoc(fn) instead of fn.doc so inherited docstrings are found and indentation is cleaned) and #486 (generate the input schema from the Args part of the docstring). Two proposed PRs (#1979, #2295) would add griffe-based parsing with auto-detection of Google, NumPy, and Sphinx formats; both also keep explicit Field(description=...) annotations as the higher-priority source, but neither PR is reported as merged. Until this lands, one commenter's practical workaround is to write explicit JSON Schema for each tool's input instead of relying on docstring parsing: it is more verbose, but it produces exactly the schema you want and gives the model accurate descriptions per parameter.
Did this work for you?What a GitHub user tried on GitHub (Didn't work)
In the issue body, the reporter reproduced the behavior with a Google-style docstring on def add_numbers(a: float, b: float) -> float: func_metadata(add_numbers).arg_model.model_json_schema() produced properties containing only title and type for a and b, with no descriptions.
Source: https://github.com/modelcontextprotocol/python-sdk/issues/226 (opens external site)
Did this work for you?What @heath-hunnicutt-ruach-tov tried on GitHub (Outcome unclear)
PR #1979 proposed implementing the maintainer's guidance: use griffe to auto-detect Google, NumPy, and Sphinx docstring formats (adapted from pydantic-ai) and populate parameter descriptions, with Field(description=...) taking precedence.
Did this work for you?What @ameenalkhaldi tried on GitHub (Outcome unclear)
PR #2295 similarly proposed parsing Google, NumPy, and Sphinx docstrings with griffe to extract parameter descriptions into tool JSON schemas, with explicit Field(description=...) annotations always taking priority.
Did this work for you?What @m13v tried on GitHub (Worked)
Commenter reported that in their MCP servers they wrote explicit JSON Schema for each tool's input instead of relying on docstring parsing; they found it more verbose but able to produce the exact schema and better parameter descriptions for the model.
Did this work for you?
Related questions
- MCP python-sdk simple-chatbot: 'Attempted to exit cancel scope in a different task than it was entered in'
- Why is my MCP resource template (greeting://{name}) not available in Claude Desktop?
- How to disable TLS certificate verification (verify=False) in MCP streamablehttp_client?
- anyio.ClosedResourceError in MCP StreamableHTTP message router on fast-failing requests?
- Python MCP SDK streamable HTTP: 'Error in message router' ClosedResourceError after 307 redirect