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

No annotations are provided, so the description must carry the full burden of behavioral disclosure. It only states the intended effect and does not mention idempotency, behavior when the user is already a default reviewer, required permissions, or any side effects.

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, clear sentence with no filler or redundant phrasing. It is appropriately sized for a simple operation and front-loads the core action and scope.

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?

For a simple two-parameter mutation, the description is mostly adequate, and the schema documents the required inputs. However, with no output schema and no annotations, the description omits behavioral context such as return values, error conditions, and permission requirements, leaving some gaps for an agent.

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 both parameters (username and repo_slug) are already meaningfully documented. The description adds minimal semantic context by clarifying the user is added as a 'default reviewer' and the repository is the target, but does not go beyond the schema's baseline.

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 ('Add') and resource ('user as default reviewer for the repository'), making the intended action unambiguous. It clearly differs from sibling tools like list_default_reviewers, get_default_reviewer, and remove_default_reviewer by describing the write action.

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 no guidance on when to use this tool versus alternatives, nor does it mention prerequisites, permissions, or repository context. The sibling tool names imply the category of default-reviewer operations, but the description does not explicitly explain when adding is appropriate.

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

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

With no annotations, the description carries the burden of explaining behavior. It clearly conveys the primary side effect: posting a comment. However, it does not disclose whether permissions are required, whether the comment is posted as the authenticated user, whether the operation is reversible, or what the response contains.

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 with no filler. It front-loads the action and format, earning its place entirely.

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?

For a simple three-parameter mutation tool, the description gives enough to understand the tool's core purpose, but it omits any mention of return value, required permissions, or side effects beyond posting. Since there is no output schema and no annotations, slightly more context would improve completeness.

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 already documents repo_slug and pr_id, and content is left generic. The description adds meaningful semantics by specifying that content should be a Markdown comment, which clarifies the otherwise undocumented content parameter and partially compensates for the 67% schema coverage.

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 uses a specific verb (Post), a clear resource (comment on a pull request), and notes the Markdown format. This clearly separates it from sibling tools like list_pr_comments, get_pr_comment, and update_pr_comment, since 'Post' unambiguously means creating a new comment.

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 states the action but gives no guidance on when to choose this tool over alternatives such as update_pr_comment or resolve_pr_comment. It does not mention that this is only for new comments, nor does it exclude cases where a comment already exists.

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

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. 'Approve a pull request' names the action but does not explain side effects, permissions required, whether the PR must be open, whether approval is idempotent, or what happens to existing approvals.

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 with no wasted words and is easy to parse quickly. However, it is so terse that it contributes little behavioral or contextual information beyond the tool's name.

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?

With no output schema and no annotations, the description is the only source of context, but it only states the action. It omits the approval workflow context, possible results, required reviewer role, and constraints such as not approving one's own pull request.

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 already documents both parameters with 100% coverage, so the description does not need to add param-level detail. The description provides no additional semantics beyond the schema, so the baseline score of 3 is appropriate.

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 uses a specific verb ('Approve') and resource ('pull request'), so an agent can clearly tell this tool performs a code-review approval action. It does not explicitly contrast it with siblings like unapprove_pull_request or request_pr_changes, but the core purpose is unambiguous.

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 no guidance on when to use this tool versus alternatives such as unapprove_pull_request, request_pr_changes, or merge_pull_request. There are no conditions, prerequisites, or exclusions mentioned.

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

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

With no annotations, the description carries the full burden for behavioral disclosure. It only states the basic create action and does not mention side effects, validation rules, required permissions, branch handling, or response behavior. It adds no behavioral context beyond what the tool name already conveys.

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 short sentence, so it is concise in size, but it is essentially a restatement of the tool name and provides not additional structured guidance. For a tool with 7 parameters and 23 sibling operations, this is underspecification rather than effective conciseness.

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 tool has 7 parameters, no output schema, and no annotations, yet the description is only one generic sentence. It misses important operational context such as when to choose this over update/merge/decline, prerequisites like branching or permissions, and any post-create behavior. This is incomplete for reliable agent invocation.

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 71%, so the input schema already documents the meaning of most parameters. The tool description itself adds no parameter-specific information, but the schema provides enough semantic grounding for the required fields. Thus the baseline of 3 is appropriate.

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?

