Skip to main content

Tools

Capabilities an agent can call — an HTTP endpoint, an MCP server, your own client, or a pipeline of the three.

Overview​

A tool is what an agent calls out to. It is registered per project and attached to an agent through its tool_bindings — by reference, or inline for a one-off. Gate a tool with guardrails binds an http tool by reference.

typeWhat it calls
httpAn HTTP endpoint you name, with placeholders, headers and a body mode.
mcpAn MCP server, optionally scoped to an allowlist of its tools.
clientNothing server-side: the run pauses and your code supplies the result.
pipelineAn ordered sequence of other tools, wiring each step's input from earlier results.
builtinOperations of this API, in the tool's own project — see builtin tools.

This module is a verbatim mirror of the runtime: every field, method, status code and error shape is the runtime's own, re-rooted under the project in the path.

See the OpenAPI spec for the full endpoint and schema reference, or browse it rendered under API Reference → Tools.

Data Model​

Tool​

FieldTypeDescription
idstringPublic ID of the tool
project_idstringPublic ID of the owning project
namestringTool name
typehttp | client | mcp | builtin | pipelineTool type
descriptionstring, nullableWhat the tool does (sent to the model)
parametersobject, nullableJSON Schema for tool input. On http and pipeline tools every call's input, preset_parameters merged in, must satisfy it: otherwise the call is 400 VALIDATION_FAILED before any guardrail or dispatch. mcp actions declare their own on the server.
executeobject, nullableExecution config for http tools. Supported fields: url (required), method (default POST), headers, body_mode and response_mode. The url may contain {paramName} placeholders (e.g. /users/{userId}) that are replaced at call time with the corresponding tool argument value (URL-encoded). Arguments consumed as path parameters are excluded from the query string and request body. body_mode is json (default) or multipart. In multipart mode the merged tool arguments are sent as a multipart/form-data body: scalar fields become plain form fields and a field shaped like { content_type, filename, data_base64 } is decoded from base64 and attached as a file part (the hardcoded Content-Type: application/json is dropped so fetch sets the multipart boundary itself). response_mode is json (default: the body parsed as JSON, else returned as text) or base64, which returns a 2xx body as { content_type, filename, data_base64 } — the same file shape multipart accepts, so a pipeline step can relay a downloaded file. filename comes from Content-Disposition and is omitted when the target names none. In either mode a 2xx body over TOOL_RESPONSE_MAX_BYTES is 502 TOOL_RESPONSE_TOO_LARGE; a non-2xx body over it is cut to it. auth adds a computed request credential, for targets whose Authorization value cannot be expressed as a static header. Supported auth.type values: - aws_sigv4 — signs the request with AWS Signature Version 4. Requires region, service, access_key_id and secret_access_key; session_token is optional (temporary credentials). Incompatible with body_mode: multipart, whose body bytes are not known at signing time. - gcp_service_account — mints a Google OAuth 2.0 access token from a signed service account assertion and sends it as a bearer token. Requires credentials (the service account key file JSON, as a string) and scopes (a non-empty array). Tokens are cached per service account and scope set until shortly before they expire. - oauth_connection — sends the access token of the OAuth connection the turn's actor holds through oauth_client_id, refreshing it when it expires. The call is refused unless both the caller and the agent's policy_ids allow oauth-connections:UseOauthConnection on the connection. With no actor it fails with TOOL_AUTH_FAILED; for an actor holding no connected connection, 409 OAUTH_CONNECTION_REQUIRED naming how to reconnect. Credential fields accept {{secret:...}} references and should use them — a tool is readable by anyone who can GET /tools, and the stored reference is what is echoed back, never the resolved value. A credential slot takes a reference, never a literal: a literal secret_access_key, session_token or credentials under auth, a literal credential-named headers value (Authorization, Cookie, or a name containing api-key/token/secret/password), or a url carrying a password or a literal credential-named query parameter (those names, plus key and sig/signature) is refused with 400 LITERAL_CREDENTIAL, meta.paths naming each one. A stored literal reads back as {"no_echo": true} (a url holding one is masked whole), an object rather than a string so a read-edit-write round trip fails the schema check instead of writing the placeholder in as the credential. A value carrying a {{secret:...}} reference is the wiring, not the credential, and stays readable. headers values additionally accept {{context:<key>}} references, resolved per call from the caller's tool_context, so a per-user credential can be placed in the real header the target expects (Authorization: Bearer {{context:ocaToken}}) instead of only in a prefixed context header. Valid only inside headers — a context value is caller-supplied, so it may not steer the url — and a key missing from the tool_context at call time fails the tool call with MISSING_TOOL_CONTEXT_KEY rather than sending an empty credential. See the Tool Context reference.
mcpobject, nullableMCP server config (url, headers). headers values accept {{secret:...}} and {{context:<key>}} references, resolved right before the outbound MCP request; url accepts {{secret:...}} only. A literal credential in headers or url is refused, exactly as in execute. pin_definitions: true pins each action's definition; see mcp_pins.
mcp_pinsobject, nullableFor an mcp tool with mcp.pin_definitions: the SHA-256 digest of each action's definition, written once by the first listing an agent turn makes (a deferred server's tools as each is first described). An action whose live definition differs, or that has no pin, is withheld from the model. null until pinned; PATCH with mcp_pins: null or a new mcp.url clears it, and the next listing pins again.
actionsstring[], nullableAllowlist of actions to expose. For builtin tools: action names (required). For mcp tools: an optional allowlist of MCP tool names — when set, only those tools are exposed to the model and callable via /call; when null, the entire MCP server surface is exposed. Ignored for other tool types.
denied_actionsstring[], nullableFor mcp tools: an optional denylist of MCP tool names to hide. Applied after actions and taking precedence over it — a name in both lists is denied. This is the ergonomic way to scope a read+write MCP server read-only: deny just the write tools instead of enumerating every read tool in actions. Names not listed are exposed. null (default) denies nothing. Ignored for other tool types.
context_keysstring[], nullableOptional allowlist of tool_context keys that may be forwarded to this tool as prefixed context headers (X-Naturali-Context-<key> by default). When null, every key in the caller's tool_context is forwarded. When set, only the listed keys are, so a per-user credential in tool_context can be confined to the tools that need it; [] forwards none. The server-pinned identity keys (session_id, actor_id, actor_external_id) are always forwarded. A key consumed by a {{context:<key>}} token in this tool's own headers is substituted regardless of this list — the tool declared that header itself.
preset_parametersobject, nullableFixed parameters pinned on every call this tool makes, whatever its type. Keys matching fields in the input schema are removed from the schema shown to the model, and a pinned value wins over one the model or a direct caller supplies for the same key. On an mcp tool a preset reaches each action whose input schema declares it; an action whose schema declares no properties receives every one. Values accept {{context:<key>}} references, resolved per call from the caller's tool_context, so a pin can be the run's own value — the one account this run may act on — rather than one fixed when the tool was created. A resolved value is retyped to the parameter's declared schema type; a key missing from the call's tool_context fails the call with MISSING_TOOL_CONTEXT_KEY rather than sending the literal placeholder. {{secret:...}} is not resolved here. See the Tool Context reference.
pipelineobject, nullablePipeline definition for pipeline tools: an ordered steps array, each step invoking a tool (optional action) and building its input from earlier results via JSON Logic evaluated over { input, steps }. A step references its tool either by tool_id (an existing, persisted tool) or by an inline tool definition — the same shape as CreateToolRequest minus project_id — executed directly without a Tool row, but never both. An inline step tool cannot itself be of type pipeline. An optional output maps the final result; steps may be empty when output is set, which computes output over the input alone. A literal credential in an inline step tool is refused, exactly as in execute.
output_mappingobject, nullableUniversal JSON Logic mapping applied to the tool's raw result, for every tool type (http, mcp, builtin, pipeline, client). Evaluated over { output: <raw result>, input: <merged input>, action: <action> }, so { "var": "output.text" } extracts a bare scalar field instead of requiring a wrapping pipeline tool, { "var": "input.title" } echoes back a field of the request that produced the response, and { "var": "action" } reads the mcp or builtin action that ran (null on other types). For pipeline tools this runs after the pipeline's own output mapping, over that mapping's result.
guardrail_idsstring[], nullableGuardrails attached at the tool scope, governing this tool wherever it is used, by any agent.
trusted_outputbooleanWhether this tool's results are content no attacker can write. A result from a tool with false (the default) counts toward runtime.generations.untrusted_tool_results.total when it enters a generation's context; a search-knowledge or get-document result from a builtin tool counts toward runtime.generations.knowledge_results.total either way.
created_atstring (date-time)
updated_atstring (date-time)

