Create a tool
Define a tool the agent can invoke. Creating it does not attach it to
anything — use POST /agents/{id}/tools for that, so one tool can serve
many agents.
Authorizations
API key for authentication
Body
type discriminates the shape. HTTP tools additionally require
httpMethod and baseUrlPattern; client tools take neither.
http, client 1 - 100Must start with a letter and contain only letters, numbers, and underscores.
^[a-zA-Z][a-zA-Z0-9_]*$What the model reads to decide whether to call this tool. The most important field on the object — most "my tool never fires" problems are description problems.
Required for http tools.
GET, POST, PUT, PATCH, DELETE Required for http tools. Internal addresses are rejected —
RFC 1918 ranges, loopback, IPv6 ULA, link-local including the
cloud metadata endpoint at 169.254.169.254, and known private DNS
names.
What the agent does when the tool returns.
speaks narrates the result (default). listens stays silent and waits
— right for tools that hand off, like a transfer. speaks-once speaks
only if it did not already speak just before invoking, which prevents
"Checking that for you… here is the result…" double-talk.
speaks, listens, speaks-once Seconds with an s suffix, e.g. "2.5s" or "10s". Must be greater
than 0 and at most 40s. Defaults to 2.5s when unset.
^\d+(\.\d+)?s$"5s"
Declares which credentials the tool needs and how each is sent. The
secret values themselves live in authTokens.
options is a list of acceptable alternatives — satisfying any one
entry is enough, which is how you offer "either an API key or a bearer
token".
Plaintext credential values keyed by credential name, encrypted before storage and never returned.
Every key must be declared in
httpSecurityOptions.options[].requirements, or the request is
rejected. This catches typos like stcokApiKey that would otherwise
persist silently and 401 against your endpoint at call time with
nothing useful in the logs.
The reverse is not required: you may declare two credentials as alternatives and supply only one.
Response
Tool created
A tool the agent can invoke during a call.
The function name the model sees.
http, client HTTP tools only.
GET, POST, PUT, PATCH, DELETE HTTP tools only.
What the agent does when the tool returns.
speaks narrates the result (default). listens stays silent and waits
— right for tools that hand off, like a transfer. speaks-once speaks
only if it did not already speak just before invoking, which prevents
"Checking that for you… here is the result…" double-talk.
speaks, listens, speaks-once Declares which credentials the tool needs and how each is sent. The
secret values themselves live in authTokens.
options is a list of acceptable alternatives — satisfying any one
entry is enough, which is how you offer "either an API key or a bearer
token".
Which credential slots hold a stored value. Credential values are
never returned by this API — this map exists so a UI can render
•••••••• for a set slot and an empty field for an unset one.
Seconds with an s suffix, e.g. "2.5s" or "10s". Must be greater
than 0 and at most 40s. Defaults to 2.5s when unset.
^\d+(\.\d+)?s$"5s"
Attests the tool is side-effect free, letting the runtime run it eagerly while the agent is still speaking and discard the result if the conversation turns elsewhere. Set it only on lookups — never on a booking or a payment.
How many agents this tool is attached to.