Added MCP metadata and annotations to ToolDefinition.metadata

docs/mcp/client.md

@@ -231,6 +231,10 @@ calculator_server = MCPServerSSE(
 agent = Agent('openai:gpt-4o', toolsets=[weather_server, calculator_server])
 ```
 
+## Tool `meta`, `annotations` & `output_schema`
+
+MCP tools often include metadata that provides additional information about the tool's characteristics, which can use useful in [`toolset filtering`][pydantic_ai.toolsets.FilteredToolset].  These properties are available in the [`ToolDefinition.metadata`][pydantic_ai.tools.ToolDefinition.metadata].
+
 ## Custom TLS / SSL configuration
 
 In some environments you need to tweak how HTTPS connections are established –

pydantic_ai_slim/pydantic_ai/mcp.py

@@ -254,6 +254,11 @@ async def get_tools(self, ctx: RunContext[Any]) -> dict[str, ToolsetTool[Any]]:
                     name=name,
                     description=mcp_tool.description,
                     parameters_json_schema=mcp_tool.inputSchema,
+                    metadata={
+                        'meta': mcp_tool.meta,
+                        'annotations': mcp_tool.annotations.model_dump() if mcp_tool.annotations else None,
+                        'output_schema': mcp_tool.outputSchema or None,
+                    },
                 ),
             )
             for mcp_tool in await self.list_tools()

pydantic_ai_slim/pydantic_ai/tools.py

@@ -488,6 +488,12 @@ class ToolDefinition:
         See the [tools documentation](../deferred-tools.md#human-in-the-loop-tool-approval) for more info.
     """
 
+    metadata: dict[str, Any] | None = None
+    """Tool metadata that can be set by the toolset this tool came from. It is not sent to the model, but can be used for filtering and tool behavior customization.
+
+    For MCP tools, this contains the `_meta`, `annotations`, and `output_schema` fields from the tool definition.
+    """
+
     @property
     def defer(self) -> bool:
         """Whether calls to this tool will be deferred.

tests/mcp_server.py

@@ -11,14 +11,15 @@
     SamplingMessage,
     TextContent,
     TextResourceContents,
+    ToolAnnotations,
 )
 from pydantic import AnyUrl, BaseModel
 
 mcp = FastMCP('Pydantic AI MCP Server')
 log_level = 'unset'
 
 
-@mcp.tool()
+@mcp.tool(annotations=ToolAnnotations(title='Celsius to Fahrenheit'))
 async def celsius_to_fahrenheit(celsius: float) -> float:
     """Convert Celsius to Fahrenheit.
 

tests/test_logfire.py

@@ -387,6 +387,7 @@ async def my_ret(x: int) -> str:
                                 'strict': None,
                                 'sequential': False,
                                 'kind': 'function',
+                                'metadata': None,
                             }
                         ],
                         'builtin_tools': [],
@@ -780,6 +781,7 @@ class MyOutput:
                                 'strict': None,
                                 'sequential': False,
                                 'kind': 'output',
+                                'metadata': None,
                             }
                         ],
                         'allow_text_output': False,

tests/test_mcp.py

@@ -1251,6 +1251,22 @@ async def test_tool_returning_multiple_items(allow_model_requests: None, agent:
         )
 
 
+async def test_tool_metadata_extraction():
+    """Test that MCP tool metadata is properly extracted into ToolDefinition."""
+
+    server = MCPServerStdio('python', ['-m', 'tests.mcp_server'])
+    async with server:
+        ctx = RunContext(deps=None, model=TestModel(), usage=RunUsage())
+        tools = [tool.tool_def for tool in (await server.get_tools(ctx)).values()]
+        # find `celsius_to_fahrenheit`
+        celsius_to_fahrenheit = next(tool for tool in tools if tool.name == 'celsius_to_fahrenheit')
+        assert celsius_to_fahrenheit.metadata is not None
+        assert celsius_to_fahrenheit.metadata.get('annotations') is not None
+        assert celsius_to_fahrenheit.metadata.get('annotations', {}).get('title', None) == 'Celsius to Fahrenheit'
+        assert celsius_to_fahrenheit.metadata.get('output_schema') is not None
+        assert celsius_to_fahrenheit.metadata.get('output_schema', {}).get('type', None) == 'object'
+
+
 async def test_client_sampling(run_context: RunContext[int]):
     server = MCPServerStdio('python', ['-m', 'tests.mcp_server'])
     server.sampling_model = TestModel(custom_output_text='sampling model response')

tests/test_tools.py

@@ -146,6 +146,7 @@ def test_docstring_google(docstring_format: Literal['google', 'auto']):
             'strict': None,
             'kind': 'function',
             'sequential': False,
+            'metadata': None,
         }
     )
 
@@ -179,6 +180,7 @@ def test_docstring_sphinx(docstring_format: Literal['sphinx', 'auto']):
             'strict': None,
             'kind': 'function',
             'sequential': False,
+            'metadata': None,
         }
     )
 
@@ -220,6 +222,7 @@ def test_docstring_numpy(docstring_format: Literal['numpy', 'auto']):
             'strict': None,
             'kind': 'function',
             'sequential': False,
+            'metadata': None,
         }
     )
 
@@ -261,6 +264,7 @@ def my_tool(x: int) -> str:  # pragma: no cover
             'strict': None,
             'kind': 'function',
             'sequential': False,
+            'metadata': None,
         }
     )
 
@@ -300,6 +304,7 @@ def my_tool(x: int) -> str:  # pragma: no cover
             'strict': None,
             'kind': 'function',
             'sequential': False,
+            'metadata': None,
         }
     )
 
@@ -345,6 +350,7 @@ def my_tool(x: int) -> str:  # pragma: no cover
             'strict': None,
             'kind': 'function',
             'sequential': False,
+            'metadata': None,
         }
     )
 
@@ -378,6 +384,7 @@ def test_only_returns_type():
             'strict': None,
             'kind': 'function',
             'sequential': False,
+            'metadata': None,
         }
     )
 
@@ -402,6 +409,7 @@ def test_docstring_unknown():
             'strict': None,
             'kind': 'function',
             'sequential': False,
+            'metadata': None,
         }
     )
 
@@ -444,6 +452,7 @@ def test_docstring_google_no_body(docstring_format: Literal['google', 'auto']):
             'strict': None,
             'kind': 'function',
             'sequential': False,
+            'metadata': None,
         }
     )
 
@@ -479,6 +488,7 @@ def takes_just_model(model: Foo) -> str:
             'strict': None,
             'kind': 'function',
             'sequential': False,
+            'metadata': None,
         }
     )
 
@@ -523,6 +533,7 @@ def takes_just_model(model: Foo, z: int) -> str:
             'strict': None,
             'kind': 'function',
             'sequential': False,
+            'metadata': None,
         }
     )
 
@@ -887,6 +898,7 @@ def test_suppress_griffe_logging(caplog: LogCaptureFixture):
             'strict': None,
             'kind': 'function',
             'sequential': False,
+            'metadata': None,
         }
     )
 
@@ -958,6 +970,7 @@ def my_tool_plain(*, a: int = 1, b: int) -> int:
                 'strict': None,
                 'kind': 'function',
                 'sequential': False,
+                'metadata': None,
             },
             {
                 'description': None,
@@ -972,6 +985,7 @@ def my_tool_plain(*, a: int = 1, b: int) -> int:
                 'strict': None,
                 'kind': 'function',
                 'sequential': False,
+                'metadata': None,
             },
         ]
     )
@@ -1059,6 +1073,7 @@ def my_tool(x: Annotated[str | None, WithJsonSchema({'type': 'string'})] = None,
                 'strict': None,
                 'kind': 'function',
                 'sequential': False,
+                'metadata': None,
             },
             {
                 'description': None,
@@ -1071,6 +1086,7 @@ def my_tool(x: Annotated[str | None, WithJsonSchema({'type': 'string'})] = None,
                 'strict': None,
                 'kind': 'function',
                 'sequential': False,
+                'metadata': None,
             },
         ]
     )
@@ -1107,6 +1123,7 @@ def get_score(data: Data) -> int: ...  # pragma: no branch
             'strict': None,
             'kind': 'function',
             'sequential': False,
+            'metadata': None,
         }
     )