Read text file

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already cover readOnlyHint, idempotentHint and destructiveHint=false, so safety is handled. The description adds genuinely new behavior: documents come back read-only with no rev, offset/limit reports total lines and rev (required for edit_file line edits), and HTML/RTF/EML/FB2 read raw unless extract:true. It stops short of describing pagination or exact return shapes, but the important rev/read-only nuances are disclosed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded paragraph that begins with the core action and then layers modes, content-type behavior, and sibling routing. Dense but essentially every clause carries information; the long compound sentences slightly hurt scannability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, so the description correctly mentions return-relevant facts (total lines, rev, numbered lines with section markers) and rev's role for edit_file. It is nearly complete for a 6-param read tool, though it never clarifies its relationship to the read_file sibling, leaving one ambiguity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is only 50% (head, tail and path are undocumented in the schema), so the description must compensate. It does: head/tail = 'N lines from an edge', offset/limit = 'an arbitrary 1-based line range', and extract:true = their text for HTML/RTF/EML/FB2. Only the interplay/precedence between head and tail and limit is left implicit.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Read one file') and then enumerates the distinct read modes (whole file, head/tail edge slices, offset/limit 1-based ranges, document/HTML/RTF handling). An agent can tell exactly what the tool does and how it differs from read_multiple_files, read_media_file, and read_pdf_page.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly routes to alternatives with conditions: 'Several files at once: read_multiple_files; images and page images: read_media_file / read_pdf_page.' It also states which modes apply to which content types (documents vs HTML/RTF/EML/FB2), leaving little to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.