PR readiness

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

Goes well beyond the readOnly/destructive annotations: it defines the four verdict values and their exact preconditions, discloses that the tool is 'Stricter than the merge button' (optional failing/running checks also block), and classifies which reason codes mean 'cannot verify yet' versus genuine obstacles. It also states the negative capability boundary ('never merges, publishes a draft, pushes or rewrites history') and the error envelope shape {code, message, retryable, retry_after_seconds?}.

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 a single-sentence purpose, then ordered as when-to-use, verdict semantics, reason codes, safety boundary, errors, example — a sensible reading order. It is dense and somewhat long, and lines like 'Ready, green, merged and done are different words' shade into coaching, but each block carries operational weight.

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 two-parameter verification tool with an output schema, virtually nothing an agent needs is missing: verdict meanings, blocking conditions, reason-code taxonomy, owner semantics, error format, and a concrete call example. Even though an output schema exists, the verdict vocabulary is explained in prose where it matters most.

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; the description earns an increment by tying the sha parameter to a concrete workflow (pass the full sha from `git rev-parse HEAD` after your push) and surfacing the stale_head consequence in the verdict vocabulary. Much of this duplicates the schema's own field descriptions, so it is reinforcement rather than new information.

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 ('Check whether a GitHub pull request is verified ready to merge') and adds the source qualifier 'from live GitHub data', which signals freshness rather than cached state. An agent knows exactly what it gets back — a verification verdict, not a generic PR fetch.

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?

Explicit invocation timing is given three ways: 'before you say a PR is ready, green, mergeable or done', 'after every push', and 'again immediately before any final claim'. It also names the alternative behaviour it replaces (asserting readiness without verification) and specifies the expected_head_sha workflow with `git rev-parse HEAD`.

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