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

No annotations are provided, so the description carries the full burden. It describes what each mode returns (e.g., kernel returns title + kernel + stage + connection_count), which is helpful behavioral context. However, it doesn't disclose whether reads are cached, whether they have side effects (likely none, but unstated), or any permissions. For a read-only tool the gap is modest.

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?

The description is dense but well-structured: it front-loads 'PRIMARY' and then enumerates modes with clear return descriptions and a closing usage recommendation. It could be slightly tighter but every sentence serves a purpose.

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 adequately explains what each mode returns for a reader tool. It covers the main modes and gives guidance. The only missing piece is explicit differentiation from get_piece, but overall it's complete for an agent to choose and call.

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 100% description coverage, so baseline would be 3. The description adds substantial meaning by explaining each mode's return shape and the 'id' parameter is only mentioned implicitly. It goes beyond the enum labels by describing the payload, which is valuable.

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 clearly states the verb (read) and resource (piece), and the mode enumeration distinguishes it from siblings like get_piece. However, the name 'read' is generic and the description never explicitly differentiates from get_piece, which is a likely alternative.

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 tells when to use each mode with a cost-benefit framing: kernel for scanning, summary for considering, body for committing, meta for topology. It also references read(id, 'kernel') etc. This is as clear as it gets.

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