Skip to navigation
API ReferenceAgent Tools

Create an agent tool

View as Markdown

Registers a webhook tool that the agent’s language model may call during conversations, on voice calls and text channels alike. The model decides when to call it from name and description, so write the description as an instruction: what the tool does and when to use it.

The request is processed in this order: the agent must exist and be fully provisioned at the voice provider (else 409 AGENT_PROVISIONING, with Retry-After: 5); url and authConfig.tokenUrl are resolved through DNS and must point to a public address; the name must be unique on the agent (case-insensitive); the agent must have fewer than 50 tools. The tool is then stored and the agent’s complete tool list is pushed to the provider.

Side effects. Updates the agent in the voice engine (the agent’s system tools such as end_call are preserved). If the push fails the new tool is rolled back and the request answers 500; nothing is left stored. authConfig is encrypted at rest. The mutation is written to the audit log.

Idempotency. No Idempotency-Key support, but a retry cannot create a duplicate: if the first attempt succeeded, the retry answers 409 TOOL_NAME_CONFLICT. Confirm with GET /api/agents/{agentId}/tools.

Webhook events. audit.log_recorded for endpoints subscribed to it. See Webhooks.

Access

  • Required scope: write.
  • Rate limit: Configuration mutations — 10 requests/min per workspace, shared with other agent configuration writes, in addition to the General API limit. See Rate limits.
  • Plan: Available on every plan.

Authentication

AuthorizationBearer

Workspace API key: jl_ followed by 64 lowercase hex characters, created by the workspace owner in the dashboard (Settings → API Keys) and sent as Authorization: Bearer jl_.... The plaintext is shown once, at creation; Jelliu stores only a SHA-256 hash. A workspace can hold up to 25 active keys.

ScopeGET / HEADPOST / PUT / PATCH / DELETEAdmin-only routes
readYesNoNo
writeYesYesNo
fullYesYesYes

Operations restricted to admins or owners reject keys without the full scope with 403, and say so in their description. No key, whatever its scope, can mint or revoke API keys or rotate a webhook secret — that requires a signed-in owner session. A revoked key stops authenticating within about 10 seconds. See Authentication.

Path parameters

agentIdstringRequiredformat: "uuid"
UUID of the agent that will own the tool.

Request

This endpoint expects an object.
namestringRequiredformat: "^[a-z][a-z0-9_]*$"1-100 characters

Function name the model sees. Lowercase letters, digits and underscores, starting with a letter. Unique per agent, compared case-insensitively (409 TOOL_NAME_CONFLICT otherwise).

descriptionstringRequired5-2000 characters
What the tool does and when to use it. The model relies on this text alone to decide whether to call the tool, so be explicit about the trigger and the limits.
urlstringRequiredformat: "uri"<=2000 characters

Endpoint the provider calls, http or https. May contain {identifier} placeholders filled from pathParams. Must not target private, loopback or reserved addresses: the syntax is checked by validation and the hostname is also resolved through DNS (400 when it resolves to a private IP).

typeenumOptionalDefaults to webhook

Tool kind. Only webhook exists: the provider calls your HTTP endpoint.

Allowed values:
methodenumOptionalDefaults to GET

HTTP method of the request. bodyParams are only sent with POST, PUT and PATCH; with GET and DELETE they are stored but ignored.

Allowed values:
headerslist of objectsOptionalDefaults to []

Request headers. Only entries with value_type: fixed and a non-empty fixed_value are sent; llm_prompt headers are ignored. Header values are returned by the read endpoints, so treat them as visible to anyone with read access.

pathParamslist of objectsOptionalDefaults to []

Values substituted into the matching {identifier} placeholders of url.

queryParamslist of objectsOptionalDefaults to []

Query-string parameters. Model-filled ones are required unless required is false.

bodyParamslist of objectsOptionalDefaults to []

Top-level properties of the JSON request body (POST, PUT and PATCH only).

authTypeenumOptionalDefaults to none

Declared authentication scheme, stored with authConfig. These two fields are not currently part of the configuration pushed to the voice provider, so they do not authenticate live calls today; send credentials as a fixed header instead.

authConfigobjectOptional

Credentials matching authType. Encrypted at rest (AES-256-GCM, bound to the workspace), never returned by any endpoint and excluded from agent version snapshots. On update the whole object is replaced, and blank strings count as absent. Not currently part of the configuration pushed to the voice provider.

responseTimeoutSecsintegerOptional1-120Defaults to 20
Seconds the provider waits for your response before telling the model the tool failed.
toolCallSoundenumOptional
Sound played on voice calls while the request is in flight. Omit for silence.
Allowed values:
toolCallSoundBehaviorenumOptionalDefaults to auto

When toolCallSound plays.

Allowed values:
dynamicVariableAssignmentslist of objectsOptionalDefaults to []
Values to copy from the tool's JSON response into conversation dynamic variables. Stored and returned, but not currently included in the configuration pushed to the provider, so they have no effect on live conversations today.
positionintegerOptional>=0Defaults to 0

Sort key. Tools are listed and pushed by position, then by creation time.

Response

Tool created and live at the voice provider.
dataobject

A webhook tool as returned by the API. Keys are snake_case (the request bodies use camelCase). auth_config is never returned.

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
404
Not Found Error
409
Conflict Error
429
Too Many Requests Error
500
Internal Server Error