Tools

Call a tool

Directly invokes a tool and returns its output. Supported for http, mcp, and pipeline tools. client tools cannot be invoked server-side and will return 422. A pipeline tool runs its declared steps in order and returns the mapped output (or the last step's output); action is ignored and input is the pipeline input. For mcp tools the action field is required and identifies which tool name to invoke. For http tools action is ignored. When an mcp tool declares an actions allowlist, an action outside it is rejected with 400 VALIDATION_FAILED ("not available on this tool") before any outbound request is made. preset_parameters stored on the tool are pinned over the caller-supplied input before execution: a key the tool presets keeps its preset value even when input sets it. Keys the presets do not name are taken from input as sent. Guardrails attached to the tool or to its project adjudicate the call before dispatch, composing project + tool scope. A call this route cannot await a decision on — class C (human sign-off), class D, or a class-B tripwire — is refused with 422 TOOL_DISPATCH_FAILED, whose meta carries the tool_id and the outcome. A pipeline tool is adjudicated before its first step runs, and every step is adjudicated as the call of that tool it is.

A credential scoped to a project the tool is shared with, through an accepted share, calls it in that project: the calling project's guardrails adjudicate it, it is metered there with publisher_project_id, and the tool receives the calling project as the calling_project_id tool context key.

post/v1/projects/{project_id}/tools/{tool_id}/call

Request

  • Base URL: https://api.naturali.ai
  • URL: https://api.naturali.ai/v1/projects/{project_id}/tools/{tool_id}/call
  • Auth: one of:
    • HTTP bearer
    • OAuth 2 (authorization code, authorization URL https://api.naturali.ai/authorize, token URL https://api.naturali.ai/token, scopes: mcp:access)

Path parameters

tool_idstring required

Request body

actionstring

For mcp tools: the MCP tool name to invoke (must be in the tool's actions allowlist when one is set, and must not be in its denied_actions denylist). Ignored for http tools.

inputobject

Input parameters for the tool call. These are merged with the tool's preset_parameters before execution; a preset value wins over the same key sent here.

tool_contextobject

Key/value context for this call, forwarded to the tool as X-Naturali-Context-<key> request headers and resolving any {{context:<key>}} token in the tool's execute.headers, mcp.headers or preset_parameters. Narrowed by the tool's context_keys allowlist when it sets one. This route has no session, so it stamps no server-derived identity: the reserved keys session_id, actor_id and actor_external_id are dropped from this bag (in any casing) rather than forwarded, so a downstream tool can still trust that a context header naming one is server-derived. Every other key becomes an HTTP header name and must match that grammar, or the call fails with INVALID_TOOL_CONTEXT_KEY.

Example request

{
  "tool_context": {
    "tenantId": "acme",
    "userToken": "tok_abc123"
  }
}

Response

Tool output

unknown required

Changes

No recorded changes to this operation across all 1 revision of this API.