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

Annotations already convey that this is a non-read-only, non-idempotent mutation. The description adds the behavioral nuance that this is a general comment (not inline), which helps set expectations about the comment's scope. No contradictions.

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

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

The description is two sentences long, with the first sentence front-loading the main purpose and scope, and the second sentence offering a clear alternative. No wasted words.

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 simple nature of the tool, full schema coverage, and annotations, the description covers purpose, scope, and alternatives well. The lack of an output schema is mitigated by the fact that return values are not critical for a comment-posting tool. Sibling differentiation is strong.

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 four parameters (body, repo, pr_id, workspace) having meaningful descriptions in the schema. The tool description does not add parameter-specific details, so the baseline score of 3 is appropriate.

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

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

The description clearly states the action ('Post') and the resource ('a general comment on a pull request'), explicitly noting it is not tied to a specific file or line. It also distinguishes the tool from the sibling add_pr_inline_comment, making purpose unmistakable.

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 tells when to use this tool (general comments) and when not to (inline comments), directing users to add_pr_inline_comment as an alternative. This is exactly the kind of usage guidance expected.

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

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

Annotations already indicate mutating (readOnlyHint=false) and non-destructive (destructiveHint=false). The description adds the critical behavioral nuance that the comment anchors to a specific diff line and that line numbers must exist in the diff, going beyond annotation basics. It doesn't detail side effects like notifications or edits, but no contradictions exist.

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

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

Two short sentences with no filler. The first sentence states the action, the second provides usage guidance. Front-loaded and efficient.

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 a straightforward mutation tool with good schema coverage and annotations, the description covers the essential context: what it does, when to prepare with `get_pr_diff`, and how it differs from `add_pr_comment`. With no output schema, the description adequately supports correct invocation.

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

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

Schema coverage is 100% with clear descriptions for all 7 parameters, setting a baseline of 3. The description adds value by explaining the semantics of `line` ('confirm line numbers are present in the diff') and implicitly mapping 'specific file and line' to `path` and `line` parameters, providing guidance beyond the schema.

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

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

