Tool return types and docstrings are not used

[Krogager]

Initial Checks

• I confirm that I'm using the latest version of Pydantic AI

Description

I noticed that the return type annotations and docstrings of tools are not actually used by pydantic-ai. I was struggling to make my agent understand the instructions and only now noticed that my agent didn't even see the instructions because (part of it) was placed under the "Returns" section of the docstring.

I was wondering if this was left out intentionally, and if so, what was the reason to do so?
If this is indeed intentional, I think it should be mentioned in the documentation somewhere.

Example Code

Python, Pydantic AI & LLM client version

python 3.12
pydantic==2.10.6
pydantic-ai==0.0.40
pydantic-ai-slim==0.0.40
pydantic-graph==0.0.40
pydantic_core==2.27.2

[Kludex]

The return type hint is not included because there's no way to include it in the definition.

The docstring is included. Please provide code that proves otherwise, so I can check.

[Krogager]

Using this code, I don't see anything in the ToolDefinition regarding the return-part of the docstring:

from pprint import pprint
from pydantic_ai.tools import Tool

def test_tool_fct(test_arg: str) -> str:
    """Tool description

    Args:
        test_arg: Test argument
        

    Returns:
        Nothing
    """
    return "nothing"

test_tool = Tool(
    test_tool_fct,
    takes_ctx=False,
)

tool_def = await test_tool.prepare_tool_def(None)
pprint(tool_def)

I also tried running it with an agent like this:

from pydantic_ai.agent import Agent
from pydantic_ai.models.test import TestModel

model = TestModel()
agent = Agent(
    model=model,
    tools=[test_tool]
)
result = await agent.run("hello")
for tool in model.last_model_request_parameters.function_tools:
    pprint(tool)

The following is printed out as a result of my code:

ToolDefinition(name='test_tool_fct',
               description='Tool description',
               parameters_json_schema={'additionalProperties': False,
                                       'properties': {'test_arg': {'description': 'Test '
                                                                                  'argument',
                                                                   'title': 'Test '
                                                                            'Arg',
                                                                   'type': 'string'}},
                                       'required': ['test_arg'],
                                       'type': 'object'},
               outer_typed_dict_key=None)

[alexmojaki]

@Krogager initially I agreed with you, but now I think it would make more sense if users wrote:

def test_tool_fct(test_arg: str) -> str:
    """Tool description. Returns nothing as a string.

    Args:
        test_arg: Test argument
    """

This way it's very clear what the tool description will be and the user doesn't have to guess. So I think we should actually discourage Returns: in the docstring, maybe even with a warning.

[Krogager]

@Krogager initially I agreed with you, but now I think it would make more sense if users wrote:

def test_tool_fct(test_arg: str) -> str:
"""Tool description. Returns nothing as a string.

Args:
    test_arg: Test argument
"""

This way it's very clear what the tool description will be and the user doesn't have to guess. So I think we should actually discourage Returns: in the docstring, maybe even with a warning.

Thanks for the reply @alexmojaki . I agree that it is easy to fix the problem by restructuring the docstring, but at the moment it is not very transparent to the user that a docstring has to be formatted that way. I think a warning would be nice and also to document it clearly in the documentation.

[Kludex]

I brought this to our daily call. We should append to the description both return type and return docstring, if available.