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

No annotations are provided, so the description must disclose behavior. It only mentions 'Supports threaded conversations', which is already implied by the parentId parameter schema. It omits permissions required, side effects like notifications, default behaviors for state/severity/project, and what the response contains.

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

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

Three sentences, front-loaded with the core action, but the second sentence largely repeats the first's list of use cases, and the third is a fragment. Some redundancy reduces conciseness.

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

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

For a write tool with no annotations and no output schema, the description is thin on behavioral context. The rich schema documents parameters well, but the description does not compensate for missing annotation coverage or explain return/notification 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 all seven parameters are fully documented in the schema, including defaults for state and severity. The description adds no parameter-specific meaning beyond what the schema provides, 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?

States a specific verb 'Add' and resource 'comment to a pull request', with clear review-oriented purpose. However, it does not distinguish this from sibling add_comment_inline, leaving ambiguity about which tool to use for line-specific versus general PR comments.

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

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

Explicitly lists when to use the tool (review feedback, questions, suggestions, discussions), giving clear context. But it provides no exclusions or alternatives, such as using add_comment_inline for inline comments or edit_comment to modify an existing comment.

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

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

No annotations are provided, so the description carries the full behavioral burden, yet it discloses nothing about permissions needed, whether the comment triggers notifications, immediacy of visibility, or rate limits. 'Supports threaded conversations' gestures at behavior but the concrete mechanism (parentId) and the draft-vs-published distinction are only in the schema, leaving a write tool materially under-described.

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 first sentence is front-loaded and informative, but the second sentence re-enumerates the same use cases ('review feedback, ask questions, suggest improvements, participate in discussions') already implied by the list in sentence one. That duplication costs space without adding selection signal.

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 10-parameter write tool with no annotations and no output schema, the description is sufficient to convey what the tool does but thin on what an agent needs to act safely: no permission/auth context, no note on draft publication flow, no return information. It is minimally adequate rather than 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 description coverage is 100% across all 10 parameters, so the schema already documents line numbering, lineType enum, state, severity, parentId, and repository/project resolution. The description adds no syntax, format, or coordination detail beyond what the schema states, which is the baseline case.

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 gives a specific verb (Add), resource (inline comment), and precise scope (to specific lines of a PR diff), which cleanly separates it from a general PR comment. It stops short of naming the sibling it differs from (add_comment for non-line-anchored comments), so an agent must infer the boundary rather than being told it.

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

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

It offers a list of situations (review feedback, questions, suggestions, discussion), which implies usage but does not state when NOT to use it or name alternatives such as add_comment for general PR comments or publish_review for batch review submission. The guidance is largely a restatement of the purpose sentence rather than routing logic.

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

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

With no annotations, the description carries the full behavioral burden. It usefully discloses that the approval is attributed to the caller's identity, but says nothing about required permissions, whether approval is idempotent, how it interacts with existing reviews/approvals, or that it does not itself merge the change.

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?

Three short sentences, front-loaded with the action, with no filler. The final identity sentence is slightly redundant with 'as the current user' but does add attribution detail.

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 state-changing operation the description covers purpose and usage and the schema covers inputs, and there is no output schema to explain. The missing piece is behavioral: preconditions, permission requirements, and how to reverse the action, which nothing else in the definition supplies.

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 prId, project, and repository, including the BITBUCKET_DEFAULT_PROJECT fallback. The description adds no parameter-level meaning beyond that, which is the expected baseline here.

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?

States a specific verb and resource ('Approve a pull request') plus the actor ('as the current user'), which is enough to distinguish it from merge_pull_request or decline_pull_request. It stops short of naming the adjacent siblings (unapprove_pull_request, merge_pull_request) that an agent could confuse it with.

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?

'Use this to signal that you have reviewed the changes and they are ready to be merged' gives clear situational context for when to call it. There are no exclusions or explicit alternatives, so an agent must infer that it should use unapprove_pull_request to undo and merge_pull_request to actually land the code.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. While it mentions the tool's purpose, it lacks details on behavioral traits such as pagination behavior (implied by the 'limit' parameter but not explained), error handling, authentication requirements, or rate limits. This is a significant gap for a tool with multiple parameters and no annotations.

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 appropriately sized and front-loaded, with two concise sentences that directly state the tool's purpose and usage context. Every sentence earns its place without redundancy or unnecessary elaboration.

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 (5 parameters, no output schema, no annotations), the description is adequate but incomplete. It covers the basic purpose and usage but lacks behavioral details (e.g., output format, error cases) that would help an agent use it effectively. Without annotations or an output schema, more context is needed for full completeness.

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

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

