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

No annotations are supplied, so the description carries the full behavioral burden. It does disclose the threading/reply behavior, which is genuine value, but for a write operation it says nothing about required permissions or scopes, whether the comment body supports markdown, whether edits/deletes are possible afterwards, or what happens on failure — all material for a mutating call.

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 then the one branching behavior an agent needs. Nothing repeats the name or the title, and nothing could be cut without losing 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?

This is a write tool with no annotations, no output schema, 40% parameter coverage, and an undocumented required 'id' whose meaning the agent must guess. Given that combination, the description should do more than explain threading — at minimum it should identify what 'id' refers to and what a successful call returns or affects.

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 only 40%, and the description compensates well for the one genuinely ambiguous optional parameter, explaining exactly what parentId does and what omitting it means. However, the bare 'id' parameter is left unexplained, and it is genuinely ambiguous here since a comment-posting tool could be taking a pull request id or a comment id; 'text' likewise has no note on formatting. Partial compensation for a coverage gap.

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

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

"Post a comment on a pull request" names a specific verb (post) and resource (comment on a pull request), which cleanly separates it from the read-oriented siblings (bitbucket_list_pull_requests, bitbucket_get_pull_request, bitbucket_get_activities). It doesn't explicitly contrast itself with any sibling, and no sibling is a near-duplicate writer, so the omission is minor.

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 real conditional guidance, but only for the parentId parameter: include it to reply under an existing comment, omit it for top-level. There is no guidance on when to reach for this tool at all, no prerequisites, and no mention of alternatives such as resolve_task for the comment-like task workflow.

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 supplied, so the description carries the full burden; it does signal a read-only operation and tells the agent what kinds of events appear in the stream, which is genuine behavioral content. However, it says nothing about pagination behavior (the presence of a limit parameter suggests paging), result ordering, or whether the stream is truncated by default.

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

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

A single front-loaded sentence with no filler; the resource and the returned content come first and the usage hint trails it. Nothing here could be cut without losing 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 four-parameter read tool with no annotations and no output schema, the description leaves too much unsaid: the identity of `id`, pagination semantics, and any indication of the shape of an activity entry. An agent could call it but might pass the wrong identifier or mis-handle paging.

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 only 50%, so the description needs to compensate and does not. Critically, it never says that `id` is the pull request ID (an agent could read it as a project or activity ID), and it gives no meaning to `limit` such as default page size or maximum. Only `project` and `repo` are documented, and that documentation lives in the schema, not the description.

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 ("Get the activity stream of a pull request") and enumerates the contents (comments, approvals, updates), so an agent knows what comes back. It stops short of naming which sibling to prefer — notably bitbucket_get_blocker_comments, which is a narrower slice of the same data.

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?

"for reading the discussion thread" implies the use case, which is more than nothing, but there is no explicit when-to-use/when-not guidance and no mention of the obvious alternative (bitbucket_get_blocker_comments) or of how this relates to bitbucket_get_pull_request. The agent must infer the routing.

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

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

With no annotations, the description carries the full burden. It does disclose the meaningful payload shape (each task comes with OPEN/RESOLVED state and an id), which tells the agent what it can decide on, but it says nothing about pagination, result size, permission requirements, or whether state can be changed here.

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

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

A single front-loaded sentence with no filler; the resource and the returned fields are stated in the first pass an agent reads.

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

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

For a simple three-parameter read tool with no output schema, the description covers what is fetched and what fields are returned (state and ids). Only pagination and ordering behavior are missing, which is a minor gap at this complexity.

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

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

Schema coverage is 67%, with 'id' left undocumented in the schema; the phrase 'on a pull request' usefully clarifies that id refers to the pull request id, alongside project and repo. Beyond that mapping it adds no format or constraint detail, which is acceptable given the moderate schema coverage.

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

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

