126 lines
3.3 KiB
Markdown
126 lines
3.3 KiB
Markdown
# 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:**
|
|
```python
|
|
{
|
|
"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**
|
|
```python
|
|
{
|
|
"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
|
|
|
|
```python
|
|
# ✅ 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.
|