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

The annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so safety is covered. The description still adds real behavioral value: it discloses the return modality (text content vs. an actual viewable image for PNG/JPEG/GIF/WebP) and that the content is the current shared, author-level manuscript text rather than a compiled artifact. It omits failure behavior for missing files and any size or binary-handling limits.

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?

Three short sentences, front-loaded with the primary return value, then the optional range, then the image special case. No filler; the only slightly loose sentence is 'The content is the author's manuscript text', which is terse but meaningful.

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?

With no output schema, the description carries the burden of describing returns, and it does so for both the text and image cases. For a four-parameter read tool that is nearly sufficient; what is missing is how a nonexistent path or a non-image binary file is reported.

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% – path and project_id are documented inline, but start_line and end_line have no schema descriptions. The description compensates directly by explaining the range is optional, 1-based, and inclusive, which is exactly the semantics an agent would otherwise have to guess.

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?

The description gives a specific verb and resource ('Returns a text file's content'), adds a scope qualifier ('as everyone sees it now'), and clarifies that images are returned as pictures rather than bytes. That clearly separates it from the write/edit/delete/rename siblings without naming them, but it never explicitly routes to a sibling (e.g. list_files to enumerate, search_project to grep text).

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?

Usage is implied – fetch a file's contents, optionally a line range – but there is no explicit when-to-use / when-not-to-use statement and no named alternative for related needs such as discovering a path or searching within a project. The agent can infer the case but must reason about it.

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