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 a query.",
"parameters": {
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "The search query."
},
"max_results": {
"type": "integer",
"description": "Maximum number of results.",
"minimum": 1,
"maximum": 10,
"default": 5
}
},
"required": [
"query"
],
"additionalProperties": false
}
}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
Define the tool contract
This builder checks its supported JSON Schema subset. Names must be unique; zero-parameter tools are valid. Description completeness is editorial guidance, separate from structural validity. Provider-specific strict modes can impose additional rules.
Parameters
Generated Schema
{
"name": "search_web",
"description": "Search the web for a query.",
"parameters": {
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "The search query."
}
},
"required": [
"query"
],
"additionalProperties": false
}
}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