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

Annotations already cover read-only, idempotent, closed-world, non-destructive, so the description's job is to add what they cannot. It does: "It never fails: if the board cannot be checked it says why and you proceed uncoordinated" is a genuinely useful fail-open contract, and the enumeration of returned fields (checks, last active, live or stale) tells the agent what state it will get back.

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 decisive instruction is front-loaded and no sentence is filler, but the body is one long semicolon-chained run-on that is dense to parse. Slight structural cost against otherwise tight prose.

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?

Six optional parameters with no output schema means the description must carry the return-value burden, and it does by itemizing every category of result plus the verdict vocabulary (free, held live, held stale, closed). Combined with the never-fails behavior, an agent has everything needed to call and interpret it.

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 baseline is 3, but the description adds intent the schema lacks: pass repo as owner/name from your git remote, session_id/branch exist to surface your own claims separately, paths drive conflict detection, and issues yield a one-line verdict. These tie each parameter to an outcome rather than restating it.

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?

Opens with a specific imperative verb and trigger ("Call this before you claim or start an issue") and then enumerates exactly what one call returns: active claims, your own claims, unclaimed ready-phase issues, path conflicts, and per-issue verdicts. This is clearly distinguishable from siblings like who_holds or live_sessions, which cover only a subset of this aggregate view.

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 when-to-use is explicit and placed first: call it before claiming or starting an issue. The condition for the self-claim view ("if you pass session_id or branch") is also stated. It stops short of naming an alternative sibling or saying when NOT to call it, so it lands at 4 rather than 5.

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