pi_merge

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

With no annotations, the description carries the full burden and does well: it discloses the merge strategy (--no-ff), the two refusal preconditions, and conflict behavior (aborts and reports). It omits what state the worktree/branch is left in after abort and whether the commit is unconditional, leaving a small gap.

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?

Two tight sentences with zero filler; the action is front-loaded and the failure semantics follow immediately. Every clause carries information.

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 mutation tool with no annotations and no output schema, the description covers preconditions and failure modes adequately. It could say more about post-merge state and what the success response contains, but an agent has what it needs to invoke it correctly.

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 both parameters are documented there ('worker id from pi_spawn', 'merge commit message'). The description adds no format or behavioral detail about id or message, so the baseline 3 applies.

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 precise compound action: commit a finished worker's worktree changes and merge its branch (--no-ff) into the spawning repo. The verb+resource is unambiguous and the 'worker' framing separates it from generic git tools and from siblings like pi_cleanup or pi_diff.

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?

Clearly scopes usage to a 'finished worker' and gives explicit preconditions under which it refuses (worker still running, main tree has tracked changes). It does not name a sibling alternative (e.g. pi_cleanup for discarding work), so it falls just short of the explicit when-not/alternative bar.

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