Vercel AI SDK tools

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.

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 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.

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:

import { Caesar } from "caesar-search";
import { caesarTools } from "caesar-search/ai";

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

All TypeScript SDK constructor options apply. If your agent speaks MCP instead of the AI SDK, the remote MCP server 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.
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.

Official SDKs

CLI

Vercel AI SDK tools

The tools

web_search

web_fetch

Configuring the client

For agents

​The tools

​web_search

​web_fetch

​Configuring the client

​For agents

The tools

web_search

web_fetch

Configuring the client

For agents