Get the FREE Ultimate OpenClaw Setup Guide →

building-agent-tools

Scanned
npx machina-cli add skill Byunk/claude-code-essentials/building-agent-tools --openclaw
Files (1)
SKILL.md
2.8 KB

Building Tools for AI Agents

Workflow

  1. Define Purpose

    • Identify what agents need to accomplish with this tool
    • Determine if existing tools can be consolidated
    • Plan the tool's interface for agent consumption

  2. Design Interface

    • Choose descriptive, namespaced tool names
    • Define parameters with clear types and descriptions
    • Design output format for maximum signal, minimum tokens

  3. Implement

    • Build with token efficiency in mind
    • Add pagination, filtering, sensible defaults
    • Return semantic identifiers, not raw IDs

  4. Validate

    • Test with real agent workflows
    • Check token consumption patterns
    • Verify error messages guide agents toward solutions

Design Principles

Tool Consolidation

  • More tools don't lead to better outcomes
  • Combine related operations into single tools
  • Example: schedule_event that checks availability AND creates event
  • Avoid simple CRUD-style tools that require multiple calls

Namespacing

  • Prefix related tools with service name: asana_projects_search, asana_users_search
  • Group by domain to help agents distinguish functionality
  • Use consistent naming patterns across tool families

Meaningful Context

  • Return high-signal information, not raw data dumps
  • Resolve cryptic UUIDs to human-readable identifiers
  • Include response_format parameter (concise/detailed) for flexibility
  • Surface relevant metadata agents need for next steps

Token Efficiency

  • Implement pagination with sensible defaults
  • Add filtering parameters to reduce unnecessary data
  • Truncate large responses intelligently
  • Prefer structured output over verbose prose

Tool Descriptions

  • Invest heavily in clear, explicit descriptions
  • Describe what the tool does, when to use it, and what it returns
  • Include parameter constraints and valid values
  • Small description improvements yield large performance gains

Anti-Patterns

  • Creating many granular tools instead of consolidated operations
  • Returning raw IDs that agents can't interpret
  • Omitting pagination on potentially large result sets
  • Vague tool descriptions that leave agents guessing
  • Error messages that don't help agents recover
  • Requiring agents to make multiple calls for common workflows

MCP-Specific Patterns

Tool Registration

  • Use descriptive name and description in tool schema
  • Define inputSchema with JSON Schema for parameters
  • Mark required vs optional parameters explicitly

Response Format

  • Return structured JSON for predictable parsing
  • Include success/error indicators
  • Provide actionable error messages

Source

git clone https://github.com/Byunk/claude-code-essentials/blob/main/essentials/skills/building-agent-tools/SKILL.mdView on GitHub

Overview

Guides building tools for AI agents and MCP tool APIs. It emphasizes token efficiency, meaningful context, and disciplined namespacing to improve signal, reuse, and scalability. The workflow covers defining purpose, designing interfaces, implementing with best practices, and validating against real agent workflows.

How This Skill Works

Develop a tool by defining its purpose for agent consumption, then design a descriptive, namespaced interface with clear input types and a concise output format. Implement with token efficiency in mind (pagination, filters, defaults), then validate through real agent workflows and structured JSON responses with clear success/error indicators.

When to Use It

  • Designing a new tool interface for AI agents or MCP tool APIs
  • Consolidating related actions into a single tool to avoid multiple calls
  • Implementing token-efficient outputs with pagination and filtering
  • Applying namespacing to clearly group tools by domain (e.g., service_action)
  • Ensuring outputs are structured with clear success/error indicators and actionable errors

Quick Start

  1. Step 1: Define the tool's purpose for agent consumption and outline its interface
  2. Step 2: Implement with token efficiency: add pagination, filtering, sensible defaults, and structured output
  3. Step 3: Validate with real agent workflows and iterate on error messages for clarity

Best Practices

  • Consolidate related ops into single tools rather than many granular ones
  • Use descriptive, namespaced tool names (e.g., service_action) and consistent patterns
  • Return high-signal context: resolve IDs to readable identifiers, include metadata
  • Design outputs for maximum signal with minimum tokens; add pagination and filters
  • Provide explicit, actionable tool descriptions including constraints and valid values

Example Use Cases

  • schedule_event that checks availability and creates the event in one tool
  • asana_projects_search: search projects within Asana via a namespaced tool
  • asana_users_search: look up users with structured output and meaningful identifiers
  • A tool implementing pagination and filtering to return a subset of results
  • A tool with a response_format parameter to switch between concise and detailed output

Frequently Asked Questions

Add this skill to your agents
Sponsor this space

Reach thousands of developers ↗