anydocs AGENTS.md

anydocs

When the anydocs MCP server is available, use search_docs with the product's source and then read_doc before answering questions about that product's documentation.

MCP server: BM25 search over other tools' documentation. Ingest in CI → SQLite FTS5 → publish as a GitHub Release asset → the client downloads it and serves five tools locally.

The rest of this file is for agents working on anydocs, and none of it ships. What reaches someone using the server is SERVER_INSTRUCTIONS and the five tool docstrings in server.py — about 1,000 tokens, and the only guidance a caller will ever see. So a lesson that should change how a caller behaves has to be written there. Writing it down here reaches nobody but us.

And those 1,000 tokens are not one channel, they are two. Measured with a behavioural canary on Claude Code 2.1.220 - "begin every reply with <token>" planted in each surface, then a question needing no tool, n=3 each way:

	in context before the model decides to search?
SERVER_INSTRUCTIONS (~100 tokens)	yes - fired 3/3
the five tool docstrings (~900 tokens)	no - 0/3. Schemas are deferred and arrive only after a tool search, which happens only once the model has already decided to use anydocs

So SERVER_INSTRUCTIONS is the only text we ship that is in front of the model when it decides whether to search; a docstring can only change how well it searches once it already has. Note what that costs us: the source names injected into the tool schemas (enum + description) are on the deferred side, so at the moment an agent decides whether to search, nothing has told it this server covers Claude Code at all.

The deferral is not fixed. "anthropic/alwaysLoad": true in a tool's _meta un-defers it, and Claude Code respects it. We do not use it, because it was measured and it does not change what the model decides - see the rejected table.

Neither of the two surfaces we ship carries the weight the AGENTS.md line does, and that is now two experiments, not a guess. Writing the line's content into SERVER_INSTRUCTIONS lands on the bare server (22% against 22%). Putting every docstring in context with alwaysLoad lands on the bare server too. The project-instruction channel has an authority ours does not, so the README's Step 2 is not a documentation convenience, it is the product.

But the project-instruction channel is not closed to us - we can only write to it manually, and a plugin does not have to. A Claude Code plugin can ship a SessionStart hook alongside the MCP server; the hook returns the line's content as hookSpecificOutput.additionalContext, which Claude Code wraps in a system reminder and inserts before the first prompt, the same delivery a project's AGENTS.md gets. Screened at $2, no judge, turn counts only, same Ollama question, no AGENTS.md file present: skipped the search 0 of 6, oss_provider 5 of 6 - where alwaysLoad (a server-side attempt at the same goal) scored 2 of 6. Passed the same pre-registered bar that alwaysLoad failed.

Not shipped yet, and n=6 only establishes that this did not die on the first screen. It needs a properly sized arm before anyone quotes a number, it only helps Claude Code (Codex and Cursor users still need the manual line), and a hook is code a plugin runs on the user's machine, which is a higher trust bar than a stdio MCP server and should be disclosed as such if shipped. Worth a follow-up: package the server + hook as a plugin, then measure it as a fifth arm.

Do not ask a model what is in its own context - it will confidently make it up. Asked directly, it answered ABSENT, NAME_ONLY and UNKNOWN, and all three were wrong. Only the behavioural canary is evidence.

Keep this file to rules — the things a future session must not get wrong. The story of how each rule was found is in git log, where the commit messages run to forty lines and cost nothing to carry.