type defaults to http; any other value is 400, on an inline definition in an agent too. actions is also the set of operations a builtin tool may run — see Tool actions.

Key Concepts​

Secrets and per-call context in headers​

A tool's own headers — on execute for http, on mcp for MCP — accept two kinds of reference, resolved at call time rather than stored resolved: {{secret:<id>}} pulls a secret, and {{context:<key>}} pulls a value from the call's tool_context. A static credential belongs in the first; a per-user one in the second. A credential written as a literal is refused with 400 LITERAL_CREDENTIAL, and one stored earlier reads back as {"no_echo": true}.

Writing a {{secret:<id>}} reference into execute, mcp or a pipeline step needs the right to use that secret. A key narrowed by capabilities has it with tools:CreateTool or tools:UpdateTool; without it the write answers 403.

Per-call context in preset_parameters​

{{context:<key>}} also resolves inside preset_parameters values, not just headers — so a pin can be the caller's own value instead of one fixed when the tool was created. This is how a tool pins a parameter to "the one account this run may act on" rather than a value baked in at write time:

{ "preset_parameters": { "account_id": "{{context:accountId}}" } }

The resolved value is retyped to the parameter's declared schema type — a tool_context entry is always a string, but a parameter typed integer gets an integer. A key missing from the call's tool_context fails the call with MISSING_TOOL_CONTEXT_KEY, the same fail-closed behavior as a missing header reference, rather than sending the literal placeholder through.