Description states a clear action and resource: 'Create a new pull request'. This distinguishes it from sibling read/update/merge/decline operations in the sibling list. However, it does not add any distinguishing detail beyond the tool name itself.

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 like update_pull_request or merge_pull_request. The phrase 'a new pull request' implies the creation case but gives no explicit context, prerequisites, or exclusions.

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

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. It only names the action without explaining what declining does to the pull request, whether it is reversible, or what side effects occur.

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 one short, front-loaded sentence with no filler words. The parenthetical 'reject' reinforces intent without adding unnecessary length.

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?

For a mutation tool with no annotations and no output schema, the description is too thin. It does not disclose consequences, prerequisites beyond 'open', permissions, reversibility, or what the caller should expect after invocation.

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 covers 100% of parameters, so the schema already documents repo_slug, pr_id, and message. The description adds no parameter-level meaning beyond the core intent, which is acceptable given full schema coverage.

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 ('Decline (reject)') and a specific resource ('an open pull request'), making the operation immediately recognizable. It also distinguishes this tool from siblings like merge_pull_request, approve_pull_request, and request_pr_changes by naming a distinct action.

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 phrase 'an open pull request' implies the valid target state and gives some contextual guidance. However, it does not explicitly say when to prefer this over request_pr_changes or merge_pull_request, nor does it mention any exclusions.

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

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

No annotations are present, so the description must carry the full burden. It only says 'Get', which implies a read-only operation, but it does not disclose side effects, required permissions, error behavior, or what happens when no matching default reviewer exists. The description adds no behavioral context beyond the verb itself.

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 focused sentence with no filler and the key word 'specific' is front-loaded. It is concise, though slightly under-specified for usage and behavior.

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?

For a simple two-parameter getter, the description plus fully documented schema is minimally workable. But with no output schema and no annotations, the description omits return-value shape and error behavior, so it is not complete.

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 coverage is 100% and both parameters already have descriptions ('Bitbucket username' and 'Repository slug'), so the schema carries the parameter documentation. The description adds little beyond 'specific,' which is consistent with username being the lookup key.

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 says the action ('Get') and the resource ('a specific default reviewer'), and 'specific' distinguishes it from sibling list_default_reviewers. It does not explicitly say that the username parameter selects the reviewer, but that is clear from the required parameters.

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 word 'specific' implies use when the agent already knows the target reviewer via username, rather than when enumerating all default reviewers. However, it never names list_default_reviewers or add/remove_default_reviewer, so the when-not-to-use guidance is left to inference.

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

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

With no annotations provided, the description carries the behavioral disclosure burden. It explicitly reveals the non-obvious truncation to 8 KB and identifies the output format as a unified diff. It does not comment on side effects, but 'Get' reasonably implies a read operation.

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?

A single, front-loaded sentence conveys the core action, the target resource, and the important truncation caveat without wasted words. Every element 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?

For a simple two-parameter read tool, the description covers purpose, output type, and the main limitation. It lacks explicit mention of read-only guarantees or behavior when the diff exceeds the truncation limit, but these are minor gaps for this complexity level.

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?

Both parameters are already fully described in the input schema: pr_id as 'Pull request ID' and repo_slug as 'Repository slug'. The tool description adds no parameter-level meaning beyond this, so the baseline score of 3 applies.

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 uses a specific verb and resource: 'Get the unified diff for a pull request.' It clearly distinguishes from sibling tools like get_pull_request by specifying the diff output and adding the unique truncation behavior.

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 the clear usage context: retrieve the patch/diff content for a pull request. However, it does not explicitly name alternatives or state when not to use this tool, so it falls short of full guidance.

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

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

There are no annotations, so the description carries the full burden of disclosing behavior. It states only 'Get', which implies a read operation, but does not disclose return format, error behavior, authentication needs, or whether the comment is a general PR comment or an inline review comment. This is a clear gap for a tool with no structural safety hints.

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?

A single sentence with no wasted words, completely front-loaded and easy to parse. It contains exactly one clause that names the operation and the resource.

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 is minimally sufficient for a simple fetch-by-ID operation, and all three required parameters are documented in the schema. However, without annotations or an output schema, important context is missing: what the returned comment object looks like, whether the comment may be unresolved or deleted, and how it relates to list_pr_comments. An agent could invoke it correctly, but it would be guessing about the response.

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%, with repo_slug, pr_id, and comment_id each carrying a short description. The description adds no additional meaning to parameters, so it rightfully rests on the schema's definitions; the baseline of 3 applies because the schema does the heavy lifting.

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 uses the specific verb 'Get' with a clear resource ('a specific comment on a pull request'), and the word 'specific' distinguishes it from list_pr_comments among siblings. However, it does not explicitly name the alternative or state the unique identifier that selects the comment, so it stops short of the level of differentiation seen in the highest-caliber definitions.

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 given about when to use this tool versus alternatives such as list_pr_comments, add_pr_comment, or update_pr_comment. There is no mention of prerequisites, exclusions, or context that would tell an agent which sibling to choose; the usage context is only implicit from the brevity of 'Get a specific comment'.

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

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

