Server Quality Checklist

Tool Scores

• bb_create_issueC
  2.9/5.0
  Behavior2/5

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

  Annotations already declare readOnlyHint=false and destructiveHint=false, so the 'create' action is consistent. However, the description adds no extra behavioral context such as authentication needs, rate limits, or side effects. Since annotations already cover the basic safety profile, the description provides little additional value.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness4/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is a single, concise sentence with no redundancy. It is appropriately front-loaded and does not waste words, though it is minimal to the point of being sparse.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness3/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a tool with six parameters (one required) and an output schema, the description is thin. It does not mention the repo detection default (though that is in the schema) or any expected return behavior. The schema fills some gaps, but the description could provide more context for an agent to decide when and how to use it.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema description coverage is 100%, so all six parameters are fully documented in the schema. The description itself adds no parameter-level details, which is acceptable given the schema's thoroughness. This matches the baseline of 3.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose4/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description states a clear verb ('create') and resource ('an issue in a Bitbucket repository'), which distinguishes it from sibling tools like bb_create_pull_request. It is specific enough for an agent to understand the core action, though it does not mention the repository context beyond the generic phrase.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines2/5

  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 bb_create_pull_request or bb_create_branch. The description does not mention any prerequisites, typical use cases, or conditions that would make this the preferred choice.

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

• bb_get_pull_requestB
  3.2/5.0
  Behavior2/5

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

  Annotations already declare readOnlyHint=true, so the description's 'Get' adds no new behavioral information. It does not mention large diff payloads, default response scope, or any operational caveats, though the schema's include_diff description separately warns about size.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is a single front-loaded sentence with no filler. It is appropriately sized for a simple getter tool.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a read-only PR fetch with a complete parameter schema, an output schema, and readOnly/openWorld annotations, the short description is almost sufficient. The main missing element is routing guidance among the pull-request-specific sibling tools.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema description coverage is 100%, so the schema fully documents all six parameters and their defaults. The description adds no parameter information, so it stays at the baseline 3.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose4/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description uses a clear verb and resource ('Get details of a pull request') and is readily distinguishable from list/create siblings. It doesn't specify which details are covered, so it's not a 5, but it is specific enough for selection.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines2/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  No guidance is given for when to call this instead of bb_list_pull_requests, bb_get_pr_diffstat, or bb_get_pr_file_content. The intended use is only implied by the verb 'Get'.

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

• bb_read_fileB
  3.2/5.0
  Behavior2/5

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

  The description adds no behavioral detail beyond what the readOnlyHint annotation already conveys. It does not mention behavior on missing files, binary content, encoding, or which branch/commit is used for resolution, though the schema partially covers the branch parameter. There is no contradiction with the annotations.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is a single, front-loaded sentence with no filler or repetition. It states the action and object clearly without redundantly restating schema fields.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a simple read operation with a fully documented input schema and an existing output schema, the description is mostly sufficient for an agent to invoke the tool correctly. The main gap is lack of routing guidance among sibling file-content tools, but the schema covers invocation details.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema description coverage is 100%, so the input schema already documents all parameters meaningfully. The description itself adds no parameter-level detail, 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.

  Purpose4/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description states a specific verb ('read'), resource ('file'), and container ('Bitbucket repository'), so an agent immediately knows the core operation and that it is not a write or delete tool. However, it does not explicitly differentiate from sibling tools like bb_get_pr_file_content, which also serves file content in a Bitbucket context.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines2/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description provides no when-to-use guidance or alternatives. It does not explain when to choose this over bb_get_pr_file_content or bb_get_pr_file_diff, leaving tool selection mostly to inference from names.

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

