---
title: "AI agent tool reference | Nutrient Web SDK"
canonical_url: "https://www.nutrient.io/guides/web/ai-assistant/ai-agent-tools/tool-reference/"
md_url: "https://www.nutrient.io/guides/web/ai-assistant/ai-agent-tools/tool-reference.md"
last_updated: "2026-05-29T15:33:59.518Z"
description: "How to wrap Nutrient Web SDK methods as AI agent tools, with examples for searching, annotating, filling forms, and editing pages."
---

# Tool reference

Wrap any method on `NutrientViewer.Instance` as a tool. The pattern is always the same: Define an input schema matching the method’s parameters, write an execute function that calls the SDK, and return a plain JavaScript object.

The SDK returns Immutable.js objects. Call `.toJS()` to convert them before returning to the model.

## Reading document content

An agent typically reads the document before taking action, like searching for text, checking what annotations exist, or inspecting form fields.

### Searching text

`instance.search(term)` finds all occurrences of a string across the document. Each result includes the page index and surrounding text, giving the agent context about where content appears:

```typescript

async function execute({ query }, instance) {
  const results = await instance.search(query);
  return results.toJS();
}

```

### Reading annotations

`instance.getAnnotations(pageIndex)` returns every annotation on a page: type, text content, bounding box, and ID. The agent uses this to understand what markup already exists before adding or modifying annotations:

```typescript

async function execute({ pageIndex }, instance) {
  const annotations =
    await instance.getAnnotations(pageIndex);
  return annotations.toJS();
}

```

### Inspecting forms

`instance.getFormFieldValues()` returns all field values as key-value pairs. `instance.getFormFields()` returns metadata: field names, types, and validation options. Together, these provide the form’s structure and current state:

```typescript

async function execute(instance) {
  const values = await instance.getFormFieldValues();
  const fields = await instance.getFormFields();
  return { values: values.toJS(), fields: fields.toJS() };
}

```

The result includes field names, current values, and field types (text, checkbox, radio, dropdown). The agent uses the field names when calling `setFormFieldValues()` later.

## Annotating documents

To add an annotation, the agent provides a page index, text content, and a bounding box. The execute function constructs the SDK annotation object from these plain values.

Bounding box coordinates are in PDF points. The origin is at the bottom-left of the page:

```typescript

async function execute(
  { pageIndex, text, left, top, width, height },
  instance,
) {
  const annotation =
    new NutrientViewer.Annotations.TextAnnotation({
      pageIndex,
      text: { format: "plain", value: text },
      boundingBox: new NutrientViewer.Geometry.Rect({
        left, top, width, height,
      }),
    });
  const [created] = await instance.create(annotation);
  return { id: created.id };
}

```

The SDK supports many annotation types beyond text: ink, shapes, highlights, stamps, and more. See the [annotations API reference](https://www.nutrient.io/api/web/Annotations/) for the full list. Each type has its own constructor parameters, but the wrapping pattern is the same: Build the SDK object from plain tool arguments, call `instance.create()`, and return the ID.

To modify an existing annotation, use `instance.update(annotation)`. To remove one, use `instance.delete(annotationId)`.

## Working with forms

`instance.setFormFieldValues(values)` fills in fields by name. The agent passes an object mapping field names to values — the same names returned by `getFormFieldValues()`:

```typescript

async function execute({ values }, instance) {
  await instance.setFormFieldValues(values);
  return { updated: Object.keys(values) };
}

```

A typical agent workflow reads the form fields first to discover available field names, and then it fills them in.

## Navigating the viewer

`instance.setViewState(updater)` controls the viewer’s current page, zoom, and layout. These tools help the agent guide the user to relevant content after searching or annotating:

```typescript

async function execute({ pageIndex }, instance) {
  instance.setViewState((v) =>
    v.set("currentPageIndex", pageIndex),
  );
  return { navigatedTo: pageIndex };
}

```

## Editing pages

`instance.applyOperations()` removes or rotates pages. These operations change the document structure and are irreversible:

```typescript

async function execute({ pageIndexes }, instance) {
  await instance.applyOperations([
    { type: "removePages", pageIndexes },
  ]);
  return { removed: pageIndexes };
}

```

`instance.applyRedactions()` permanently removes redacted content. `instance.exportPDF({ flatten: true })` burns annotations into the PDF. Both are irreversible.

## Writing tool descriptions

The description determines when the model selects the tool. Include what the method does, what it returns, and any dependencies on other tools:

- `"Search the document for a text string. Returns matching locations with page index."`

- `"Add a text annotation to a page. Call get_page_info first to understand dimensions."`

- `"Remove pages from the document. Irreversible."`

Mentioning prerequisites (like calling `get_page_info` before creating an annotation) helps the model plan multistep workflows.

See the [Vercel AI SDK](https://www.nutrient.io/guides/web/ai-assistant/ai-agent-tools/vercel-ai-sdk.md) and [LangChain](https://www.nutrient.io/guides/web/ai-assistant/ai-agent-tools/langchain.md) pages for how to register these tools with a framework. Any method on `NutrientViewer.Instance` can be wrapped as a tool using the same pattern; refer to the [API reference](https://www.nutrient.io/api/web/) for the full list.
---

## Related pages

- [Integrating Nutrient Web SDK with AI agents](/guides/web/ai-assistant/ai-agent-tools.md)
- [LangChain](/guides/web/ai-assistant/ai-agent-tools/langchain.md)
- [Vercel AI SDK](/guides/web/ai-assistant/ai-agent-tools/vercel-ai-sdk.md)