github_list_pull_request_files

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

Beyond the annotations (readOnly, idempotent, non-destructive), the description reveals two behaviors: it verifies the head SHA before and after reading, and it returns null patch values for binary or unavailable diffs. These add meaningful context about reliability and edge cases, fully satisfying the transparency requirement given the existing annotations.

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 sentences pack the core purpose, the pagination rule, the SHA verification, and the null-patch behavior with zero redundancy. The most important information (what the tool reads) is front-loaded, and every sentence earns its place.

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 paginated read tool with no output schema, the description covers the key aspects: the content returned (metadata and patches), the pagination signal (hasNextPage), and a common edge case (binary/unavailable diffs). It does not spell out the exact response shape (e.g., field names like 'files' or 'hasNextPage'), but the essential information is present.

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?

The input schema already fully documents all four parameters (100% coverage), so the baseline is 3. The description adds value by explaining the pagination loop (use consecutive page values) and that the page is tied to a review run, giving the page parameter practical usage context beyond its schema description. This lifts it to a 4.

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 ('Read'), a precise resource ('one 100-file page of changed-file metadata and GitHub-provided text patches'), and the binding condition ('bound to a review run'). This clearly distinguishes it from sibling tools like github_get_pull_request or github_get_pull_request_checks without naming them.

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 gives explicit pagination guidance ('Use consecutive page values until hasNextPage is false') and clarifies the review-run binding, which provides clear context for when to use this tool. However, it does not explicitly contrast itself with alternatives or state when not to use it, so it stops short of the full 5.

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