There are no annotations, so the description must carry the behavioral burden. The verb 'Get' signals a read-only operation and 'full details' suggests a comprehensive response, but the description does not disclose not-found behavior, response shape, or other caveats. Core behavior is clear, but depth is limited.

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 front-loaded sentence with no filler. 'Full details' and 'specific' add meaning beyond the tool name, and it is appropriately concise for a simple retrieval operation.

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?

For a low-complexity read tool with two well-documented parameters, the description is largely sufficient: it states the operation and target resource. However, with no output schema and no annotations, response contents and selection guidance are left somewhat implicit.

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 coverage is 100%, and both parameters already have meaningful descriptions: repo_slug is 'Repository slug' and pr_id is 'Pull request ID'. The tool description adds no extra parameter-level meaning, so the baseline score of 3 applies.

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 ('Get') and resource ('pull request'), and the phrase 'full details of a specific pull request' clearly differentiates this from list_pull_requests and other PR-level operations. It is unambiguous about what the tool does.

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 the tool is for retrieving one pull request's details rather than listing PRs or getting a diff, but it provides no explicit when-to-use guidance or alternatives. An agent must infer usage from the word 'specific' and the tool name.

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

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

No annotations are present, so the description carries the full burden of behavioral disclosure. It does not mention pagination, return format, authentication needs, or any potential side effects; 'list' only implies a read-only operation.

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, clear sentence with no filler or redundant wording. It is appropriately front-loaded with the primary action and object.

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?

For a simple listing tool, the description is minimally viable but leaves gaps: there is no mention of pagination behavior, output shape, or the optional search capability. Since no output schema exists, slightly more context would be valuable.

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 schema already documents repo_slug and search, and the description adds no parameter-specific meaning. The page parameter lacks any description and is not explained in the tool description either, leaving its behavior implicit.

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 ('List') and resource ('branches') within a repository, making the core purpose clear. It is distinct enough from sibling tools like list_repositories and list_pull_requests, though it does not explicitly differentiate itself.

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. The context is only implied by the word 'branches', and no exclusions or conditions for choosing another tool are mentioned.

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

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

No annotations are provided, so the description carries the full burden. 'List' implies a read-only operation, and the parenthetical explains what default reviewers are, but the description does not disclose response format, pagination, error conditions, or permission requirements. For a simple list operation this is acceptable but not rich.

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, direct sentence with no filler. It front-loads the core action and resource, and the parenthetical adds useful context without bloating the text.

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 tool is simple: one required parameter, no nested objects, and no output schema. The description fully identifies what the tool does and the parenthetical clarifies the domain meaning of the results. Minor gaps like return format or empty-result behavior are not critical given the tool's simplicity.

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 schema has full 100% description coverage for the single parameter repo_slug, already stating it is a 'Repository slug'. The tool description adds no additional parameter-level meaning, so the baseline score of 3 is appropriate.

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 ('List') and resource ('default reviewers for a repository') and adds a clarifying parenthetical that these are auto-added to new PRs. It is clearly distinguishable from sibling tools like get_default_reviewer, add_default_reviewer, and remove_default_reviewer.

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 clearly frames the tool's context: it lists the default reviewers configured at the repository level. It does not explicitly call out sibling alternatives or state when not to use it, but the read-only 'list' phrasing distinguishes it naturally from the add/remove/get sibling tools.

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

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

With no annotations, the description carries the full behavioral burden but only restates the operation. It does not disclose that results are paginated via the page parameter, what 'all' means with respect to pagination, or any ordering/return behavior. It is not misleading, but it reveals little beyond the basic action.

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?

A single concise sentence, front-loaded with the verb and object, with no filler. Every word 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?

For a list tool with no output schema and no annotations, the definition should at least explain pagination and return shape. The missing page semantics and lack of usage context leave an agent guessing how to retrieve the full set of comments.

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 schema already describes repo_slug and pr_id, but the page parameter has no description and the tool description does not compensate. The phrase 'all comments' suggests broad scope but never explains how page interacts with retrieving all comments, leaving an agent unsure whether one call or multiple paged calls are needed.

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 uses a specific verb ('List') and identifies the exact resource ('comments on a pull request'). The word 'all' helps distinguish it from single-comment tools like get_pr_comment, and the overall purpose is immediately clear.

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 given about when to use this tool versus siblings like get_pr_comment, add_pr_comment, or list_pull_requests. The usage context is only implicit in the verb 'List', with no exclusions, prerequisites, or alternative routing.

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

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

