Designing Tools

Tools should be narrow, explicit, and predictable. During a live call, each tool adds latency, so keep the contract focused on the minimum action needed.

Good tool names

Use action-oriented names:

• check_availability
• create_booking
• lookup_customer
• cancel_appointment

Avoid broad names like handle_request or database_query.

Parameters

Use JSON Schema object parameters with clear required fields.

{
  "type": "object",
  "properties": {
    "customer_phone": {
      "type": "string",
      "description": "Caller phone number in E.164 format."
    },
    "date": {
      "type": "string",
      "description": "Requested date as YYYY-MM-DD."
    }
  },
  "required": ["customer_phone", "date"]
}

Responses

Return concise JSON. The model does not need internal database fields unless they affect the conversation.

{
  "status": "available",
  "message": "There are openings at 15:00 and 16:30."
}

Failure cases

Prefer explicit errors that the model can recover from.

{
  "error": {
    "code": "customer_not_found",
    "message": "No customer exists for that phone number."
  }
}