Agent search tools

AI answers pre-select chunks and hand them to the model. Bash tools do the opposite: they give an agent a read-only virtual /docs filesystem built from the same static index, and let it explore with ls, cat, find, grep, and rg. Reach for this when the agent should decide what to read — multi-step research, "find everywhere X is configured," or when one retrieval pass isn't enough. There's no network, no code execution, and no writes.

Wire the tools

Both factories take the same (index, content) and return ready-to-register tools plus instructions to add to your system prompt.

import { streamText } from "ai";
import { createDocsBashTool } from "leadtype/search/bash";

const { tools, instructions } = await createDocsBashTool(index, content);

const result = streamText({
  model: "openai/gpt-5.5",
  system: `Answer from the docs. ${instructions}`,
  tools,
  prompt: query,
});

Need the raw filesystem (for a custom tool layer)? createDocsBashFileMap(index, content) returns the /docs file map the adapters are built on.

When to use which

Situation	Use
Direct Q&A over docs, fast and cheap	AI answers (pre-retrieved chunks)
Agent needs to explore, follow references, or read whole files	Bash tools (this page)
You want both	Register bash tools and seed the prompt with `createAnswerContext`

Notes

The filesystem is read-only and sandboxed: ls/cat/find/grep/rg only. No network, no execution, no writes.
It's the same index + content from Add search — no extra build step.
Tool-driven exploration costs more tokens and round-trips than a single grounded answer; default to AI answers and escalate to tools when the task is genuinely multi-step.
These tools run in-process inside your own AI app. To expose docs to external clients (Claude Desktop, Cursor, a hosted endpoint) instead, run the MCP server — same index, standalone process.