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

# Vercel AI SDK tools

> Give any Vercel AI SDK agent Caesar search and read tools with one import.

```bash theme={"system"}
npm install caesar-search ai
```

The `ai` package (version 5 or newer) is an optional peer dependency of `caesar-search` — optional for the rest of the SDK, required for this subpath. Importing `caesar-search/ai` without it fails at module resolution.

```ts theme={"system"}
import { generateText } from "ai";
import { caesarTools } from "caesar-search/ai";

const { text } = await generateText({
  model,
  tools: caesarTools(),
  prompt: "What changed in Postgres 17 logical replication?",
});
```

The default client reads `CAESAR_API_KEY`. Create a key in the [Caesar app](https://app.trycaesar.com) and set it in the runtime environment before the model calls these tools.

## The tools

`caesarTools()` returns two enumerable tools:

| Tool         | Purpose                                                    |
| ------------ | ---------------------------------------------------------- |
| `web_search` | Search the web with ranked results and provenance handles. |
| `web_fetch`  | Read a URL or `doc_id` as clean markdown.                  |

Use the TypeScript SDK client directly for other API actions. Legacy direct properties `caesar_search` and `caesar_read` remain available for existing code, but they are non-enumerable so they are not sent to models as tool choices.

### web\_search

| Parameter         | Type                              | Description                                      |
| ----------------- | --------------------------------- | ------------------------------------------------ |
| `query`           | string, required                  | The search query.                                |
| `max_results`     | number                            | Maximum results, 1-50. Default 8.                |
| `response_format` | `compact` \| `standard` \| `full` | compact (default) is the token-efficient choice. |

Runs `client.search(query, { maxResults, verbosity })`. The `ids_only` verbosity is deliberately omitted from the tool's `response_format` enum — it exists at the client level, but is a poor fit for tool results. See [response shaping](/concepts/response-shaping).

### web\_fetch

| Parameter    | Type             | Description                                                 |
| ------------ | ---------------- | ----------------------------------------------------------- |
| `target`     | string, required | URL or doc\_id to read.                                     |
| `query`      | string           | Query context for the read.                                 |
| `max_chars`  | number           | Optional content character cap. Omit for the full document. |
| `start_char` | number           | Resume a truncated read from this character offset.         |

Runs `client.read(target, { query, maxChars, startChar })`.

## Configuring the client

Pass your own configured client to control auth, timeouts, and retries:

```ts theme={"system"}
import { Caesar } from "caesar-search";
import { caesarTools } from "caesar-search/ai";

const tools = caesarTools({
  client: new Caesar({ timeoutMs: 10000, maxRetries: 1 }),
});
```

All [TypeScript SDK](/clients/sdks/typescript) constructor options apply. If your agent speaks MCP instead of the AI SDK, the [remote MCP server](/clients/mcp/remote) exposes the same two tools.

## For agents

* Tool results default to `compact` to protect the context window. Ask for `standard` or `full` only when you need passages or [provenance](/concepts/provenance).
* Thread `doc_id` values between tool calls: `web_search` returns a `doc_id` per result, and it is the most reliable `target` for `web_fetch` — more stable than re-passing the URL.