Github Get Pr Status Checks

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

Annotations declare readOnlyHint=true and destructiveHint=false, and the description adds significant behavioral context beyond that: pagination caps, the supplemental query drain, and the critical truncation semantics (truncated=True and downgrading 'passing' to 'unknown'). This prevents an agent from acting on an incomplete view.

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 compact and front-loaded: the first sentence states the core purpose, the second covers pagination, and the third covers truncation. The workflow pointer is a minor tangent but useful. No filler, though the unexpanded MAX_* constants could be considered mild jargon.

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?

With an output schema present, return-value details are covered elsewhere. Annotations cover the safety profile. The description fills the remaining operational gaps: pagination limits, the supplemental drain, and the truncation downgrade behavior. An agent has everything needed to invoke this correctly and interpret partial results.

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 0%, so the description must compensate. It explains the tool operates on a PR's HEAD commit and implicitly maps repo_owner, repo_name, and pr_number to identifying the PR. The three parameters are self-descriptive names, so the description adds enough meaning without needing explicit per-parameter docs.

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 states a specific verb and resource: 'Return the CI check runs and commit status for a pull request's HEAD commit.' This clearly distinguishes it from sibling tools like github_get_pr_content (which fetches content) and github_get_pr_diff (which fetches diffs).

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 'Workflow and conventions' sentence points the agent to github_get_skill('pr-analysis'), which provides when/where to use this tool. It does not explicitly name alternatives or give negative usage guidance, but the workflow pointer is clear and actionable context.

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