No annotations are provided, so the description is the only source of behavioral information. It conveys a read-only 'list' action but omits pagination behavior, permissions, ordering, or any indication of what the returned statuses contain, leaving significant behavior undisclosed.

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 front-loaded sentence with no filler. Every word contributes to identifying the action and resource.

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?

For a tool with no annotations and no output schema, the description is too thin. It does not mention pagination, the page parameter's role, or any return-value details, so an agent could under-specify a request or miss statuses beyond the first page.

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 schema coverage at 67%, pr_id and repo_slug are already documented, and the description adds no parameter-specific meaning. The optional page parameter is entirely unexplained, so an agent has no guidance on how pagination works or when to set it.

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 uses a specific verb ('List') and names the exact resource ('commit/build statuses for a pull request'), which clearly separates it from sibling tools like list_pull_requests and list_pr_comments.

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 resource scope provides implied usage context: use this whenever commit/build statuses for a PR are needed. It does not explicitly name alternatives or state when not to use it, so guidance is present only by inference.

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

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

No annotations are present, so the description carries the full burden of behavioral disclosure. It conveys that this is a listing operation but does not disclose pagination behavior, the default OPEN state filter, or any response characteristics; no meaningful behavioral context is added beyond the verb 'list'.

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 front-loaded sentence with no filler or redundant wording. Every word contributes to identifying the operation, making it highly concise for the intended purpose.

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?

For a tool with no output schema and no annotations, the description is too thin: it omits when to use it versus the many PR-related siblings, does not describe return values, and leaves pagination and filtering behavior implied. An agent can infer the basic call but cannot confidently distinguish it or handle edge cases.

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 description only echoes the repository scope via 'for a repository' and adds no meaning for the page or state parameters. With only 33% schema description coverage, the description does little to compensate for the poorly documented parameters.

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 uses a specific verb ('List'), resource ('pull requests'), and scope ('for a repository'), making the core operation clear. It does not explicitly distinguish itself from siblings like get_pull_request or list_pr_comments, though the plural 'pull requests' implies a collection-level listing.

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?

There is no guidance on when to choose this tool over alternatives such as list_pr_comments, get_pull_request, or list_repositories. The description simply restates the operation and leaves tool selection entirely to the agent's inference.

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

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

Annotations are absent, so the description carries the full burden of behavioral disclosure. It adds a useful scope qualifier ('configured workspace') but does not clarify pagination behavior, and 'all repositories' is potentially misleading given the page parameter. Read-only intent is implicit in the verb 'List', but details like output shape and ordering are left unstated.

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 front-loaded sentence with no filler words. Every term ('List', 'all', 'repositories', 'configured workspace') contributes meaning. It is compact, scannable, and appropriate for a simple list operation.

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?

Given no annotations and no output schema, the description leaves gaps around pagination and the exact shape of returned repository objects. The phrase 'all repositories' is ambiguous with the optional page parameter—an agent may not know whether one call returns everything or requires iterating pages. It is adequate for a simple listing but not fully complete for safe autonomous invocation.

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 schema provides 100% description coverage for both 'page' and 'search', so the baseline is 3. The description adds no parameter-specific context beyond what the schema already documents, such as how search interacts with the 'all repositories' claim. It does not harm clarity, but it also does not elevate it.

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 uses the specific verb 'List' with the resource 'repositories' and the scope 'configured workspace'. It is immediately distinguishable from sibling tools such as list_branches and list_pull_requests, which operate on different resources. The purpose is unambiguous and needs no inference.

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 explicit guidance is provided about when to use this tool over alternatives, nor does it mention exclusions. The context of sibling tools strongly implies that this is the tool for listing repositories, but that is inferred rather than stated. The description would benefit from a brief note such as 'use this for workspace-level repository listing, not for branch or PR listing'.

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

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

There are no annotations, so the description carries the transparency burden. It does disclose a useful non-obvious behavior: omitting merge_strategy uses the repository's configured default, falling back to merge_commit. However, it does not mention side effects such as whether the source branch gets closed, failure conditions for mergeable PRs, or whether the merge is reversible.

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?

