get_pull_request_changes

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

With no annotations provided, the description carries the burden of behavioral disclosure. It implies a read-only operation by saying 'Get list', but it does not mention pagination or the fact that the 'limit' parameter may prevent returning 'all' files for large PRs. The description could be more transparent about this edge case.

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, concise sentence that front-loads the core purpose and includes the key output details. No unnecessary words or repetition.

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?

The description explains the output fields (paths and change types) but omits the pagination behavior tied to the 'limit' parameter. Since there is no output schema and no annotations, the description leaves a gap about how many files are actually returned and how to page through results. Given the tool's complexity, this is incomplete but not severely so.

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 100%, so the schema already documents all four parameters. The description does not add any additional meaning to the parameters; it only describes the response. Therefore, it meets the baseline without adding extra value.

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 that the tool lists all changed files in a pull request with file-level metadata such as paths and change types. It uses a specific verb and resource and distinguishes itself from siblings like get_pull_request_diff and get_pull_request_file_diff by focusing on the file list rather than diff content.

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 its use case: when you need the list of changed files and their metadata, not the actual diff. It does not explicitly name alternatives or state when not to use it, but the clear scope and sibling context provide adequate guidance.

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