feat: extract parameter descriptions from docstrings into tool JSON schemas#2295
feat: extract parameter descriptions from docstrings into tool JSON schemas#2295ameenalkhaldi wants to merge 3 commits intomodelcontextprotocol:mainfrom
Conversation
…chemas Parse Google, NumPy, and Sphinx-style docstrings using the griffe library to automatically include parameter descriptions in generated tool JSON schemas. This means users no longer need to use Field(description=...) annotations for their tool parameters — standard Python docstrings work out of the box. Explicit Field descriptions always take priority over docstring descriptions. Github-Issue:modelcontextprotocol#226 Reported-by:salman1993
GoogleOptions was added in a later griffe version and is not available in griffe 1.5.0 (the minimum version). The default parser options work correctly without it. Github-Issue:modelcontextprotocol#226
| logging.root.setLevel(logging.ERROR) | ||
| yield | ||
| logging.root.setLevel(old_level) | ||
|
|
There was a problem hiding this comment.
This sets the root logger level, which will suppress all logging globally (not just griffe's) for the duration of the context manager. It's also not thread-safe — concurrent code that logs during this window will silently lose messages.
Should target the griffe logger specifically:
@contextmanager
def _suppress_griffe_logging() -> Iterator[None]:
logger = logging.getLogger("_griffe")
old_level = logger.getEffectiveLevel()
logger.setLevel(logging.ERROR)
yield
logger.setLevel(old_level)(_griffe is the internal logger name griffe uses — you can verify with griffe.logger)
pyproject.toml
Outdated
| ] | ||
| dependencies = [ | ||
| "anyio>=4.9", | ||
| "griffe>=1.5.0", |
There was a problem hiding this comment.
griffe pulls in transitive deps (colorama, etc.) and is a non-trivial addition to the dependency tree for what's ultimately a convenience feature (docstring → description). Most users who care about tool descriptions are already using Field(description=...) or Annotated.
Worth considering:
- Making this an optional/extra dependency (e.g.,
mcp[docstrings]), with a graceful fallback when not installed - Or using a simpler regex-based approach for the most common docstring formats (Google-style
Args:covers the vast majority of cases)
Replace the griffe library with simple regex patterns for parsing Google, NumPy, and Sphinx-style docstrings. This eliminates the new runtime dependency while maintaining full functionality. All 42 tests continue to pass. Github-Issue:modelcontextprotocol#226
|
Good point — replaced griffe with a simple regex-based parser in 735bc50. Zero new dependencies now. The regex approach covers Google ( |
Summary
Closes #226.
Tool functions with standard Python docstrings now automatically get parameter descriptions included in their generated JSON schemas. Previously, parameter descriptions were only available through explicit
Field(description=...)annotations — now Google, NumPy, and Sphinx-style docstrings are parsed and parameter descriptions are extracted into the schema.Before:
{"city": {"type": "string", "title": "City"}}After:
{"city": {"type": "string", "title": "City", "description": "The city to get weather for"}}Implementation
Field(description=...)annotations always take priority over docstring descriptionsChanges
pyproject.toml: Addedgriffe>=1.5.0as a runtime dependencyfunc_metadata.py: Added docstring parsing helpers and integrated them into the parameter schema generation looptest_func_metadata.py: 9 new tests covering Google/NumPy/Sphinx styles, priority logic, edge casesTest plan