Read File

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

With no annotations, the description carries the full behavioral burden. It discloses meaningful traits: text decoding with errors replaced, binary output as base64, and a max_bytes cap to avoid flooding context. It does not cover failure modes or permissions, but the main behavioral surface is well described.

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 sentences, with the core purpose front-loaded and each sentence earning its place. The formatting using backticked parameter names makes the guidance easy to scan, with no filler.

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?

The presence of an output schema covers return-value details, and the description covers the main input behaviors and the safety-motivated max_bytes cap. It is complete enough to call correctly, but lacks explicit sibling selection guidance and failure-behavior notes, so it stops short of a 5.

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?

The schema has no per-parameter descriptions, so the description must compensate. It explains the semantics of encoding (errors replaced), binary (raw bytes base64-encoded), and max_bytes (read cap), adding real meaning beyond the schema's types and defaults. Path is left implicit, but that is acceptable given the tool's clear purpose.

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 opens with "Read a file's contents," a specific verb+resource statement that clearly identifies what the tool does. It is clear enough to distinguish from siblings like write_file, list_dir, and stat, though it does not explicitly name or contrast them.

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?

There is no guidance on when to choose read_file over alternatives such as stat, exists, or list_dir. The description explains parameter behaviors but does not provide explicit when-to-use or when-not-to-use context.

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