update_pull_request

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

No annotations are provided, so the description carries the full burden. It discloses the optimistic locking behavior via the version parameter and explains that leaving fields empty or None means keep current. It does not mention potential side effects like notifications or draft status implications, but for a straightforward update tool the transparency is adequate.

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 well-structured: a brief introductory sentence followed by a clear parameter list. With 9 parameters, the list is necessary but not overly verbose. It is front-loaded with the purpose. Minor room for improvement: could combine the parameter list into a more compact format.

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 essential aspects: what the tool does, the required version parameter, and the behavior of optional parameters. It does not need to describe the output schema. It could mention that project_key, repo_slug, and pr_id identify the repository and pull request, but the schema already provides those as required fields. Overall, it is fairly complete for a mutation 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?

The input schema has 0% coverage with no parameter descriptions. The description compensates by listing all arguments and explaining each one's meaning and behavior (e.g., 'Current version of the PR (required for optimistic locking)', 'New description (None to keep current, empty string to clear)'). This adds significant value beyond the schema.

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 'Update a pull request's title, description, reviewers, target branch, or draft status.' It specifies the verb 'Update' and the resource 'pull request', and lists the specific attributes that can be modified. This distinguishes it from sibling tools like update_pull_request_comment and update_pull_request_task.

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 provides clear context for when to use this tool: when updating any of the listed PR fields. It also explains the requirement for the version parameter for optimistic locking and advises to get it from get_pull_request. However, it does not explicitly state when not to use it or contrast with alternatives like approve or merge PR tools.

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