A single front-loaded sentence conveys the core action and the most important parameter nuance in a parenthetical, with no filler. Every part of the description 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 tool has no annotations and no output schema, and the description does not state return values, error/failure conditions, permissions, or side effects of merging. For a 5-parameter mutation tool, this leaves an agent without enough context to fully predict outcomes or handle failures.

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 schema covers repo_slug, pr_id, and message but leaves merge_strategy and close_source_branch underdocumented. The description adds meaningful semantics for merge_strategy by explaining the defaulting behavior when omitted, but it does not clarify close_source_branch or message beyond what the schema already provides, so it only partially compensates for the coverage gap.

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 uses a specific verb ('Merge') and resource ('an open pull request'), which clearly distinguishes it from sibling PR lifecycle tools like update_pull_request, decline_pull_request, and approve_pull_request. An agent can immediately understand the core operation this tool performs.

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 states that the PR must be open but provides no guidance on when this tool is preferred over alternatives such as decline_pull_request or update_pull_request. No prerequisites or decision criteria are given; any usage direction is only implicit in the tool's name.

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

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. It only says 'Remove' without explaining side effects, idempotency, error behavior, or auth requirements. This is a meaningful gap for a mutating operation.

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, front-loaded sentence with no filler words. It states exactly the operation and object in minimal space.

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?

For a simple two-parameter mutation with no output schema, the description names the action and object adequately. However, it omits behavior around removal failure, repeated removal, and whether this affects only the given repository, leaving some context for the agent to infer.

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%, with both username and repo_slug documented by name. The description adds little beyond the schema, but because the schema already explains the parameters, baseline 3 is appropriate.

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 uses a specific verb ('Remove') with a clear object ('a user from default reviewers'), which distinguishes this tool from its siblings list_default_reviewers, get_default_reviewer, and add_default_reviewer. No ambiguity remains about the primary action.

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 no guidance on when to use this tool versus the related add/list/get default reviewer tools. It does not state prerequisites, such as whether the user must currently be a default reviewer, nor does it mention any exclusions or alternatives.

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

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

With no annotations, the description must carry the behavioral burden. It clearly discloses the core state transition (resolved -> open), which is meaningful. It does not disclose permissions, idempotency, or behavior on already-open threads, but the single state change is adequately communicated.

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 front-loaded sentence with no filler. Every word contributes to identifying the action and target.

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?

For a simple three-parameter state-transition tool, the description plus fully documented schema is nearly sufficient. It could be improved by explicitly naming the inverse sibling or noting that the thread must already be resolved, but nothing blocks correct invocation.

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 coverage is 100%, and all three parameters (repo_slug, pr_id, comment_id) already have baseline descriptions. The tool description adds no extra parameter semantics beyond what the schema provides, so the baseline of 3 applies.

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 names a specific verb ('reopen') and a precise resource ('resolved comment thread on a pull request'), making the tool's action unambiguous. It also distinguishes itself from the sibling resolve_pr_comment by inversion without needing to name it.

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 phrase 'resolved comment thread' implies the intended use case: reopening a thread that was previously resolved. However, it does not explicitly state when not to use it or point to alternatives such as resolve_pr_comment or update_pr_comment.

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

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

No annotations are present, so the description carries the full burden. It does not disclose whether this action changes the PR review state, requires reviewer permissions, is reversible, or whether a message is expected. The behavioral impact beyond the phrase 'request changes' is left entirely implicit.

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 with no filler or redundant wording. It is efficient, though it does sacrifice behavioral detail for brevity.

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?

For a mutating review action with no annotations and no output schema, the description is too sparse. It does not explain the effect on the pull request, how it relates to sibling review actions, or what additional context the agent should consider before invoking it.

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 parameters are already documented. The description adds no extra meaning about message intent, pr_id usage, or repo_slug context, but it does not need to because the schema handles parameter semantics.

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 the verb and resource: it requests changes on a pull request. It is distinct enough from obvious siblings like approve_pull_request, but it does not explicitly differentiate itself from update_pull_request or add_pr_comment.

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?

There is no guidance on when to use this tool versus alternatives such as approve_pull_request, unapprove_pull_request, or add_pr_comment. The agent must infer usage from the tool name alone.

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

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

