Get exact-head pull request merge requirements

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the description doesn't need to repeat that. It adds valuable context beyond annotations: 'Missing policy visibility or head movement is reported as incomplete evidence and never interpreted as no requirement.' This clarifies how the tool handles uncertain data, which is not obvious from annotations alone.

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 description is a single dense sentence that efficiently enumerates the aggregated components without redundancy. It front-loads the 'Read-only' nature and then lists all policy aspects. Every word earns its place, making it concise yet comprehensive.

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?

Given the tool's complexity (aggregating six different aspects) and the existence of an output schema (which likely defines the full response structure), the description covers the key inputs and outputs adequately. It also includes the critical caveat about incomplete evidence handling, making it sufficiently complete for an agent to understand what to expect.

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% as all parameters have descriptions. The tool description doesn't add additional parameter semantics beyond what the schema already provides. It mentions 'expected pull-request head' but that's a restatement of expected_head_sha's description. The description adds no extra nuance to parameters, so baseline 3 is appropriate.

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?

The description clearly states what the tool does with specific verbs and resources: 'aggregate effective branch/ruleset merge policy, current required checks, exact-head review/thread state, base freshness, mergeability, and allowed merge methods'. It distinguishes itself from sibling tools like gh_get_pr_checks or gh_get_pr by focusing on a comprehensive merge requirements aggregation for an exact head SHA.

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 description implies when to use it ('for one expected pull-request head') and includes a critical behavioral caveat about missing policy visibility, which helps the agent decide based on incomplete evidence. However, it doesn't explicitly name alternative tools or state 'use this instead of X', though the sibling context makes the distinction clear.

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