Beginner-Friendly Topic
Take your time - it's perfectly normal to re-read this topic 2-3 times. Try the interactive code editor below to run code yourself. Use the Q&A section to check your understanding before moving on.You've got this!
Tool Definitions
Tool definitions tell the agent controller everything it needs to know to use a tool correctly. A well-written definition prevents misuse and improves reliability.
8 min•By Priygop Team•Updated 2026
Complete Tool Definition
Complete Tool Definition
# A complete, production-quality tool definition
web_search_tool = {
"name": "web_search",
"description": (
"Search the web for current information about a topic. "
"Use this tool when you need up-to-date information that "
"you do not already have in context. "
"Do NOT use this for calculations or retrieving local data."
),
"parameters": {
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "The search query. Be specific for better results.",
},
"max_results": {
"type": "integer",
"description": "Maximum number of results to return. Default is 5.",
"default": 5,
},
},
"required": ["query"],
},
"returns": {
"type": "array",
"description": "List of search results, each with title, url, and snippet.",
},
}
print("Tool defined:", web_search_tool["name"])
print("Required params:", web_search_tool["parameters"]["required"])Description Writing Tips
- Say what the tool does, not how it works internally
- Say WHEN to use it — what situation calls for this tool
- Say when NOT to use it — prevents the agent from picking the wrong tool
- Keep it to 2-4 sentences. Longer descriptions reduce clarity.
- Use action verbs: 'searches', 'retrieves', 'creates', 'sends'
- Include the format of the output if it affects how results are used
Key Takeaways
- Tool definitions tell the agent controller everything it needs to know to use a tool correctly.
- Say what the tool does, not how it works internally
- Say WHEN to use it — what situation calls for this tool
- Say when NOT to use it — prevents the agent from picking the wrong tool