Tool
read
Not file reading — querying the index for a precise cut. The parse already happened, so read returns the richest representation that fits the budget on the call: full content if it fits, else structure, else a headline. Everything else on this page is a way of choosing what “richest” means.
You ask your agent “map the website project — don’t read any files” — this is what it sends. The same operation is a shell command, which is the form you script against.
Your agent calls — mcp
You call — cli
What comes back — the same on both surfaces
That is this documentation’s own project, mapped for 257 tokens without opening a file. Ask for
tree: headlines instead and every file arrives with a line describing what it is for. Scripting
against it? --json and --jsonl emit structured records instead of the rendered
view.
Parameters
| Parameter | What it does | |
|---|---|---|
| uri | required | The address. Globs allowed in the path, fragments after it, one modifier at the end. Join several with ;. |
| tokenBudget | optional | A contract, not a hint: you get the richest representation that fits inside it. Start at 800–2000 and raise it when the answer is worth more. |
The sixteen modifiers
Append => modifier to any address to choose what comes back. One modifier per address; those
written with a colon take a parameter after it.
| Modifier | Parameter | What comes back |
|---|---|---|
| content | — | Full text with line numbers. Assembles resolvable @ references in place. |
| content: | literal | Raw source, references left untouched. Use it when you are about to edit the file. |
| content: | preview | The reference manifest and its projected cost, without fetching the targets. |
| structure | — | Signatures without bodies — classes, methods, headings. |
| headline | — | One line summarising each file, as a flat list. |
| tree: | folders / files / headlines | A directory tree at the detail level you ask for. Folders is cheapest. |
| find: | keywords | Semantic search inside the matched files, with snippets. |
| similar: | seed URI | Rank the scope by likeness to a seed document, using stored vectors. |
| grep: | text | Literal text search. All-lowercase is case-insensitive; any capital makes it exact. |
| regex: | pattern | Regular-expression line search across the scope. |
| where | local / remote | Resolve the address to a path on disk, or to a GitHub URL. |
| changes | — | Working-copy git changes in the scope, grouped staged, unstaged, untracked. |
| concepts | — | The invariants this repository has recorded about the scope, most specific first. |
| history: | query (optional) | The commits behind the matched files, symbols, or lines. A query reranks them by relevance. |
| blame | — | Line attribution grouped by commit — down to a single symbol. |
| question: | your question | A synthesised answer over the matched content, with citations. |
| lint: | errors / warnings | Diagnostics aggregated from annotations in the scope. |
| coverage: | uncovered / content | Coverage as a symbol summary, the uncovered gaps, or source with an execution gutter. |
Composing them
Glob, fragment, and modifier are independent, so they multiply. The whole address grammar is available in front of every one of these.
Budget is a contract
Breadth and depth trade against each other inside the number you set. A glob matching hundreds of files spends the budget on headlines; the same budget on ten files buys the structure of each; on one file it buys the whole thing. Narrow the address to go deep, widen it to go broad.
This page names what exists. The depth behind every name ships inside the binary at help:///: the bounds, the failure modes, how they compose. It answers to explore and read exactly like your code does. Install it, and your agent has the manual.