# Execute a governed tool

Call a catalogue tool through the tool gateway, read the one response shape every outcome uses, and resume a call held for approval once a reviewer has decided.

`POST /public/v1/tools/execute` runs a tool from the tenant's catalogue: an MCP server's tool, a hosted or OpenAPI-backed one, or a database tool. On the way the call passes the platform's governance: the emergency deny-list, the guardrail tool rails, the tool policy for that tool and, when the policy says so, a human decision in the Control Room. Every outcome, a refusal included, is a 200 with the same body. Read the fields, not the status.

**Who can use it:** anyone holding an API key with the **Execute tools** scope, which also lists the catalogue. Policies are set by administrators on the Control Room's Policies page; approvals are decided by reviewers with the approve capability.

## Find the tool

`GET /public/v1/tools` returns `tools[]`, each with `name`, `namespacedName` (`mcp_<server>_<tool>`), `description`, `inputSchema`, `mcpName`, `mcpId`, `kind` (`READ` or `WRITE`) with `kindBasis`, `sourceKind` and `riskLevel`, plus `total`, `mcpCount`, `truncated` and `undiscoveredSources` for servers whose tools could not be read. Filter with `mcp_name`, `kind`, `source_kind`, `basis`, `q`, `limit` (up to 1000; left out, everything) and `offset`.

`kind` says whether a tool may change something. When the server declares it, `kindBasis` is `annotation`; otherwise it comes from the HTTP verb of an OpenAPI tool or from the name, erring on the side of `WRITE`. Treat `WRITE` as "may mutate", not as certain.

Name the tool in the call one of three ways:

| Fields | Resolves to |
| --- | --- |
| `mcpId` and `toolName` | That server's tool of that name |
| `toolName` as the namespaced name, `mcp_<server>_<tool>` | The first server matching the middle part |
| `mcpName` and `toolName` | The tool on the server of that name |

A bare `toolName` with neither hint does not resolve and comes back as `error` set to `Tool not found`.

## The request and the response

The body takes `toolName`, `arguments`, `mcpId`, `mcpName`, `sessionId` (groups calls into one MCP session for servers that keep state) and `approvalId`. `tenantId` and `userId` are overwritten from the key.

| Field | Meaning |
| --- | --- |
| `result` | The tool's own result: `content[]` and `isError` |
| `error` | Empty on success. A sentence when the tool failed, was not found, ran out of time, or returned more than the result cap allows |
| `blocked`, `message`, `policyName`, `policiesApplied` | A refusal: by the tool policy (`Blocked by tool policy: <id>`), by the deny-list (`capability:deny_list`) or by a rail (`tool_sql_injection`, `tool_path_traversal`, `tool_command_injection`) |
| `requiresApproval`, `approvalId`, `approvalStatus` | The policy wants a human decision; `approvalStatus` is `pending`, later `consumed` or `denied` |
| `toolName`, `mcpName`, `mcpId`, `latencyMs` | What ran and how long it took |

## Quick start

Run a read tool and branch on the outcome:

**cURL**

```bash
curl -X POST "https://<your tenant host>/public/v1/tools/execute" \
  -H "Authorization: Bearer kapi_..." \
  -H "Content-Type: application/json" \
  -d '{"mcpName": "crm", "toolName": "lookup_account", "arguments": {"account_id": "A-4471"}}'
```

**Python**

```python

BASE = "https://<your tenant host>/public/v1"
HEADERS = {"Authorization": "Bearer kapi_..."}

def run_tool(call):
    r = requests.post(f"{BASE}/tools/execute", headers=HEADERS, json=call)
    r.raise_for_status()                                 # only transport and key errors are non-200
    out = r.json()
    if out.get("blocked"):
        raise PermissionError(f"{out['policyName']}: {out['message']}")
    if out.get("requiresApproval"):
        return {"pending": out["approvalId"], "message": out["message"]}
    if out.get("error"):
        raise RuntimeError(out["error"])
    return out["result"]

call = {"mcpName": "crm", "toolName": "lookup_account", "arguments": {"account_id": "A-4471"}}
outcome = run_tool(call)
if "pending" in outcome:
    print("held for approval:", outcome["pending"])   # resend `call` with approvalId once decided
else:
    print(outcome["content"])
```

**TypeScript**

