Copy page

Agent tooling

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.

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

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

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.