tool-design

Design tools by writing clear descriptions that answer: what the tool does, when to use it, what inputs it accepts, what it returns, and how it handles errors. This foundation ensures agents understand and trust your tools.

Consolidation reduces complexity and improves agent reliability. A single well-designed comprehensive tool is easier for agents to understand and use correctly than many narrow tools that create decision overhead.

Architectural reduction means using minimal primitive operations to build your tool set. Simpler primitives maximize reliability, reduce maintenance burden, and give agents clearer contracts to work with.

Include examples, document default behaviors, and prescribe clear error handling in your tool description. Actionable error messages and token-efficient response formats guide agents to use tools correctly and recover from edge cases.

Consolidate when tools share similar inputs, outputs, or decision logic, or when an agent must choose between them. Keep tools separate only when they serve fundamentally different purposes and never need to be selected together.

Enforce consistent naming conventions and documentation patterns across all tools. Standardized naming and docs reduce agent confusion, lower token usage, and make your tool set more maintainable as it grows.