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

With no annotations provided, the description carries the full burden of disclosing side effects. It only states the approval action, but does not mention idempotency, reversibility, required permissions, or what the API returns. For a state-changing operation, this is insufficient.

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, well-constructed sentence with no redundant information. It is appropriately concise and 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 tool is simple and the parameters are well-documented, but the description lacks behavioral details such as side effects, idempotency, and usage context. Since there are no annotations or output schema, the description alone is not fully complete for a mutation tool, though it is adequate for basic understanding.

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 provides descriptions for all three parameters with 100% coverage, so the schema already documents the parameters. The description adds no additional parameter meaning beyond what the schema provides, 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 clearly states the action ('Approves') and the resource ('a pull request'), adding the actor context ('as the authenticated user'). It distinguishes from sibling tools like unapprove or decline by using the specific verb 'approve'.

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 no guidance on when to use this tool versus alternatives, such as whether to approve vs. merge or decline, nor any prerequisites like PR status or permissions. It only states the action itself.

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 full responsibility for behavioral disclosure. It merely states the creation action without revealing potential side effects, permission requirements, or return behavior. For a mutation tool with no annotations, 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 concise sentence that front-loads the primary action and key context (from source to destination). Every word earns its place with no redundancy.

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?

Although the schema thoroughly documents parameters, the description lacks essential contextual information such as return value, behavior on duplicate PRs, branch existence requirements, or any prerequisites. With no output schema and no annotations, the description is not complete enough for an agent to fully anticipate tool behavior.

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 parameter meanings are fully documented in the schema. The description adds no meaningful parameter semantics beyond naming source and destination branches, which are already in the schema. Baseline 3 is appropriate when 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 clearly states the tool creates a new pull request from a source branch into a destination branch. It uses a specific verb and resource, and naturally distinguishes itself from sibling tools like update, merge, or decline.

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?

Usage is implied by the description: use this tool to create a pull request. However, there is no explicit guidance on when not to use it or mention of alternative tools. The sibling list provides options but the description itself does not reference them.

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 behavior. It explains the core behavior and parameter relationships, but does not disclose what happens when conflicting parameters are supplied (e.g., both inlinePath and parentId) or what the response contains. Slightly opaque but still informative.

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?

Two crisp sentences with the action upfront and usage details following. Every word earns its place; no fluff 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?

For a create tool with 7 parameters and no output schema, the description covers the essential invocation logic. It misses return-value hints, but the sibling tools (e.g., get/update/delete) and schema descriptions largely fill the context gap.

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%, so baseline is 3. The description adds value by explaining the semantic grouping of parameters (inlinePath/inlineLine vs parentId vs neither), which is not evident from the schema alone.

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 action ('Adds a comment to a pull request') with a clear resource. It distinguishes three modes—inline, reply, and general—which sets it apart from sibling comment tools like update/delete/list.

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?

Provides clear guidance on when to use each parameter combination (inlinePath/inlineLine for anchored comments, parentId for replies, omit both for general). However, it does not explicitly name alternative tools or state when not to use this tool, so it lacks explicit 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?

With no annotations, the description is the sole source for behavioral disclosure, but it only states the action without detailing consequences (e.g., PR state changes, notifications, irreversibility) or permissions required. The qualifier 'open' implies a precondition but does not explain behavior for non-open PRs.

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 zero filler. It is front-loaded with the action and resource, making it easy to parse quickly. 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?

Given that this is a mutation tool with no annotations and no output schema, the description is incomplete. It does not explain the outcome, return value, error cases (e.g., if the PR is already closed), or any side effects. The simplicity of the tool lowers the bar slightly, but the lack of critical behavioral context remains a gap.

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 all four parameters already have clear descriptions (e.g., 'Reason for declining', fallback environment variables). The tool description adds no further parameter semantics, but the schema does the heavy lifting, warranting the baseline score.

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 'Declines an open pull request' clearly states the specific action (decline) and the resource (pull request), and uses the qualifier 'open' to scope its applicability. This distinguishes it from sibling tools like approve, merge, update, and unapprove.

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. It does not mention that declining is appropriate when rejecting a PR, nor does it exclude cases like merging or approving. The context must be inferred entirely from the tool name and description.

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, and the description gives minimal behavioral detail. It does not disclose that deletion is permanent, mention required permissions, or describe error behavior when the comment does not exist.

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. It is concise and front-loaded with the action.

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 that this is a destructive action with no annotations and no output schema, the description is insufficiently complete. It does not explain the return value, error scenarios, or side effects, leaving the agent with little to infer about behavior beyond the basic action.

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 covers 75% of parameters with descriptions, so the description adds no new parameter semantics. However, the 'commentId' parameter lacks a description in both the schema and the tool description, leaving a gap that the description fails to address.

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 action and resource: 'Deletes a comment from a pull request.' This is a specific verb+resource scoped to comments, distinguishing it from sibling tools that update, create, get, or list pull request 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?

