Drop generated titles from tool input and output schemas (#3757)

Author: Kludex

docs/advanced/low-level-server.md

@@ -61,7 +61,7 @@ asyncio.run(main())
 The same text the `@mcp.tool()` version produced. Two honest differences:
 
 * `result.structured_content` is `None`. The high-level server wraps a `-> str` into `{"result": ...}` for you; here nobody builds what you didn't build.
-* `list_tools` returns the schema **you** typed, character for character. The high-level version had `"title": "Query"` on every property and a `"title": "search_booksArguments"` at the root: Pydantic artifacts. Down here, if it's on the wire, you put it there.
+* `list_tools` returns the schema **you** typed, character for character. Down here, if it's on the wire, you put it there.
 
 In a test you skip uvicorn and the port: `Client(server)` takes a low-level `Server` in-process exactly like it takes an `MCPServer`, and **[Testing](../get-started/testing.md)** is that pattern.
 

docs/client/index.md

@@ -72,11 +72,10 @@ and `tool.input_schema` is the JSON Schema the server derived from the function'
 {
   "type": "object",
   "properties": {
-    "query": {"title": "Query", "type": "string"},
-    "limit": {"default": 10, "title": "Limit", "type": "integer"}
+    "query": {"type": "string"},
+    "limit": {"default": 10, "type": "integer"}
   },
-  "required": ["query"],
-  "title": "search_booksArguments"
+  "required": ["query"]
 }
 ```
 

docs/handlers/context.md

@@ -30,10 +30,9 @@ This is the part to internalise. Here is the input schema `tools/list` reports f
 {
   "type": "object",
   "properties": {
-    "query": {"title": "Query", "type": "string"}
+    "query": {"type": "string"}
   },
-  "required": ["query"],
-  "title": "search_booksArguments"
+  "required": ["query"]
 }
 ```
 

docs/handlers/dependencies.md

@@ -28,10 +28,9 @@ Here is the input schema `tools/list` reports for `reserve_book`:
 {
   "type": "object",
   "properties": {
-    "title": {"title": "Title", "type": "string"}
+    "title": {"type": "string"}
   },
-  "required": ["title"],
-  "title": "reserve_bookArguments"
+  "required": ["title"]
 }
 ```
 

docs/handlers/lifespan.md

@@ -32,10 +32,9 @@ Nothing new. `ctx` is a **Context** parameter, so the SDK injects it and it neve
 {
   "type": "object",
   "properties": {
-    "genre": {"title": "Genre", "type": "string"}
+    "genre": {"type": "string"}
   },
-  "required": ["genre"],
-  "title": "count_booksArguments"
+  "required": ["genre"]
 }
 ```
 

docs/servers/structured-output.md

@@ -19,10 +19,9 @@ Because of it, the tool the SDK sends during `tools/list` carries an `output_sch
 ```json
 {
   "properties": {
-    "result": {"title": "Result", "type": "integer"}
+    "result": {"type": "integer"}
   },
   "required": ["result"],
-  "title": "get_temperatureOutput",
   "type": "object"
 }
 ```
@@ -59,9 +58,9 @@ Declare the shape as a Pydantic `BaseModel` and return an instance:
 ```json
 {
   "properties": {
-    "temperature": {"description": "Degrees Celsius.", "title": "Temperature", "type": "number"},
-    "humidity": {"description": "Relative humidity, 0 to 1.", "title": "Humidity", "type": "number"},
-    "conditions": {"title": "Conditions", "type": "string"}
+    "temperature": {"description": "Degrees Celsius.", "type": "number"},
+    "humidity": {"description": "Relative humidity, 0 to 1.", "type": "number"},
+    "conditions": {"type": "string"}
   },
   "required": ["temperature", "humidity", "conditions"],
   "title": "WeatherData",
@@ -125,20 +124,19 @@ A `list[...]` isn't a JSON object either, so it gets the `{"result": ...}` wrapp
   "$defs": {
     "WeatherData": {
       "properties": {
-        "temperature": {"title": "Temperature", "type": "number"},
-        "humidity": {"title": "Humidity", "type": "number"},
-        "conditions": {"title": "Conditions", "type": "string"}
+        "temperature": {"type": "number"},
+        "humidity": {"type": "number"},
+        "conditions": {"type": "string"}
       },
       "required": ["temperature", "humidity", "conditions"],
       "title": "WeatherData",
       "type": "object"
     }
   },
   "properties": {
-    "result": {"items": {"$ref": "#/$defs/WeatherData"}, "title": "Result", "type": "array"}
+    "result": {"items": {"$ref": "#/$defs/WeatherData"}, "type": "array"}
   },
   "required": ["result"],
-  "title": "get_forecastOutput",
   "type": "object"
 }
 ```
@@ -158,7 +156,6 @@ Ask for a two-day forecast and `structured_content` is `{"result": [{...}, {...}
 ```json
 {
   "additionalProperties": {"type": "number"},
-  "title": "get_temperaturesDictOutput",
   "type": "object"
 }
 ```
@@ -169,7 +166,7 @@ result.structured_content  # {"London": 16.2, "Reykjavik": 4.4}
 
 The keys must be `str`. A `dict[int, float]` can't be a JSON object, so it falls back to the `{"result": ...}` wrapper.
 
-Dictionary results use Pydantic's `TypeAdapter` for validation and serialization. If you inspect a tool's `FuncMetadata.output_model`, it holds the dictionary type annotation with its schema title.
+Dictionary results use Pydantic's `TypeAdapter` for validation and serialization. If you inspect a tool's `FuncMetadata.output_model`, it holds the dictionary type annotation itself.
 
 ## Validation
 

docs/servers/tools.md

@@ -24,15 +24,14 @@ From those type hints the SDK generates a JSON Schema and sends it to the client
 {
   "type": "object",
   "properties": {
-    "query": {"title": "Query", "type": "string"},
-    "limit": {"title": "Limit", "type": "integer"}
+    "query": {"type": "string"},
+    "limit": {"type": "integer"}
   },
-  "required": ["query", "limit"],
-  "title": "search_booksArguments"
+  "required": ["query", "limit"]
 }
 ```
 
-Both arguments are in `required` because neither has a default. You'll fix that in a moment. (The `title` keys are Pydantic artifacts; the properties, their types, and `required` are the contract.)
+Both arguments are in `required` because neither has a default. You'll fix that in a moment. There are no `title` keys: the ones Pydantic would derive from the class and field names only repeat them. A title you set yourself with `Field(title=...)` is kept.
 
 There is no `$schema` key either: MCP treats a schema without one as **JSON Schema 2020-12**, which is what Pydantic generates, so there is nothing to choose until you write schemas by hand on the **[low-level Server](../advanced/low-level-server.md#the-dialect-is-json-schema-2020-12)**.
 
@@ -79,11 +78,10 @@ The schema follows:
 {
   "type": "object",
   "properties": {
-    "query": {"title": "Query", "type": "string"},
-    "limit": {"default": 10, "title": "Limit", "type": "integer"}
+    "query": {"type": "string"},
+    "limit": {"default": 10, "type": "integer"}
   },
-  "required": ["query"],
-  "title": "search_booksArguments"
+  "required": ["query"]
 }
 ```
 

src/mcp/server/mcpserver/tools/base.py

@@ -21,7 +21,7 @@
     returns_input_required,
 )
 from mcp.server.mcpserver.utilities.context_injection import find_context_parameter
-from mcp.server.mcpserver.utilities.func_metadata import FuncMetadata, func_metadata
+from mcp.server.mcpserver.utilities.func_metadata import FuncMetadata, UntitledJsonSchema, func_metadata
 from mcp.shared._callable_inspection import is_async_callable
 from mcp.shared.exceptions import MCPError
 from mcp.shared.inbound import find_invalid_x_mcp_header
@@ -104,7 +104,9 @@ def from_function(
             skip_names=skip_names,
             structured_output=structured_output,
         )
-        parameters = func_arg_metadata.arg_model.model_json_schema(by_alias=True)
+        parameters = func_arg_metadata.arg_model.model_json_schema(by_alias=True, schema_generator=UntitledJsonSchema)
+        # The arguments model is generated, so its class-name title says nothing.
+        parameters.pop("title", None)
         if (reason := find_invalid_x_mcp_header(parameters)) is not None:
             raise InvalidSignature(f"Tool {func_name!r} has an invalid x-mcp-header annotation: {reason}")
 

src/mcp/server/mcpserver/utilities/func_metadata.py

@@ -63,7 +63,17 @@ def _returns_content(annotation: Any) -> bool:
     return False
 
 
-class StrictJsonSchema(GenerateJsonSchema):
+class UntitledJsonSchema(GenerateJsonSchema):
+    """A JSON schema generator that leaves out the titles pydantic derives from field names.
+
+    They only repeat the property key; titles set explicitly with `Field(title=...)` are kept.
+    """
+
+    def field_title_should_be_set(self, schema: Any) -> bool:
+        return False
+
+
+class StrictJsonSchema(UntitledJsonSchema):
     """A JSON schema generator that raises exceptions instead of emitting warnings.
 
     This is used to detect non-serializable types during schema generation.
@@ -128,6 +138,9 @@ def model_post_init(self, context: Any, /) -> None:
         if self.output_model is not None and self.output_schema is None:
             # StrictJsonSchema raises instead of warning, so an unserializable return type fails construction.
             schema = self._output_adapter(self.output_model).json_schema(schema_generator=StrictJsonSchema)
+            if self.wrap_output:
+                # The `{"result": ...}` wrapper is ours, so its class-name title says nothing.
+                schema.pop("title", None)
             self.output_schema = _inline_root_ref(schema)
 
     def _output_adapter(self, output_model: Any) -> TypeAdapter[Any]:
@@ -338,7 +351,7 @@ def func_metadata(
         field_metadata: list[Any] = []
 
         if param.annotation is inspect.Parameter.empty:
-            field_metadata.append(WithJsonSchema({"title": param.name, "type": "string"}))
+            field_metadata.append(WithJsonSchema({"type": "string"}))
         # Check if the parameter name conflicts with BaseModel attributes
         # This is necessary because Pydantic warns about shadowing parent attributes
         if hasattr(BaseModel, field_name) and callable(getattr(BaseModel, field_name)):
@@ -508,7 +521,7 @@ def _create_output_model(original_annotation: Any, type_expr: Any, func_name: st
             if len(args) == 2 and args[0] is str:
                 # TODO: should we use the original annotation? We are losing any potential `Annotated`
                 # metadata for Pydantic here:
-                model = Annotated[type_expr, Field(title=f"{func_name}DictOutput")]
+                model = type_expr
             else:
                 # dict with non-str keys needs wrapping
                 model = _create_wrapped_model(func_name, original_annotation)

tests/client/test_client.py

@@ -158,15 +158,13 @@ async def test_client_list_tools(app: MCPServer):
                         name="greet",
                         description="Greet someone by name.",
                         input_schema={
-                            "properties": {"name": {"title": "Name", "type": "string"}},
+                            "properties": {"name": {"type": "string"}},
                             "required": ["name"],
-                            "title": "greetArguments",
                             "type": "object",
                         },
                         output_schema={
-                            "properties": {"result": {"title": "Result", "type": "string"}},
+                            "properties": {"result": {"type": "string"}},
                             "required": ["result"],
-                            "title": "greetOutput",
                             "type": "object",
                         },
                     )