The description gives a specific verb and resource ('List the tasks (blocker comments) on a pull request') and even resolves a terminology ambiguity by equating 'tasks' with 'blocker comments'. It is clearly distinct from mutation siblings like bitbucket_resolve_task or bitbucket_add_comment, though it does not explicitly name the closest read sibling (bitbucket_get_activities).

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 only implied: an agent can infer this is the read path for reviewing open/resolved tasks on a PR, but there is no statement of when to prefer it over bitbucket_get_activities or bitbucket_get_pull_request. No prerequisites or exclusions are given.

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

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

No annotations are supplied, so the description carries the full burden. It effectively communicates that this is a read-only status check rather than a mutation, which is valuable given the presence of a merge sibling, and it names the result fields. It does not mention authorization requirements, whether status is computed live, or any caveats about stale results.

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

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

A single sentence with no filler, front-loaded with the action and followed immediately by the concrete output keys. It could be marginally tighter but 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 low-complexity read tool with no output schema, the description does the important work of naming the returned fields, which is what an agent needs to interpret results. Missing only the pre-merge-check guidance that would fully round out a read-only status 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 coverage is 67% with project and repo described inline (including examples) and only the numeric id left bare. The description adds no meaning beyond the schema — no note about what the id refers to (pull request ID) or whether project/repo are case-sensitive — so it neither compensates nor detracts.

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 ('Get the merge state of a pull request') and even enumerates the key returned fields (canMerge, conflicted, veto reasons). It is clearly distinct from bitbucket_merge_pull_request, though it does not explicitly contrast with bitbucket_get_pull_request.

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

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

Usage is implied — an agent would call this to check mergeability before invoking bitbucket_merge_pull_request — but the description never states that intent or names the alternative. There are no exclusions or prerequisites, so the routing must be inferred.

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 supplied, so the description carries the full disclosure burden. "Get" implies a safe read, but nothing is said about permissions/authentication needed, behavior when the id does not exist, or whether related data (diffs, comments) is excluded and must be fetched by sibling tools — meaningful gaps for a tool with zero structured 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?

A single front-loaded sentence with the returned fields packed into one parenthetical. No filler, no repetition of the tool 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 simple three-parameter getter the description is close to sufficient, and the parenthetical partly compensates for the missing output schema. However, it omits notable return attributes (state, author, timestamps) and says nothing about failure modes, so an agent still has to discover the response shape empirically.

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

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

Schema coverage is 67%: project and repo already have examples in the schema, while id is bare. The description only restates that lookup is by id and adds no format or scoping detail beyond that. The moderate coverage and minimal added meaning land at 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?

"Get one pull request by id" states a specific verb, resource, and cardinality, which separates it from bitbucket_list_pull_requests without naming it. The parenthetical enumerates what comes back (title, description, branches, reviewers, draft flag), reinforcing the resource identity.

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 only implied: fetch a single PR when its id is known. There is no explicit statement of when to prefer this over bitbucket_list_pull_requests (unknown id, browsing) or over sibling readers such as bitbucket_get_merge_status and bitbucket_get_activities, and no prerequisites are mentioned.

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

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

No annotations are provided, so the description must carry the behavioral burden. It discloses that this is a list operation and names state options plus page size, but omits default state, default/max page size, pagination mechanics, ordering, and auth requirements. For a read-only listing tool, this is adequate but incomplete.

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, front-loaded with purpose and no redundant wording. It could be slightly more structured with parameter defaults, but it is efficient and clear.

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 four-parameter list tool with no annotations and no output schema, the description covers purpose and key filters but lacks defaults, pagination details beyond page size, ordering, and expected return shape. It is minimally 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 only 50%, with state and limit undocumented in the schema. The description compensates by naming allowed state values (OPEN/MERGED/DECLINED/ALL) and clarifying that limit means page size, though it does not specify defaults or ranges.

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

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

The description states a specific verb 'List' and resource 'pull requests in a repository', clearly distinguishable from sibling bitbucket_get_pull_request which retrieves a single PR. It does not explicitly contrast with all siblings, but the purpose is clear.

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

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

