Tool parameters

A tool takes values from three different places, and the difference matters for security as much as correctness.

dynamic

The model fills these in from the conversation. Untrusted input.

static

Never seen by the model. Sent on every invocation.

automatic

Filled by the platform. The live call’s ID, for instance.

Choosing the right map

The rule of thumb: does this value describe what the caller wants, or who is asking?

{
  "dynamicParameters": {
    "date":     { "location": "body", "required": true,
                  "schema": { "type": "string", "description": "Appointment date as YYYY-MM-DD" } }
  },
  "staticParameters": {
    "clinicId": { "location": "body", "value": "northside-01" }
  },
  "automaticParameters": {
    "callId":   { "location": "body", "knownValue": "KNOWN_PARAM_CALL_ID" }
  }
}

clinicId is static deliberately. If it were dynamic, a caller could talk the agent into booking at a different clinic. Anything identifying who is asking — tenant IDs, account scoping, API versions, feature flags — belongs in staticParameters, where the model can neither see nor invent it.

A parameter name may appear in only one of the three maps. Reusing a name across two is rejected with 400, because which value wins would be ambiguous.

Dynamic parameters

{
  "orderId": {
    "location": "path",
    "required": true,
    "schema": {
      "type": "string",
      "description": "The customer's order number, usually eight digits"
    }
  }
}

enum

required

string, number, boolean, object, or array.

string

Written for the model, not for a developer. “The customer’s order number, usually eight digits” beats “order identifier” — it lets the agent notice when a caller has misread six digits and ask them to repeat.

string[]

Constrain to a fixed set. Better than describing the options in prose, because the model cannot drift outside it.

Validate every dynamic parameter server-side. These values came from speech recognition — treat them exactly as you would input typed by an anonymous user.

Static parameters

Constant values attached to every invocation and never exposed to the model.

{ "apiVersion": { "location": "header", "value": "2026-08-01" } }

value accepts any JSON — string, number, object, array.

Automatic parameters

Filled by the platform at call time.

{ "callId": { "location": "body", "knownValue": "KNOWN_PARAM_CALL_ID" } }

KNOWN_PARAM_CALL_ID is what makes long-running tools possible — your worker learns which live call to post a result back into.

Where the value goes

HTTP tools need a location on every parameter. Both the short and canonical long forms are accepted; the long form is what reaches the runtime.

Location	Canonical	Best for
`header`	`PARAMETER_LOCATION_HEADER`	API keys, content types, metadata
`query`	`PARAMETER_LOCATION_QUERY`	Filters, search terms, optional values
`path`	`PARAMETER_LOCATION_PATH`	Resource IDs, via `{placeholders}` in the URL
`body`	`PARAMETER_LOCATION_BODY`	Structured data, several related values

Path parameters must match a placeholder in baseUrlPattern:

https://api.yourcompany.com/orders/{orderId}

Client tool parameters have no location — nothing is being placed into an HTTP request. Declare schema and required only.

Get started

Core concepts

Tools

Telephony

Apps & SDKs

Guides

Examples

Speech to text

Help

dynamic

static

automatic

Choosing the right map

Dynamic parameters

Static parameters

Automatic parameters

Where the value goes

dynamic

static

automatic

​Choosing the right map

​Dynamic parameters

​Static parameters

​Automatic parameters

​Where the value goes

Choosing the right map

Dynamic parameters

Static parameters

Automatic parameters

Where the value goes