• bb_create_pull_requestB
  3.3/5.0
  Behavior2/5

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

  The description adds no behavior beyond the annotations: it only restates the core operation. It fails to disclose side effects such as creating a remote pull request, the default close_source_branch=true behavior that deletes the source branch on merge, or any required authentication/permissions.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  A single sentence with no filler, front-loaded with the core action and object. It is appropriately concise for a simple creation tool.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness3/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Given the output schema and 100% parameter coverage, the description is minimally sufficient for basic invocation, but it leaves out usage context and behavioral side effects. It is adequate but not complete for a mutation tool with 7 parameters.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  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 seven parameters and their defaults. The description adds no parameter-specific meaning, and the baseline of 3 applies.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states the action (create) and the resource (a new pull request in a Bitbucket repository), distinguishing it from siblings like bb_create_repository and bb_create_branch. The specificity of 'pull request' also separates it from read/list PR tools.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines2/5

  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 when creating a PR instead of an issue or branch is appropriate, nor any prerequisites or exclusions.

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

• bb_create_repositoryB
  3.3/5.0
  Behavior3/5

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

  Annotations show readOnlyHint=false, destructiveHint=false, idempotentHint=false, so this is understood to be a mutating, non-idempotent operation. The description adds no extra behavioral context beyond that, such as whether creating a repository with an existing name fails, whether it interacts with issues/private defaults, or what access is required. With annotations present, a 3 is reasonable but the description could add more.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness3/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is a single clear sentence, appropriately brief. However, it is the minimum viable statement: it doesn't add any contextual information beyond the tool name and resource. It is concise but lacks enriching detail that would make it more helpful.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness3/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Given the schema covers all parameters and there is an output schema, the description is functionally sufficient. However, it doesn't communicate important context such as how the workspace and project_key interplay, the fact that '~' targets personal workspace (already in the schema), or any constraints like naming rules. It is adequate but not complete.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema description coverage is 100%, so parameters are already well documented in the schema. The description itself adds no parameter-level detail. Baseline 3 applies since schema carries the load; no additional value is provided by the description.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose4/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description states a specific verb and resource: 'Create a new repository in Bitbucket.' This clearly differs from sibling tools like bb_create_branch or bb_create_issue. However, it lacks detail about workspace/project context that would help distinguish from other create-family tools.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines3/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description gives no explicit when-to-use guidance or alternatives. However, the tool name and description naturally imply its use case: creating a new repository. The workspace and project_key parameter descriptions hint at the required context, but no explicit guidance is given about when to use this vs. other tools.

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

• bb_delete_fileB
  3.3/5.0
  Behavior3/5

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

  Annotations already disclose destructiveHint=true and readOnlyHint=false, so the description does not need to restate the safety profile. However, it adds no context about the tool's commit behavior (e.g., that a commit is created on the specified branch) or permission requirements. The description merely restates the operation without enriching the behavioral picture beyond what annotations and schema parameters imply.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is a single, front-loaded sentence that states the action and target immediately. It contains no filler or redundant words, making it easy for an agent to parse quickly.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness3/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  With a simple action, destructive annotations, and a fully documented schema, the description covers the basics. However, it omits the fact that deletion is performed via a commit on a branch, which is a meaningful behavioral detail for an agent deciding whether to call this tool. The branch and message parameters hint at commit semantics, but the description itself does not confirm it, leaving a small but real completeness gap.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  All five parameters have schema descriptions, so the schema carries the semantic burden. The tool description does not add any parameter-specific meaning, such as how path should be formatted or how repo_slug/workspace are resolved. This meets the baseline expected when schema coverage is 100%.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose4/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description uses the specific verb 'Delete' and identifies the resource as 'a file from a Bitbucket repository', making the operation clear. It does not explicitly differentiate from sibling tools like bb_write_file, but the name and resource make the purpose unambiguous.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines2/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description offers no guidance on when to use this tool versus alternatives. It does not mention that it should be used instead of bb_write_file for removing files, nor does it specify any preconditions like the repository being available locally. This leaves the agent to infer usage solely from the name.

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

• bb_delete_issueB
  3.3/5.0
  Behavior2/5

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

  The annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=false, so the description merely restates the basic delete action without adding behavioral context. It does not disclose whether deletion is permanent, whether associated data is removed, or what failure cases may occur.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is a single, clear sentence with no redundancy. It conveys the core operation efficiently and is easy to parse quickly.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness3/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  The description is adequate for a destructive tool whose annotations and schema cover the key safety and parameter information, but it lacks guidance on when to use the tool and what the real-world consequences are. The presence of an output schema and full parameter documentation reduces the need to explain return values or arguments.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema coverage is 100%, so all three parameters are documented in the input schema, including defaults for repo_slug and workspace. The description adds no additional parameter context, 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.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states a specific action ('Delete') and a specific resource ('an issue from a Bitbucket repository'). This distinguishes the tool from sibling tools like bb_create_issue and bb_get_pull_request without needing to inspect the schema.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines2/5

  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, nor does it mention any preconditions, such as required permissions or whether the issue must belong to the current repository. Usage context is only implied by the tool name and action.

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

• bb_create_branchB
  3.4/5.0
  Behavior2/5

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

  The description merely restates the mutating action and adds no behavioral context beyond the annotations, such as failure on duplicate branches, required write permissions, or side effects of the default start_point. It does not contradict the annotations, but it contributes little beyond them.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  A single, compact sentence that front-loads the core action and object with no filler. It earns its place without redundancy.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a straightforward creation tool with a 100%-described schema and an output schema, the description is mostly sufficient. The only real gap is the absence of when-to-use guidance, which is minor for such a simple operation.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  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 four parameters and defaults. The description adds no extra parameter meaning, which places it at the baseline for high coverage.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description names a specific verb and resource: creating a branch in a Bitbucket repository. This clearly separates it from sibling tools like bb_create_repository and bb_create_pull_request. The purpose is immediately understandable.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines2/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  No guidance is given on when to prefer this tool over alternatives or when not to use it. The description relies entirely on the tool name and the agent's inference from the sibling list, and no prerequisites or exclusions are mentioned.

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

• bb_get_pr_file_diffA
  3.8/5.0
  Behavior3/5

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

  Annotations already declare readOnlyHint=true and openWorldHint=true, so the read-only safety profile is covered. The description adds useful specificity about the result being a line-by-line diff for one file, but does not disclose details such as diff format, hunk context, or whether file metadata is included. This is acceptable because an output schema exists, but the description alone adds only moderate behavioral insight beyond the annotations.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is a single sentence with no wasted words. The core action, target resource, and scoping qualifiers are front-loaded, making it easy for an agent to parse and act on quickly.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a read-only file-diff tool with an output schema and fully documented parameters, the description conveys the essential scope and operation. It is slightly incomplete because it does not explicitly route the agent toward siblings like bb_get_pr_all_file_diffs or bb_get_pr_file_content, but this gap is relatively minor given the clarity of the wording.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  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 defaults for repo_slug and workspace. The description does not add meaningful parameter-level detail beyond reinforcing that file_path targets a single file, so it meets the schema-reliant baseline without exceeding it.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description identifies a specific verb ('Get'), a clear resource ('line-by-line diff'), and a precise scope ('one specific file in a pull request'). This distinguishes it from siblings like bb_get_pr_all_file_diffs and bb_get_pr_diffstat, making the tool's purpose unambiguous.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines3/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description implies when to use the tool: when a line-by-line diff of a single file is needed. However, it does not explicitly mention alternatives or state when not to use it, leaving the agent to infer the distinction from sibling tool names rather than receiving direct routing guidance.

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

• bb_requestA
  3.8/5.0
  Behavior1/5

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

  The description directly contradicts the annotations: it says 'Call ANY Bitbucket Cloud 2.0 REST endpoint' and the schema explicitly allows POST, PUT, DELETE, and PATCH with a request body, yet readOnlyHint is true. This is a serious inconsistency that could cause an agent to believe all requests are safe and non-mutating. The description also does not disclose authentication requirements, rate limits, or that responses may include raw/unprocessed bodies.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is dense but every sentence earns its place: base URL, placeholder substitution, endpoint discovery via bb_list_endpoints, pagination behavior, and the escape-hatch scope are all covered in five concise sentences. It is front-loaded with the core purpose and avoids repetition of schema fields.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a generic raw-API tool with an output schema and 100% parameter coverage, the description covers the essential operational details: base path, placeholder substitution, pagination, and how to discover endpoint-specific paths. It could additionally mention authorization preconditions or error/rate-limit behavior, but the existing guidance plus schema is sufficient for most correct calls.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters4/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema coverage is 100%, so the schema already documents all parameters. The description adds meaningful semantics beyond the schema: paths are relative to the 2.0 base URL, placeholders must be replaced with real values, paginate=true follows Bitbucket's next links and merges all pages, and raw mode is relevant for diff/patch/log endpoints. This is solid added value for an agent selecting and invoking parameters.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description opens with a specific verb and resource: 'Call ANY Bitbucket Cloud 2.0 REST endpoint directly.' It clearly frames the tool as an escape hatch for endpoints not wrapped by purpose-built bb_* tools and enumerates examples (merges, pipelines, webhooks, permissions). This distinguishes it from sibling tools and leaves no ambiguity 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.

  Usage Guidelines4/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description gives explicit usage guidance: use it for everything the purpose-built bb_* tools do not wrap, call bb_list_endpoints first to get paths and params, and enable paginate=true on list endpoints. It clearly conveys the fallback role but does not explicitly say to prefer a purpose-built tool when one exists, which is implied but not stated as a negative rule.

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

• bb_write_fileA
  3.8/5.0
  Behavior3/5

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

  The description correctly indicates a mutating operation, consistent with readOnlyHint=false and destructiveHint=false. However, it adds little beyond the annotations; it does not mention commit behavior, overwrite semantics, or other side effects that could matter to an agent.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is a single, clear, front-loaded sentence with no filler. Every word contributes to defining the tool's core purpose.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Given the full parameter schema, output schema, and annotations, the description is largely sufficient for a straightforward write operation. It could be slightly stronger by explicitly noting that the write creates a commit, but the schema already covers branch and commit message defaults.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  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 six parameters. The description adds no additional parameter-level meaning or usage detail, keeping this at the baseline.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description states a specific action ('Write or update') and a precise resource ('a file in a Bitbucket repository'). It is easily distinguished from sibling tools like bb_read_file and bb_delete_file.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines3/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description implies the tool is used when a file needs to be created or modified in Bitbucket, but it gives no explicit guidance about when not to use it or how it compares to alternative tools for reading or deleting files.

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

• bb_get_pr_diffstatA
  4.1/5.0
  Behavior4/5

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

  The annotations already declare readOnlyHint=true, so the safe read-only nature is covered. The description adds useful behavioral context beyond annotations by specifying exactly what the tool returns: per-file added/removed line counts plus a totals summary. There is no contradiction with annotations, and no hidden side effects are suggested.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is a single, well-structured sentence that front-loads the core purpose and immediately specifies the output scope. There is no filler, repetition, or unnecessary detail.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness5/5

  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 full schema coverage, an output schema, and clear annotations, the description is complete. It tells the agent what the tool returns and the schema covers all parameter details. Nothing essential is missing for correct invocation.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  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 pr_id, repo_slug, and workspace, including the default behavior for repo_slug. The description adds no additional parameter-level semantics, which is acceptable because the schema carries the full burden. A baseline 3 is appropriate.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description uses a specific verb ('Get') and a specific resource ('diffstat for a pull request'), and further clarifies what a diffstat is: every modified file with added/removed line counts and a totals summary. This distinguishes it clearly from sibling tools like bb_get_pr_file_diff or bb_get_pr_all_file_diffs, which return file content or diffs rather than aggregate counts.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines3/5

  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 you need summary counts rather than actual diffs—but it never explicitly names alternatives or states when not to use it. With siblings like bb_get_pr_file_diff and bb_get_pr_all_file_diffs present, explicit routing guidance would have made the usage intent unambiguous.

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

• bb_pr_list_commentsA
  4.1/5.0
  Behavior4/5

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

  The annotation readOnlyHint=true already signals a safe read operation, and the description adds meaningful behavior beyond that: comments are classified as inline, replies, and resolved-thread comments. It does not contradict the annotations and provides useful context about the tool's output shape.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is a single sentence that front-loads the core purpose and then adds only high-value distinguishing detail. There is no filler, repetition, or unnecessary background.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness5/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Given the read-only annotation, an output schema, and fully documented parameters, the description is complete for selecting and invoking the tool correctly. It explains the key behavioral distinctions an agent needs and does not need to restate schema defaults or return structures.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema description coverage is 100%, so the input schema fully documents pr_id, max_pages, repo_slug, workspace, and include_resolved. The description adds no parameter-specific behavior beyond what the schema already states, 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.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description uses a specific verb and resource: 'List comments on a pull request', then clearly distinguishes the tool by describing output nuances (inline with file/line, replies, resolved threads). This separates it from sibling comment-related tools like bb_pr_comment and bb_pr_resolve_thread.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines3/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The intended use is implied: use this tool when you need to enumerate PR comments and understand their inline, reply, or resolution status. However, there is no explicit guidance about when not to use it or which sibling tool to prefer for related tasks like posting comments or resolving threads.

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

• bb_pr_resolve_threadA
  4.1/5.0
  Behavior3/5

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

  Annotations already indicate this is a mutating, non-idempotent, non-destructive operation. The description is accurate but adds little behavioral detail beyond the annotations, such as permission requirements, undo semantics, or 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.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is one short, front-loaded sentence with no filler or redundant information. It clearly communicates the tool's purpose without wasting tokens.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness5/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a simple write operation with complete parameter documentation, an output schema, and annotations, the description is sufficient. An agent can invoke this tool correctly based on the description and structured data alone.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  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 well documented. The description does not add any parameter-level detail, but it also does not need to since the schema covers the meanings of pr_id, repo_slug, workspace, and comment_id.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description states a specific verb ('Mark') and resource ('pull request comment thread') with a clear target state ('resolved'). It is easy to distinguish from siblings like bb_pr_list_comments or bb_pr_comment because the resolution action is explicitly named.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines4/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description provides clear context: use this tool when a pull request comment thread should be marked resolved. It does not explicitly name alternatives or exclusions, but the action is distinct enough among siblings that an agent can select it correctly.

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

• bb_get_pr_all_file_diffsA
  4.2/5.0
  Behavior4/5

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

  The annotations already declare readOnlyHint=true, so the read-only nature is covered by structured metadata. The description adds useful behavioral context beyond the name by emphasizing the single-call aggregation and efficiency advantage over per-file calls. No contradictions with annotations are present.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is a single, efficient sentence that communicates both the tool's function and its key benefit. It is front-loaded with the core purpose and contains no redundant or filler wording.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a read-only tool with a clear output schema and thoroughly documented parameters, the description is sufficient to guide correct invocation. It could additionally mention cases where per-file diff retrieval might be preferable, but overall the context provided is strong.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  The input schema has 100% description coverage, with each parameter including a clear explanation and relevant defaults. The description adds no additional parameter-level detail, so the schema carries the semantic burden as expected; 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.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly identifies the action ('Get'), the resource ('the complete diff for every modified file in a pull request'), and the batching benefit over the sibling tool bb_get_pr_file_diff. This makes the tool's purpose unambiguous and easily distinguishable from similar siblings.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines4/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description explicitly names bb_get_pr_file_diff as the per-file alternative and states that this tool is 'much more efficient' for multi-file diffs. It gives the agent a clear reason to choose this tool for whole-PR diff retrieval, though it stops short of explicitly saying when to prefer the single-file variant.

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

• bb_get_pr_file_contentA
  4.2/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true and openWorldHint=true, so the safe read-only nature is covered. The description adds useful behavioral context by specifying that it fetches both branches' content in one call, which is more than a simple single-file read. No contradiction with annotations.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  A single, well-structured sentence that front-loads the action and object, then adds branch scope and intended use. Every word earns its place; no repetition or filler.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  The description, combined with full schema coverage, readOnly/openWorld annotations, and an output schema, provides enough for an agent to select and invoke the tool correctly. The main gap is not explicitly routing away from diff-based siblings, but 'side-by-side review' sufficiently implies the distinction.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema description coverage is 100%, so all five parameters are already documented in structured form. The description adds minimal parameter-specific meaning beyond clarifying the 'both branches' behavior, which maps to include_both. This is an acceptable baseline given the schema's completeness.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  Uses a specific verb and resource: 'Get one file's content' at 'both the source and destination branches of a pull request'. This clearly distinguishes it from sibling diff tools like bb_get_pr_file_diff and bb_get_pr_all_file_diffs, which return diffs rather than full file contents.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines4/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The phrase 'for side-by-side review' gives clear context for when this tool is appropriate: when both full file versions are needed for comparison. It does not explicitly name alternatives or exclusions, but the dual-branch scope makes the intended use case evident.

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

• bb_list_pull_requestsA
  4.2/5.0
  Behavior4/5

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

  Annotations already signal readOnlyHint and openWorldHint, so the description's main job is to add behavioral context beyond that. It adds the useful source_branch-to-PR-number resolution behavior and clarifies that results are filterable, which goes beyond the structured annotations without contradicting them.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is two sentences, front-loads the core purpose, and follows with a targeted usage tip. No filler or redundant restatement of the tool name appears.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness5/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Given the output schema is present, annotations cover read-only and open-world behavior, and all parameters are documented in the schema, the description supplies the one missing contextual clue—how to bridge from a branch name to a PR number. This is sufficient for a list tool with optional filters.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters4/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Input schema coverage is 100%, so the baseline is 3, but the description adds meaning to the source_branch parameter by explaining its practical role in resolving branch names to PR numbers. This is genuine semantic value beyond the schema's simple field description.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose4/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly identifies the operation as listing pull requests in a repository and enumerates the available filters. It differentiates itself from fetching a single PR by using 'list', but it does not explicitly contrast itself with bb_get_pull_request or other siblings.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines4/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description gives one strong, actionable usage guideline: use the source_branch filter to resolve a branch name to its PR number when the user references a branch instead of a PR. However, it does not state when to prefer an alternative tool such as bb_get_pull_request for single-PR details.

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

• bb_pr_approveA
  4.2/5.0
  Behavior4/5

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

  The description adds meaningful behavioral context beyond annotations by noting that the approval is visible to the team. This is a real side-effect that an agent should understand before invoking the tool.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  Two short sentences carry the full message with no filler. The core action comes first, and the important usage caveat follows immediately.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  The description is sufficient for a simple, well-documented PR action: it states what it does, when to use it, and a key side-effect. The output schema and parameter descriptions cover the remaining operational detail, though it does not mention potential failure conditions or prerequisites.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema description coverage is 100%, and the schema already documents pr_id, repo_slug, and workspace clearly. The description does not add parameter-level detail, 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.

  Purpose4/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states the action: approve a pull request as the authenticated user. It does not explicitly compare itself to sibling tools like bb_pr_request_changes, but the approve verb makes the purpose unambiguous.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines5/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description gives an explicit usage condition with a strong exclusion: 'only call it when the user has asked for an approval.' This is direct, actionable guidance that prevents inappropriate calls.

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

• bb_pr_request_changesA
  4.2/5.0
  Behavior4/5

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

  Annotations already indicate this is a non-read, non-idempotent mutation. The description adds useful behavior beyond those hints: the action is attributed to the authenticated user and is 'visible to the team,' which tells the agent the call has a visible side effect and should not be made casually.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  Two sentences with no filler; the primary purpose is front-loaded and the usage guardrail is stated compactly. Every sentence carries meaning.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  With a complete schema, an output schema, and a clear usage guardrail, the definition is sufficient for a simple PR review action. It could add prerequisites (e.g., open PR, permissions) but these are largely implied and not critical for correct selection.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters3/5

  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 pr_id, repo_slug, and workspace. The description does not add parameter-specific detail, but it does not need to under the baseline for complete schema coverage.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  States a specific action ('Request changes') on a specific resource ('a pull request') and adds the agent-scoping condition 'as the authenticated user.' The action is distinct from sibling tools like bb_pr_approve or bb_pr_comment, so an agent can pick it without further schema inspection.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines4/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  Gives an explicit gate: 'only call it when the user has asked to request changes.' This is a clear when-to-use/exclusion, though it does not name alternatives or describe situations where it should not be used beyond the user-request condition.

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

• bb_search_repositoriesA
  4.5/5.0
  Behavior3/5

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

  readOnlyHint and openWorldHint already establish that this is a safe read over the open world, and the description adds no further behavioral caveats such as auth requirements, rate limits, ordering, or pagination. The only extra trait is the ISO 8601 date restriction, which is more of a parameter constraint than a 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.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  Two sentences with the core verb, query syntax, and alternative mode in the first and second lines; no filler. Front-loaded and easy to scan.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness5/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a read-only search tool with a full input schema, an output schema, and annotations, the description supplies the missing pieces: query-syntax semantics, the ISO date rule, and routing to file-content search. Nothing an agent needs to invoke it correctly is absent.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters4/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Because schema coverage is 100%, baseline is 3; the description elevates this by giving representative syntax for four query dimensions and explicitly limiting dates to ISO 8601. It doesn't add information about page/pagelen/workspace, but those are simple and fully documented in the schema.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  States a clear action ('Search repositories') and a specific resource (Bitbucket repositories), with concrete query-syntax examples for names, project keys, languages, and dates. The final sentence explicitly differentiates it from file-content search, so an agent can distinguish it from sibling endpoints.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines5/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  Provides an explicit conditional: use this tool to search repository metadata; use bb_list_endpoints code-search endpoints instead when the goal is file contents. This is a clear when/when-not pair with a named alternative.

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

• bb_pr_commentA
  4.6/5.0
  Behavior4/5

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

  Annotations show this is a mutating, non-destructive operation, and the description aligns. It adds valuable behavior beyond annotations: file_path and line must be paired for inline anchoring, parent_id enables replies, and omitting both creates a general comment.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  Two focused sentences with no wasted words. The core action is front-loaded, and the conditional placement rules are compressed into a clear, scannable structure.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness5/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  The description covers all three behavioral modes of the tool and the conditions that trigger them. Combined with full schema coverage and an output schema, nothing essential is missing for an agent to invoke the tool correctly.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters5/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema coverage is 100%, but the description adds parameter-relationship semantics not visible from individual schemas. It explicitly explains the coupling of file_path and line, the purpose of parent_id, and what happens when neither is supplied.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  States a specific verb ('Add a comment') and resource ('pull request'), making the core action unambiguous. It also differentiates itself from sibling tools like bb_pr_list_comments and bb_pr_resolve_thread by being the creation endpoint, and clarifies the three placement modes inline, reply, and general.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines4/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  Provides clear context for when to use the tool: commenting on a pull request. The description also gives operational guidance for the three comment modes (inline, reply, general), though it does not explicitly mention exclusions or alternative tools.

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

• bb_list_endpointsA
  4.7/5.0
  Behavior4/5

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

  The readOnlyHint annotation already covers side-effect safety, so the bar is lower. The description reinforces this by describing search/find operations with no mutation language. It also adds context about the source (Atlassian OpenAPI spec), which is helpful. A slight improvement could be an explicit 'does not modify any resources', but not necessary given the annotation.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is two sentences, no filler. It packs purpose, usage context, and a search tip into a tight, well-structured format. The example 'pull request comment' vs 'comment' is concise and effective.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness5/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a discovery tool, the description provides all necessary context: what it does, when to use it, how to use its main parameter, and the downstream step (bb_request). The presence of an output schema means the return value doesn't need to be explained. Everything an agent needs to correctly invoke this tool is covered.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters4/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema descriptions cover all five parameters, so baseline is 3. The main description adds valuable semantics for the `search` parameter (whitespace-separated terms must all match and that using more terms narrows results), which goes beyond the schema 'Terms matched against...'. This extra guidance justifies a 4.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states the tool searches the full Bitbucket Cloud REST API to find the right method, path, and params. It explicitly differentiates itself from purpose-built siblings by positioning itself as the fallback when no bb_* tool covers the task.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines5/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  Provides explicit when-to-use guidance ('Call this FIRST whenever no purpose-built bb_* tool covers what you need') and how to integrate with the workflow ('pass the result to bb_request'). Also explains the multi-term AND search behavior with a concrete example, leaving no ambiguity.

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