Phase 1: Tool Schema Design

Objective: Design validated tool schemas for your agent

Steps

1. Identify Required Tools

Ask the user:

"What actions should the agent be able to perform?"
"What external systems will the agent interact with?"
"What parameters does each tool need?"

Example agent: Travel booking

search_flights - Find available flights
book_flight - Reserve a flight
search_hotels - Find hotels
book_hotel - Reserve accommodation

2. Design Tool Schema with `strict: true`

Template:

{
    "name": "tool_name",
    "description": "Clear description of what this tool does",
    "strict": True,  # ← Enables strict mode
    "input_schema": {
        "type": "object",
        "properties": {
            "param_name": {
                "type": "string",
                "description": "Clear parameter description"
            }
        },
        "required": ["param_name"],
        "additionalProperties": False  # ← Required
    }
}

Example: Flight Search Tool

{
    "name": "search_flights",
    "description": "Search for available flights between two cities",
    "strict": True,
    "input_schema": {
        "type": "object",
        "properties": {
            "origin": {
                "type": "string",
                "description": "Departure city (e.g., 'San Francisco, CA')"
            },
            "destination": {
                "type": "string",
                "description": "Arrival city (e.g., 'Paris, France')"
            },
            "departure_date": {
                "type": "string",
                "format": "date",
                "description": "Departure date in YYYY-MM-DD format"
            },
            "return_date": {
                "type": "string",
                "format": "date",
                "description": "Return date in YYYY-MM-DD format (optional)"
            },
            "travelers": {
                "type": "integer",
                "enum": [1, 2, 3, 4, 5, 6],
                "description": "Number of travelers"
            },
            "class": {
                "type": "string",
                "enum": ["economy", "premium", "business", "first"],
                "description": "Flight class preference"
            }
        },
        "required": ["origin", "destination", "departure_date", "travelers"],
        "additionalProperties": False
    }
}

3. Apply JSON Schema Limitations

✅ Supported:

All basic types (object, array, string, integer, number, boolean)
enum for constrained values
format for strings (date, email, uri, uuid, etc.)
Nested objects and arrays
required fields
additionalProperties: false (required!)

❌ NOT Supported:

Recursive schemas
Numerical constraints (minimum, maximum)
String length constraints
Complex regex patterns

4. Add Clear Descriptions

Good descriptions help Claude:

Understand when to call the tool
Know what values to provide
Format parameters correctly

# ✅ Good: Clear and specific
"origin": {
    "type": "string",
    "description": "Departure city and state/country (e.g., 'San Francisco, CA')"
}

# ❌ Vague: Not helpful
"origin": {
    "type": "string",
    "description": "Origin"
}

Output

Well-designed tool schemas ready for implementation.

3.3 KiB Raw Permalink Blame History