Tools give agents the ability to interact with the real world — reading databases, calling APIs, executing code, and manipulating files. Designing effective tool interfaces is crucial for agent reliability.

Anatomy of a Good Tool

A tool needs three things to work well with an LLM:

1. Clear name: Descriptive, action-oriented (e.g., search_customer_orders not query_db)
2. Precise description: When to use it, what it returns, edge cases
3. Typed parameters: Clear input schema with descriptions and constraints

@tool
def search_customer_orders(
    customer_email: str,
    status: Literal["pending", "shipped", "delivered", "cancelled"] | None = None,
    date_from: str | None = None,
    date_to: str | None = None,
    limit: int = 10,
) -> str:
    """Search for customer orders by email address.
    
    Use when a customer asks about their order status, delivery, or order history.
    Returns order details including order ID, items, status, and tracking info.
    
    Args:
        customer_email: The customer's email address (required)
        status: Filter by order status (optional)
        date_from: Start date in YYYY-MM-DD format (optional)
        date_to: End date in YYYY-MM-DD format (optional)
        limit: Maximum number of orders to return (default: 10)
    """

Tool Design Principles

1. Single responsibility: Each tool does one thing well
2. Informative errors: Return helpful error messages, not stack traces
3. Idempotent reads: Read operations should be safe to retry
4. Confirmation for writes: Destructive actions should require explicit confirmation
5. Bounded outputs: Limit response size to avoid flooding the context window
6. Timeout handling: Set reasonable timeouts and handle failures gracefully

Tool Categories

Dynamic Tool Selection

For agents with many tools (20+), use a two-stage approach:

1. Tool retrieval: Embed tool descriptions and retrieve the most relevant 5-10 based on the user's request
2. Tool selection: Present only relevant tools to the LLM for selection

This prevents confusion from too many options and reduces context window usage.

Tool Composition

Complex tasks often require multiple tools in sequence:

• Search → Read → Analyze → Write → Send
• Each tool's output feeds into the next tool's input
• The agent decides the sequence based on the task

Design tools that produce outputs consumable by other tools. Standardize output formats (JSON with consistent fields).