The schema description coverage is 100%, so the schema already documents all parameters thoroughly. The description does not add any additional meaning or context beyond what the schema provides (e.g., it doesn't explain parameter interactions or default values beyond the schema). Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

The description clearly states the tool's purpose with specific verbs ('browse and list') and resources ('files and directories in a Bitbucket repository'). It distinguishes this from sibling tools like 'get_file_content' (which retrieves content) or 'search' (which searches across repositories) by focusing on structural exploration.

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

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

The description provides clear context for when to use this tool ('to explore repository structure, find files, or navigate directories'), but it does not explicitly state when not to use it or name specific alternatives. For example, it doesn't clarify that 'get_file_content' should be used for reading file contents instead of this tool.

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

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

With no annotations, the description carries the full behavioral burden. It does disclose a useful side effect ('Automatically sets up branch references and can assign reviewers'), but says nothing about required permissions, what happens on branch conflicts, or what the call returns.

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?

Three short sentences, front-loaded with the core action and with zero filler. There is mild redundancy between the first sentence's goal list and the second sentence's use cases, which keeps it from a 5.

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 ten-parameter mutation tool with no annotations and no output schema, the description covers intent but not outcome — an agent is not told whether the response contains a PR id, url, or reviewers assigned. The schema compensates for parameter detail, but the behavioral surface remains thin.

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 ten parameters in detail (defaults, fork/cross-repo behavior, reviewer arrays). The description adds essentially no parameter-level meaning beyond 'can assign reviewers', 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 opens with a specific verb+resource ('Create a new pull request') and enumerates concrete goals (propose code changes, request reviews, merge feature branches). It is clearly distinct from read/merge/decline siblings by name, though it never explicitly contrasts itself with them.

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?

It gives clear when-to-use conditions: submitting code for review, merging a feature branch, contributing changes. It stops short of naming alternatives or exclusions, so an agent is not told, for example, that actually merging is done by merge_pull_request rather than this tool.

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 discloses that the action 'declines or rejects' and 'closes the PR without merging,' which implies a destructive mutation. However, it lacks details on permissions required, whether the action is reversible, or any rate limits. It adds some behavioral context but is incomplete for a mutation tool.

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 front-loaded with the core action and usage guidelines in two concise sentences. Every sentence earns its place by clarifying purpose, when to use, and the outcome, with no wasted words. It is appropriately sized for the tool's complexity.

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

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

Given no annotations and no output schema, the description is moderately complete. It covers purpose and usage well but lacks details on behavioral aspects like permissions or reversibility. For a mutation tool with 4 parameters and no structured safety hints, it should provide more context on risks or requirements, leaving some gaps.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description does not add any additional meaning or syntax details beyond what the schema provides. It mentions a 'reason for declining' which aligns with the 'message' parameter but doesn't elaborate further. Baseline 3 is appropriate when the schema handles parameter documentation.

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

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

The description clearly states the specific action ('decline or reject a pull request') and resource ('pull request'), distinguishing it from siblings like 'merge_pull_request' by specifying it 'closes the PR without merging.' It avoids tautology by explaining the outcome rather than just restating the name.

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 explicitly states when to use this tool: 'when changes are not acceptable, conflicts with project direction, or when the PR needs significant rework.' It also distinguishes from alternatives by noting it 'closes the PR without merging,' contrasting with 'merge_pull_request.' This provides clear context and exclusions.

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

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

No annotations are provided, so the description carries the full burden. It discloses the key restriction (default branch cannot be deleted), which is genuine behavioral value, but says nothing about permission requirements, irreversibility, whether the remote branch is affected, or how failures are reported for a destructive operation.

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

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

Three short sentences, front-loaded with the action, then the hard constraint, then the usage context. No filler or redundancy; every sentence 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?

Covers purpose, the critical constraint, and usage context for a 3-parameter mutation with no annotations. Because there is no output schema, it could have stated what a successful delete returns or how a rejected default-branch delete surfaces, which is the remaining 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 three parameters (branch, project, repository) are already documented, including the BITBUCKET_DEFAULT_PROJECT fallback. The description adds no format or semantic detail beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb (delete) and resource (branch) scoped to a Bitbucket repository, and immediately narrows it with the constraint that the default branch cannot be deleted. An agent can distinguish this from the read-side siblings (list_branches, browse_repository) without opening the schema.

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?

Explicitly names when to use it: cleanup after merging pull requests or removing stale feature branches. There is no explicit when-not guidance beyond the default-branch restriction and no named alternative, but the intended context is unambiguous.

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, and it does add one real behavioral fact: the operation is guarded by optimistic locking. However, it omits whether deletion is permanent or recoverable, what permissions are required, and what happens on a version mismatch — meaningful gaps for a destructive mutation.

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 short sentences, zero filler, and the effect (delete a comment) is front-loaded ahead of the precondition. Nothing requires trimming.

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 5-parameter destructive tool with no annotations and no output schema, the description covers purpose and the locking precondition but leaves the failure mode (version conflict), permission requirements, and endpoint/project resolution unaddressed. The schema fills in parameter details, so 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.

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

Schema coverage is 100%, so every parameter is already documented, including version's 'Obtain from get_comments or add_comment response' guidance. The description's optimistic-locking note largely restates the schema's version field description, adding no syntax or format detail beyond it. 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?

States a specific verb and resource: 'Delete a comment from a pull request.' That is unambiguous against siblings like add_comment and edit_comment, which differ by verb. It stops short of explicitly naming the alternative to use when a comment should be modified rather than removed, so it is clear but not sibling-differentiating in text.

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 a prerequisite ('Requires the comment version for optimistic locking') but no explicit when-to-use guidance or named alternatives (e.g. use edit_comment to modify instead). Usage is implied by the verb rather than 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?

With no annotations, the description carries the burden and it does disclose the optimistic-locking requirement for the version field. However, it says nothing about permission requirements or what happens on a version mismatch, which are the key behavioral risks for an edit operation.

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

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

Three short sentences, front-loaded with the action, then intent, then the critical precondition. No filler or 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?

For a mutation tool with no annotations and no output schema, the description covers the action, purpose, and the version precondition adequately. It could say more about failure modes, but nothing critical is missing for correct invocation.

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

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

Schema description coverage is 100%, so every parameter is already documented in the schema, including version's optimistic-locking purpose. The description's note about the version repeats the schema rather than adding new meaning, so 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 states a specific verb and resource: 'Edit an existing comment on a pull request.' This clearly separates it from add_comment and delete_comment. It stops short of explicitly naming those siblings, so a 4 rather than a 5.

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?

'Use this to fix typos, update information, or reformat comments' gives concrete when-to-use context for editing versus creating or deleting. There is no explicit exclusion of alternatives, but the intent is unambiguous.

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

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

No annotations are provided, so the description carries the full behavioral burden. It claims "Retrieve all activities," which conflicts with the schema's default pagination (limit 25, nextPageStart-style paging) and it never mentions the fetchAll flag's role in actually retrieving everything — a materially misleading omission for this tool.

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 sentences, front-loaded with the core purpose. The second sentence largely restates the first ("complete activity history and timeline" repeats "all activities... timeline events"), so it does not fully earn its place, but there is no padding beyond that.

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 6-parameter, paginated read tool with no annotations and no output schema, the description covers the what but not the how: no pagination behavior, no note on what a returned activity looks like, and no guidance on fetchAll versus manual paging. Minimum viable but with clear gaps.

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

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

Schema description coverage is 100%, so every parameter (prId, limit, start, project, fetchAll, repository) is already documented in the schema. The description adds no syntax, default, or paging detail beyond that, 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?

States a specific verb (Retrieve) and resource (activities for a pull request) and enumerates the event types covered: comments, reviews, commits, and other timeline events. This implicitly positions it as the aggregate view over get_comments, get_reviews, and list_commits, though it never names those siblings explicitly.

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?

"Use this to get the complete activity history and timeline" gives implied usage context, but there is no when-not guidance and no mention of the obvious alternatives (get_comments, get_reviews, list_commits) that return subsets of the same data. An agent must infer the choice.

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 exist, so the description carries the full behavioral burden. It implies a read-only retrieval and names the source systems, but says nothing about permissions, pagination, or what happens when a PR has no reports — meaningful gaps for an unannotated tool.

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 tight sentences: the action first, then the use case. No redundancy or filler; the purpose is 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?

There is no output schema and no annotations, so the description is the only source of context. It names the report types but does not hint at result shape, empty-state behavior, or permissions, leaving the agent with an incomplete picture of the call's outcome.

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 all three parameters (prId, project, repository) are already documented in the schema. The description adds no parameter-level detail beyond what the schema provides, which is the correct baseline.

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

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

Specific verb ("Retrieve") plus concrete resource ("Code Insights reports ... and their annotations for a pull request") with named examples (SonarQube, security scans). It does not explicitly contrast with siblings like get_reviews or get_comments, but the resource is distinctive enough to disambiguate.

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?

"Use this to check quality gates, code coverage, security findings, and other CI/CD analysis results" gives clear intended use cases. There is no explicit when-not guidance or routing to an alternative sibling, which keeps it 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?

No annotations are provided, so the description carries the full disclosure burden. It usefully clarifies that the result set is filtered to comments only, excluding reviews and commits, but says nothing about read-only safety guarantees, pagination/fetchAll behavior, rate limits, or return shape — gaps the schema only partially covers.

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 sentences, zero filler, with the core action stated first and the usage condition immediately after. Every clause earns its place.

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

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

For a simple read tool with fully documented parameters and no output schema, the description covers what it returns and when to choose it. Pagination and defaulting behavior (project env fallback, limit/start) live in the schema, so nothing critical is missing, though the return format is left implicit.

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

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

Schema description coverage is 100%: all six parameters (prId, limit, start, project, fetchAll, repository) are documented inline, including pagination semantics and the fetchAll recommendation. The description adds no parameter-level meaning beyond the schema, 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?

States a specific verb (Retrieve) and resource (comments from a pull request) and explicitly narrows scope with 'only the comments,' which distinguishes it from the sibling tools that return mixed activity streams (get_activities, get_reviews). An agent can route correctly without opening the schema.

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?

Gives an explicit when-to-use condition: 'when you specifically want to read the discussion and feedback comments without other activities like reviews or commits.' The alternatives are named by category (reviews, commits) rather than by tool name (get_reviews, get_activities), so routing is clear but not fully 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 discloses the meaningful behavioral trait of aggregating across all projects/repositories and the authenticated-user scope, but says nothing about permissions, rate limits, pagination semantics beyond schema defaults (default state=OPEN, limit=25), or return shape.

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?

Three short sentences, front-loaded with the core action and scope. The final sentence ('without needing to specify each one') partially restates the 'across all repositories' claim already made in sentence one, costing a little efficiency.

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 7-parameter, all-optional read tool with 100% schema coverage and no output schema, the description covers what the tool does and when to reach for it. It omits default values (state=OPEN, limit=25, order=NEWEST) and pagination guidance, but those live in the schema.

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 baseline is 3, but the description adds real meaning by tying the role values to user intent (review = REVIEWER, authored = AUTHOR, participating = PARTICIPANT), clarifying why an agent would pick each enum value.

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

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

States a specific verb and resource ('List pull requests') plus a scope qualifier ('across all repositories for the authenticated user'), which separates it from the per-repository list_pull_requests sibling. However, it never names that sibling explicitly, so the differentiation is inferential rather than stated.

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?

Gives clear usage context mapping to the role enum: 'see PRs you need to review, PRs you authored, or PRs you are participating in.' It does not state when NOT to use this tool or name the alternative (list_pull_requests for a single repo), so it stops short of full routing 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 carries the full burden of behavioral disclosure. It describes what the tool returns ('code differences showing what lines were added, removed, or modified') and the purpose of those differences. However, it doesn't mention important behavioral aspects like whether this is a read-only operation (implied but not stated), potential rate limits, authentication requirements, or what format the diff is returned in (unified diff, JSON, etc.).

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 efficiently structured with two sentences. The first sentence states the core purpose, and the second provides usage context. Every sentence earns its place by adding value - no redundant or vague language. It's appropriately sized for a tool with 5 parameters and good schema documentation.

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

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

For a tool with 5 parameters, 100% schema coverage, but no annotations and no output schema, the description is adequate but has gaps. It explains the purpose and usage context well, but doesn't address the output format or behavioral constraints that would be important for an agent to use this tool effectively. The absence of output schema means the description should ideally mention what format the diff is returned in.

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 5 parameters thoroughly. The description doesn't add any parameter-specific information beyond what's in the schema. It mentions 'diff' generally but doesn't explain how parameters like contextLines or maxLinesPerFile affect the output format. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

The description clearly states the tool's purpose with specific verbs ('retrieve', 'show') and resource ('code differences for a pull request'). It distinguishes this tool from siblings like get_pull_request (which likely returns metadata) or get_file_content (which retrieves file contents rather than diffs). The description explicitly mentions what the diff shows: 'lines were added, removed, or modified'.

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

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

The description provides clear context for when to use this tool: 'to understand the scope of changes, review specific code modifications, or analyze the impact of proposed changes before merging.' This gives the agent specific scenarios for invocation. However, it doesn't explicitly state when NOT to use this tool or mention alternatives like get_pull_request for high-level information.

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 effectively describes the core functionality (retrieving file content) and mentions pagination behavior for large files, which is useful context. However, it doesn't cover other important behavioral aspects like error conditions (e.g., file not found), authentication requirements, rate limits, or response format details.

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 perfectly sized and front-loaded: the first sentence states the core purpose, the second provides usage context, and the third offers specific guidance for edge cases (large files). Every sentence earns its place with zero wasted words or 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?

For a read operation with 6 parameters and no output schema, the description provides adequate but incomplete coverage. It explains the what and when-to-use well, but lacks details about return values, error handling, and authentication requirements that would be helpful given the tool's complexity and absence of both annotations and output schema.

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 description coverage is 100%, so the schema already documents all 6 parameters thoroughly. The description adds minimal value beyond the schema by mentioning the 'start' parameter for pagination and implying text-based file usage, but doesn't provide additional syntax, format, or constraint details that aren't already in the schema descriptions.

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

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

The description clearly states the specific action ('Retrieve the content'), resource ('a specific file from a Bitbucket repository'), and scope ('with pagination support'). It distinguishes this tool from siblings like 'browse_repository' (which likely lists files) or 'get_diff' (which compares changes) by focusing on reading file contents directly.

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

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

The description provides clear context on when to use this tool ('to read source code, configuration files, documentation, or any text-based files') and includes an explicit alternative for large files ('use start parameter to paginate'). However, it doesn't explicitly state when NOT to use it or compare it to all sibling tools (e.g., vs. 'get_diff' for file comparisons).

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. It implies a read-only operation through verbs like 'retrieve' and 'check,' but doesn't explicitly state permission requirements, rate limits, or error behaviors. It adds some context about the scope of returned data but lacks details on pagination or response format.

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 efficiently structured in two sentences: the first states the purpose and scope, the second provides usage guidelines. Every phrase adds value without redundancy, making it appropriately sized and front-loaded with essential information.

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 read operation with 3 parameters, 100% schema coverage, and no output schema, the description provides adequate purpose and usage context. However, without annotations or output schema, it lacks details on return format, error handling, or authentication needs, leaving some gaps for the agent to infer.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters thoroughly. The description doesn't add any parameter-specific information beyond what's in the schema, maintaining the baseline score of 3 for adequate but not enhanced parameter documentation.

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

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

The description clearly states the verb 'retrieve' and resource 'pull request' with specific details included ('comprehensive details about a specific pull request including status, reviewers, commits, and metadata'). It distinguishes from siblings like get_comments or get_diff by emphasizing comprehensive details rather than specific aspects.

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

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

The description provides clear context for when to use this tool ('to check PR status, review progress, understand changes, or gather information before performing actions like merging or commenting'), which helps differentiate it from write-oriented siblings like merge_pull_request. However, it doesn't explicitly state when NOT to use it or name specific alternatives among siblings.

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

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

With no annotations, the description carries the full behavioral burden. 'Fetch' implies a read-only, non-destructive operation and it names the returned content (review history, approval status), but it says nothing about permissions, rate limits, or whether pagination affects completeness. Adequate but incomplete for a no-annotation tool.

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 tight sentences with the core action front-loaded. The second sentence is a list of use cases that earns most of its space, though it is mildly redundant with the first.

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 read tool with no output schema and no annotations, the description adequately conveys what the tool returns (review history and approval status) and when to use it. Pagination details are covered by the schema. Minor gaps remain around permissions and return structure, but nothing essential is missing.

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

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

Schema description coverage is 100%, so all six parameters are already documented in the schema, including limit, start, fetchAll, project, repository, and prId. The description adds no parameter-level detail beyond that, which is the expected baseline when the schema does the heavy lifting.

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

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

States a specific verb+resource: 'Fetch the review history and approval status of a pull request.' This clearly distinguishes it from nearby siblings like get_comments, get_activities, and approve_pull_request. It does not explicitly name those siblings, so it falls short of a 5.

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?

Gives clear use contexts: check who reviewed the PR, see approval status, understand feedback, or judge merge-readiness. However, it offers no exclusions or explicit routing to alternatives such as get_comments or get_activities, so an agent must infer which tool to pick.

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

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

No annotations are provided, so the description carries the full behavioral burden. It does disclose the return content (names, latest commits, default-branch identification), which is genuinely useful. But it says nothing about pagination behavior, permissions/scopes required, or that the operation is strictly read-only — modest disclosure for a zero-annotation tool.

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 sentences, zero waste. The action and scope are front-loaded in sentence one and usage contexts follow in sentence two. Nothing is padded or redundant.

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 usefully compensates by summarizing the returned data (branch names, latest commits, default branch marker). Combined with 100%-covered parameters, an agent has enough to call it. It falls short of 5 only because pagination/return-shape details and any auth prerequisites are left implicit.

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

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

Schema description coverage is 100%, with all five parameters (limit, start, project, filterText, repository) documented inline including defaults and env-var fallbacks. The description adds no additional parameter meaning beyond the schema. Baseline 3 is appropriate when the schema does all the work.

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?

States a specific verb and resource ('List branches in a Bitbucket repository') and goes further to enumerate what the listing contains: branch names, latest commits, and the default branch. An agent can immediately distinguish this from list_commits, delete_branch, or browse_repository without inspecting the schema.

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 second sentence gives concrete usage contexts: 'explore available branches, find branch names for checkout or PR creation, or verify branch existence before operations.' This is clear when-to-use guidance. It does not, however, name an alternative or state exclusions (e.g. when to prefer list_commits or browse_repository instead), 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?

No annotations are provided, so the description carries the full behavioral burden. Read-only behavior is implied by 'List' and the filtering semantics are stated, but auth requirements, result ordering, pagination totals, and error behavior are never disclosed. Adequate for a low-risk listing tool, but thin for a definition with zero annotation coverage.

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 sentences, front-loaded with the operation and then the use cases; no redundancy. The use-case list is slightly generic filler ('understand the evolution of a branch'), which keeps it from a 5.

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 100% parameter coverage and no output schema, the description need not explain return values or field formats. It covers purpose, filters, and usage contexts; only cross-tool disambiguation and pagination/ordering expectations are missing, which are minor for a read-only list endpoint.

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 six parameters (limit, start, author, branch, project, repository) are already fully documented in the schema, including defaults and the client-side matching caveat for author. The description only restates branch/author filtering, adding no syntax or format detail beyond the schema. 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?

States a specific verb and resource ('List commits in a Bitbucket repository') plus the scoping modifiers (branch/author filters). It is immediately distinguishable from siblings like list_branches, list_pull_requests, or get_diff without opening any schema.

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 second sentence gives concrete use cases ('review commit history, find specific changes, track contributions, understand the evolution of a branch'), which is clear routing context. However, it names no alternatives or exclusions, so an agent isn't told when to prefer get_diff or browse_repository instead.

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 describes the return format ('Returns project keys, names, descriptions and visibility settings') which is valuable, but doesn't mention authentication requirements, rate limits, error conditions, or pagination behavior beyond what's implied by the parameters. It adequately covers the core behavior but lacks comprehensive operational details.

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 efficiently structured with two sentences that each serve distinct purposes: the first states the core functionality, the second provides usage guidance and return format. There's no wasted language, and key information is front-loaded appropriately.

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

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

For a list operation with 2 parameters, 100% schema coverage, and no output schema, the description provides good context about purpose, usage scenarios, and return format. However, without annotations or output schema, it could benefit from more detail about authentication, error handling, or pagination behavior to be 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?

Schema description coverage is 100%, so the schema already fully documents both parameters (limit and start). The description doesn't add any parameter-specific information beyond what's in the schema. This meets the baseline expectation when schema coverage is complete.

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

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

The description clearly states the specific action ('Discover and list'), resource ('all Bitbucket projects'), and scope ('you have access to'), distinguishing it from sibling tools like list_repositories or search. It provides a comprehensive purpose statement that goes beyond a simple tautology.

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 explicitly states when to use this tool: 'Use this first to explore available projects, find project keys, or when you need to work with a specific project but don't know its exact key.' It provides clear context for usage scenarios, though it doesn't explicitly mention when NOT to use it or name specific alternatives.

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

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

No annotations are provided, so the description carries the full behavioral burden. 'List' strongly implies a read-only, non-destructive operation, but the description does not explicitly confirm this, mention permission requirements, or describe side effects. The schema covers pagination parameters like limit and start, so key operational details are present elsewhere.

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, front-loaded with the core operation and followed by concrete usage examples. Every sentence earns its place, and there is no redundant or vague 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?

Given seven parameters but 100% schema description coverage, the structured input is well documented. There is no output schema, so the description does not explain the return shape or ordering, but for a standard list operation the purpose and usage context are sufficiently covered. The only notable gap is the lack of explicit read-only confirmation without annotations.

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 every parameter is already documented in the input schema with defaults, enums, and filter semantics. The description mentions state, author, and direction filters but adds no syntax, format, or edge-case detail beyond what the schema already states. A baseline 3 is appropriate when the schema does the heavy lifting.

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

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

The description states a specific verb and resource: 'List pull requests in a Bitbucket repository filtered by state, author, or direction.' This clearly identifies the operation and its filtering scope. It does not explicitly distinguish this tool from the singular sibling get_pull_request, but the plural/list framing makes the distinction largely self-evident.

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 second sentence gives clear usage contexts: finding open PRs, seeing pending reviews, discovering PRs awaiting merge, and getting an overview of PR activity. It does not state when not to use this tool or name explicit alternatives, but the intended usage is well articulated.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions what the tool returns ('repository names, slugs, clone URLs, and project associations'), which is helpful. However, it doesn't disclose important behavioral traits such as whether this is a read-only operation (implied but not stated), pagination behavior (hinted at by 'limit' and 'start' parameters but not explained in description), authentication requirements, rate limits, or error conditions. For a tool with no annotations, this leaves significant gaps.

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 appropriately sized with three sentences that are front-loaded with the core purpose. Each sentence adds value: the first states what the tool does, the second provides usage context, and the third describes the return values. There's minimal waste, though it could be slightly more structured (e.g., separating purpose from usage more clearly).

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 (3 parameters, no output schema, no annotations), the description is partially complete. It covers the purpose, usage hints, and return values, but lacks details on behavioral aspects like pagination, authentication, or error handling. With no output schema, the description's mention of return values is helpful, but it doesn't fully compensate for the missing annotations and behavioral context. It's adequate but has clear gaps.

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

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

The input schema has 100% description coverage, providing clear documentation for all three parameters ('project', 'limit', 'start'). The description adds no additional parameter-specific information beyond what's in the schema. According to the rules, when schema_description_coverage is high (>80%), the baseline score is 3 even with no param info in the description, which applies here.

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 purpose: 'Browse and discover repositories within a specific project or across all accessible projects.' It specifies the verb ('browse and discover') and resource ('repositories'), and mentions the scope ('specific project or across all accessible projects'). However, it doesn't explicitly differentiate from sibling tools like 'browse_repository' or 'list_projects', which would be needed for a score of 5.

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 context by stating 'Use this to find repository slugs, explore codebases, or understand the repository structure,' which suggests when this tool might be appropriate. However, it doesn't provide explicit guidance on when to use this versus alternatives like 'browse_repository' or 'list_projects', nor does it mention any exclusions or prerequisites. The guidance is present but not comprehensive.

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. It clearly indicates this is a write/mutation operation ('merge'), but doesn't disclose permissions needed, whether the merge is reversible, rate limits, or what happens on failure. It mentions strategy selection but doesn't explain default behavior if strategy is omitted.

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 well-structured sentences with zero waste. First sentence states purpose and prerequisites, second provides strategic guidance. Every word earns its place, and the most critical information (what it does and when to use it) is 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?

For a mutation tool with no annotations and no output schema, the description does well on purpose and guidelines but lacks behavioral details about permissions, reversibility, error conditions, or return values. Given the complexity of merging code changes, more transparency about what happens during execution would be beneficial.

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 5 parameters thoroughly. The description doesn't add any parameter-specific information beyond what's in the schema, but doesn't need to since schema coverage is complete. 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 specific action ('merge'), the resource ('an approved pull request'), and the outcome ('into the target branch'). It distinguishes this tool from siblings like 'decline_pull_request' or 'create_pull_request' by focusing on the final integration step after approval.

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?

Explicitly states when to use this tool: 'when a PR has been reviewed, approved, and is ready to be integrated.' It also provides guidance on choosing the merge strategy based on team workflow and repository history, offering contextual decision-making criteria.

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

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

No annotations are provided, so the description carries the full behavioral burden. It usefully discloses that this is a batch mutation that transitions PENDING comments to published, but omits irreversibility, permission requirements, and what happens when no pending comments exist. For a mutation tool with zero annotation coverage this is only partial disclosure.

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

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

Three tight sentences, front-loaded with the core action and followed by optional effects and a clarifying summary. No filler or 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?

With no output schema and no annotations, the description should ideally cover the mutation's consequences and success/failure behavior. It adequately explains the primary effect and the optional status, but leaves auth requirements and error conditions unaddressed for a 5-parameter 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 description coverage is 100%, so the schema already documents every parameter, including the participantStatus enum and commentText. The description references the status and overview comment but adds no syntax or format detail beyond what the schema provides, making the baseline 3 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?

States a specific verb ('Publish') plus resource ('all pending review comments on a pull request') and the exact scope ('at once', 'batch operation'). The phrase 'transitions all PENDING comments to published' distinguishes it from single-comment siblings like add_comment or add_comment_inline without needing to open either schema.

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 batch/publish framing, and the description notes the optional status side-effect, but it never states when to prefer this over add_comment, add_comment_inline, or approve_pull_request, nor any preconditions such as needing pending comments to exist. The when-to-use context is inferable but not 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It describes what the tool does (searching code/files across repositories) and mentions filtering capabilities, but doesn't address important behavioral aspects like authentication requirements, rate limits, error conditions, or what the response format looks like. The description provides basic operational context but misses key behavioral details.

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 appropriately sized with three sentences that each add value. It's front-loaded with the core purpose, followed by usage context and capabilities. While efficient, the third sentence could be slightly more structured by separating the filtering and optimization aspects more clearly.

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 search tool with 6 parameters, no annotations, and no output schema, the description provides adequate context about what the tool does but lacks important completeness elements. It doesn't describe the return format, result structure, pagination behavior, or error handling. The description covers the 'what' but misses the 'what comes back' and operational constraints.

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 6 parameters thoroughly. The description mentions 'filtering by project, repository, and query optimization' which aligns with parameters but doesn't add significant meaning beyond what the schema provides. The baseline of 3 is appropriate when the schema does the heavy lifting.

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

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

The description clearly states the tool's purpose with specific verbs ('search for code or files') and resources ('across repositories'), distinguishing it from sibling tools like browse_repository or get_file_content. It explicitly mentions searching both file contents and filenames, providing a comprehensive 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 provides clear context for when to use this tool ('to find specific code patterns, file names, or content within projects and repositories'), but doesn't explicitly mention when not to use it or name specific alternatives among the sibling tools. It implies usage for search tasks but 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 carries the full burden. It usefully clarifies that only the caller's own approval is affected, but a mutation tool should also disclose failure modes such as behavior when no prior approval exists, permission requirements, and whether the PR's review state is otherwise untouched. Those gaps leave the behavioral profile only partly 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?

Two sentences, zero waste: the first states the action and the second states the triggering conditions. The core action is front-loaded and nothing is repeated from the schema or name.

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

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

For a three-parameter mutation tool with no annotations and no output schema, the description covers what the tool does and when to use it but says nothing about results or failure handling. It is minimally viable rather than fully self-sufficient.

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 prId, repository, and project are all documented in the schema, including the BITBUCKET_DEFAULT_PROJECT fallback for project. The description adds no parameter-level detail beyond the schema, 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?

States a precise verb+resource ('Remove your approval from a pull request') and is instantly distinguishable from the sibling approve_pull_request and from decline_pull_request. The object scope ('your approval') is explicit, so an agent knows this is a self-approval retraction, not a general review 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?

Gives clear situational guidance ('retract a previous approval if you discover issues after approving or if the PR has changed since your review'), which tells the agent exactly when to reach for this tool. It does not name alternatives or exclusions (e.g., using decline_pull_request when the PR should be blocked), so it falls short of a full when/when-not specification.

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 behavioral burden, and it delivers the key trait: read-modify-write semantics that preserve fields not explicitly changed, avoiding loss of reviewers or metadata. It does not cover permissions/auth requirements or error behavior, which keeps it short of a 5.

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 tight sentences, front-loaded with the action and scope, followed by the safety behavior. No filler 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 6-parameter mutation tool with no annotations and no output schema, the description covers the mutation scope and the preservation guarantee well. Remaining gaps are auth requirements and failure behavior, which are minor relative to the core semantics it does provide.

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 every parameter is already documented in the schema, including omission semantics for reviewers. The description only restates the mutable field set, adding no syntax or format detail beyond schema, so the baseline of 3 applies.

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

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

States a specific verb (update) and resource (existing pull request) and enumerates the mutable fields (title, description, reviewers). An agent can distinguish this from create_pull_request, merge_pull_request, or decline_pull_request purely from the description.

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 'Update an existing pull request', but there is no explicit when-to-use guidance, no distinction from state-changing siblings like merge/decline/approve, and no stated prerequisites. Adequate but leaves the agent to infer context.

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