> ## Documentation Index
> Fetch the complete documentation index at: https://sdk.revise.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Tools for your agent

> Hand the document to whatever model you already run.

The SDK exposes the same document tools Revise's own agent uses. They are
JSON-schema described, safe to call without React state or browser focus, and
operate on semantic document structure rather than UI geometry.

## The loop

```ts theme={null}
const definitions = editor.tools.getDefinitions();

const response = await yourModel.createMessage({
  messages,
  tools: definitions.map((tool) => ({
    name: tool.name,
    description: tool.description,
    input_schema: tool.inputSchema,
  })),
});

for (const call of response.toolCalls) {
  const result = await editor.tools.execute(call.name, call.input);
  messages.push({
    role: "tool",
    tool_call_id: call.id,
    content: result.agentFeedback ?? JSON.stringify(result.output),
  });
}
```

That is the whole integration: schemas out, results back in. The definitions
are generated from the same source as Revise's production agent, so they carry
the descriptions and constraints the tools were designed with.

## Results

```ts theme={null}
interface ReviseEditorToolExecutionResult {
  toolCallId: string;
  name: string;
  success: boolean;
  error?: string;
  errorCode?: string;
  agentFeedback?: string;   // model-oriented explanation, success or failure
  output?: unknown;         // structured metadata
  context?: string;         // block-ID-preserving HTML from read/search tools
}
```

<Warning>
  A rejected edit resolves — it does not throw. Always check `success`, and
  feed `agentFeedback` back to the model: it explains *why* a call failed in
  terms the model can act on, which is usually the difference between a retry
  that works and one that repeats the mistake.
</Warning>

Read and search tools return `context`: HTML that preserves block IDs, inline
formatting, tables, and notes rather than flattening the document to plain
text. Those IDs are what mutation tools target, so the read/act cycle composes.

## Working with blocks

The model reads a window of the document, then edits by block ID:

```ts theme={null}
const read = await editor.tools.execute("read_blocks_from_index", {
  index: 0,
  context_notes: "Looking for the liability clause",
});

await editor.tools.execute("replace", {
  id: "b12",
  replacements: [
    {
      find: "capped at the fees paid",
      replace: "capped at two years of fees paid",
      occurrence: "unique",
    },
  ],
});
```

<Tip>
  `replace` operates inside **one** block. Two edits in different blocks are
  two calls — a single call with finds spanning blocks fails rather than
  partially applying.
</Tip>

## Routing to a document

Every tool schema carries an optional `document_id`. Omit it for the active
document, or target any ready document in the same editor:

```ts theme={null}
await editor.tools.execute("set_title", { title: "Exhibit A" }, {
  documentId: "exhibit-a",
});

// or bind a controller once
const exhibit = editor.tools.forDocument("exhibit-a");
await exhibit.execute("measure_document", {});
```

## Suggestions or direct edits

By default, mutations in a `suggesting` document land as tracked changes. Pass
`directMode` to apply them outright:

```ts theme={null}
await editor.tools.execute("style_blocks", input, { directMode: true });
```

See [tracked changes](/guides/tracked-changes) for when that is appropriate.

## What is not a tool

Review navigation, comment-panel state, focus, viewport, and zoom are host
APIs, not agent tools. An agent should not be clicking "next suggestion" — it
should be making semantic edits and letting your UI present them. See
[architecture](/concepts/architecture).

The full catalogue is in the [tool reference](/api/agent-tools).