The description states a specific action ('Post a comment on a specific file and line within a pull request's diff') with a clear verb and resource. It distinguishes itself from the sibling `add_pr_comment` (general comments) and other comment-related tools.

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 tells when to use this tool versus alternatives: 'Use `get_pr_diff` first if you need to confirm line numbers are present in the diff. For general PR comments, use `add_pr_comment`.' This is direct and actionable.

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

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

Annotations already indicate this is a write operation and not destructive. The description adds valuable behavioral details beyond the schema, such as branch default behavior, Markdown interpretation, and the requirement for UUIDs with curly braces. This provides useful context on how the tool behaves in different scenarios.

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 compact and front-loaded with the core action. Each clause adds necessary detail about defaults, Markdown, and reviewers, with no fluff. It is a single dense sentence that earns its length.

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

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

While the description covers purpose and parameter details, it leaves a gap about how the tool identifies the repository when not run from a checkout. Only 'title' is required in the schema, and the description does not clarify whether workspace/repo can be inferred or are necessary in other contexts. This ambiguity could lead to incorrect 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%, and the description largely echoes schema descriptions (e.g., default branches, Markdown). It adds a small nuance about 'when run from inside a checkout' and 'configured main branch,' but this is marginal. The baseline of 3 is appropriate because the schema already documents all parameters well.

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 'Open a new pull request,' a specific verb and resource that clearly distinguishes it from sibling tools like update_pr or get_pr. This explicitly states what the tool does and leaves no ambiguity about its function.

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

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

The context is clear: it creates a new PR, as opposed to the other siblings. However, it does not explicitly mention when not to use it or mention alternatives. The defaults for branches provide useful context, but the description could have stated 'use this instead of update_pr' or similar.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, so the safety profile is covered. The description adds valuable behavior: the exact verdict enum values and the meaning of NO_STATUSES, which is not in the schema. This extends beyond 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?

The description is dense but well-structured: purpose first, then usage, then verdict values, then the NO_STATUSES caveat. Every sentence contributes essential information, and the most critical usage points are 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?

With no output schema, the description explains the verdict values and their semantics. It also addresses the common pitfall of interpreting NO_STATUSES. For a simple read-only status lookup, it covers everything needed to call the tool correctly and interpret the result.

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

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

Schema coverage is 100%, so baseline is 3. The description adds clarification that commit and pr_id are mutually exclusive options, and that omitting both uses HEAD — a nuance not fully captured by the schema alone (schema only mentions commit defaults to HEAD). This pushes it to 4.

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 immediately answers 'is this commit green?' and explicitly states the mechanism (Bitbucket commit build statuses). It distinguishes itself from siblings by referencing list_pipelines as an alternative for the NO_STATUSES case, making its purpose unique and 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?

Provides explicit instructions on how to select the target: pass commit or pr_id, and defaults to HEAD if neither is given. It also tells the agent when to fall back to list_pipelines (when verdict is NO_STATUSES), giving clear usage context.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint: false. The description adds valuable behavioral context beyond these: output is capped at max_bytes (default 100 KB) keeping the end, tail_lines returns last N lines, and the default behavior for step_uuid. This enriches the agent's understanding without contradicting 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 well-structured and front-loaded. It leads with the core purpose, then explains parameter behaviors, and ends with an alternative tool. Every sentence provides distinct value, with no redundancy or filler.

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

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

With 6 parameters, 1 required, and no output schema, the description covers all critical aspects: defaults, limits, acceptance criteria for pipeline_uuid, and alternative tools. Nothing an agent needs to correctly call this tool 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 the baseline is 3. However, the description adds substantial meaning: pipeline_uuid accepts build numbers and curly braces, step_uuid has a default based on failure state, tail_lines and max_bytes have specific behaviors. This goes beyond the schema descriptions, making the tool far more usable.

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 fetches log output of a pipeline step, with a specific verb+resource. It distinguishes itself from siblings by explicitly naming list_pipelines as an alternative for step state, avoiding ambiguity.

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 explicit usage guidance: when to use tail_lines, when to omit step_uuid (to get first failed step), and when to prefer list_pipelines instead. It names the alternative and the condition for selecting it, leaving no inference required.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so safety is well-covered. The description adds a list of metadata fields returned, which is useful, but it does not disclose any additional behavioral aspects like error handling, auth requirements, or rate limits. The added context is moderate, not rich.

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

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

The description is a single, efficient sentence that immediately states the action and the resource. No fluff or redundant information; every word contributes to understanding the tool's purpose.

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

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

For a simple read-only metadata fetch, the description is fairly complete. It explicitly lists the return fields, which serves as a mini output specification since no output schema exists. However, it omits edge-case behaviors like what happens if the PR doesn't exist, and it doesn't clarify parameter optionality (schema shows all optional). Still, it covers the core expectations well.

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

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

The input schema describes all three parameters (repo, pr_id, workspace) with 100% coverage, so the description doesn't need to add parameter details. It also doesn't, relying on the schema to provide the necessary semantics. Baseline 3 is appropriate given the schema's thoroughness.

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 ('Fetch') and identifies the exact resource ('Bitbucket pull request's metadata'), listing the key fields returned (title, state, author, branches, description, URL). This clearly distinguishes it from sibling tools like list_prs or get_pr_diff, which serve different purposes.

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

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

The description implies usage for retrieving a single pull request's metadata, but it does not explicitly state when to use this tool over alternatives or any exclusions. For example, it doesn't mention that list_prs should be used for multiple PRs or that get_pr_diff is for changes. Guidance is implied rather than explicit.

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

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

Beyond the annotations (readOnlyHint, idempotentHint, destructiveHint false), the description reveals two important behaviors: the output is capped at max_bytes and the tail is dropped with a note when it overflows, and stat_only:true returns a per-file summary instead of the diff text. These are critical user-facing traits that are not inferable from annotations alone.

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 with zero wasted words. The first sentence states the core purpose; the second provides actionable usage guidance and a critical limiter (max_bytes). Information is front-loaded and every sentence adds value.

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 has six optional parameters, no output schema, and no nested objects, the description covers most concerns an agent would have: how to avoid large diffs, the cap and its effect, and the distinction between summary and full diff. It doesn't detail the exact format of the stat_only summary, but that's a minor gap. The absence of required parameters is addressed indirectly by the tool's design, though not explicitly clarified.

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

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

The schema already fully describes all six parameters (100% coverage), so the baseline is 3. However, the description adds meaning beyond the schema by explaining how to combine stat_only and paths for large PRs (a workflow) and by noting the default max_bytes. It gives practical guidance on parameter usage, justifying a slight bump.

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: 'Fetch the unified diff for a pull request.' This clearly states the tool's function and distinguishes it from sibling tools like get_pr (which retrieves PR metadata) and list_prs (which lists PRs). The scope is unambiguous.

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

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

The description gives explicit guidance on how to handle large PRs: start with stat_only:true, then use paths to fetch specific parts. It also mentions the max_bytes cap and tail-drop behavior, which are practical usage constraints. It does not name alternative tools because no direct alternative exists, but the provided strategy is clear and actionable.

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

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

Annotations already cover read-only, idempotent, open-world, and non-destructive traits. The description adds valuable behavioral context: the fallback to source-branch pipelines when no pipeline is attributable to the PR, the semantics of the match field ('none' vs fallback), and that steps include UUIDs used by get_pipeline_step_log. This exceeds the safety profile and explains edge cases without contradicting 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 four dense sentences with no fluff. It leads with the primary purpose, moves to scoping, then edge-case behavior, and finally a cross-reference to a sibling tool. Every sentence adds information; none are redundant or filler.

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

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

For an 8-parameter tool with no required parameters and no output schema, the description covers everything an agent needs: scoping variants, default behavior, fallback semantics, meaning of match and note, and the link to step logs. It's self-sufficient for correct invocation and interpretation of results.

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 the schema already documents each parameter. The description adds meaning beyond that by explaining how parameters interact (e.g., 'with none of those it uses the PR for the current branch'), that commit accepts short or full SHAs, and that include_steps controls cost with a default true. This goes beyond simple parameter listings, so it earns above the baseline 3.

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

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

The description opens with a specific verb ('Find') and resource ('Bitbucket Pipelines builds'), and clarifies the output ('per-step pass/fail state'). It names the scoping parameters and even routes to a sibling tool (get_pipeline_step_log), so an agent can distinguish it from other pipeline-related tools without reading their schemas.

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

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

It explicitly enumerates when to use each scoping parameter (build_number, commit, branch, pr_id), describes the default behavior when none are given (PR of current branch), and explains the fallback logic and the distinction between match: 'none' and a fallback. It also tells the agent to use get_pipeline_step_log when step logs are needed, providing clear guidance on tool selection.

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?

The description claims 'List all comments' but the schema includes a limit parameter defaulting to 100, making 'all' misleading without mentioning pagination. While annotations correctly indicate readOnlyHint and idempotentHint, the description adds a flawed scope assertion and omits the default limit behavior.

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: the first states the action and scope, the second specifies sorting. There is no redundant phrasing or filler, and the key information 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?

Without an output schema, the description provides only a minimal return description ('sorted oldest-first') and fails to reconcile the limit parameter with the 'all' claim. It does not describe response structure or pagination, leaving agents to infer too much about the actual result set.

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?

All four parameters are fully described in the schema (100% coverage), so the description adds no additional parameter meaning. It does not mention limit, repo, workspace, or pr_id, but the schema already handles those, giving a baseline 3.

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

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

The description clearly specifies the action ('List'), the resource ('comments on a pull request'), and adds discriminating detail about including both general and inline comments. This distinguishes it from sibling comment-modification tools like add_pr_comment and reply_to_pr_comment.

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

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

The description makes it obvious this is for fetching comments rather than modifying them, but it does not explicitly mention exclusions or alternative tools. Since sibling names like add_pr_comment and resolve_pr_comment clearly indicate other use cases, the context is sufficient.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, covering safety. The description adds useful behavioral context: it returns results sorted newest first and respects the `limit` parameter. It does not mention authentication, rate limits, or pagination beyond the limit, but the annotations significantly reduce the burden.

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, directly front-loaded with the core purpose, and every clause adds value. No fluff or irrelevant details.

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

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

For a list operation with no output schema, the description covers the essential behavior: scope, filters, limit, and sort order. It does not describe the response object fields, but given the openWorldHint and the standard nature of Bitbucket PR data, this is sufficient. Slightly less complete than the ideal because it doesn't mention alternatives or edge cases.

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

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

Schema coverage is 100%, so each parameter already has a clear description. The tool description restates that filtering is possible by state, author UUID, or branch, but does not add new meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the action ('List'), the resource ('pull requests in a Bitbucket repository'), and the scope (filterable by state, author, or branch). It effectively distinguishes itself from sibling tools like get_pr (single PR) and create_pr.

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

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

The description implies usage for listing PRs with filters but does not explicitly state when to prefer this tool over alternatives like get_pr for a single PR or list_pr_comments for comments. There are no exclusions or when-not-to-use guidance, leaving the context implicit.

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

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

Annotations already indicate the tool is a non-read-only, non-destructive write operation. The description adds valuable behavioral context: for inline comments, path and line are inherited from the parent comment. This explains threading semantics beyond what annotations convey.

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, followed by targeted guidance about a potential misuse. No redundant or fluff content.

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

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

For a simple reply tool, the description covers purpose, usage, and the key threading behavior. It lacks explicit return value details, but no output schema is present and the description sufficiently enables 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?

The schema has 100% description coverage for all five parameters, so the baseline is 3. The description adds a note about comment_id's role in threading and parent inheritance, but it does not elaborate on other parameter formats or values beyond the schema.

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 'reply' and resource 'PR comment' with the outcome 'threaded reply.' It explicitly distinguishes itself from the sibling tool add_pr_inline_comment, clarifying that this tool creates a threaded reply rather than a sibling comment.

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

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

It gives clear when-to-use context: reply to an existing comment to create a threaded reply. It also provides an explicit exclusion: do not use add_pr_inline_comment because that posts a sibling comment, naming the alternative and its consequence.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=true. The description adds the default value (resolved=true) and the ability to unresolve, which is useful. Beyond that, it does not disclose additional behavioral traits (e.g., permissions, side effects) but the annotations cover the safety profile adequately.

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 concise with two sentences. The first sentence states the core action, and the second provides the default and a useful pointer to list_pr_comments. Every word earns its place, with 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?

Given no output schema and all parameters well-documented in the schema, the description covers the essential aspects: what the tool does, the default behavior, and how to check current state. It could mention edge cases or prerequisites, but for a simple mutation tool, it is sufficiently complete.

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

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

Schema coverage is 100%, and the description does not add much beyond the schema. The default value for `resolved` is already in the schema ('True to mark resolved (default), false to unresolve'), so the description's mention of 'Defaults to resolved=true' is redundant. No extra parameter insights are provided.

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

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

The description clearly states the tool's function: 'Mark a PR comment as resolved or unresolved.' This is a specific verb (mark) with a specific resource (PR comment) and state change. It distinguishes itself from sibling tools like add_pr_comment and reply_to_pr_comment, which create or reply to comments.

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

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

The description provides clear context for usage: it sets a comment's resolution state with a default. It also directs users to list_pr_comments to check current state, which is helpful. However, it does not explicitly mention alternatives or when not to use the tool, but the clarity of purpose and the reference to list_pr_comments give sufficient 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?

Beyond the annotations (readOnlyHint=false, destructiveHint=true), the description adds significant context: it consumes build minutes, can deploy, and requires a specific OAuth scope. It also warns about the need for user confirmation for custom pipelines. This enriches the agent's understanding of side effects and prerequisites, which is exactly what the dimension rewards.

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 compact yet information-dense: it front-loads the core purpose, then explains defaults, then warns about side effects and required scope. Every sentence earns its place, with no room for fluff. The three-sentence structure is well-organized and easy to parse.

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

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

For a tool with six parameters, all documented in the schema, and no output schema, the description covers the key behavioral points: what it does, when to use it, what to watch out for (build minutes, deployments, user confirmation), and a concrete prerequisite (OAuth scope). An agent has everything needed to invoke the tool correctly and safely without further inference.

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 parameters are already documented in the schema. The description repeats some key semantics (e.g., branch defaults to current git branch, commit pins to SHA) and mentions custom_pipeline, but it does not add meaning beyond what the schema descriptions already state. Since the schema carries the load, a baseline of 3 is appropriate; the description adds marginal value.

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

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

The description clearly states the action (start a Bitbucket pipeline) and specifies two distinct modes: re-running a branch build or executing a definition from the custom section of bitbucket-pipelines.yml. This is a specific verb+resource with enough detail to distinguish it from the sibling tools (e.g., list_pipelines, get_pipeline_step_log) without needing to inspect each one.

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

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

Provides explicit guidance on when to use the tool and when to exercise caution: it warns to confirm with the user before running a custom pipeline not selected together, and it states the required OAuth scope (pipeline:write) plus a rerun of setup if needed. It also clarifies the default behavior for branch and commit, showing how to control the build target. This level of context is ample for an agent to make the correct call.

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

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

Annotations already indicate this is a write operation (readOnlyHint: false), idempotent, and not destructive. The description adds the two-state behavior (draft vs. ready) but does not disclose additional context like auth needs, effects on existing state, or response shape. It aligns with annotations, so no contradiction, but adds minimal value beyond them.

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

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

The description is one concise, front-loaded sentence that clearly communicates the core purpose and parameter usage. It contains no fluff or redundant wording, earning a top score.

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 simplicity and the schema providing full parameter descriptions, the description covers the essential behavior. It lacks details on how to identify the PR (e.g., pr_id/workspace) but those are in the schema. The absence of an output schema is not a gap here since the action is a state change.

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. The description reinforces the meaning of the 'draft' parameter by explaining true/false mappings, but this is already present in the schema property description. No additional parameter nuance is provided beyond the schema.

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

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

The description clearly states the tool's specific action: 'Mark a pull request as draft or ready for review.' It uses a specific verb ('Mark') and resource ('pull request'), and distinguishes itself from siblings like 'update_pr' by focusing solely on draft state. The directional semantics (draft true/false) are explicit.

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

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

The description implies when to use the tool (when toggling draft state) but does not provide explicit guidance on when to use it over alternatives like 'update_pr', nor does it mention exclusions or prerequisites. There is no 'when to use vs alternatives' text, which is a clear gap.

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?

The description adds critical behavioral detail beyond annotations: omitted fields are left unchanged, description is Markdown, and reviewers replace the full list including the UUID curly-brace format. These are non-obvious traits that significantly aid correct invocation.

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 concise sentences with the purpose front-loaded. Every sentence delivers operational value—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 6-parameter optional-input tool without an output schema, the description captures all essential behaviors: partial updates, Markdown handling, and reviewer replacement semantics. It doesn't discuss response/error details, but that is less critical for an update 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?

With 100% schema coverage, the baseline is 3, but the description adds global semantics like 'fields you omit are left unchanged' and 'pass an empty array to clear all reviewers,' which enrich the meaning of omitted and empty values. This elevates it above the baseline.

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

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

The description opens with 'Update a pull request's title, description (the PR Overview), and/or reviewers,' clearly identifying the action and the specific resource fields. This distinguishes it from sibling tools like get_pr (read-only) and create_pr.

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 states 'Pass any combination — fields you omit are left unchanged,' which gives a clear usage rule. It doesn't explicitly mention alternatives, but the partial-update semantics are a strong contextual signal for when to use this tool.

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