No guidance is provided on when to use this tool versus alternatives. The description simply states what it does, with no mention of 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?

With no annotations provided, the description must carry the full burden. The verb 'fetches' indicates a read-only operation but does not disclose any additional behavioral traits such as required permissions, rate limits, or what fields are included in 'full details'. It adds minimal context beyond the action 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 sentence of 14 words, front-loaded with the core action and resource. Every word earns its place, with no fluff 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 tool is a simple 'get' with complete schema coverage, but there is no output schema. The description says 'full details' without specifying what those details include, leaving some ambiguity about the return structure. It is minimally sufficient but could be clearer about expected response fields.

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 all three parameters are already documented in the input schema. The description adds no extra parameter semantics. Per the rubric, a high coverage 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?

The description clearly states the verb 'fetches' with a specific resource ('full details of a single pull request'), and distinguishes from siblings like bb_get_pull_request_description by emphasizing 'full details' rather than just the description. It is unambiguous and specific.

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 when to use this tool via 'full details' and 'single pull request', making the context clear. However, it does not explicitly mention alternatives or exclusions, such as pointing to bb_get_pull_request_description for description-only needs. It stops short of fully explicit 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?

No annotations are provided, so the description must disclose behavioral traits. It only restates the basic fetch operation without mentioning authentication, read-only nature, error handling, or what the response contains. This is minimal and doesn't add meaningful 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?

The description is a single, front-loaded sentence with no redundant words. It conveys the core function immediately.

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?

Since there is no output schema, the description should clarify what is returned, but it does not. The description is adequate for a simple fetch but leaves gaps regarding the response format and any subtle behaviors. For a tool with no annotations and no output schema, more context is needed.

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 repoSlug, workspace, and pullRequestId with descriptions, giving 75% coverage. The description itself does not discuss parameters, but the schema covers most meaning. CommentId lacks a description, but the tool's purpose makes it clear. Baseline 3 is appropriate given high 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 the specific verb 'Fetches' and specifies the resource as a single comment on a pull request, triaged by ID. This clearly distinguishes it from sibling tools like list, create, update, and delete 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 description implies the tool is for retrieving a specific comment by ID, but it does not explicitly state when to use it instead of bb_list_pull_request_comments or mention any exclusions. The purpose is clear but no explicit guidance is given.

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 of behavioral disclosure. It communicates a read-only fetch and specifies the return format as raw Markdown, which is helpful. However, it omits details like error behavior, authentication needs, or whether a missing description returns null, leaving some ambiguity.

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 sentence that front-loads the core action and scope. Every word contributes value, with no redundant or filler content.

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 read-only tool with fully documented parameters and no output schema, the description adequately explains the return value ('raw Markdown') and narrow scope. It lacks only minor edge-case details such as behavior when the pull request is not found or inaccessible, which would make it fully 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?

The input schema already provides 100% coverage with descriptive text for all three parameters, including environment-variable fallbacks for workspace and repoSlug. The description adds no additional parameter semantics, 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 the specific verb 'Fetches' and clearly identifies the resource as 'a pull request's description text'. The qualifiers 'just' and 'raw Markdown' precisely scope the operation and distinguish it from sibling tools like bb_get_pull_request or bb_get_pull_request_diff.

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 'just a pull request's description text' implies this is the lightweight alternative to fetching a full pull request, giving the agent clear contextual guidance. However, it does not explicitly name an alternative or state when not to use it, so it falls short of a 5.

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 full burden of disclosure. It indicates the output is raw text, implying a read-only fetch operation. However, it does not mention potential large response sizes, rate limits, or authentication requirements, leaving some behavioral aspects 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 concise sentence of 12 words, front-loaded with the action and resource. Every word earns its place with no redundancy or filler.

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 fetch tool with full schema coverage, the description is largely complete. It clearly states the purpose and output format. The main minor gap is the lack of explicit differentiation from the diffstat sibling, but the phrase 'unified diff ... as raw text' implicitly covers this.

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 describes all four parameters with 100% coverage, including fallback behavior and limits. The description adds no extra parameter 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 ('Fetches') and clearly identifies the resource ('unified diff of a pull request') and output format ('raw text'). This distinguishes it from the sibling tool bb_get_pull_request_diffstat, which would return statistics rather than the diff 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?

