Github Update Pr Branch

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

The description discloses a behavioral safety mechanism beyond the annotations: providing expected_head_sha causes the tool to refuse rather than overwrite. This complements the idempotentHint and destructiveHint annotations, which already cover safety, explaining the guard behavior in context.

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 two sentences with no filler. The core action comes first, followed immediately by the practical instruction for safe invocation. Every clause 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?

The definition covers the essential flow (fetch head_sha, pass as expected_head_sha) and the output is already detailed in an output schema. With annotations and schema present, nothing critical for correct invocation is missing.

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 only 25%, but the description compensates by explaining that expected_head_sha should be sourced from the head_sha of github_get_pr_content and why it matters. The other three parameters are self-explanatory from their names, though not elaborated.

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 opens with a concrete verb-object statement, 'Updates the pull request branch with the latest upstream changes,' which names the exact resource and action. This clearly distinguishes the tool from siblings like github_update_pr or github_merge_pr, which cover different PR operations.

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 practical step-by-step guidance: 'Read head_sha from github_get_pr_content and pass it as expected_head_sha' to avoid overwriting a concurrent push. This is strong usage instruction, though it does not explicitly compare against alternative PR-update tools.

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