# Agent guidance

The DocAI plugin ships a `SKILL.md` for Claude Code, a `.mdc` rule for Cursor
and an `AGENTS.md` section for Codex. All three carry the same four
instructions, because all three are steering the same [25 tools](/mcp).

This page is the reasoning behind the rules. Installing the server is [plugins
and commands](/plugins), and what each tool does is the [MCP server](/mcp)
page. The rules steer calls against the endpoints in [parsing](/parsing),
[extraction](/extraction) and [knowledge bases and
search](/knowledge-bases).

The text opens with the only framing that matters:

> DocAI parses documents into grounded, citable artifacts. These tools reach
> the user's own knowledge bases.

Not a sandbox, not a copy. The agent is operating on production data with an
organization-root key.

## Why this is the mechanism, not documentation about one

It is tempting to read guidance as a description of how the tools behave, with
the real enforcement somewhere underneath. For most of what follows, there is
nothing underneath.

The server has exactly one hard control: two permanent-delete tools are not
registered unless `DOCAI_MCP_ALLOW_DESTRUCTIVE` is set. That is real, because a
tool that does not exist cannot be called. Everything else is available to the
model on request. Nothing at the protocol level stops an agent from parsing a
thousand pages it did not need, looping through your monthly quota, or reading
forty documents into context to answer one question about a clause.

The API cannot stop it either, because none of that is an error. The key is
valid, the quota is there to be spent, and every call is a legitimate one. The
difference between a cheap session and an expensive session is entirely in
which tools get called, in what order.

That decision is made by the model, and the only input you have into it is the
guidance. So the four rules below are the control surface. Deleting them does
not remove documentation, it removes the mechanism.

## Start at the index

> `docai_kb_index` returns every file in a knowledge base with its parse status
> and artifact links in one call. Use it before anything else. Do not list
> files and then fetch each one — that is slower and tells you less.

The untrained pattern is: list the files, then fetch each one to see whether it
parsed, then fetch its artifacts. For 200 documents that is around 400 round
trips, each with a response the model reads, and it still does not have the
artifact links in one place.

`docai_kb_index` is one request that returns all of it. The saving is not just
latency. Every intermediate response is tokens through the model's context, and
by the time the crawl finishes the early responses may have been squeezed out
of the window — so the agent has paid for the information and lost it. One
index call is one response that stays.

The index is the read model built for exactly this question. Reconstructing it
by hand is more work for a worse answer.

## Search before you read

> `docai_search` runs full-text search over parsed evidence and returns exact
> file and segment pointers. It calls no model, so it costs the user nothing.
> Reading whole documents to find one clause wastes context and money; search
> first, then read only what you need.

This is the rule with the clearest money attached, and it is worth being
precise about which money.

There are two costs in play. **[Credits](/quickstart#credits)** are what DocAI
charges, and they are
spent by model work — parsing, extraction. `docai_search` is a Postgres
full-text read over already-parsed evidence. It calls no model, so it spends no
credits, ever, at any volume. **Tokens** are what your editor's model charges,
and they are spent by whatever the agent reads.

An agent that reads whole documents to find a clause spends heavily on the
second while gaining nothing on the first. Search costs zero credits and
returns file and segment pointers, so the follow-up read is one artifact rather
than forty, and it arrives with the coordinates needed to cite it. Fewer
tokens, a shorter context, and a more precise answer, from the cheaper call.

The sequence the rule asks for is: `docai_search` to find where the answer
lives, `docai_read_artifact` for that file only, `docai_get_segments` when the
answer needs to point at a line rather than a document. There is a worked
example on the [MCP server page](/mcp#a-worked-session).

## Check credits before bulk work

> Parsing and extraction cost credits per page. `docai_parse_bulk` and
> `docai_extract_bulk` can spend a lot at once. Call `docai_credits` first,
> tell the user what the operation will cost, and let them decide.

Two tools take a set rather than a document, and their cost scales with the
set. `docai_parse_bulk` spends per page across every file. `docai_extract_bulk`
spends per file.

A single mistyped folder path is the failure this rule exists for. The agent is
not doing anything wrong at the API level — the call succeeds, the credits go —
and you find out afterwards.

`docai_credits` is read-only and free. The rule asks the agent to call it, state
the balance and the expected cost, and stop for an answer. That last part is the
point: a confirmation the user never sees is not a confirmation.

## An API key is the whole organization

> DocAI API keys are not scoped — one key can read and write every knowledge
> base the organization has. Treat every write as production. Ask before
> deleting anything, and never delete to tidy up unless the user asked for it.

DocAI has proper role-based access control for people: permissions such as
`files.read` or `parse.run`, plus per-resource grants on individual knowledge
bases. An API key bypasses all of it. There is no read-only key and no
knowledge-base-scoped key today.

So the agent's blast radius is the organization, not the project you happen to
have open. It can reach a knowledge base nobody on this project has ever
touched.

The last clause is the one that earns its place. "Never delete to tidy up
unless the user asked for it" exists because tidying is a plausible, helpful
thing for a model to volunteer — clearing failed jobs, removing duplicates,
cleaning a knowledge base that looks abandoned. Every one of those is a
reasonable inference and a data loss. Removal happens when it was requested,
and not otherwise.

`docai_delete_file` is a soft delete and recoverable, which is why it stays
available. The two irreversible tools are hidden entirely unless
`DOCAI_MCP_ALLOW_DESTRUCTIVE` is set — the one place where a hard control backs
the rule up rather than the rule standing alone.

## Where the text lives

The guidance is written once, in `editors/guidance.md`, and copied into each
editor's format at release: `SKILL.md` with Claude Code frontmatter, `.mdc`
with a Cursor rule header, a section in `AGENTS.md` for Codex.

A test asserts the copies stay byte-identical to the source. Three copies of
the same four paragraphs, maintained by hand, is precisely how a rule gets
fixed in one place and quietly stays wrong in the other two — and since the
rules are the mechanism, a drifted copy is a drifted safety control, not a
stale document.

To see where each copy is installed, see [plugins and
commands](/plugins).