Make ToolDefinition.description optional and fix Bedrock description handling (#1507)

Co-authored-by: Douwe Maan <douwe@pydantic.dev>

Author: dmontagu

docs/direct.md

@@ -66,7 +66,7 @@ async def main():
             function_tools=[
                 ToolDefinition(
                     name=Divide.__name__.lower(),
-                    description=Divide.__doc__ or '',
+                    description=Divide.__doc__,
                     parameters_json_schema=Divide.model_json_schema(),
                 )
             ],

docs/tools.md

@@ -451,7 +451,6 @@ print(test_model.last_model_request_parameters.function_tools)
 [
     ToolDefinition(
         name='foobar',
-        description='This is a Foobar',
         parameters_json_schema={
             'properties': {
                 'x': {'type': 'integer'},
@@ -462,6 +461,7 @@ print(test_model.last_model_request_parameters.function_tools)
             'title': 'Foobar',
             'type': 'object',
         },
+        description='This is a Foobar',
     )
 ]
 """
@@ -591,7 +591,6 @@ print(test_model.last_model_request_parameters.function_tools)
 [
     ToolDefinition(
         name='greet',
-        description='',
         parameters_json_schema={
             'additionalProperties': False,
             'properties': {

pydantic_ai_slim/pydantic_ai/_function_schema.py

@@ -35,7 +35,7 @@ class FunctionSchema:
     """Internal information about a function schema."""
 
     function: Callable[..., Any]
-    description: str
+    description: str | None
     validator: SchemaValidator
     json_schema: ObjectJsonSchema
     # if not None, the function takes a single by that name (besides potentially `info`)

pydantic_ai_slim/pydantic_ai/_griffe.py

@@ -19,7 +19,7 @@ def doc_descriptions(
     sig: Signature,
     *,
     docstring_format: DocstringFormat,
-) -> tuple[str, dict[str, str]]:
+) -> tuple[str | None, dict[str, str]]:
     """Extract the function description and parameter descriptions from a function's docstring.
 
     The function parses the docstring using the specified format (or infers it if 'auto')
@@ -35,7 +35,7 @@ def doc_descriptions(
     """
     doc = func.__doc__
     if doc is None:
-        return '', {}
+        return None, {}
 
     # see https://github.com/mkdocstrings/griffe/issues/293
     parent = cast(GriffeObject, sig)

pydantic_ai_slim/pydantic_ai/mcp.py

@@ -98,7 +98,7 @@ async def list_tools(self) -> list[tools.ToolDefinition]:
         return [
             tools.ToolDefinition(
                 name=self.get_prefixed_tool_name(tool.name),
-                description=tool.description or '',
+                description=tool.description,
                 parameters_json_schema=tool.inputSchema,
             )
             for tool in mcp_tools.tools

pydantic_ai_slim/pydantic_ai/models/anthropic.py

@@ -416,7 +416,7 @@ async def _map_user_prompt(
     def _map_tool_definition(f: ToolDefinition) -> BetaToolParam:
         return {
             'name': f.name,
-            'description': f.description,
+            'description': f.description or '',
             'input_schema': f.parameters_json_schema,
         }
 

pydantic_ai_slim/pydantic_ai/models/bedrock.py

@@ -62,6 +62,7 @@
         SystemContentBlockTypeDef,
         ToolChoiceTypeDef,
         ToolConfigurationTypeDef,
+        ToolSpecificationTypeDef,
         ToolTypeDef,
         VideoBlockTypeDef,
     )
@@ -228,14 +229,16 @@ def _get_tools(self, model_request_parameters: ModelRequestParameters) -> list[T
 
     @staticmethod
     def _map_tool_definition(f: ToolDefinition) -> ToolTypeDef:
-        return {
-            'toolSpec': {
-                'name': f.name,
-                'description': f.description,
-                'inputSchema': {'json': f.parameters_json_schema},
-            }
+        tool_spec: ToolSpecificationTypeDef = {
+            'name': f.name,
+            'inputSchema': {'json': f.parameters_json_schema},
         }
 
+        if f.description:  # pragma: no branch
+            tool_spec['description'] = f.description
+
+        return {'toolSpec': tool_spec}
+
     @property
     def base_url(self) -> str:
         return str(self.client.meta.endpoint_url)

pydantic_ai_slim/pydantic_ai/models/gemini.py

@@ -773,7 +773,7 @@ class _GeminiFunction(TypedDict):
 
 def _function_from_abstract_tool(tool: ToolDefinition) -> _GeminiFunction:
     json_schema = tool.parameters_json_schema
-    f = _GeminiFunction(name=tool.name, description=tool.description, parameters=json_schema)
+    f = _GeminiFunction(name=tool.name, description=tool.description or '', parameters=json_schema)
     return f
 
 

pydantic_ai_slim/pydantic_ai/models/google.py

@@ -534,7 +534,7 @@ def _function_declaration_from_tool(tool: ToolDefinition) -> FunctionDeclaration
     json_schema = tool.parameters_json_schema
     f = FunctionDeclarationDict(
         name=tool.name,
-        description=tool.description,
+        description=tool.description or '',
         parameters=json_schema,  # type: ignore
     )
     return f

pydantic_ai_slim/pydantic_ai/models/groq.py

@@ -333,7 +333,7 @@ def _map_tool_definition(f: ToolDefinition) -> chat.ChatCompletionToolParam:
             'type': 'function',
             'function': {
                 'name': f.name,
-                'description': f.description,
+                'description': f.description or '',
                 'parameters': f.parameters_json_schema,
             },
         }