What Makes a Good Tool?
Well-designed tools are the foundation of capable AI agents. A tool's schema, naming, and documentation directly impact how reliably an LLM can use it.
Design Principles
Follow these principles to create tools that agents can use effectively.
Clear Naming
Use descriptive, unambiguous names. "search_web" is better than "sw" or "query".
Explicit Parameters
Every parameter should have a clear type, description, and constraints.
Predictable Outputs
Return consistent, structured responses. Include error messages in the output.
Minimal Scope
Each tool should do one thing well. Prefer many focused tools over few complex ones.
Schema Design
Tool schemas tell the LLM how to use your tools. Good schemas prevent errors.
Good Schema
{
"name": "search_web",
"description": "Search the web for information",
"parameters": {
"query": {
"type": "string",
"description": "The search query",
"required": true
},
"max_results": {
"type": "integer",
"description": "Maximum results (1-10)",
"default": 5
}
}
}Bad Schema
{
"name": "sw",
"parameters": {
"q": { "type": "string" },
"n": { "type": "number" }
}
}Error Handling
Tools should handle errors gracefully and return informative messages the LLM can act on.
Tool Schema Builder
Build and validate tool schemas interactively
Tool Name
Define your tool's identity
Parameters
2 parameters defined
Generated Schema
JSON Schema output
{
"name": "search_web",
"description": "Search the web for information on a given query",
"parameters": {
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "The search query"
},
"max_results": {
"type": "number",
"description": "Maximum number of results to return (1-10)"
}
},
"required": [
"query"
]
}
}Key Takeaways
- 1Tool design directly impacts agent reliability
- 2Explicit schemas with descriptions prevent LLM confusion
- 3Return structured errors the agent can understand and act on
- 4Test tools with various inputs to find edge cases