Read dimensions, tags and notes

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds valuable behavioral context: stale=true lists rows with a specific shape, checked counts what was compared, unverified lists sizes nothing can confirm, and the warning that 'an empty list with nothing checked is not a clean plan.' It also discloses the fallback note-checking behavior (a note standing on a piece or beside a single piece that shares a number is checked). This goes beyond the annotations without contradicting them.

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 every sentence earns its place: it covers the stale mode, checked counts, unverified lists, the note-checking rule, q= search, the no-args schedule, and the sibling edit_annotations. It is front-loaded with the core purpose ('Plan annotations, read') and then details modes. It is long, but the complexity of the tool justifies the length; no filler or repetition.

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 read-only tool with an output schema, the description is remarkably complete. It explains all three invocation modes (stale, q, no-args), the exact row shapes, the meaning of checked and unverified, the note-checking fallback, and the relationship to edit_annotations. The output schema covers the schedule structure, so the description doesn't need to repeat it. An agent has everything needed to call this tool correctly.

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 100%, so the schema already documents both parameters. The description adds meaning beyond the schema: it explains what stale=true returns (rows [id, written, measured, against, text]) and what q= does ('searches label text on every storey'), plus the regex variant. It also clarifies the no-args mode returns the schedule. This is more than the baseline 3 for full schema coverage.

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 'Plan annotations, read' and then enumerates exactly what the tool does: lists stale dimensions/notes, checks counts, lists unverified sizes, searches label text, and returns a schedule. This clearly distinguishes it from sibling tools like edit_annotations (which 'turns modes on and off, ties dimensions and bakes chains') and update (which sets piece properties).

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?

The description gives explicit when-to-use guidance: 'run it after moving geometry, before handing the plan over.' It also explains the modes (stale, q, no-args) and contrasts with edit_annotations, which is the sibling that modifies annotations. The q= and re: syntax is fully specified, so an agent knows exactly when to invoke this read tool versus a write tool.

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