Remote Read

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

With no annotations, the description carries the full disclosure burden. It does add two real behavioral facts — reads are 'bounded' (implying truncation via limit/offset) and a SHA-256 revision is surfaced for optimistic concurrency — but omits error behavior for non-UTF-8 or missing paths, permission requirements, and whether the revision is usable in remote_apply_patch.

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 sentence with zero filler; the resource and the revision behavior are stated immediately. Nothing is repeated from the name or title.

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?

For a 4-parameter tool with fully undescribed parameters, no annotations, and no output schema, the description is too thin. It should at minimum define offset/limit semantics, clarify the return shape (text plus revision), and state how the revision feeds the editing tools.

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 description coverage is 0% across 4 parameters, and the description never names or explains limit, offset, project_id, or relative_path. 'Bounded' is the only faint gesture toward limit/offset, leaving the two undocumented non-obvious parameters to guesswork.

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 concrete verb and resource ('Read bounded UTF-8 text') plus a distinguishing characteristic (returned SHA-256 revision for optimistic editing). It never names or contrasts with the adjacent siblings (remote_stat, remote_list, remote_search), so an agent must infer which read tool applies.

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?

No when-to-use, when-not-to-use, or alternative routing is given. 'For optimistic editing' hints at the intended workflow but does not say when to prefer this over remote_stat or remote_search, nor what prerequisites exist.

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