Orbitali Docs

Designing Tools

Model callable functions for live phone conversations.

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.

Choose how tools run

Custom tools are available on HTTP and webhook agents. HTTP tools call an endpoint per tool; webhook tools send agent:tool-call events to the agent’s Server URL. Static agents do not support these custom tools. Built-in tools and connected MCP tools are separate.

Follow HTTP agent setup or webhook agent setup, then use the design principles below.

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."
  }
}

On this page