Set triage lane

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

Goes well beyond the annotations (which only declare idempotent, non-destructive writes) by disclosing the confirmation gate, the needs_confirmation outcome, atomic all-or-nothing resolution, unresolved candidate listing, and that previous lanes are returned for undo. The only missing detail is whether partial writes can occur mid-batch, though 'nothing is changed' largely covers this.

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?

Use-case, notes, and example sections make it scannable and front-loaded, with each note carrying a distinct rule. The lane list is repeated in both the use_case block and the schema enum, which is slight redundancy but not harmful.

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?

An output schema exists, so return values need only light mention; the description still notes that previous lanes come back. For a mutation tool with a confirmation flow, the safety rules, resolution requirement, and failure outcomes are all covered.

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 baseline is 3; the description still adds real meaning by explaining when confirmed=true is required and why app ids beat names when two games share a title. The lane vocabulary is largely duplicated from the enum description, which caps it below 5.

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?

States a specific verb ('Put games in a triage lane') plus the exact set of destinations (next, someday, skip, done, none) and the immediate-persistence behavior. The parenthetical synonyms (up next, finished, beaten) make the lane vocabulary unambiguous, and 'none' is explicitly framed as untriaging rather than a fifth lane.

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?

Gives explicit when-to-act rules: a single named game can be moved freely, more than five games or unnamed skip/done requires asking first, then confirmed=true. It also routes to the right sibling for ambiguity (backlog_find_games) and for ordering (backlog_reorder_next), and warns against inferring 'done' from playtime.

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