Extract parameter descriptions from docstrings (#3872)

Author: jlowin

docs/servers/prompts.mdx

@@ -54,7 +54,7 @@ def generate_code_request(language: str, task_description: str) -> list[Message]
 *   **Parameters:** The function parameters define the inputs needed to generate the prompt.
 *   **Inferred Metadata:** By default:
     *   Prompt Name: Taken from the function name (`ask_about_topic`).
-    *   Prompt Description: Taken from the function's docstring.
+    *   Prompt Description: Taken from the summary of the function's docstring. If the docstring includes parameter descriptions (Google, NumPy, or Sphinx style), they populate each prompt argument's description in the MCP protocol (see [Argument Descriptions](#argument-descriptions)).
 <Tip>
 Functions with `*args` or `**kwargs` are not supported as prompts. This restriction exists because FastMCP needs to generate a complete parameter schema for the MCP protocol, which isn't possible with variable argument lists.
 </Tip>
@@ -88,7 +88,7 @@ def data_analysis_prompt(
 </ParamField>
 
 <ParamField body="description" type="str | None">
-  Provides the description exposed via MCP. If set, the function's docstring is ignored for this purpose
+  Provides the description exposed via MCP. If set, the function's docstring is ignored for the prompt description, though docstring-derived argument descriptions still apply (see [Argument Descriptions](#argument-descriptions)).
 </ParamField>
 
 <ParamField body="tags" type="set[str] | None">
@@ -201,6 +201,28 @@ Good choices: `list[int]`, `dict[str, str]`, `float`, `bool`
 Avoid: Complex Pydantic models, deeply nested structures, custom classes
 </Warning>
 
+### Argument Descriptions
+
+<VersionBadge version="3.2.4" />
+
+FastMCP parses your function's docstring to extract the prompt description and per-argument descriptions. Google, NumPy, and Sphinx styles are all supported:
+
+```python
+@mcp.prompt
+def analyze_data(dataset: str, method: str = "summary") -> str:
+    """Generate an analysis prompt for a dataset.
+
+    Args:
+        dataset: URI or identifier of the dataset to analyze.
+        method: Type of analysis to perform (summary, detailed, etc).
+    """
+    return f"Please perform a '{method}' analysis on {dataset}."
+```
+
+The free-form text above the `Args` section — whether a single line or multiple paragraphs — becomes the prompt description, and each argument's docstring entry becomes the description on the corresponding `PromptArgument` in the MCP protocol. Sections like `Returns`, `Raises`, and `Example` are excluded from the description but otherwise ignored.
+
+If an argument already has an explicit description — via `Annotated[x, "..."]` or `Field(description=...)` — that description takes precedence over the docstring. This makes it safe to adopt docstring-based descriptions incrementally: existing annotations keep working, and docstrings fill in the gaps.
+
 ### Return Values
 
 Prompt functions must return one of these types:

docs/servers/tools.mdx

@@ -36,7 +36,7 @@ def add(a: int, b: int) -> int:
 
 When this tool is registered, FastMCP automatically:
 - Uses the function name (`add`) as the tool name.
-- Uses the function's docstring (`Adds two integer numbers...`) as the tool description.
+- Parses the function's docstring for the tool description and, if present, per-parameter descriptions (see [Docstring Descriptions](#docstring-descriptions)).
 - Generates an input schema based on the function's parameters and type annotations.
 - Handles parameter validation and error reporting.
 
@@ -70,7 +70,7 @@ def search_products_implementation(query: str, category: str | None = None) -> l
 </ParamField>
 
 <ParamField body="description" type="str | None">
-  Provides the description exposed via MCP. If set, the function's docstring is ignored for this purpose
+  Provides the description exposed via MCP. If set, the function's docstring is ignored for the tool description, though docstring-derived parameter descriptions still apply (see [Docstring Descriptions](#docstring-descriptions)).
 </ParamField>
 
 <ParamField body="tags" type="set[str] | None">
@@ -289,6 +289,33 @@ The default flexible validation mode is recommended for most use cases as it han
 
 You can provide additional metadata about parameters in several ways:
 
+#### Docstring Descriptions
+
+<VersionBadge version="3.2.4" />
+
+FastMCP parses your function's docstring to extract both the tool description and per-parameter descriptions. Google, NumPy, and Sphinx docstring styles are all supported — the parser tries each and uses whichever finds parameter descriptions:
+
+```python
+@mcp.tool
+def process_image(
+    image_url: str,
+    resize: bool = False,
+    width: int = 800,
+) -> dict:
+    """Process an image with optional resizing.
+
+    Args:
+        image_url: URL of the image to process.
+        resize: Whether to resize the image.
+        width: Target width in pixels.
+    """
+    # Implementation...
+```
+
+The free-form text above the `Args` section — whether a single line or multiple paragraphs — becomes the tool description, and each parameter's docstring entry becomes the description for that parameter in the generated schema. Sections like `Returns`, `Raises`, and `Example` are excluded from the description but otherwise ignored.
+
+If a parameter already has an explicit description — via `Annotated[x, "..."]` or `Field(description=...)` — that description takes precedence over the docstring. This makes it safe to adopt docstring-based descriptions incrementally: existing annotations keep working, and docstrings fill in the gaps.
+
 #### Simple String Descriptions
 
 <VersionBadge version="2.11.0" />

pyproject.toml

@@ -25,6 +25,7 @@ dependencies = [
     "jsonref>=1.1.0",
     "uncalled-for>=0.2.0",
     "watchfiles>=1.0.0",
+    "griffelib>=2.0.0",
 ]
 
 requires-python = ">=3.10"

src/fastmcp/prompts/function_prompt.py

@@ -36,6 +36,7 @@
     call_sync_fn_in_threadpool,
     is_coroutine_function,
 )
+from fastmcp.utilities.docstring_parsing import ParsedDocstring, parse_docstring
 from fastmcp.utilities.json_schema import compress_schema
 from fastmcp.utilities.logging import get_logger
 from fastmcp.utilities.types import get_cached_typeadapter
@@ -152,11 +153,9 @@ def from_function(
             if param.kind == inspect.Parameter.VAR_KEYWORD:
                 raise ValueError("Functions with **kwargs are not supported as prompts")
 
-        description = (
-            metadata.description
-            if metadata.description is not None
-            else inspect.getdoc(fn)
-        )
+        # Parse the outer docstring (before unwrapping) to preserve the class
+        # docstring as the prompt description for callable class instances.
+        outer_docstring = parse_docstring(fn)
 
         # Normalize task to TaskConfig and validate
         task_value = metadata.task
@@ -175,6 +174,24 @@ def from_function(
         if isinstance(fn, staticmethod):
             fn = fn.__func__
 
+        # For callable classes, argument descriptions must come from
+        # __call__'s docstring — where the exposed parameters are actually
+        # declared. The class docstring's Args section, if any, typically
+        # describes __init__, so falling back to it would risk injecting
+        # constructor docs into __call__'s arguments on overlapping names.
+        # The description, however, comes from the class docstring (which
+        # describes what the prompt IS) when present.
+        inner_docstring = parse_docstring(fn)
+        parsed_docstring = ParsedDocstring(
+            description=outer_docstring.description or inner_docstring.description,
+            parameters=inner_docstring.parameters,
+        )
+        description = (
+            metadata.description
+            if metadata.description is not None
+            else parsed_docstring.description
+        )
+
         # Transform Context type annotations to Depends() for unified DI
         fn = transform_context_annotations(fn)
 
@@ -184,6 +201,18 @@ def from_function(
         parameters = type_adapter.json_schema()
         parameters = compress_schema(parameters, prune_titles=True)
 
+        # Inject parameter descriptions from the docstring into the schema.
+        # Explicit annotations (Field(description=...), Annotated[x, "..."])
+        # already have a "description" key and take precedence.
+        if parsed_docstring.parameters:
+            properties = parameters.get("properties", {})
+            for param_name, param_desc in parsed_docstring.parameters.items():
+                if (
+                    param_name in properties
+                    and "description" not in properties[param_name]
+                ):
+                    properties[param_name]["description"] = param_desc
+
         # Convert parameters to PromptArguments
         arguments: list[PromptArgument] = []
         if "properties" in parameters:

src/fastmcp/tools/function_parsing.py

@@ -18,6 +18,7 @@
     without_injected_parameters,
 )
 from fastmcp.tools.base import ToolResult
+from fastmcp.utilities.docstring_parsing import ParsedDocstring, parse_docstring
 from fastmcp.utilities.json_schema import compress_schema
 from fastmcp.utilities.logging import get_logger
 from fastmcp.utilities.types import (
@@ -164,9 +165,9 @@ def from_function(
                             f"Parameter '{arg_name}' in exclude_args must have a default value."
                         )
 
-        # collect name and doc before we potentially modify the function
+        # collect name and description before we potentially modify the function
         fn_name = getattr(fn, "__name__", None) or fn.__class__.__name__
-        fn_doc = inspect.getdoc(fn)
+        outer_docstring = parse_docstring(fn)
 
         # if the fn is a callable class, we need to get the __call__ method from here out
         if not inspect.isroutine(fn) and not isinstance(fn, functools.partial):
@@ -175,6 +176,19 @@ def from_function(
         if isinstance(fn, staticmethod):
             fn = fn.__func__
 
+        # For callable classes, parameter descriptions must come from
+        # __call__'s docstring — where the exposed parameters are actually
+        # declared. The class docstring's Args section, if any, typically
+        # describes __init__, so falling back to it would risk injecting
+        # constructor docs into __call__'s schema on overlapping names.
+        # The description, however, comes from the class docstring (which
+        # describes what the tool IS) when present.
+        inner_docstring = parse_docstring(fn)
+        parsed_docstring = ParsedDocstring(
+            description=outer_docstring.description or inner_docstring.description,
+            parameters=inner_docstring.parameters,
+        )
+
         # Transform Context type annotations to Depends() for unified DI
         fn = transform_context_annotations(fn)
 
@@ -195,6 +209,18 @@ def from_function(
             input_schema, prune_params=prune_params, prune_titles=True
         )
 
+        # Inject parameter descriptions from the docstring into the schema.
+        # Explicit annotations (Field(description=...), Annotated[x, "..."])
+        # already have a "description" key and take precedence.
+        if parsed_docstring.parameters:
+            properties = input_schema.get("properties", {})
+            for param_name, param_desc in parsed_docstring.parameters.items():
+                if (
+                    param_name in properties
+                    and "description" not in properties[param_name]
+                ):
+                    properties[param_name]["description"] = param_desc
+
         output_schema = None
         # Get the return annotation from the signature
         sig = inspect.signature(fn)
@@ -282,7 +308,7 @@ def from_function(
         return cls(
             fn=fn,
             name=fn_name,
-            description=fn_doc,
+            description=parsed_docstring.description,
             input_schema=input_schema,
             output_schema=output_schema or None,
             return_type=original_output_type,

src/fastmcp/utilities/docstring_parsing.py

@@ -0,0 +1,65 @@
+"""Extract descriptions from function docstrings.
+
+Uses griffelib to parse Google, NumPy, and Sphinx-style docstrings. The
+interface is intentionally narrow — a single function returning a
+`ParsedDocstring` — so the implementation can be swapped without touching
+callers.
+"""
+
+from __future__ import annotations
+
+import inspect
+import logging
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from typing import Any
+
+from griffe import Docstring, DocstringSectionKind
+
+_PARSERS = ("google", "numpy", "sphinx")
+
+logger = logging.getLogger("griffe")
+# Griffe warns about missing type annotations in docstrings, which is noisy
+# and irrelevant — we only care about descriptions.
+logger.setLevel(logging.ERROR)
+
+
+@dataclass(frozen=True)
+class ParsedDocstring:
+    """The extracted description and per-parameter descriptions from a docstring."""
+
+    description: str | None = None
+    parameters: dict[str, str] = field(default_factory=dict)
+
+
+def parse_docstring(fn: Callable[..., Any]) -> ParsedDocstring:
+    """Parse a function's docstring into a summary and parameter descriptions.
+
+    Tries Google, NumPy, and Sphinx parsers in order, using the first one that
+    successfully extracts parameter descriptions. If none do, returns the full
+    docstring as the description with no parameter descriptions.
+    """
+    doc = inspect.getdoc(fn)
+    if not doc:
+        return ParsedDocstring()
+
+    # Try each parser and use the first one that finds parameters.
+    for parser in _PARSERS:
+        docstring = Docstring(doc, lineno=1, parser=parser)
+        sections = docstring.parse()
+
+        description: str | None = None
+        parameters: dict[str, str] = {}
+
+        for section in sections:
+            if section.kind == DocstringSectionKind.text and description is None:
+                description = section.value
+            elif section.kind == DocstringSectionKind.parameters:
+                for param in section.value:
+                    parameters[param.name] = param.description
+
+        if parameters:
+            return ParsedDocstring(description=description, parameters=parameters)
+
+    # No parser found parameters — return the full docstring unchanged.
+    return ParsedDocstring(description=doc)