The description implies the tool is for retrieving a raw diff when needed, but it does not explicitly state when to prefer this over alternatives like bb_get_pull_request_diffstat or bb_get_pull_request. There is no mention of exclusions or alternative usage, so guidance is implied rather than explicit.

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. It indicates a read-only operation with 'Fetches' and describes the output, but it does not disclose potential behavioral traits such as authentication requirements, error cases, or how the diffstat is aggregated (e.g., across the entire PR vs. a specific commit). The description is accurate but minimal.

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, well-structured sentence that front-loads the main action ('Fetches') and concisely states the deliverable. Every word earns its place, with no redundancy.

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 tool's low complexity (3 parameters, 1 required, no output schema), the description adequately covers the essential purpose and return value, specifying that it provides added/removed/modified and line counts per file. It lacks details on the exact response structure or possible errors, but for a simple read-only diffstat tool, it is sufficiently 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% with descriptions for all three parameters, including fallback behavior for repoSlug and workspace. The description text adds no further parameter information beyond what the schema provides, so it meets the baseline for high schema coverage without enhancing 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 clearly states the tool's function: fetching a per-file summary of changes (added/removed/modified, line counts) for a pull request. It uses a specific verb ('Fetches') and resource ('per-file summary'), and the term 'diffstat' naturally distinguishes it from sibling tools like bb_get_pull_request_diff, which returns the actual diff.

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 when to use the tool by specifying 'per-file summary of changes', which suggests it is for summarized views rather than full diffs. However, it does not explicitly name alternatives or provide when-not-to-use guidance, so the usage context is only implied, not clearly stated.

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 burden. It discloses a key behavioral filter ('non-deleted') and scopes (inline code comments and replies), which adds value. However, it does not mention pagination, ordering, authentication requirements, or potential rate limits, leaving gaps in behavioral 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?

