list_pull_request_files

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. The description does not state whether this is a read-only operation (it presumably is, given the name), whether authentication is required, any pagination behavior, rate-limit implications, what the max_items parameter does in practice, or the return format. It's a read operation with zero annotation coverage and no behavioral context added.

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, complete sentence with zero fluff: 'List changed files in a pull request.' It's appropriately sized relative to its simplicity. However, it may be slightly under-specified given there are 4 parameters including a default owner field and a max_items limit that aren't explained. Still, for its length, it's efficient and front-loaded.

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?

There is an output schema present, which shifts some burden away from the description. But the tool has 4 parameters at 0% schema description coverage, no annotations, and no behavioral context. For a GitHub pull request file-listing tool, the description could reasonably mention pagination/limiting behavior (max_items default of 300) or the owner/repo relationship default. As-is, it's a minimal but not entirely inadequate description for a simple listing tool.

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%, meaning the description adds nothing about any of the 4 parameters. The baseline for compensating for low coverage would be to explain parameters, but none are described. However, the parameter names (repo, owner, pull_number, max_items) are fairly self-descriptive for a GitHub API context, which slightly mitigates the gap. The description adds essentially no semantic value beyond what the schema already presents, so the score reflects the low coverage without the compensation the guidance advises.

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 'List changed files in a pull request' has a specific verb (list) and resource (changed files in a pull request), which is clear enough. However, it does not distinguish this from siblings like list_pull_requests, get_pull_request, or list_pull_request_reviews, all of which also relate to pull requests. The purpose is clear but not uniquely differentiated among closely related siblings.

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?

No guidance is provided on when to use this tool versus alternatives. There's no mention of when listing changed files is the appropriate operation, what scenarios call for it, or how it differs from other list_* siblings in the same GitHub context. The agent must infer usage from the name and description alone. Some implied context exists (it's for changed files in a PR), but no explicit exclusions or alternative recommendations.

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