Tool Design for Agents

Tools define the contract between deterministic systems and non-deterministic agents. Poor tool design creates failure modes that no amount of prompt engineering can fix.

The Consolidation Principle

If a human engineer cannot definitively say which tool should be used, an agent cannot do better.

Instead of: list_users , list_events , create_event

Use: schedule_event (finds availability and schedules)

Tool Description Structure

Answer four questions:

• What does the tool do?

• When should it be used?

• What inputs does it accept?

• What does it return?

Well-Designed Tool Example

def get_customer(customer_id: str, format: str = "concise"): """ Retrieve customer information by ID.

Use when:
- User asks about specific customer details
- Need customer context for decision-making
- Verifying customer identity

Args:
    customer_id: Format "CUST-######" (e.g., "CUST-000001")
    format: "concise" for key fields, "detailed" for complete record

Returns:
    Customer object with requested fields

Errors:
    NOT_FOUND: Customer ID not found
    INVALID_FORMAT: ID must match CUST-###### pattern
"""

Poor Tool Design (Anti-pattern)

def search(query): """Search the database.""" pass

Problems: Vague name, missing parameters, no return description, no usage context, no error handling.

Architectural Reduction

Production evidence shows: fewer, primitive tools can outperform sophisticated multi-tool architectures.

File System Agent Pattern: Provide direct file system access instead of custom tools. Agent uses grep, cat, find to explore. Works because file systems are well-understood abstractions.

When reduction works:

• Data layer well-documented

• Model has sufficient reasoning

• Specialized tools were constraining

• Spending more time maintaining scaffolding than improving

MCP Tool Naming

Always use fully qualified names:

Correct

"Use the BigQuery:bigquery_schema tool..."

Incorrect (may fail)

"Use the bigquery_schema tool..."

Response Format Optimization

format: str = "concise" # "concise" | "detailed"

Let agents control verbosity. Concise for confirmations, detailed when full context needed.

Error Message Design

Design for agent recovery:

{ "error": "NOT_FOUND", "message": "Customer CUST-000001 not found", "suggestion": "Verify customer ID format (CUST-######)" }

Tool Collection Guidelines

• 10-20 tools for most applications

• Use namespacing for larger collections

• Ensure each tool has unambiguous purpose

• Test with actual agent interactions

Anti-Patterns

• Vague descriptions: "Search the database"

• Cryptic parameters: x , val , param1

• Missing error handling: Generic errors

• Inconsistent naming: id vs identifier vs customer_id

Best Practices

• Write descriptions answering what, when, returns

• Use consolidation to reduce ambiguity

• Implement response format options

• Design error messages for recovery

• Establish consistent naming conventions

• Test with actual agent interactions

• Question if tools enable or constrain reasoning

• Build minimal architectures for model improvements