The description is a single, compact sentence that front-loads the action and resource, and every word adds value. There is no wasted text or repetition of schema details.

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 list tool with no output schema and no annotations, the description adequately covers the core behavior and key filtering. It could benefit from mentioning pagination or response characteristics, but the current level is sufficient for an agent to understand the tool's purpose and scope.

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 parameters including fallback behavior for repoSlug and workspace. The description adds no additional parameter-level meaning beyond clarifying the resource context, so the baseline 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 ('Lists') and clearly identifies the resource ('comments on a pull request') including scope ('inline code comments and replies'). It distinguishes from siblings like bb_get_pull_request_comment (singular) and bb_list_pull_requests (which lists PRs, not 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 description implies usage for retrieving all comments on a PR but does not explicitly state when to choose this tool over alternatives like bb_get_pull_request_comment or how it relates to create/update/delete comment tools. Sibling names provide some context, but no direct when/when-not guidance is given.

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. It implies a read-only list operation and mentions optional filtering, but does not disclose pagination behavior, default state (OPEN), output shape, or any auth/rate-limit context. The schema provides parameter defaults, but behavioral traits remain largely unspecified.

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 redundant words. It front-loads the action and resource immediately, making it highly scannable and appropriately concise.

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?

There is no output schema, so the description should clarify return behavior. 'Lists pull requests' only partially does this; it omits that results are paginated (given pagelen param) and what fields/objects are returned. For an agent to correctly process results, this is a notable gap. The complexity is moderate, so a few more details would be warranted.

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 baseline is 3. The description's reference to filtering by state or query string adds no new insight beyond the schema's per-parameter descriptions, which already explain state, query, pagelen, and fallbacks.

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 'Lists', the resource 'pull requests', and the scope 'in a repository', which distinguishes it from sibling tools like get, create, update, merge, etc. It also mentions optional filters, adding operational clarity.

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 context for use is evident: it's for listing pull requests, as opposed to single-PR operations. However, it does not explicitly state when not to use it or name alternatives like bb_get_pull_request for a single PR, missing the higher bar for explicit 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 description must carry full burden. 'Merges' implies mutation but gives no details about side effects (e.g., reverting not possible), what happens to source branch, or whether it requires special permissions.

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?

One short sentence with zero wasted words. It is concise and front-loaded, though slightly under-specified in content.

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 6 parameters, no annotations, and no output schema, a single sentence is insufficient. Missing information about merge strategy defaults, branch handling, and post-merge state makes the description incomplete for a non-trivial 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?

Schema coverage is 67%, leaving mergeStrategy and closeSourceBranch undocumented in both schema and description. The description adds no parameter context, so agents must infer behavior from names/enums alone.

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 clearly states 'Merges an open pull request' with a specific verb and resource. It distinguishes itself from sibling tools like get, update, decline, and approve by using 'merge' as the 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?

No guidance on when to use this tool versus alternatives. It does not mention prerequisites (e.g., PR must be open, approvals required) or exclusion cases (e.g., not for declined PRs).

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. It clearly discloses the core behavior (removing approval) and the scope (authenticated user's). This adds value beyond the title, but it does not mention edge cases such as whether an error occurs if the user has not approved, or if the operation is idempotent.

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 communicates the action and scope without any unnecessary words. It is well-structured and easy to parse.

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 mutation tool with fully documented parameters, the description covers the primary action. However, with no output schema and no annotations, it does not explain return values, potential errors, or prerequisites (e.g., having approved first), leaving moderate gaps in 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?

Schema coverage is 100% for all 3 parameters (repoSlug, workspace, pullRequestId), so the schema already documents their meaning. The description adds no parameter-specific detail, warranting the baseline score of 3.

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 'Removes' and clearly identifies the resource as 'the authenticated user's approval from a pull request'. This distinguishes it from sibling tools like bb_approve_pull_request and bb_decline_pull_request.

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 usage when the user wants to remove their approval from a pull request. However, it does not explicitly mention when not to use it or compare it to alternatives like bb_approve_pull_request. The context is sufficient but lacks explicit 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?

With no annotations provided, the description must disclose behavior itself. It reveals that only open PRs can be updated and that fields are partially updated, which is useful. However, it does not mention permissions, response format, or side effects like what happens when changing the destinationBranch.

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 long, front-loaded with the primary purpose, and every sentence provides useful guidance without redundancy. It is concise and well-structured.

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 tool's moderate complexity, no output schema, and no annotations, the description covers the essential purpose, update semantics, and relationship to a sibling. It could mention response details or parameter-specific behaviors, but the provided information is sufficient for an agent to use the tool correctly in most 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 schema covers 71% of parameters with descriptions, so the baseline is near 3. The description adds meaningful semantics by stating that only provided fields are changed and omitted fields are left as-is, which applies to all parameters and clarifies the PATCH-like behavior.

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 action: 'Updates an open pull request,' with a specific verb and resource. It also distinguishes this tool from the description-only sibling by directing users to bb_update_pull_request_description for description-only edits.

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 explicit guidance on when to prefer the sibling tool for description-only edits, which is a clear exclusion. It also explains the partial-update behavior ('Only the provided fields are changed; omit a field to leave it as-is'), helping the agent decide which fields to pass.

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 full burden of behavioral disclosure. It does add valuable context by stating 'Only the comment's author can edit it,' which indicates a potential failure condition. However, it does not disclose other important behaviors such as whether the update is idempotent, how errors are reported if the comment doesn't exist, or any side effects (e.g., notifications). This is adequate 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 concise sentence front-loaded with the core action ('Edits the body of an existing comment') followed by the key constraint. Every word earns its place; there is no redundant information or filler. It is an exemplary model of brevity and clarity.

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 relatively simple mutation tool with 5 parameters (3 required) and no output schema, the description covers the essential context: what it does, the resource it acts on, and a critical authorization constraint. The schema fills in parameter details, and the sibling list clarifies it is specifically for pull request comments. It lacks some depth (e.g., response format, error cases), but given the tool's simplicity, this is sufficient for an agent to select and invoke it effectively.

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 80%, which is high (>80% threshold), so the baseline is 3. The tool description itself adds no parameter semantics beyond what the schema already provides. The schema already describes 'content' as 'New comment body (Markdown), replaces the existing text,' and the fallback behavior of repoSlug and workspace. The names of pullRequestId and commentId are self-explanatory.

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 tool's specific action: 'Edits the body of an existing comment.' This uses a specific verb ('edits') and a clear resource ('body of an existing comment'), which distinguishes it from sibling tools like bb_update_pull_request_description (updates the description) and bb_create_pull_request_comment (creates a new comment). The added author-only restriction further disambiguates its scope.

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 conveys clear usage context: it is for editing an existing comment's body, and it explicitly notes that only the comment's author can edit it, which serves as an implicit exclusion for non-authors. However, it does not explicitly name alternative tools or state when not to use it beyond the author restriction, so it stops short of a 5.

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 of behavioral disclosure. It accurately states the mutation ('Replaces') and explicitly lists what remains unchanged, which is critical for a partial update. It does not discuss permissions or response contents, but the behavior is simple and well-covered.

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 that states the primary action and key boundary in one breath. Every word earns its place; there is no redundancy or filler.

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 single-field update with no output schema, the description adequately covers the core purpose and scope. It would benefit from mentioning that the old description is irrevocably replaced (though 'replaces' implies this) and any prerequisite like the PR existing, but these are implicit. The description is complete enough for 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?

Schema description coverage is 100% for all 4 parameters, so the schema already documents each field. The description adds context by explaining the effect on the existing description and clarifying that other PR fields are untouched, but it does not provide additional parameter-level syntax or format details beyond the schema. 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 ('Replaces') and resource ('pull request's description'), and clearly distinguishes from sibling tools like bb_update_pull_request by scoping only to the description field. It explicitly states what it does not affect (title, reviewers, destination branch), making it 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 implies when to use this tool: when only the description needs updating, not other PR attributes. It provides clear exclusions ('without touching its title, reviewers or destination branch'), though it does not name alternative tools like bb_update_pull_request explicitly. Still, the guidance is stronger than average.

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