It indicates optional state and page size filters, implying use for browsing or filtering pull requests, but gives no explicit when-to-use guidance versus get_pull_request or when-not, and no prerequisites.

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 supplied, so the description carries the full burden, and it does the most important part: it flags irreversibility and the confirm gate, and discloses version-selection behavior and the available merge strategies. It stops short of stating permission requirements, what happens on conflict/failure, or whether the source branch is deleted or closed after merge.

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?

Four short clauses, each carrying a distinct and necessary fact (irreversibility, required confirm, version default, optional params plus strategy values), with the most safety-critical warning front-loaded. No filler.

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

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

For a 7-parameter destructive tool with no annotations and no output schema, the definition covers the decision-critical surface: risk, gate, defaulting, and strategy choice. Gaps are secondary but real — the meaning of id, success/failure outcomes, and permission prerequisites are left unstated.

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 only 29%, so the description must compensate; it does so partially by explaining confirm, version semantics, message, and the strategyId values (merge-commit/squash/fast-forward) that the schema leaves as a bare string. However, the low-coverage parameters project/repo/id get no clarification — notably id, a bare number with no indication of whether it is a PR number or internal id.

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 and resource ("merge a pull request") preceded by the irreversibility marker, which immediately distinguishes it from every sibling (list/get/merge-status/comment tools). An agent can classify the operation 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?

It gives hard preconditions — confirm:true is mandatory and the action is irreversible — plus a default-behavior rule ("uses the current PR version unless one is given"). What it lacks is routing guidance versus the closest sibling: it never suggests checking bitbucket_get_merge_status or reading the PR first before committing the merge.

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 disclose a real internal behavior: it fetches the comment version first and then flips state to RESOLVED (implying an optimistic-concurrency mechanism). It omits permission requirements, idempotency, reversibility, and what a failed resolve looks like.

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, with the operation and its mechanism front-loaded. 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 4-required-parameter mutation with no annotations and no output schema, the description covers the mechanism but leaves the `id` parameter and the caller's prerequisites undefined. It also says nothing about the return value or side effects, which matters given no 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 coverage is 50%: repo and project are documented in the schema, while `id` and `commentId` are bare numbers. The description clarifies commentId as the blocker comment's id but never says what `id` is (presumably the pull request id), leaving a required parameter unexplained in both places.

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

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

The description uses a specific verb+resource ("Resolve a task (blocker comment) on a pull request") and clarifies that the task is a blocker comment, which distinguishes it from siblings like bitbucket_get_blocker_comments and bitbucket_add_comment. It stops short of naming a sibling explicitly, but the operation is unambiguous.

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

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

There is no explicit when-to-use or when-not-to-use guidance, and no mention of prerequisites such as first discovering the comment via bitbucket_get_blocker_comments. The phrase "by its comment id" implies the calling context but leaves alternatives and ordering to inference.

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

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

No annotations are supplied, so the description carries the full burden, and it delivers the single most important behavioral fact: the underlying PUT replaces the whole resource, so the tool re-sends title, description and reviewers to avoid clobbering them. Still missing is any statement about required permissions 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?

Two sentences, zero filler, with the action first and the data-preservation caveat 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 four-parameter mutation with no annotations and no output schema, the definition covers the main hazard (destructive PUT semantics) well. It stops short of describing the response or confirming whether the call fails on stale data.

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

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

Schema description coverage is only 50% — 'id' and 'draft' are undocumented in the schema. The description clarifies 'draft' as the PR's draft flag but never identifies 'id' as the pull request ID, so it only partially compensates for the gap.

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

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

States a specific verb and target ('Turn a pull request's draft flag on or off'), which no sibling tool does — the siblings cover listing, fetching, merging, and commenting. An agent can route to it 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?

Usage is implied by the operation itself, but there is no explicit guidance on prerequisites or alternatives, e.g. calling bitbucket_get_pull_request first to read the current draft state before flipping it. Adequate but leaves inference to the agent.

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