Agent Tool Builder Kit

Overview

A skill for creating custom tools that AI agents can use — designing tool interfaces, implementing handlers, and integrating tools with agent frameworks. Covers tool definition patterns, input validation, error handling, and testing for tools used by Claude Code, LangChain, CrewAI, and other agent systems.

When to Use

• Creating custom tools for Claude Code agents
• Building MCP (Model Context Protocol) tools
• Designing tool interfaces for LangChain or CrewAI agents
• Wrapping existing APIs as agent-callable tools
• Testing and validating agent tool behavior

Quick Start

Copy
# Create a custom tool
claude "Build a tool that searches our internal documentation"

# Create an MCP tool
claude "Create an MCP server tool for querying our PostgreSQL database"

Tool Anatomy

Tool Definition

Every agent tool needs:

Copy
interface ToolDefinition {
  name: string;           // Unique identifier (e.g., "search_docs")
  description: string;    // What the tool does (helps the agent decide when to use it)
  parameters: {           // JSON Schema for inputs
    type: "object";
    properties: Record<string, ParamSchema>;
    required: string[];
  };
  handler: (params: any) => Promise<ToolResult>;  // The actual implementation
}

Claude Code Tool Example

Copy
const searchDocsTool = {
  name: "search_docs",
  description: "Search internal documentation for relevant articles. Use when the user asks about company policies, procedures, or product documentation.",
  parameters: {
    type: "object",
    properties: {
      query: {
        type: "string",
        description: "The search query"
      },
      category: {
        type: "string",
        enum: ["policy", "product", "engineering", "all"],
        description: "Category to search in. Default: all"
      },
      limit: {
        type: "number",
        description: "Maximum results to return. Default: 5"
      }
    },
    required: ["query"]
  },
  handler: async ({ query, category = "all", limit = 5 }) => {
    const results = await docsAPI.search(query, { category, limit });
    return {
      content: results.map(r => `**${r.title}**\n${r.snippet}\n[Link](${r.url})`).join('\n\n'),
      metadata: { totalResults: results.total }
    };
  }
};

MCP Server Tool

Copy
// MCP tool definition
server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: [{
    name: "query_database",
    description: "Run a read-only SQL query against the application database",
    inputSchema: {
      type: "object",
      properties: {
        query: { type: "string", description: "SQL SELECT query to execute" },
        params: { type: "array", description: "Query parameters for prepared statements" }
      },
      required: ["query"]
    }
  }]
}));

// MCP tool handler
server.setRequestHandler(CallToolRequestSchema, async (request) => {
  if (request.params.name === "query_database") {
    const { query, params } = request.params.arguments;
    // Validate it's a SELECT query
    if (!query.trim().toUpperCase().startsWith('SELECT')) {
      return { content: [{ type: "text", text: "Error: Only SELECT queries are allowed" }] };
    }
    const result = await db.query(query, params);
    return { content: [{ type: "text", text: JSON.stringify(result.rows, null, 2) }] };
  }
});

Tool Design Principles

1. Clear Descriptions

The description is how the agent decides to use your tool:

Copy
// BAD: Vague description
description: "Does stuff with users"

// GOOD: Specific, actionable description
description: "Look up a user by email address. Returns user profile including name, role, team, and last login date. Use when the user asks about a specific person or needs to verify account details."

2. Validated Inputs

Copy
async function handler(params: any) {
  // Validate required fields
  if (!params.query || typeof params.query !== 'string') {
    return { error: "query is required and must be a string" };
  }
  // Validate constraints
  if (params.limit && (params.limit < 1 || params.limit > 100)) {
    return { error: "limit must be between 1 and 100" };
  }
  // Sanitize inputs
  const sanitizedQuery = params.query.trim().substring(0, 500);
  // ... execute
}

3. Structured Responses

Copy
// BAD: Raw data dump
return JSON.stringify(dbResult);

// GOOD: Formatted for the agent to understand
return {
  summary: `Found ${results.length} users matching "${query}"`,
  results: results.map(u => `- ${u.name} (${u.email}) - ${u.role}`).join('\n'),
  hasMore: total > results.length
};

Testing Tools

Copy
describe('search_docs tool', () => {
  it('returns relevant results for valid query', async () => {
    const result = await searchDocsTool.handler({ query: 'vacation policy' });
    expect(result.content).toContain('vacation');
    expect(result.metadata.totalResults).toBeGreaterThan(0);
  });

  it('handles empty results gracefully', async () => {
    const result = await searchDocsTool.handler({ query: 'xyznonexistent' });
    expect(result.content).toContain('No results');
  });

  it('validates required parameters', async () => {
    const result = await searchDocsTool.handler({});
    expect(result.error).toContain('query is required');
  });

  it('respects limit parameter', async () => {
    const result = await searchDocsTool.handler({ query: 'policy', limit: 2 });
    expect(result.results.length).toBeLessThanOrEqual(2);
  });
});

Best Practices

1. Write great descriptions — The agent picks tools based on descriptions
2. Keep tools focused — One tool = one capability
3. Return formatted output — Markdown, not raw JSON
4. Handle errors gracefully — Return error messages, don't throw
5. Validate all inputs — Never trust agent-generated parameters
6. Add examples in descriptions — Help the agent understand expected usage
7. Rate limit expensive tools — Prevent runaway API calls
8. Log tool usage — Track which tools are called and with what params
9. Version your tools — Breaking changes should be versioned
10. Test with the agent — Verify the agent actually uses the tool correctly