read
Read a file with automatic caching. Returns full content on first read, indicates unchanged content, or provides a diff for modifications.
Instructions
Read a file. Automatically returns the most token-efficient response.
Use this for a single file. For 2+ files, prefer batch_read.
Behavior (automatic — no configuration needed):
First read: returns full content and seeds the cache.
Unchanged re-read: returns
"unchanged": true(content already in context).Modified re-read: returns a unified diff of changes.
External changes: detected automatically via mtime + content hash.
If response contains "unchanged": true, do NOT re-read — you already
have the full content from a prior read. Use offset/limit to recover
specific line ranges after truncation or context loss.
Args:
path: File path (absolute or relative to project root). Use absolute
paths for files outside the current project root.
max_size: Maximum content size to return before summarization.
offset: 1-based starting line number for targeted reads.
limit: Number of lines to return from offset.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | ||
| max_size | No | ||
| offset | No | ||
| limit | No |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| truncated | No | ||
| path | No | ||
| content | No | ||
| lines | No | ||
| unchanged | No | ||
| is_diff | No | ||
| semantic_match | No | ||
| total_tokens | No | ||
| hint | No | ||
| from_cache | No | ||
| tokens_saved | No | ||
| tokens_original | No | ||
| tokens_returned | No | ||
| params | No |