A tool description is the metadata an agent uses to understand and call a tool. It identifies the tool, explains its purpose, and describes the parameters it accepts. Registered through an SDK, this information lets the model choose tools without repeating every detail in the instruction prompt. section 7.2.3 section 5.4.1
Design descriptions so the agent can distinguish tools and use them safely:
- Make overlapping tools visibly different; descriptions should distinguish search_documents from search_files well enough for disambiguation. section 4.2.1
- State the tool’s purpose and parameter constraints, such as requiring a single keyword query. section 7.2.3
- Keep general tool details in metadata and reserve prompts or inline guidance for policies such as preferring one tool in a specific situation. section 7.2.3
A description fixes tool use
A retrieval agent initially exposes search_knowledge and returns an incorrect answer. Renaming the tool to search_knowledge_by_keyword and documenting that query accepts one keyword makes the intended use clearer, while the prompt remains focused on the task. section 7.2.3
Descriptions define available operations
The SequentialThinking tool describes a flexible process for breaking down complex problems, revising thoughts, and maintaining context. The agent sees this description, but the tool itself acts as a scratch pad rather than reasoning independently. section 5.4.1
Figure 4.5 A single agent is transformed into a multi-agent flow. The agent role is broken down into three well-defined, distinct roles/agents, each encapsulating a well-defined set of tools appropriate to that role. The single agent becomes a flow of a research tools agent, a planning agent, and a filesystem agent.
Use the flow diagram to see why distinct roles need distinct tool sets and why overloaded agents benefit from clearer boundaries. section 4.2.1
