# <Tool />

Grant one schema-validated JavaScript capability to its nearest containing <Agent />.
Canonical: https://agent-markup-language.com/docs/reference/primitives/tool/
Documentation index: https://agent-markup-language.com/docs/
Complete documentation: https://agent-markup-language.com/docs/llms.txt

`<Tool />` grants an application function created by `defineTool()` to its nearest containing [`<Agent />`](https://agent-markup-language.com/docs/reference/primitives/agent/). The function runs in the AML application process, not inside an active [`<Sandbox />`](https://agent-markup-language.com/docs/reference/primitives/sandbox/).

```tsx
import { Agent, AmlRuntime, defineTool, Tool } from "@aml-jsx/sdk"
import { DeterministicAgentProvider } from "@aml-jsx/sdk/testing"
import { z } from "zod"

const lookupOrder = defineTool({
  name: "lookup_order",
  description: "Read one order by its public identifier",
  input: z.object({ id: z.string() }),
  execute: async ({ id }) => ({ id, status: "paid" }),
})

const runtime = new AmlRuntime({ agentProvider: new DeterministicAgentProvider() })
await runtime.evaluate(
  <Agent>
    <Tool use={lookupOrder} />
    Summarize order A-42.
  </Agent>
)
```

This example uses Zod as a Standard Schema implementation; install it separately with `npm install zod`.

## Call a Tool from application code

Call the function returned by `defineTool()` inside an active AML function component when application code, rather than a model, chooses to run the Tool:

```tsx
import { AmlRuntime, defineTool } from "@aml-jsx/sdk"
import { z } from "zod"

const loadOrder = defineTool({
  name: "load_order",
  description: "Load one order for application workflow code",
  input: z.object({ id: z.string() }),
  output: z.object({ id: z.string(), status: z.literal("paid") }),
  execute: async ({ id }) => ({ id, status: "paid" as const }),
})

async function Workflow() {
  const order = await loadOrder({ id: "order-17" })
  return `${order.id}:${order.status}`
}

await new AmlRuntime().evaluate(<Workflow />)
```

Calling `loadOrder()` requires no surrounding `<Agent />` or `<Tool />`. It validates and snapshots through the same registered Tool execution path, inherits evaluation cancellation and tracing, and runs in the AML host process. Calling a Tool never grants it to a model. The callable API is available only while the function component is active, and AML joins started calls before enclosing resources clean up.

The same Tool can be granted separately when a model should decide whether to call it:

```tsx
<Agent>
  <Tool use={loadOrder} />
  Check order-17.
</Agent>
```

`<Tool use>` accepts only the exact callable returned by `defineTool()`. An inline definition is valid—`<Tool use={defineTool({...})} />`—but a structurally similar plain object is not.

## Props

| Prop  | Type      | Required | Meaning                                         |
| ----- | --------- | -------- | ----------------------------------------------- |
| `use` | `AmlTool` | yes      | Exact Tool identity returned by `defineTool()`. |

`<Tool />` accepts no children or `name` prop. Tool names must be unique inside one `<Agent />` and may be restricted by the runtime `allowedTools` allowlist.

## Execution boundary

- AML validates model input before calling `execute`.
- Tool output must be JSON-compatible and is snapshotted before it crosses the provider boundary.
- An optional output schema validates the function's returned value.
- The callback receives cancellation and trace context, but it does not inherit Sandbox process execution merely because its Agent is sandboxed.
- Sibling and parent `<Agent />` components do not receive the grant unless they declare it separately.

**Caution — A Tool is application authority**

The model may invoke every granted Tool. Validate authorization and containment inside the callback; prompt
instructions are not an access-control boundary.

See the runnable [`programmatic-tool` example](https://github.com/we-are-singular/aml/blob/main/examples/src/core/programmatic-tool.tsx), [Build a JavaScript Tool](https://agent-markup-language.com/docs/cookbook/tools/), [Tool or MCP?](https://agent-markup-language.com/docs/cookbook/tool-or-mcp/), and [production security](https://agent-markup-language.com/docs/production/security/).