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

Adds substantial behavior beyond annotations: each reported worktree creates a provisional hold, the hold is visible as `hold`, automatic dispatch withholds it, it is not a lease, lacks a token, expires after 60 minutes, and an explicit claim converts it. These details align with the annotations rather than 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?

Front-loads the critical machine-tool/proxy-only framing, then uses the remaining sentences for necessary hold semantics. The length is justified by the complexity of the side effects and lifecycle.

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?

Covers caller, scope, side effects, hold lifecycle, dispatch behavior, claim interaction, and exclusions. With no output schema, this is enough for an agent to understand why it should not call the tool and what would happen if it did.

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 field-level meaning is already documented. The description still adds useful input semantics by specifying that only unclaimed `rtsc-NN/<slug>` worktrees should be reported and by listing what is ignored: already claimed, terminal, `work:false`, or out-of-project items.

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 and resource (report git worktrees) and immediately identifies the caller as the mcp-proxy rather than an agent. This clearly distinguishes it from agent-facing sibling tools like claim_issue and next_issue.

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?

Explicitly says the proxy calls this on its own and an agent never needs to, which is a clear when/when-not instruction. It also explains interactions with claim_issue, next_issue, next_batch, and check_claim, leaving little ambiguity.

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