{{secret:<id>}} is not resolved in preset_parameters — only in headers. A secret belongs in a header a tool's own endpoint reads, never in a parameter value the model or the tool call log can see.

Per-user credentials reach a tool as a header​

A tool endpoint often needs to act as the person the run is for, not as the project: one user's calendar, one user's orders, one user's account on a third-party API. Putting that credential in the tool's own headers cannot express it — those headers are fixed at write time and shared by every call.

The credential travels per call instead, in the tool_context a caller attaches when it starts work. The runtime forwards each entry as a request header on every http/mcp tool call the agents make, named X-Naturali-Context- followed by your key verbatim:

X-Naturali-Context-ocaToken: usr_token_V1StGXR8Z5jdHi6B

Two properties are worth reading twice. The key is appended verbatim — no character is re-cased and no separator is inserted, so ocaToken and oca_token are two different keys producing two different headers. And the prefix is always applied: a caller cannot name an arbitrary header, which is what stops caller-supplied data from overwriting a credential the tool configured for itself.

Keys starting with naturali_, in any case, are set by the platform only, so a tool can trust them. A tool_context, or a loop node's item_tool_context, naming one is 400 INVALID_TOOL_CONTEXT_KEY, with meta.keys naming the keys, on every path that writes one: a route that takes one, a builtin tool call in a generation, and a formation's validate, plan and deploy. The one exception is the root tool_context of a tool call (POST /v1/projects/{project_id}/tools/{tool_id}/call), including the one a call-tool action passes to the tool it calls: there such a key is dropped, and the platform's own keys, when the call has any, are sent in its place.

Read the header case-insensitively. HTTP field names are case-insensitive and HTTP/2 sends them lowercased, so your endpoint will usually see x-naturali-context-ocatoken however you spelled the key:

// Node / Express / Koa — incoming header names are lowercased for you
const ocaToken = req.headers['x-naturali-context-ocatoken'];

Landing the value in Authorization​

Most targets want the credential in the header they already use, not in a prefixed one. The tool says so, with a {{context:<key>}} reference in its own headers — the tool knows the header shape its endpoint expects, and the caller only supplies the value:

