Agent tool builder

Agent Tool Builder

Tools are how AI agents interact with the world. A well-designed tool is the difference between an agent that works and one that hallucinates, fails silently, or costs 10x more tokens than necessary.

This skill covers tool design from schema to error handling. JSON Schema best practices, description writing that actually helps the LLM, validation, and the emerging MCP standard that's becoming the lingua franca for AI tools.

Key insight: Tool descriptions are more important than tool implementations. The LLM never sees your code - it only sees the schema and description.

When to Use

• User mentions or implies: agent tool
• User mentions or implies: function calling
• User mentions or implies: tool schema
• User mentions or implies: tool design
• User mentions or implies: mcp server
• User mentions or implies: mcp tool
• User mentions or implies: tool use
• User mentions or implies: build tool for agent
• User mentions or implies: define function
• User mentions or implies: input_schema

Core Workflow

1. Confirm the request matches this skill's trigger, scope, and risk profile.
2. Use the topic map to identify the relevant pattern, checklist, or example before writing detailed guidance or code.
3. Load references/full-guidance.md when implementation details, examples, anti-patterns, validation checks, or edge cases are needed.
4. Apply only the relevant guidance instead of loading or repeating the entire reference by default.
5. Verify the result against any validation checks, limitations, security notes, or platform constraints in the reference.

Topic Map

• Principles
• Capabilities
• Scope
• Tooling
• Standards
• Frameworks
• Patterns
• Tool Schema Design
• Detailed Descriptions (Most Important)
• Parameter Descriptions
• Use Enums When Possible
• Required vs Optional
• Tool with Input Examples
• Tool Error Handling
• Return Informative Errors
• Anthropic Tool Result with Error
• Error Categories to Handle
• Implementation Pattern

Reference Map

• references/full-guidance.md preserves the complete original guidance, including examples and detailed edge cases.

Limitations

• Use this skill only when the task clearly matches the scope described above.
• Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
• Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.

Progressive Loading

Keep this SKILL.md as the compact routing and workflow entrypoint. Load the reference file only when the user task requires the deeper implementation material.