Added MCP metadata and annotations to ToolDefinition.metadata (#2880)

Co-authored-by: Douwe Maan <[email protected]>

Author: ChuckJonas

docs/mcp/client.md

@@ -318,6 +318,10 @@ calculator_server = MCPServerSSE(
 agent = Agent('openai:gpt-4o', toolsets=[weather_server, calculator_server])
 ```
 
+## Tool metadata
+
+MCP tools can include metadata that provides additional information about the tool's characteristics, which can be useful when [filtering tools][pydantic_ai.toolsets.FilteredToolset]. The `meta`, `annotations`, and `output_schema` fields can be found on the `metadata` dict on the [`ToolDefinition`][pydantic_ai.tools.ToolDefinition] object that's passed to filter functions.
+
 ## Custom TLS / SSL configuration
 
 In some environments you need to tweak how HTTPS connections are established –

pydantic_ai_slim/pydantic_ai/agent/__init__.py

@@ -1006,6 +1006,7 @@ def tool(
         schema_generator: type[GenerateJsonSchema] = GenerateToolJsonSchema,
         strict: bool | None = None,
         requires_approval: bool = False,
+        metadata: dict[str, Any] | None = None,
     ) -> Callable[[ToolFuncContext[AgentDepsT, ToolParams]], ToolFuncContext[AgentDepsT, ToolParams]]: ...
 
     def tool(
@@ -1021,6 +1022,7 @@ def tool(
         schema_generator: type[GenerateJsonSchema] = GenerateToolJsonSchema,
         strict: bool | None = None,
         requires_approval: bool = False,
+        metadata: dict[str, Any] | None = None,
     ) -> Any:
         """Decorator to register a tool function which takes [`RunContext`][pydantic_ai.tools.RunContext] as its first argument.
 
@@ -1067,6 +1069,7 @@ async def spam(ctx: RunContext[str], y: float) -> float:
                 See [`ToolDefinition`][pydantic_ai.tools.ToolDefinition] for more info.
             requires_approval: Whether this tool requires human-in-the-loop approval. Defaults to False.
                 See the [tools documentation](../deferred-tools.md#human-in-the-loop-tool-approval) for more info.
+            metadata: Optional metadata for the tool. This is not sent to the model but can be used for filtering and tool behavior customization.
         """
 
         def tool_decorator(
@@ -1083,7 +1086,9 @@ def tool_decorator(
                 require_parameter_descriptions,
                 schema_generator,
                 strict,
+                False,
                 requires_approval,
+                metadata,
             )
             return func_
 
@@ -1105,6 +1110,7 @@ def tool_plain(
         schema_generator: type[GenerateJsonSchema] = GenerateToolJsonSchema,
         strict: bool | None = None,
         requires_approval: bool = False,
+        metadata: dict[str, Any] | None = None,
     ) -> Callable[[ToolFuncPlain[ToolParams]], ToolFuncPlain[ToolParams]]: ...
 
     def tool_plain(
@@ -1121,6 +1127,7 @@ def tool_plain(
         strict: bool | None = None,
         sequential: bool = False,
         requires_approval: bool = False,
+        metadata: dict[str, Any] | None = None,
     ) -> Any:
         """Decorator to register a tool function which DOES NOT take `RunContext` as an argument.
 
@@ -1168,6 +1175,7 @@ async def spam(ctx: RunContext[str]) -> float:
             sequential: Whether the function requires a sequential/serial execution environment. Defaults to False.
             requires_approval: Whether this tool requires human-in-the-loop approval. Defaults to False.
                 See the [tools documentation](../deferred-tools.md#human-in-the-loop-tool-approval) for more info.
+            metadata: Optional metadata for the tool. This is not sent to the model but can be used for filtering and tool behavior customization.
         """
 
         def tool_decorator(func_: ToolFuncPlain[ToolParams]) -> ToolFuncPlain[ToolParams]:
@@ -1184,6 +1192,7 @@ def tool_decorator(func_: ToolFuncPlain[ToolParams]) -> ToolFuncPlain[ToolParams
                 strict,
                 sequential,
                 requires_approval,
+                metadata,
             )
             return func_
 

pydantic_ai_slim/pydantic_ai/mcp.py

@@ -256,6 +256,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

@@ -255,6 +255,7 @@ class Tool(Generic[AgentDepsT]):
     strict: bool | None
     sequential: bool
     requires_approval: bool
+    metadata: dict[str, Any] | None
     function_schema: _function_schema.FunctionSchema
     """
     The base JSON schema for the tool's parameters.
@@ -277,6 +278,7 @@ def __init__(
         strict: bool | None = None,
         sequential: bool = False,
         requires_approval: bool = False,
+        metadata: dict[str, Any] | None = None,
         function_schema: _function_schema.FunctionSchema | None = None,
     ):
         """Create a new tool instance.
@@ -332,6 +334,7 @@ async def prep_my_tool(
             sequential: Whether the function requires a sequential/serial execution environment. Defaults to False.
             requires_approval: Whether this tool requires human-in-the-loop approval. Defaults to False.
                 See the [tools documentation](../deferred-tools.md#human-in-the-loop-tool-approval) for more info.
+            metadata: Optional metadata for the tool. This is not sent to the model but can be used for filtering and tool behavior customization.
             function_schema: The function schema to use for the tool. If not provided, it will be generated.
         """
         self.function = function
@@ -352,6 +355,7 @@ async def prep_my_tool(
         self.strict = strict
         self.sequential = sequential
         self.requires_approval = requires_approval
+        self.metadata = metadata
 
     @classmethod
     def from_schema(
@@ -406,6 +410,7 @@ def tool_def(self):
             parameters_json_schema=self.function_schema.json_schema,
             strict=self.strict,
             sequential=self.sequential,
+            metadata=self.metadata,
         )
 
     async def prepare_tool_def(self, ctx: RunContext[AgentDepsT]) -> ToolDefinition | None:
@@ -488,6 +493,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.

pydantic_ai_slim/pydantic_ai/toolsets/function.py

@@ -99,6 +99,7 @@ def tool(
         strict: bool | None = None,
         sequential: bool = False,
         requires_approval: bool = False,
+        metadata: dict[str, Any] | None = None,
     ) -> Callable[[ToolFuncEither[AgentDepsT, ToolParams]], ToolFuncEither[AgentDepsT, ToolParams]]: ...
 
     def tool(
@@ -115,6 +116,7 @@ def tool(
         strict: bool | None = None,
         sequential: bool = False,
         requires_approval: bool = False,
+        metadata: dict[str, Any] | None = None,
     ) -> Any:
         """Decorator to register a tool function which takes [`RunContext`][pydantic_ai.tools.RunContext] as its first argument.
 
@@ -166,6 +168,7 @@ async def spam(ctx: RunContext[str], y: float) -> float:
             sequential: Whether the function requires a sequential/serial execution environment. Defaults to False.
             requires_approval: Whether this tool requires human-in-the-loop approval. Defaults to False.
                 See the [tools documentation](../deferred-tools.md#human-in-the-loop-tool-approval) for more info.
+            metadata: Optional metadata for the tool. This is not sent to the model but can be used for filtering and tool behavior customization.
         """
 
         def tool_decorator(
@@ -184,6 +187,7 @@ def tool_decorator(
                 strict,
                 sequential,
                 requires_approval,
+                metadata,
             )
             return func_
 
@@ -202,6 +206,7 @@ def add_function(
         strict: bool | None = None,
         sequential: bool = False,
         requires_approval: bool = False,
+        metadata: dict[str, Any] | None = None,
     ) -> None:
         """Add a function as a tool to the toolset.
 
@@ -230,6 +235,7 @@ def add_function(
             sequential: Whether the function requires a sequential/serial execution environment. Defaults to False.
             requires_approval: Whether this tool requires human-in-the-loop approval. Defaults to False.
                 See the [tools documentation](../deferred-tools.md#human-in-the-loop-tool-approval) for more info.
+            metadata: Optional metadata for the tool. This is not sent to the model but can be used for filtering and tool behavior customization.
         """
         if docstring_format is None:
             docstring_format = self.docstring_format
@@ -250,6 +256,7 @@ def add_function(
             strict=strict,
             sequential=sequential,
             requires_approval=requires_approval,
+            metadata=metadata,
         )
         self.add_tool(tool)
 

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

@@ -1252,6 +1252,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')