Authorization: 'Bearer {{context:ocaToken}}'

A reference is legal in headers and nowhere else, url included: a context value comes from the caller, so it must never steer the outbound request. If the key is missing from the tool_context at call time the tool call fails, rather than sending Bearer with nothing after it and coming back as an opaque 401 several steps from the mistake.

Confine it with context_keys​

By default every key in the bag goes to every tool the agent can call, including endpoints you do not control. context_keys is the allowlist that stops that: set it to the keys a tool legitimately needs, and a credential meant for one endpoint stops egressing to the rest of the tool set. [] forwards none, and null (the default) forwards all.

A key the tool consumes through a {{context:...}} reference in its own headers is substituted either way — the tool declared that header itself.

Create such a tool — a per-user credential in Authorization, and nothing else in the bag reaching it:

naturali create-tool \
--project-id proj_V1StGXR8Z5jdHi6B \
--name oca \
--type mcp \
--mcp '{"url":"https://mcp.example.com/sse","headers":{"Authorization":"Bearer {{context:ocaToken}}"}}' \
--context-keys ocaToken

Then supply the value when you start the work: tool_context is a field on a session (forwarded on every call in that session), on a single agent generation, on a direct call-tool request, and — write-only — on an eval run and on a trigger, which is what puts an agent built this way on a schedule: a firing has no caller to carry a credential, so the trigger holds the bag, and a {{secret:...}} reference in it keeps the value in the secret store.

The headers are worth trusting only if the endpoint also authenticates the request as coming from your naturali deployment — a shared secret in the tool's own headers, mTLS, or a network restriction. Anyone who can reach the endpoint can set an X-Naturali-Context-* header by hand.

When a tool does not resolve​

An mcp binding is resolved at the start of every turn by listing the server's tools. When that listing does not arrive — the server unreachable or refusing the credential, a {{secret:…}} in the URL or headers that does not resolve — or arrives and leaves nothing to attach, the binding is dropped and the turn runs without it. One flaky server does not take an agent down.

The generation still completes, carrying no error. The model is told which of its tools are unavailable for the turn, and instructed to say so plainly rather than claim it lacks the capability — but it is not told why. The reason is operator-grade and would become text the model may repeat to an end user, so it goes to the activity feed instead. An expired token therefore reads to your end user as a data source that could not be reached, not as a product limitation, and not as a cause the model guessed at.

The record is an activity entry of kind tool_resolution_failed, severity warning, naming the binding, the reason and the generation. Nothing else reports it: poll or alert on ?kind=tool_resolution_failed.

An actions allowlist that excludes every tool the server returns drops the binding too, and says so in detail.reason — a binding that legitimately matches nothing is indistinguishable from a broken one until you read it.

Zero tool calls is not proof a restriction held​

A generation that completes without calling a tool looks identical whether actions withheld the tool or the credential behind it was dead. Asking the agent for the forbidden thing and watching it decline does not tell the two apart. The activity feed does: an entry for that binding means it was dropped, and the refusal you observed says nothing about the allowlist. No entry means the binding attached what the allowlist leaves, and the model had those tools to call.

Pinning MCP definitions​

An action's description and inputSchema reach the model as the server sends them on every turn. mcp.pin_definitions: true pins each action's definition on the first listing an agent turn makes, recording a SHA-256 digest per action in mcp_pins. Later, an action whose definition differs from its pin, or that has none, is withheld from the turn as an unavailable tool, and files an mcp_definition_drift exception; the other actions keep working.

To accept the changed definitions, PATCH /v1/projects/{project_id}/tools/{tool_id} with "mcp_pins": null: the next listing pins again. A new mcp.url clears the pins too. A direct call, a pipeline step and the action listing show no definition to a model and are not gated.

builtin tools call this API​

A builtin tool lets an agent run operations of this API — open a playbook case, read it back, add a document — in the tool's own project. actions names them, from Tool actions, and is required. Create one:

naturali create-tool \
--project-id proj_V1StGXR8Z5jdHi6B \
--name cases \
--type builtin \
--actions create-playbook-case \
--actions get-playbook-case