```typescript
const BASE = "https://<your tenant host>/public/v1";
const headers = { Authorization: "Bearer kapi_...", "Content-Type": "application/json" };

async function runTool(call: Record<string, unknown>) {
  const r = await fetch(`${BASE}/tools/execute`, { method: "POST", headers, body: JSON.stringify(call) });
  if (!r.ok) throw new Error(`${r.status} ${await r.text()}`);   // only transport and key errors are non-200
  const out = await r.json();
  if (out.blocked) throw new Error(`${out.policyName}: ${out.message}`);
  if (out.requiresApproval) return { pending: out.approvalId as string, message: out.message as string };
  if (out.error) throw new Error(out.error);
  return out.result;
}

const call = { mcpName: "crm", toolName: "lookup_account", arguments: { account_id: "A-4471" } };
const outcome = await runTool(call);
if ("pending" in outcome) console.log("held for approval:", outcome.pending);   // resend `call` with approvalId once decided
else console.log(outcome.content);
```

## When approval is required

A policy of `manual` on the tool holds the call. The response carries `requiresApproval` true and an `approvalId`; the request appears on the Control Room's Approvals page, where a reviewer with the approve capability approves or denies it. Nothing notifies the reviewer on the current build, and the queue does not refresh itself. A reviewer cannot decide their own request.

![The Control Room's Approvals page listing pending tool-call requests with their tool, requester and age, and approve and deny controls.](https://docs.katonic.ai/img/developers/cookbooks/govern-a-tool-with-an-approval/dev-cr-approvals.png)
*Approvals in the Control Room: tool calls parked by a policy wait here for a reviewer with the approve capability to approve or deny them.*

To resume, resend the same call, the same tool on the same server with the same `arguments`, with `approvalId` in the body. The approval is spent by that one call and the response comes back executed with `approvalStatus` set to `consumed`. A request that is not decided within 24 hours expires. Calling again with the same arguments while the request is pending returns the same `approvalId` rather than raising a second one.

| You present | What happens |
| --- | --- |
| An id still pending | The same id, and a message that it is still waiting for a reviewer |
| An id already used, expired or unknown | A new pending request is raised; the message says why the old one did not apply |
| An id granted for a different tool, server or arguments | A new pending request for this call |
| A denied id | `blocked` true, `approvalStatus` `denied`, and a message naming who declined and their note |

An approval never bypasses the deny-list, the rails or a `block` policy. Policies are `manual` (hold for approval), `block`, `auto_approve`, or `monitor` (allow and record); a tool with no policy is allowed, and where several match, `manual` wins over `block`, which wins over `monitor`.

![The Control Room's Policies page with a table of rules showing status, action, scope and priority.](https://docs.katonic.ai/img/developers/guides/execute-a-governed-tool/dev-cr-policies.png)
*Policies in the Control Room: each rule with its status, action, scope and priority, with Create Policy to add one.*

## Limits and behaviour

- The tool gateway allows a tool 240 seconds, but the public API gateway waits 60 seconds for the response, so a slower tool answers 504 `UPSTREAM_TIMEOUT` while it keeps running and its result is lost. Keep long tools inside an agent.
- A result over 4 MiB is discarded and replaced by `result.isError` true, `result.error_type` `result_too_large` and the same text in `error`. Request bodies are capped at 10 MiB.
- The tool gateway has its own limit of 600 calls per minute per tenant, answered as 429 with `error` set to `Rate limit exceeded`, `retry_after_seconds` and a `Retry-After` header, in addition to the key's limit.
- The rails are off until a guardrail profile enables them. When the rail check cannot run, the call is blocked, not allowed, with `policyName` set to `injection_tool_check`; a failure to read policies blocks the same way.
- Every call, allowed or not, writes a governance audit event carrying the approval id.
- The `POLICY_BLOCKED` and `APPROVAL_REQUIRED` codes in the error catalogue are not used by this route; the outcomes above are its only shapes.

## Troubleshooting

- **`error` says `Tool not found`**: the name form did not resolve. Pass `mcpName` or `mcpId` with the plain `toolName`, or use `namespacedName` from the list.
- **`blocked` with `policyName` `capability:deny_list`**: the key's user is on the tenant's emergency deny-list; an administrator lifts it.
- **`blocked` with a rail in `policyName`**: an argument matched an injection pattern; the message names the rails.
- **`blocked` saying the request could not be safety-checked**: the guardrail check was unreachable; retry shortly.
- **`requiresApproval` with an empty `approvalId`**: the request could not be recorded; retry, and the id comes back.
- **403 `FORBIDDEN` whose `detail` names an internal service token**: the platform's own token between its gateways is missing; an administrator, not your key.
- **401 `Invalid or expired API key` although the key works elsewhere**: the key lacks the Execute tools scope, which the gateway checks while validating the key.

## Related

- [Call tools from a completion](/developers/guides/call-tools-from-a-completion)
- [Evaluate guardrails from your own code](/developers/guides/evaluate-guardrails)
- Tools and models
- Policies in the help centre

Source: https://docs.katonic.ai/developers/guides/execute-a-governed-tool