No annotations are provided, so the description carries the full burden. 'Resolve' implies a state-changing mutation, but the description does not disclose side effects, reversibility, required permissions, or what happens after resolution. This is a minimal behavioral disclosure.

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, focused sentence with no filler or repetition. It front-loads the action and resource clearly, and every word contributes meaning.

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 tool is simple with three fully documented required parameters and no output schema. The description is adequate for basic invocation, but it omits behavioral details such as whether resolution is reversible and how the action relates to reopen_pr_comment. Minimum viable, but with clear gaps.

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 repo_slug, pr_id, and comment_id. The description adds little beyond the term 'thread', which hints that comment_id identifies a thread rather than an arbitrary comment. This meets the baseline but adds no substantial semantic 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 the specific verb 'Resolve' and the resource 'comment thread on a pull request'. This distinguishes it from siblings like add_pr_comment, update_pr_comment, and reopen_pr_comment, which all have distinct actions.

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 usage is implied by the verb and resource: use this when you want to mark a comment thread as resolved. However, the description does not explicitly contrast it with reopen_pr_comment or state when not to use it, so an agent must infer the selection context.

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

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

With no annotations provided, the description carries the behavioral burden. It clearly discloses that the tool removes an existing approval and scopes the operation to the user's own approval. Some details like behavior when no approval exists are absent, but the core mutating behavior is transparent.

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, focused sentence with no redundant words. It front-loads the action and delivers complete information efficiently.

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?

For a simple two-parameter mutation with full schema coverage and no output schema, the description provides all essential context needed to invoke the tool correctly. Nothing material 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 100%, and both parameters have straightforward schema descriptions (repo_slug and pr_id). The tool description adds no parameter-specific semantics, but the schema already documents them adequately, so a baseline score of 3 is appropriate.

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 uses a specific verb ('remove') and resource ('your approval from a pull request'), making the action unambiguous. It also clearly differentiates from the sibling approve_pull_request by stating the opposite operation.

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 phrase 'your approval' provides clear context for when this tool should be used: to withdraw an approval the current user previously gave. It does not explicitly name alternatives, but the intended use is evident from the wording.

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

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. It only says 'Update a comment' without mentioning whether the entire content is replaced, whether permissions are required, whether the operation is reversible, or what the response contains. For a mutating tool, this is a significant gap.

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, clear sentence with no wasted words. It is front-loaded with the action and resource, but it is slightly under-specified for a mutation tool with no annotations or output schema.

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?

Given the lack of annotations, lack of an output schema, and the existence of closely related sibling tools, this description is not complete enough for an agent to confidently invoke it. It does not explain how the update behaves, what it returns, or when it should be chosen over other comment-related tools.

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 already documents all four parameters with descriptions and 100% coverage, so the description need not add parameter details. The description does not contribute additional meaning beyond the schema, but the baseline of 3 is appropriate when the schema handles parameter documentation.

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 ('Update') and resource ('a comment on a pull request'), which clearly identifies the core operation. It is distinguishable from siblings like add_pr_comment, get_pr_comment, and resolve_pr_comment, though it does not explicitly specify that it updates the comment's content rather than its state.

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?

There is no guidance on when to use this tool versus alternatives such as add_pr_comment, resolve_pr_comment, or reopen_pr_comment. The verb 'Update' implies modifying an existing comment, but no explicit context or exclusions are provided.

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

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

No annotations are provided, so the description carries the full behavioral disclosure burden. It only says 'Update' and lists fields; it does not reveal whether the reviewers list replaces or appends, whether empty strings clear title/description, whether the PR must be open, or what side effects occur if the update partially fails. For a mutating tool this is a significant gap.

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?

A single sentence with no filler; the key scope (update pull request, fields affected) is front-loaded and every word contributes. It is appropriately sized for this simple tool.

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?

Given the lack of annotations and output schema, a 5-parameter mutating tool should provide more context. The description does not cover required identifiers, return value, validation rules, or post-update effects. It is minimally usable but incomplete for safe invocation.

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 40%, and the description partially compensates by listing title, description, and reviewers as the updatable fields, which adds some semantic role to those bare schema properties. However, it does not explain nuances like the format of reviewer identifiers, allowed combinations, or whether at least one optional field must be supplied.

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 names a concrete verb ('Update'), a specific resource ('a pull request'), and the exact editable fields ('title, description, or reviewers'). This distinguishes it from sibling tools like create_pull_request, merge_pull_request, and decline_pull_request without requiring the agent to inspect schemas.

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 the tool is for modifying existing pull request metadata, and the sibling list shows alternative operations, but it does not explicitly state when to prefer this tool over create_pull_request or state exclusions (e.g., use merge_pull_request for merging). The usage context is inferable but not stated.

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