Read the board

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds real value beyond that: it discloses the returned field set (including dashed=async connection semantics) and the stateful delta behavior ('changed since you last looked'), neither of which appears in the annotations or schema. It does not mention verbosity trade-offs of include_json, which the schema covers separately.

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?

One sentence, front-loaded with the deliverable and then a tight parenthetical enumeration of exactly what the structure contains. No filler, no repetition of the 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?

There is no output schema, so the description must carry the return shape — and it does, enumerating the top-level sections and key fields. The remaining gap is that 'what changed since you last looked' is undefined (delta against which baseline, and what happens on the first call), which matters for a stateful read.

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 100% and the single parameter include_json is documented in the schema as 'Also return raw element JSON (verbose)'. The description adds nothing about it, so this sits at the baseline 3 — the schema does all the work.

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 names the resource (the board) and specifies the shape of the returned structure — components with type/label/id/position/zone, connections with direction and dashed=async, zones, notes, strokes, plus a delta. That is far more specific than the title 'Read the board'. It stops short of explicitly contrasting with get_board_image, which is the obvious sibling, so it doesn't fully earn a 5.

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 only implied: 'what changed since you last looked' hints this is the tool to re-poll board state, but there is no explicit when-to-use, no exclusions, and get_board_image is never named as the alternative for a visual read. The agent must infer the routing from the sibling's name.

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