tool-design

Tool design for agents requires four essential description elements: what the tool does, when to use it, what inputs it accepts, and what it returns. Structure each tool with consistent naming, clear parameter definitions, and explicit error handling to ensure agents understand and use tools correctly without ambiguity.

Consolidate tools when they share identical inputs, outputs, or error patterns and logically belong under one namespace; keep them separate when they serve distinct use cases or have conflicting parameter structures. Evaluation patterns help verify whether consolidation improves clarity or obscures agent decision-making.

Define consistent error types and recovery paths across all tools in a collection using a shared frontmatter template. Document specific errors like NOT_FOUND and INVALID_FORMAT with actionable messages so agents can handle failures uniformly without guessing the tool's behavior.

Evaluate tool definitions against five criteria: clarity of intent, completeness of parameters, recoverability from errors, efficiency of descriptions, and consistency across the tool collection. Example-driven guidance and templates accelerate testing and catch ambiguous definitions before agents encounter them.

Yes. The core principles—structured schemas, consistent naming, explicit error handling, and evaluation patterns—apply to any language-model agent framework. The patterns focus on interface robustness and clarity, independent of the underlying agent runtime or orchestration tool.

Include the four-part description (what, when, inputs, returns), parameter constraints with defaults, example requests and responses, error codes with recovery guidance, and namespace organization. Templates and best practices reduce onboarding friction and ensure collaborators understand tool intent and constraints immediately.