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

Beyond the annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false), the description adds substantial behavior: nothing is committed until the commit tool runs, choices are applied server-side, stale hunk ids are refused, a 512 KiB cap and no-conflict-markers rule apply, and write access plus 'repo' scope are required. The only gap is the response shape, but no output schema exists and the draft semantics largely cover what an agent needs to proceed safely.

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-loaded with purpose, then the three input modes, then the commit/auth caveats — no sentence is filler. It is dense and heavily parenthesized, which makes it harder to parse on a single read, but the density is information rather than padding.

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 9-parameter, nested-object mutation tool with no output schema, the description covers draft state, sha-pinning, input-mode exclusivity, size limits, side-selection rules, auth scope, and the follow-up commit. Nothing material is missing for correct invocation.

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%, but the description adds meaning the schema does not encode: the mutual-exclusivity rule ('pass exactly one of content, choices, or keep'), the size limit on content, the semantics of 'mine' vs 'main' for keep, and the restriction that keep is the only option for binary files and one-side-deleted files. The choices enum values and the custom-lines object form are also spelled out with their server-side application behavior.

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 — saving a resolution for ONE conflicted file of a PR — and immediately scopes it as a draft, which separates it from merjax_commit_pr_conflict_resolution. The capitalized 'ONE' and file-level scope make it unmistakable versus sibling tools.

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 requires the exact (base_sha, head_sha) pair from merjax_list_pr_conflicts and says a moved branch is refused with 'reload', giving the recovery path. It also names the prerequisite listing tool, the AI proposal source (merjax_propose_pr_conflict_resolution), and the follow-up commit tool, so the agent knows both entry and exit of the workflow.

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