# Tools (/docs/build/tools)



An HTTP tool is one request to your service, made by the Runtime itself. No code
of yours runs during the session.

```ts
import { Agent, createClient, http } from "@nylorun/agents";
import { z } from "zod";

const refundOrder = http({
  name: "refund_order",
  description: "Refund an order.",
  input: z.object({ orderId: z.string(), amount: z.number() }),
  output: z.object({ refundId: z.string() }),
  url: "https://billing.example.com/refunds",
  credential: "billing",
});

export const support = Agent({ id: "support" })
  .instructions("Refund orders when the customer asks.")
  .tools(refundOrder)
  .build();

const client = await createClient();
await client.agentManifests.save({
  agent: support,
  runtime: {
    kind: "none",
    secrets: {
      billing: { type: "bearer", url: "https://billing.example.com/refunds", required: true },
    },
  },
});
```

In an [agent manifest](/docs/build/agent-manifests#tools), the same tool is the
file `tools/refund_order.json`, with `inputSchema`, `outputSchema`, and an
`http` block holding `url` and `credential`. The tool is named after its file,
and the tool policy names it by that name. A folder refuses `approval` in a
tool file (`approval_removed`); see [Approval](#approval).

`.tools()` takes one or more tools and accumulates across calls. The tool goes
into the agent manifest's harness section with its `http` target. The Runtime
sends each call through its Tool Gate, after the Tenant's
[tool policy](/docs/run/tool-policy) allows it. `credential: "billing"` names a
secret slot of the runtime section, so the save declares one; without it the
save is refused with `422 manifest_inconsistent`. See
[Credentials](#credentials).

A tool's name may not contain `__`, and no two tools share a name. No name is
reserved, but a turn fails when one of the agent's tools takes the name of a
tool our harness adds in that session, such as `bash` on an Agent with a
sandbox. See [Names](/docs/build/agent#names).

| Name | Type | Required | Description |
| ---- | ---- | -------- | ----------- |
| `name` | `string` | Yes | Tool name the model calls. |
| `description` | `string \| undefined` | No | What the model reads to decide when to call it. |
| `input` | `JsonObject \| ToolInputSchema` | Yes | Zod schema, Standard Schema, `defineSchema()` contract, or JSON Schema object. The fields the URL names fill it; the rest are the JSON body (`POST`, `PUT`, `PATCH`) or the query string (`GET`, `DELETE`). |
| `output` | `JsonObject \| ToolOutputSchema \| undefined` | No | Checked against the answer. A mismatch is a tool error the model sees. |
| `url` | `string` | Yes | Absolute `http` or `https` URL of your service. Its path may name input fields as `{field}`. |
| `method` | `HttpToolMethod \| undefined` | No | `POST` (default), `PUT`, `PATCH`, `GET`, or `DELETE`. |
| `credential` | `string \| undefined` | No | Names a `bearer` or `headers` secret slot of the runtime section, bound to `url`. The Agent's secret for `url` goes with each request. |
| `timeoutMs` | `number \| undefined` | No | How long your service may take to answer, in milliseconds. Default 60000, at most the Tenant's Runtime limit `httpToolTimeoutMs` (300000 by default). |

## The request [#the-request]

| Part                                                        | Value                                                                                                                                                                                                                                   |
| ----------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Method                                                      | `POST` by default, or the tool's `method`: `PUT`, `PATCH`, `GET` or `DELETE`.                                                                                                                                                           |
| URL                                                         | The tool's `url`, with each `{field}` its path names filled from the input.                                                                                                                                                             |
| Body                                                        | For `POST`, `PUT` and `PATCH`: the input's other fields as JSON, with `content-type: application/json`. `GET` and `DELETE` send no body.                                                                                                |
| Query string                                                | For `GET` and `DELETE`: the input's other fields, after any query string the URL has.                                                                                                                                                   |
| `Nylorun-Session-Id`, `Nylorun-Turn-Id`, `Nylorun-Agent-Id` | The session, turn, and agent the call belongs to. The agent is the agent manifest's name, or a subagent's id; never the Agent's id.                                                                                                     |
| `Idempotency-Key`                                           | The call's key. The Runtime delivers each call at least once: when a crash or a restart interrupts a call, it sends it again with the same key, up to the Tenant's Runtime limit `toolAttempts` (3 sends by default). Act once per key. |
| `traceparent`                                               | The call's W3C trace context, so your service's spans join the turn's trace. See [Traces](/docs/run/traces#trace-context).                                                                                                              |

A URL's path may name input fields as `{field}`:

```ts
export const getOrder = http({
  name: "get_order",
  description: "Read one order.",
  method: "GET",
  url: "https://orders.example.com/orders/{orderId}",
  input: z.object({ orderId: z.string(), expand: z.array(z.string()).optional() }),
  output: z.object({ id: z.string(), status: z.string() }),
});
```

A call with `{ orderId: "A 1", expand: ["items", "refunds"] }` requests
`https://orders.example.com/orders/A%201?expand=items&expand=refunds`.

* Each `{field}` is a required string, number or boolean of the input, named
  once, and only in the path. Its value is percent-encoded as one path segment
  and not sent again. An empty value, `.` or `..` fails the call before it is
  sent.
* In a query string an array repeats its name and a `null` is left out. A
  `GET` or `DELETE` tool whose input has an object field, or a field the URL's
  query string already fixes, throws when it is built (`tool.invalid`).
* A credential with `via` sends calls to its one URL, so it cannot serve a
  tool whose URL names a `{field}` (`http.credential`).

Keep anything your service needs across calls in your service, keyed by
`Nylorun-Session-Id`. A valid input schema is not authorization: check the
request in your service.

## The answer [#the-answer]

| Answer                                                                         | Result                                                                                    |
| ------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------- |
| `2xx` with JSON                                                                | The tool output, checked against `output` (`tool.invalid-output` when it does not match). |
| `2xx` with text, and no `output`                                               | The text.                                                                                 |
| `2xx` that is not JSON when `output` is set, or JSON that does not parse       | `http.invalid-response`                                                                   |
| `401`                                                                          | `credential_rejected`. The body is not shown, and the call is not retried.                |
| Any other status                                                               | `http.status`, with the start of the body.                                                |
| No answer within the timeout                                                   | `http.timeout`                                                                            |
| A refused address                                                              | `http.refused`                                                                            |
| Not sent: DNS, a refused connection, TLS                                       | `http.unreachable`                                                                        |
| Sent, and the connection lost                                                  | `http.lost`                                                                               |
| An answer over the Tenant's Runtime limit `toolAnswerBytes` (8 MiB by default) | `http.too-large`                                                                          |
| No credential for the tool's URL in the Agent's secrets                        | `http.credential`, not sent                                                               |
| Refused by the tool policy, or denied by a person                              | `tool.denied`, not sent                                                                   |
| Interrupted `toolAttempts` times by a crash or a restart                       | `tool.interrupted`: the call may have run                                                 |

Each error is a failed tool result the model sees, with its code, and the turn
goes on. See [Pauses and control](/docs/run/control#tool-call-delivery).

Each call ends in one `tool.completed` event, and a row in
`session.toolCalls()`, with `kind: "http"`, `tool` set to the tool's declared
name, and `server` set to the host of the tool's URL. See
[Events](/docs/run/events#tool-payloads).

Our harness stores an output over 32 KiB as a file artifact of the session; the
model gets a preview and reads the rest with `read_artifact`. See
[Large results](/docs/build/mcp#large-results).

## Credentials [#credentials]

`credential` names a secret slot of the runtime section the agent is saved
with: a slot of type `bearer` or `headers`, bound to the tool's exact URL. The
save checks it, and refuses a missing slot, a slot of another type, or a slot
bound to another URL with `422 manifest_inconsistent`, naming the gap:

```text
harness.tools.refund_order.http.credential "billing" is not a secret slot in runtime.secrets
```

Write the slot's value into each Agent made from the manifest:

```ts
await client.agents.put("teams/support", { manifest: "support" });
await client.agents.secrets.put("teams/support", "billing", { value: process.env.BILLING_TOKEN! });
```

The Runtime adds the Agent's secret for the tool's URL to each request, as for
a remote MCP server. Without one the call fails with `http.credential` before
it is sent. A credential with `via` sends the call to that URL instead. See
[Secret slots](/docs/run/agent-manifests#secret-slots) and
[Secrets and credentials](/docs/run/credentials).

## Approval [#approval]

Which calls wait for a person is not part of the tool. The Tenant's
[tool policy](/docs/run/tool-policy) holds or refuses calls by the tool's
declared name, agent, and input, for every agent at once. `http({ approval })`
throws, and saving an agent manifest that sets `approval` is refused. In an
agent manifest, `nylorun check` refuses it at its line:

```text
refund/tools/refund_order.json:9:3 error: approval is not set in an agent folder: tool approvals are the Tenant's tool policy, decided at the Tool Gate for every agent. To have a person approve a call, add a rule with "effect": "ask" for the tool to the Tenant's tool policy (nylorun tenant tool-policy put <file>, or PUT /v1/tenant/tool-policy)
```

## Reachability [#reachability]

The gateway must reach the tool's URL. Redirects are not followed.

* **Local Tenant.** `localhost` means your machine, and private addresses are
  allowed.
* **Server.** Set `NYLORUN_ENDPOINT_PRIVATE=refuse` and
  `NYLORUN_ENDPOINT_HTTP=refuse` unless your services live on a private
  network. See [Docker Compose](/docs/deploy/vm).

## Other tools [#other-tools]

| Tool                                            | Where it runs                                                                                                                   | `kind`    | Page                                                                                       |
| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | --------- | ------------------------------------------------------------------------------------------ |
| Remote MCP server tools                         | Your MCP server, reached through the gateway                                                                                    | `mcp`     | [MCP](/docs/build/mcp)                                                                     |
| An agent used as a tool                         | Our harness, with a fresh context                                                                                               | —         | [Subagents](/docs/build/subagents)                                                         |
| `load_skill`, `read_skill_resource`             | Our harness, when the agent has skills                                                                                          | `harness` | [Skills](/docs/build/skills)                                                               |
| `read_artifact`, `save_artifact`                | Our harness; `save_artifact` with a sandbox                                                                                     | `harness` | [Files](/docs/run/files)                                                                   |
| `tool_search`, `tool_call`                      | Our harness, when MCP tools are deferred                                                                                        | `harness` | [MCP](/docs/build/mcp#deferred-tools)                                                      |
| `bash`, `read`, `write`, `edit`, `grep`, `glob` | The sandbox of the Agent the session runs on; our harness runs a `read` of an image or PDF the model reads, to show it the file | `sandbox` | [Agents](/docs/run/agents), [Files the agent makes](/docs/run/files#files-the-agent-makes) |
| `schedule_wake`                                 | The Runtime, which books the session's next turn; with `runtime.selfWake`                                                       | `runtime` | [Triggers and wakes](/docs/run/triggers#wakes)                                             |
| `memory`                                        | The Runtime, which reads and writes the Agent's memories; with `harness.memory`                                                 | `runtime` | [Agent memory](/docs/run/memory)                                                           |

Our harness adds these tools to the model's list after the agent's own. A
custom harness offers its own; see
[Bring your own harness](/docs/build/harness#tools-of-your-own).

`tool({ run })` runs your code, so it runs only in the local engine
(`@nylorun/harness/run`). `client.agentManifests.save` refuses an agent that
has one, before sending anything. Make it an `http()` tool or serve it from a
remote MCP server. An HTTP tool runs only on the Runtime; a local `run()`
reports `http.runtime-only`.

An HTTP tool is also a stage of a [flow agent](/docs/build/flows):
`.pipe(order, refund)`. Its input is the previous stage's output.

## Next step [#next-step]

<Cards>
  <Card title="MCP" description="Declare remote MCP servers on the agent." href="/docs/build/mcp" />

  <Card title="Tool policy" description="Hold or refuse tool calls for every agent." href="/docs/run/tool-policy" />
</Cards>
