smart_read
Read files with automatic resolution per code block, matching query relevance to cut tokens while keeping key code. For precise needs, use full, diff, structure, or line ranges.
Instructions
Read a file at an automatic or caller-chosen resolution.
By default SRP selects the optimal resolution per code block from query relevance and token budget:
Blocks matching the query → FULL (complete source)
Related blocks → MEDIUM (signature + docstring)
Peripheral blocks → LOW (name only)
Irrelevant blocks → SKIP (omitted)
This reduces output by prioritizing query-relevant blocks. Use
resolution="full" whenever exact source text is required.
Automatic selection is the right default and cannot be right for every
question. Measured on this repository, a signature-level view answered
12/12 questions whose evidence lives in a signature and 0/20 whose
evidence lives in a function body. Pass resolution when you already
know which kind of question you are asking.
Args:
file_path: Path to the file to read
query: What you're looking for (improves relevance scoring)
budget: Target token budget for the output (default: 1000)
resolution: Choose "full", "medium", "diff", "structure", or
"low"; empty means automatic. "full" returns the complete
original text.
"diff" requires previous_source and returns a whole-file
unified diff. "structure" returns declarations, signatures,
and imports while eliding implementation bodies when a useful
native outline is available; otherwise it returns full source
and reports structure_backend="full-fallback". Pinned output
is not demoted to fit the budget; the response reports
over_budget instead.
previous_source: Required baseline when resolution is "diff".
line_start: First line of an exact inclusive range (1-indexed).
Must be supplied together with line_end and cannot be
combined with resolution.
line_end: Last line of an exact inclusive range (1-indexed).
fresh: Bypass same-session re-read suppression and return the
rendered output in full.
read_scope: Optional caller scope for isolating parallel agents
that intentionally share one MCP connection.
An exact repeated delivery returns only an opaque ~NNN handle.
That handle means the rendered output is byte-identical to content
already delivered in this MCP session. Pass fresh=true to expand
it. Caller-selected FULL and line ranges return raw text on cache miss;
they are not wrapped in JSON, so their text remains exact.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| fresh | No | ||
| query | No | ||
| budget | No | ||
| line_end | No | ||
| file_path | Yes | ||
| line_start | No | ||
| read_scope | No | ||
| resolution | No | ||
| previous_source | No |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |