Skip to content

πŸš€ The fast, Pythonic way to build MCP servers and clients.

Carry prompt argument titles through PromptArgument and proxies (#5749)

Aarnav Noble288485cc2c5a
diff --git a/docs/servers/prompts.mdx b/docs/servers/prompts.mdx
index 1986a50bf..e12791ae9 100644
--- a/docs/servers/prompts.mdx
+++ b/docs/servers/prompts.mdx
@@ -219,6 +219,26 @@ The free-form text above the `Args` section β€” whether a single line or multipl
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.
+### Argument Titles
+
+An argument's name is what clients send, so it is usually short. To show clients a human-readable label instead, give the parameter a title with `Field(title=...)`:
+
+```python
+from typing import Annotated
+
+from pydantic import Field
+
+
+def write_story(
+ topic: Annotated[str, Field(title="Story topic")],
+ tone: str = Field(default="playful", title="Tone of voice"),
+) -> str:
+ return f"Write a {tone} short story about {topic}."
+```
+
+The title becomes the `title` of the corresponding `PromptArgument` in the MCP protocol. Arguments without an explicit title are listed without one. A proxy keeps the argument titles its backend lists.
+
### Return Values
Prompt functions must return one of these types:
diff --git a/fastmcp_slim/fastmcp/prompts/base.py b/fastmcp_slim/fastmcp/prompts/base.py
index c9c8e7625..ef38cd62c 100644
--- a/fastmcp_slim/fastmcp/prompts/base.py
+++ b/fastmcp_slim/fastmcp/prompts/base.py
@@ -99,6 +99,9 @@ class PromptArgument(FastMCPBaseModel):
"""An argument that can be passed to a prompt."""
name: str = Field(description="Name of the argument")
+ title: str | None = Field(
+ default=None, description="Human-readable name of the argument for display"
+ )
description: str | None = Field(
default=None, description="Description of what the argument does"
)
@@ -241,6 +244,7 @@ class Prompt(FastMCPComponent):
arguments = [
SDKPromptArgument(
name=arg.name,
+ title=arg.title,
description=arg.description,
required=arg.required,
)
diff --git a/fastmcp_slim/fastmcp/prompts/function_prompt.py b/fastmcp_slim/fastmcp/prompts/function_prompt.py
index b8c2cd300..bac7362b1 100644
--- a/fastmcp_slim/fastmcp/prompts/function_prompt.py
+++ b/fastmcp_slim/fastmcp/prompts/function_prompt.py
@@ -15,12 +15,14 @@ from typing import (
Protocol,
TypeVar,
cast,
+ get_type_hints,
overload,
runtime_checkable,
)
import pydantic_core
from mcp_types import Icon
+from pydantic.fields import FieldInfo
from pydantic.json_schema import SkipJsonSchema
from fastmcp.exceptions import PromptError, ValidationError
@@ -203,6 +205,8 @@ class FunctionPrompt(Prompt):
):
properties[param_name]["description"] = param_desc
+ titles = _explicit_parameter_titles(fn)
+
# Convert parameters to PromptArguments
arguments: list[PromptArgument] = []
if "properties" in parameters:
@@ -245,6 +249,7 @@ class FunctionPrompt(Prompt):
arguments.append(
PromptArgument(
name=param_name,
+ title=titles.get(param_name),
description=arg_description,
required=param_name in parameters.get("required", []),
)
@@ -460,3 +465,31 @@ def prompt(
return decorator(fn, prompt_name)
return wrapper
+
+
+def _explicit_parameter_titles(fn: Callable[..., Any]) -> dict[str, str]:
+ """Return the titles set with `Field(title=...)` on fn's parameters.
+
+ The parameter schema cannot tell these apart from the titles Pydantic
+ generates for every parameter, and they are pruned from it, so read them
+ from the annotations and defaults instead.
+ """
+ try:
+ hints = get_type_hints(fn, include_extras=True)
+ except Exception:
+ # Unresolvable annotations: titles set as defaults still count.
+ hints = {}
+ titles: dict[str, str] = {}
+ for name, param in inspect.signature(fn).parameters.items():
+ annotation = hints.get(name, param.annotation)
+ if annotation is inspect.Parameter.empty or isinstance(annotation, str):
+ annotation = Any
+ default = (
+ pydantic_core.PydanticUndefined
+ if param.default is inspect.Parameter.empty
+ else param.default
+ )
+ title = FieldInfo.from_annotated_attribute(annotation, default).title
+ if title is not None:
+ titles[name] = title
+ return titles
diff --git a/fastmcp_slim/fastmcp/server/providers/proxy.py b/fastmcp_slim/fastmcp/server/providers/proxy.py
index 4d58c1725..6a1136af7 100644
--- a/fastmcp_slim/fastmcp/server/providers/proxy.py
+++ b/fastmcp_slim/fastmcp/server/providers/proxy.py
@@ -757,6 +757,7 @@ class ProxyPrompt(Prompt):
arguments = [
PromptArgument(
name=arg.name,
+ title=arg.title,
description=arg.description,
required=arg.required or False,
)
diff --git a/tests/prompts/test_prompt.py b/tests/prompts/test_prompt.py
index 0f84c2c41..c02ab7027 100644
--- a/tests/prompts/test_prompt.py
+++ b/tests/prompts/test_prompt.py
@@ -689,6 +689,24 @@ class TestPromptArgumentDescriptions:
assert mcp_prompt.meta is not None
assert meta_data.items() <= mcp_prompt.meta.items()
+ def test_argument_titles_from_field(self):
+ """An explicit Field(title=...) becomes the argument's MCP title."""
+ from pydantic import Field
+
+ def test_prompt(
+ name: Annotated[str, Field(title="Your name")],
+ tone: str = Field(default="playful", title="Tone of voice"),
+ topic: str = "dogs",
+ ) -> str:
+ return f"Hello, {name}!"
+
+ arguments = Prompt.from_function(test_prompt).to_mcp_prompt().arguments or []
+ assert {arg.name: arg.title for arg in arguments} == {
+ "name": "Your name",
+ "tone": "Tone of voice",
+ "topic": None,
+ }
+
class TestMessage:
def test_message_string_content(self):
diff --git a/tests/server/providers/proxy/test_proxy_server.py b/tests/server/providers/proxy/test_proxy_server.py
index 4906280d4..a8a27c027 100644
--- a/tests/server/providers/proxy/test_proxy_server.py
+++ b/tests/server/providers/proxy/test_proxy_server.py
@@ -883,6 +883,31 @@ class TestPrompts:
proxy_result = await client.list_prompts()
assert proxy_result == result
+ async def test_list_prompts_keeps_argument_titles(self):
+ """A backend's argument titles reach the proxy's clients."""
+ from fastmcp.prompts import Prompt
+ from fastmcp.prompts.base import PromptArgument
+
+ def greet(name: str) -> str:
+ return f"Hello, {name}!"
+
+ prompt = Prompt.from_function(greet)
+ prompt = prompt.model_copy(
+ update={
+ "arguments": [
+ PromptArgument(name="name", title="Your name", required=True)
+ ]
+ }
+ )
+ backend = FastMCP("Backend")
+ backend.add_prompt(prompt)
+
+ async with Client(create_proxy(backend)) as client:
+ (listed,) = await client.list_prompts()
+ assert listed.arguments == [
+ mcp_types.PromptArgument(name="name", title="Your name", required=True)
+ ]
+
async def test_render_prompt_same_as_original(
self, fastmcp_server: FastMCP, proxy_server: FastMCPProxy
):