The agent sees each action as {name}_{action} — cases_create-playbook-case here — so an agent's tool_choice, stop_conditions and step_rules name it that way. A direct POST /v1/projects/{project_id}/tools/{tool_id}/call names the action alone in action. Without a body action, an action in input or preset_parameters selects the action and is not sent to it. With one, an input action reaches only an action that declares one: a tool binding call-tool takes { "action": "call-tool", "input": { "action": "list-agents" } } and runs its target's list-agents.

RuleBehavior
actionsRequired, each one of the Tool actions. An action of a module this API does not serve, a write of an AI provider (project configuration), or any other name, is 400.
Writer holds the actionsA create, or an edit setting actions, needs a credential that may perform each action itself: a narrowed key lacking agents:DeleteAgent is refused a delete-agent tool with 403 ACTION_NOT_HELD, meta naming the action and resource. The same holds for a template's tool resource, whether actions is a literal or an expression.
Runs as the callerEach call runs as the credential that started the generation (the capabilities of its key, a trigger's policy_ids), within the agent's policy_ids; an action outside them is a tool error. An agent with run_as: agent runs it under its policy_ids alone (Execution identity). The call itself needs tools:CallTool.
preset_parametersPinned on each action whose input takes the parameter. A value may be {{context:<key>}}, resolved per call from the caller's tool_context, which confines the tool to the run's own case or actor (Per-call context in preset_parameters).
Operations of this API's ownAn action listed under Added by naturali on Tool actions runs on naturali's MCP server, with the same rules.
Exposed by an MCP serverAn MCP server binding the tool lets its caller do exactly what the tool's actions perform on the resources its presets pin.

Confining a builtin tool to one playbook case​

An agent serving several people (a channel, say) reaches every case of the project through a plain builtin tool. To confine it to one case, pin case_id to the run's value and list only actions that take a case:

naturali create-tool \
--project-id proj_V1StGXR8Z5jdHi6B \
--name this-case \
--type builtin \
--actions get-playbook-case \
--actions get-playbook-case-missing \
--actions write-playbook-case-inputs \
--actions confirm-playbook-case-node \
--actions run-playbook-case-node \
--preset-parameters '{ "case_id": "{{context:case_id}}" }'

Your application creates the case for the person and sends its id as tool_context.case_id on the generation or session. The model never sees case_id, cannot override it, and a turn without it fails the call with MISSING_TOOL_CONTEXT_KEY (per-call context). A preset reaches only the actions that take it, so list actions that read one case: an action without case_id, such as list-playbook-cases, would reach every case.

write-playbook-case-inputs, confirm-playbook-case-node and upgrade-playbook-case take wait: true, which answers once the nodes the write starts have settled, so the agent reads the result in the same turn (playbooks).

Confining a builtin tool to one end user's cases​

To let an agent find, create and fill the cases of the person it serves, pin actor_id to the run's actor. A case of another actor answers 404, and list-playbook-cases returns only this actor's.

naturali create-tool \
--project-id proj_V1StGXR8Z5jdHi6B \
--name my-cases \
--type builtin \
--actions list-playbook-cases \
--actions create-playbook-case \
--actions get-playbook-case \
--actions write-playbook-case-inputs \
--preset-parameters '{ "actor_id": "{{context:actor_id}}" }'

A turn that ran in a session carries actor_id, so a channel turn needs no tool_context. Without an actor the call fails with MISSING_TOOL_CONTEXT_KEY. The agent finds a case by subject and creates it when absent; the WhatsApp pattern shows the whole flow.

Narrowing what a builtin tool's callers send​

A builtin tool takes its action's whole input, minus its presets: create-agent-generation takes every message form, document included. To let a caller send only what you choose, wrap the tool in a pipeline whose parameters say what callers send and whose step maps it onto the action:

naturali create-tool \
--project-id proj_V1StGXR8Z5jdHi6B \
--name ask-coach \
--type pipeline \
--parameters '{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}' \
--pipeline '{"steps":[{"id":"ask","tool_id":"tool_V1StGXR8Z5jdHi6B","action":"create-agent-generation","input":{"messages":[{"role":"user","content":{"var":"input.message"}}]}}]}'

tool_V1StGXR8Z5jdHi6B is the builtin tool, whose presets pin the agent. An agent bound to the pipeline, or an MCP server serving it, shows only message. A call whose input fails parameters, such as { "message": { "type": "document" } }, is 400 before any guardrail or step runs. The same holds in a template: declare both as tool resources, the step's tool_id a { "ref": … }.

Trusted output​

trusted_output: false (the default, every type) marks a tool's results as content an attacker could write. Each one that enters a generation's context counts toward runtime.generations.untrusted_tool_results.total, which a guardrail reads to require sign-off on a write once the turn has read such content (What the turn has read). It changes nothing until a guardrail reads the key.

  • Declared once, on the tool. A tool mixing trusted and attacker-writable actions is split into two tools with different actions.
  • Knowledge reads count as knowledge. A search-knowledge or get-document result of a builtin tool counts toward runtime.generations.knowledge_results.total whatever the flag says.
  • Setting true needs guardrails:DetachGuardrail besides the write's own permission, on a stored tool, an agent's inline tool_bindings definition and a formation resource: it loosens every guardrail reading the key. Without it the write is 403 ACTION_NOT_HELD.

Calling a tool needs tools:CallTool​

An agent's call to an http, mcp or pipeline tool needs tools:CallTool on the tool for the identity the agent runs as: its caller capped by its policy_ids under run_as: caller, its policy_ids alone under run_as: agent (Execution identity). Each step of a pipeline that names a stored tool needs it too, under the authority the pipeline runs under. A refused call runs nothing and reaches the model as a FORBIDDEN tool result whose meta.action is tools:CallTool.

Calling a tool directly​

POST /v1/projects/{project_id}/tools/{tool_id}/call invokes a tool without an agent — the fastest way to check that a tool's URL, headers and mapping are right before binding it. http, mcp and pipeline tools are supported; a client tool answers 422, because there is no agent run to pause and nobody to hand the call to. For an mcp tool, action names the MCP tool to invoke, and an action outside the tool's actions allowlist is rejected before any outbound request is made. It is also what tells a broken tool from a model calling a working one badly — see Debug a failed run.

The request body also takes its own tool_context, narrowed by the tool's context_keys allowlist like any other caller — there is no session or generation behind this call, so session_id, actor_id and actor_external_id are dropped from the bag rather than forwarded.

actor_id in the body runs the call for that actor of the project, as a session for the actor would: the tool receives actor_id and actor_external_id, and an oauth_connection credential is the actor's connection. An actor outside the project answers 400 ACTOR_NOT_FOUND.

A direct call is a run, like every tool call (Runs and the allowance). On Free, once the account has used its runs for the month, it answers 403 PLAN_LIMIT_REACHED with resource: "runs" and calls nothing. A negative credit balance does not refuse it: a tool call spends no credit. Not in the generated spec. This holds however the call arrives: a call to this API or an agent's tool call.

client tools pause the run​

A client-type tool has no server-side execution: when the model calls it the generation stops with requires_action and the pending call on it. Your code does the work and posts the result back — to …/agents/{agent_id}/generate/{generation_id}/tool-outputs for a one-shot run, or …/sessions/{session_id}/tool-outputs inside a session — and the run continues from where it stopped. Run tools in your own code walks the pause, the submit and the resumed run.

output_mapping sees the result and the input​

output_mapping's JSON Logic is evaluated over { output: <raw result>, input: <merged input> }, for every tool type. So { "var": "output.text" } extracts a bare scalar instead of returning the whole envelope, and { "var": "input.title" } echoes back a field of the request that produced the response — which is how you carry a value through a call that does not return it. For a pipeline tool it runs after the pipeline's own output mapping, over that mapping's result.

http execution always sends a body, even for GET​

An http tool's resolved parameters are sent as the request body regardless of execute.method. Most servers ignore a body on a GET request, but some reject it outright; if a GET tool call fails against a target that behaves this way, that is usually why — switching the target's own route to accept POST, where one is available, sidesteps it.

Examples​

naturali create-tool \
--project-id proj_V1StGXR8Z5jdHi6B \
--name get-weather \
--type http