Please help me understand how docstrings of tools are passed to the agent.

[NikitaZemtsov]

I can't figure out when the docstrings for the tools are passed to the agent. It doesn't happen when the prompt is sent; only the function argument structure is sent. I noticed that my agent flatly refuses to call the tool if I don't add a block to system_instructions with a description for each of the tools, and this looks like a duplication of part of the tool's docstring. How appropriate is it to use part of the docstring as a description?

[adk-bot]

Response from ADK Answering Agent (experimental, answer may be inaccurate)

TLDR: The docstring of a tool is automatically used as its description for the agent. The system_instructions should not duplicate this description, but rather provide strategic guidance on when and how to use the available tools to achieve a goal.

---

Hello! That's a great question about how tool definitions are passed to the agent.

Your observation is correct that providing clear instructions is key, but you shouldn't need to duplicate the entire docstring. Here’s a breakdown of the roles of docstrings and system_instructions:

1. Tool Docstrings: The ADK framework automatically inspects your Python function, and the docstring is used as the primary description of the tool for the LLM. [1] This description, along with the function name and parameters, is sent to the model to help it understand what the tool does. A detailed and well-written docstring is crucial for the model to select the right tool for a given task.

2. System Instructions (instruction parameter): The instruction property of an Agent is meant to guide the agent's overall behavior, persona, and high-level strategy. [2] Instead of re-defining what a tool does, you should use the instructions to tell the agent when to use a tool to accomplish its goal. You can simply refer to the tool by its function name.

Example

Let's say you have a tool function named get_user_location.

• Good docstring: "Retrieves the geographical location (city, state) of the specified user."
• Good instruction: "Your goal is to send a personalized greeting. First, find the user's location using the get_user_location tool. Then, use the weather tool to find the local weather and greet them by mentioning their city and the current weather."

In this example, the instruction doesn't repeat what get_user_location does. Instead, it provides a plan that orchestrates the use of the tool in a sequence.

By separating the tool's intrinsic description (docstring) from the agent's strategic instructions (instruction), you can create more modular and effective agents.

---

References:
[1] Function Tools Documentation
[2] Agent Team Tutorial