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.
type | What it calls |
|---|---|
http | An HTTP endpoint you name, with placeholders, headers and a body mode. |
mcp | An MCP server, optionally scoped to an allowlist of its tools. |
client | Nothing server-side: the run pauses and your code supplies the result. |
pipeline | An ordered sequence of other tools, wiring each step's input from earlier results. |
builtin | Operations 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
| Field | Type | Description |
|---|---|---|
id | string | Public ID of the tool |
project_id | string | Public ID of the owning project |
name | string | Tool name |
type | http | client | mcp | builtin | pipeline | Tool type |
description | string, nullable | What the tool does (sent to the model) |
parameters | object, nullable | JSON 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. |
execute | object, nullable | Execution 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. |
mcp | object, nullable | MCP 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_pins | object, nullable | For 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. |
actions | string[], nullable | Allowlist 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_actions | string[], nullable | For 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_keys | string[], nullable | Optional 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_parameters | object, nullable | Fixed 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. |
pipeline | object, nullable | Pipeline 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_mapping | object, nullable | Universal 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_ids | string[], nullable | Guardrails attached at the tool scope, governing this tool wherever it is used, by any agent. |
trusted_output | boolean | Whether 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_at | string (date-time) | |
updated_at | string (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:
- CLI
- SDK
- curl
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
const { data: tool } = await naturali.tools.createTool({
path: { project_id: 'proj_V1StGXR8Z5jdHi6B' },
body: {
name: 'oca',
type: 'mcp',
mcp: {
url: 'https://mcp.example.com/sse',
headers: { Authorization: 'Bearer {{context:ocaToken}}' },
},
context_keys: ['ocaToken'],
},
});
curl -X POST https://api.naturali.ai/v1/projects/proj_V1StGXR8Z5jdHi6B/tools \
-H "Authorization: Bearer $NATURALI_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"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:
- CLI
- SDK
- curl
naturali create-tool \
--project-id proj_V1StGXR8Z5jdHi6B \
--name cases \
--type builtin \
--actions create-playbook-case \
--actions get-playbook-case
const { data: tool } = await naturali.tools.createTool({
path: { project_id: 'proj_V1StGXR8Z5jdHi6B' },
body: {
name: 'cases',
type: 'builtin',
actions: ['create-playbook-case', 'get-playbook-case'],
},
});
curl -X POST https://api.naturali.ai/v1/projects/proj_V1StGXR8Z5jdHi6B/tools \
-H "Authorization: Bearer $NATURALI_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "name": "cases", "type": "builtin", "actions": ["create-playbook-case", "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.
| Rule | Behavior |
|---|---|
actions | Required, 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 actions | A 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 caller | Each 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_parameters | Pinned 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 own | An action listed under Added by naturali on Tool actions runs on naturali's MCP server, with the same rules. |
| Exposed by an MCP server | An 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:
- CLI
- SDK
- curl
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}}" }'
const { data: tool } = await naturali.tools.createTool({
path: { project_id: 'proj_V1StGXR8Z5jdHi6B' },
body: {
name: 'this-case',
type: 'builtin',
actions: [
'get-playbook-case',
'get-playbook-case-missing',
'write-playbook-case-inputs',
'confirm-playbook-case-node',
'run-playbook-case-node',
],
preset_parameters: { case_id: '{{context:case_id}}' },
},
});
curl -X POST https://api.naturali.ai/v1/projects/proj_V1StGXR8Z5jdHi6B/tools \
-H "Authorization: Bearer $NATURALI_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "name": "this-case", "type": "builtin", "actions": ["get-playbook-case", "get-playbook-case-missing", "write-playbook-case-inputs", "confirm-playbook-case-node", "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.
- CLI
- SDK
- curl
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}}" }'
const { data: tool } = await naturali.tools.createTool({
path: { project_id: 'proj_V1StGXR8Z5jdHi6B' },
body: {
name: 'my-cases',
type: 'builtin',
actions: [
'list-playbook-cases',
'create-playbook-case',
'get-playbook-case',
'write-playbook-case-inputs',
],
preset_parameters: { actor_id: '{{context:actor_id}}' },
},
});
curl -X POST https://api.naturali.ai/v1/projects/proj_V1StGXR8Z5jdHi6B/tools \
-H "Authorization: Bearer $NATURALI_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "name": "my-cases", "type": "builtin", "actions": ["list-playbook-cases", "create-playbook-case", "get-playbook-case", "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:
- CLI
- SDK
- curl
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"}}]}}]}'
const { data: tool } = await naturali.tools.createTool({
path: { project_id: 'proj_V1StGXR8Z5jdHi6B' },
body: {
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' } }],
},
},
],
},
},
});
curl -X POST https://api.naturali.ai/v1/projects/proj_V1StGXR8Z5jdHi6B/tools \
-H "Authorization: Bearer $NATURALI_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "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-knowledgeorget-documentresult of abuiltintool counts towardruntime.generations.knowledge_results.totalwhatever the flag says. - Setting
trueneedsguardrails:DetachGuardrailbesides the write's own permission, on a stored tool, an agent's inlinetool_bindingsdefinition and a formation resource: it loosens every guardrail reading the key. Without it the write is403 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
- CLI
- SDK
- curl
naturali create-tool \
--project-id proj_V1StGXR8Z5jdHi6B \
--name get-weather \
--type http
const { data: tool } = await naturali.tools.createTool({
path: { project_id: 'proj_V1StGXR8Z5jdHi6B' },
body: { name: 'get-weather', type: 'http' },
});
curl -X POST https://api.naturali.ai/v1/projects/proj_V1StGXR8Z5jdHi6B/tools \
-H "Authorization: Bearer $NATURALI_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "name": "get-weather", "type": "http" }'