Agent Tool Creation

Agent Tool Creation

Designing and building tools for AI agents to use — from tool schema definition and parameter design through documentation, error handling, and security.

When to Use

• Creating custom tools for LLM agents
• Building MCP servers for agent integration
• Designing tool interfaces that agents can discover and use
• Implementing secure, robust tool execution
• Testing tools with various agent frameworks

Tool Design Pattern

from typing import Dict, List, Optional, Any
from pydantic import BaseModel, Field

class Tool:
    """A single tool that an agent can call."""
    def __init__(self, name: str, description: str, 
                 parameters: Dict, handler: callable):
        self.name = name
        self.description = description
        self.parameters = parameters  # JSON schema
        self.handler = handler
    
    def to_openai_schema(self) -> Dict:
        """Convert to OpenAI function calling format."""
        return {
            'type': 'function',
            'function': {
                'name': self.name,
                'description': self.description[:1024],
                'parameters': self.parameters,
            }
        }

class SearchTool(Tool):
    """Example: web search tool for agents."""
    def __init__(self):
        super().__init__(
            name='web_search',
            description='Search the web for current information.',
            parameters={
                'type': 'object',
                'properties': {
                    'query': {
                        'type': 'string',
                        'description': 'The search query'
                    },
                    'limit': {
                        'type': 'integer',
                        'description': 'Max results (1-10)',
                        'default': 5,
                    },
                },
                'required': ['query'],
            },
            handler=self.search,
        )
    
    def search(self, query: str, limit: int = 5) -> str:
        # Actual search implementation
        return f"Results for '{query}'..."

Common Pitfalls

1. Poor descriptions — agent doesn't understand when to use the tool; write clear descriptions
2. Too many parameters — 10+ parameters confuse agents; keep it simple (3-5 max)
3. No error handling — tool crashes without useful error message; return structured errors
4. No idempotency — tool run twice produces different results; document side effects
5. Security holes — agent can access unintended data via tool; validate permissions per tool

Verification Checklist

• Tool name is clear and unique
• Description tells agent WHEN to use the tool
• Parameters minimal (3-5 max), with descriptions and defaults
• Error handling returns structured error (not exception)
• Side effects documented in parameter descriptions
• Idempotency for read operations
• Tool tested with multiple agent frameworks
• Rate limiting and quota per tool
• Tool registered with agent's tool registry