name	ai-agent-tool-builder
description	Create MCP servers, function calling tools, and composable tool frameworks for AI agents
allowed-tools	Read, Write, Edit, Bash, Grep, Glob
version	1.0.0

AI Agent Tool Builder

Meta-Skill for Tool Creation: Build custom tools that extend AI agent capabilities through MCP servers, function calling interfaces, and tool composition patterns.

Purpose

This skill enables creation of custom tools that AI agents can use. When existing tools don't meet requirements, build new ones using MCP protocol, function calling schemas, or tool composition.

Why This Matters:

Agents need domain-specific tools beyond generic capabilities
MCP protocol enables standardized tool interfaces
Tool composition creates powerful workflows from primitives
Safe, validated tools prevent agent errors and security issues

Quick Start

4-Step Tool Creation Process:

Design: Define tool schema (name, description, parameters, outputs)
Implement: Write tool logic with validation and error handling
Test: Verify behavior with unit tests and integration tests
Integrate: Deploy MCP server or register function calling tool

Example - Simple MCP Server:

# Create FastMCP server in 5 minutes
from fastmcp import FastMCP

mcp = FastMCP("File Operations")

@mcp.tool()
def count_lines(file_path: str) -> int:
    """Count lines in a file."""
    with open(file_path) as f:
        return len(f.readlines())

Core Patterns Overview

1. MCP Server Creation

FastMCP (Python): Rapid server development with decorators and type hints. TypeScript SDK: Production-grade servers with full protocol control. Use When: Creating reusable tools for multiple agents or applications.

2. Function Calling Schema Design

JSON Schema Parameters: Define strict input validation with types and constraints. Result Schemas: Structure outputs for downstream tool consumption. Use When: Integrating with OpenAI/Anthropic function calling.

3. Tool Composition & Chaining

Sequential Chains: Pass output from one tool as input to next. Conditional Execution: Tools that route based on intermediate results. Use When: Building complex workflows from simple tool primitives.

4. Error Handling & Validation

Input Validation: Check parameters before execution to prevent failures. Graceful Degradation: Return partial results when possible, fail safely. Use When: All tools (validation prevents 80% of issues).

5. Tool Testing & Deployment

Unit Tests: Test tool logic in isolation with mock inputs. Integration Tests: Verify tool works with MCP client/agent. Use When: Before deploying any tool (testing catches edge cases).

Pattern Selection Guide

Need to create a tool?
├─ Single simple function? → Pattern 1: FastMCP (quickest)
├─ Complex API wrapper? → Pattern 1: TypeScript SDK (more control)
├─ Agent-specific tool? → Pattern 2: Function Calling Schema
├─ Multi-step workflow? → Pattern 3: Tool Composition
└─ Debugging tool issues? → Pattern 4: Error Handling + Pattern 5: Testing

Top 3 Gotchas

1. Schema Mismatches

Problem: Tool parameter schema doesn't match actual implementation. Symptom: Agent sends wrong parameters, tool crashes or returns errors. Fix: Use type hints in Python or TypeScript types, validate at runtime.

# BAD: Schema says 'file_path', function uses 'path'
@mcp.tool()
def read_file(file_path: str) -> str:
    with open(path) as f:  # NameError: 'path' not defined
        return f.read()

# GOOD: Schema matches implementation
@mcp.tool()
def read_file(file_path: str) -> str:
    with open(file_path) as f:
        return f.read()

2. Missing Error Handling

Problem: Tool crashes on invalid input, agent gets cryptic error. Symptom: "Internal server error" with no useful context. Fix: Validate inputs, catch exceptions, return descriptive error messages.

# BAD: Crashes on missing file
def read_file(file_path: str) -> str:
    with open(file_path) as f:  # FileNotFoundError kills agent
        return f.read()

# GOOD: Returns descriptive error
def read_file(file_path: str) -> str:
    try:
        with open(file_path) as f:
            return f.read()
    except FileNotFoundError:
        return f"Error: File '{file_path}' not found"

3. Security Vulnerabilities

Problem: Tool accepts arbitrary input without validation. Symptom: Command injection, path traversal, data leaks. Fix: Whitelist allowed inputs, sanitize paths, sandbox execution.

# BAD: Command injection vulnerability
def run_command(cmd: str) -> str:
    return subprocess.run(cmd, shell=True, capture_output=True).stdout

# GOOD: Whitelist allowed commands
ALLOWED_COMMANDS = {"ls", "pwd", "date"}
def run_command(cmd: str) -> str:
    if cmd not in ALLOWED_COMMANDS:
        return f"Error: Command '{cmd}' not allowed"
    return subprocess.run([cmd], capture_output=True).stdout

When to Use This Skill

Use this skill when you need to:

Create custom MCP server for domain-specific tools
Wrap existing CLI tools or APIs for agent use
Build composite tools from multiple primitives
Design function calling interfaces for OpenAI/Anthropic
Add new capabilities to existing agent systems
Ensure tools are safe, validated, and production-ready

Don't use this skill for:

Using existing tools (just call them directly)
Simple one-off scripts (no need for MCP overhead)
Tools that exist in standard libraries (reuse existing)

Quick Reference Card

FastMCP Server Skeleton

from fastmcp import FastMCP

mcp = FastMCP("Server Name")

@mcp.tool()
def tool_name(param: str) -> str:
    """Tool description for agent."""
    # Validate input
    if not param:
        return "Error: param required"

    # Execute logic
    try:
        result = do_work(param)
        return result
    except Exception as e:
        return f"Error: {str(e)}"

if __name__ == "__main__":
    mcp.run()

TypeScript MCP Server Skeleton

import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

const server = new Server({
  name: "server-name",
  version: "1.0.0"
});

server.setRequestHandler("tools/call", async (request) => {
  if (request.params.name === "tool_name") {
    // Validate and execute
    return { content: [{ type: "text", text: "result" }] };
  }
});

const transport = new StdioServerTransport();
await server.connect(transport);

Function Calling Schema Template

{
  "name": "tool_name",
  "description": "What this tool does",
  "parameters": {
    "type": "object",
    "properties": {
      "param_name": {
        "type": "string",
        "description": "What this parameter controls"
      }
    },
    "required": ["param_name"]
  }
}

Detailed Knowledge

For comprehensive information, see:

KNOWLEDGE.md: MCP architecture, function calling concepts, tool design principles
PATTERNS.md: 5 implementation patterns with code templates
EXAMPLES.md: Working MCP servers and tool composition examples
GOTCHAS.md: Common issues, debugging strategies, troubleshooting
REFERENCE.md: API documentation, protocol specs, performance benchmarks

Core Concepts Summary

Model Context Protocol (MCP)

Standardized protocol for LLM-tool communication. Defines:

Tools: Functions agents can call with parameters
Resources: Data sources agents can read (files, URLs)
Prompts: Templates agents can use
Transport: How messages are exchanged (stdio, HTTP)

Function Calling

LLM capability to invoke external functions:

Agent analyzes user request
Identifies required tool and parameters
Executes tool with validated parameters
Receives structured result
Continues conversation with result context

Tool Composition

Combining simple tools into complex workflows:

Sequential: Tool A → Tool B → Tool C
Conditional: If/else routing based on results
Parallel: Run multiple tools concurrently
Recursive: Tools that call themselves or other tools

Best Practices

DO

Start with simplest tool that solves the problem
Validate all inputs before execution
Return structured, parseable outputs
Include descriptive error messages
Test with edge cases and invalid inputs
Document tool purpose and parameters clearly
Version your tool schemas
Monitor tool usage and errors

DON'T

Execute arbitrary user commands without sanitization
Return raw exceptions to agents (leak internal details)
Create tools that modify state without confirmation
Skip input validation (agents make mistakes too)
Make tools do too many things (single responsibility)
Forget to handle network/filesystem errors
Deploy without integration testing

Integration Points

This skill works with:

mcp-server-engineer: Agent that creates MCP servers
mcp-tool-engineer: Agent that builds individual tools
context-engineering-framework: Manage tool documentation context
agent-builder-framework: Design agents that use custom tools
workflow-builder-framework: Orchestrate multi-tool workflows

Agents that should use this skill:

AI engineers building agent capabilities
DevOps engineers wrapping infrastructure tools
Domain experts creating specialized tools
Integration engineers connecting systems

Success Metrics

Quality Indicators:

Tool has clear, accurate schema
90%+ test coverage for tool logic
Graceful error handling for all failure modes
Security validation prevents common vulnerabilities
Documentation enables first-time use

Performance Indicators:

Tool responds within 2 seconds for most operations
Error rate < 1% in production
Clear error messages enable self-service debugging

Learning Path

Beginner: Start here if new to tool creation

Read KNOWLEDGE.md (MCP basics, function calling)
Follow EXAMPLES.md Example 1 (simple FastMCP server)
Run tests to verify tool works
Review GOTCHAS.md (avoid common mistakes)

Intermediate: Familiar with basic tools

Study PATTERNS.md (5 implementation patterns)
Build TypeScript MCP server (Example 2)
Implement tool composition (Pattern 4)
Add comprehensive error handling (Pattern 4)

Advanced: Building production tools

Design tool ecosystem architecture
Implement security best practices
Add monitoring and observability
Performance optimization
Contract testing for tool interfaces

Related Skills

agent-builder-framework: Design agents that use your tools
workflow-builder-framework: Orchestrate tools in complex workflows
context-engineering-framework: Manage tool documentation efficiently
security-scanning-suite: Audit tools for vulnerabilities

Next Steps

Read KNOWLEDGE.md to understand MCP and tool design principles
Try EXAMPLES.md to see working implementations
Study PATTERNS.md for implementation templates
Check GOTCHAS.md when debugging issues
Consult REFERENCE.md for API details

Quick Tip: Most tools can be built with FastMCP in under 50 lines. Start simple, iterate based on agent feedback.

ai-agent-tool-builder

Install Skill

SKILL.md