lookup_caller

The lookup_caller tool lets agents query an organization’s external client database to retrieve caller details during a live phone call. The caller’s phone number is injected automatically from the call context — the AI model doesn’t provide any parameters.

When It’s Registered

The tool is registered at session start only if the organization has a non-empty client_lookup_url configured. If the URL isn’t set, the tool doesn’t exist.

Tool Definition

{
  "name": "lookup_caller",
  "description": "Retrieves information about the person currently on the call
    from the client database. Use this tool to check whether the caller is an
    existing client and to obtain their details (name, procedures, payments,
    dates, etc.). No parameters are needed — the caller's phone number is
    provided automatically.",
  "parameters": {
    "type": "object",
    "properties": {},
    "required": []
  }
}

Empty parameters — the model calls this tool with no arguments.

Execution Flow

Model calls lookup_caller({})
  → Fetch org's client_lookup_url and client_lookup_auth from DB
  → HTTP GET {client_lookup_url}?phone={url_encoded_phone}
      Header: loquent_x_check: {client_lookup_auth}
  → Return response body as-is to the realtime model
  → Model interprets the data and speaks relevant info to caller

HTTP Request

GET https://api.example.com/clients?phone=%2B15551234567
loquent_x_check: secret-auth-token

Component	Source
URL	organization.client_lookup_url
phone query param	Caller’s number from Twilio call context (URL-encoded)
loquent_x_check header	organization.client_lookup_auth (omitted if empty)

The response body is returned as-is to the AI model. The external API controls what data the agent sees — typically client name, account details, appointment history, or a “not found” response.

Note

The phone number comes from the Twilio call context, not from the AI model. The model cannot look up arbitrary phone numbers — only the current caller’s.

Organization Configuration

Two fields on the organization record control this tool:

Field	Description
client_lookup_url	Base URL for the lookup API (required for tool to register)
client_lookup_auth	Auth token sent as loquent_x_check header (optional)

Implementing the External API

Your lookup endpoint should:

1. Accept a phone query parameter (URL-encoded E.164 format, e.g. %2B15551234567)
2. Optionally validate the loquent_x_check header for authentication
3. Return client information as a text or JSON response
4. Return a clear “not found” response for unknown numbers

The AI model receives the raw response body, so format it in a way that’s easy for the model to interpret and relay verbally.

Error Handling

• No client_lookup_url configured → tool not registered (never called)
• HTTP request fails → error logged, error string returned to model
• External API returns error → raw response returned to model as-is

Related Pages

• Agent Tools Overview — voice and task tool systems
• Agent — agent session setup and tool collection