get_pr_diff

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

Beyond the readOnlyHint and destructiveHint annotations, the description discloses critical runtime behavior: truncation at 100k chars (hard cap 400k), line-boundary truncation, and the response always reporting truncated/returnedChars so truncated output is never mistaken for complete. It also surfaces the Bitbucket timeout behavior. This is substantial added transparency.

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?

Three sentences with no filler. The first sentence states the primary function, the second covers truncation behavior, and the third gives an actionable alternative. Each sentence earns its place and the most important information is 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?

The description covers the return format (plain text), truncation reporting, and timeout handling, which is strong given there is no output schema. It does not clarify the relationship between repo and workspace or the exact meaning of pr_id, but those are inferable from sibling tools and the schema constraints. The only notable gap is the ambiguous repo/workspace schema reference.

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?

With 0% schema description coverage, the description must compensate. It does add meaning for maxChars (default 100k, hard cap 400k) beyond the schema's bare maximum. However, it does not explain repo, pr_id, or workspace, leaving their semantics to inference from names. The unusual '$ref' for repo to workspace is also unaddressed. Partial compensation, but with clear gaps.

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: 'Returns the unified diff for a pull request as plain text.' This clearly distinguishes it from siblings like get_pr_commits (commit list) and get_pull_request (PR metadata). The purpose is immediately identifiable and not a tautology.

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 an explicit when-not scenario: on very large diffs that time out (HTTP 555), it tells the agent to prefer get_pr_commits or a smaller maxChars instead of retrying. This names an alternative and the condition that selects it, satisfying the highest bar for usage guidance.

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