Sapper Board

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 implies a non-destructive read ('status', 'board') but never says so outright, and says nothing about permissions, cost, or scoping beyond 'under root'. Since an output schema exists, the absence of return-format detail is acceptable, but the read-only guarantee rests on inference rather than statement.

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 no filler; the parenthetical column list is dense but earns its place by telling the agent what the board shows. Slightly jargon-heavy but appropriately sized for a simple status tool.

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 one-parameter, output-schema-backed read tool this is nearly sufficient: it explains scope and what the board reports. The remaining gap is routing information — nothing tells the agent why to call this rather than one of the thirty-odd sibling 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 coverage is 0%, so the schema only says `root` is a string defaulting to 'runs'. The description adds that `root` is the container under which challenge graphs are enumerated, which is real meaning beyond the schema, but it does not clarify whether it is a path prefix, a directory, or a graph identifier.

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?

Names the resource (challenge graphs) and the output shape (one-line status per graph), and enumerates the columns it summarizes (flags sub/rec, intel counts, open intents, last activity). An agent can tell this is a read-only overview board, though the domain jargon ('flags sub/rec', 'intel counts') limits how legible the purpose is to an outside agent.

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 explicit when-to-use guidance and no named alternative among the many siblings (sapper_status, sapper_show, sapper_fleet, sapper_frontier). The phrase 'the commander's board' hints at a situational-awareness use case but never states when an agent should pick this over another status tool.

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