Server Quality Checklist

Tool Scores

• list_pr_commentsA
  3.7/5.0
  Behavior2/5

  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.

  Conciseness5/5

  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.

  Completeness3/5

  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.

  Parameters3/5

  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.

  Purpose5/5

  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.

  Usage Guidelines4/5

  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.

• get_prA
  3.8/5.0
  Behavior3/5

  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.

  Conciseness5/5

  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.

  Completeness4/5

  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.

  Parameters3/5

  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.

  Purpose5/5

  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.

  Usage Guidelines3/5

  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.

• set_pr_draft_stateA
  3.8/5.0
  Behavior3/5

  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.

  Conciseness5/5

  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.

  Completeness4/5

  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.

  Parameters3/5

  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.

  Purpose5/5

  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.

  Usage Guidelines3/5

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

  The description implies when to use the tool (when 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.

• get_pr_diffA
  4/5.0
  Behavior3/5

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

  Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety. The description adds that it returns raw text diff, which is useful but not extensive behavior disclosure. No contradiction with annotations.

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

  Conciseness5/5

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

  Two sentences, front-loaded with the action and return type. No redundant or extraneous information. Excellent structure.

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

  Completeness4/5

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

  The tool is simple and annotations cover safety. The description explains the return value (raw text diff) and use case. Since there is no output schema, the description sufficiently covers what the agent can expect, though it does not mention potential edge cases or limitations.

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

  Parameters3/5

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

  Schema description coverage is 100% for all three parameters (repo, pr_id, workspace), so the description does not need to add parameter semantics. The baseline of 3 applies since the schema does the heavy lifting.

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

  Purpose5/5

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

  The description clearly states 'Fetch the unified diff for a pull request' with a specific verb, resource, and differentiation from sibling tools like get_pr and list_prs. It is unambiguous and action-oriented.

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

  Usage Guidelines4/5

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

  The description provides clear context: 'suitable for reviewing what the PR changes.' It implies when to use the tool, though it does not explicitly mention alternatives or when not to use it. This meets the bar for context without exclusions.

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

• list_prsA
  4/5.0
  Behavior4/5

  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.

  Conciseness5/5

  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.

  Completeness4/5

  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.

  Parameters3/5

  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.

  Purpose5/5

  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.

  Usage Guidelines3/5

  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.

• resolve_pr_commentA
  4/5.0
  Behavior3/5

  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.

  Conciseness5/5

  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.

  Completeness4/5

  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.

  Parameters3/5

  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.

  Purpose5/5

  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.

  Usage Guidelines4/5

  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.

• create_prA
  4.1/5.0
  Behavior4/5

  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.

  Conciseness5/5

  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.

  Completeness3/5

  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.

  Parameters3/5

  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.

  Purpose5/5

  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.

  Usage Guidelines4/5

  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.

• add_pr_commentA
  4.4/5.0
  Behavior4/5

  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.

  Conciseness5/5

  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.

  Completeness4/5

  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.

  Parameters3/5

  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.

  Purpose5/5

  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.

  Usage Guidelines5/5

  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.

• reply_to_pr_commentA
  4.4/5.0
  Behavior4/5

  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.

  Conciseness5/5

  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.

  Completeness4/5

  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.

  Parameters3/5

  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.

  Purpose5/5

  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.

  Usage Guidelines5/5

  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.

• get_pipeline_step_logA
  4.5/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds value by stating the return format ('plain text log contents') and the source of identifiers, without contradicting any annotations.

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

  Conciseness5/5

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

  Two concise sentences, front-loaded with the purpose and followed by key usage guidance. No unnecessary words or repetition.

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

  Completeness5/5

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

  For a simple read-only tool with no output schema, the description fully explains what the tool does, where to get needed parameters, and what the return type is. Annotations cover safety, leaving no significant gaps.

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

  Parameters4/5

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

  Schema coverage is 100%, so all parameters are documented. The description enhances this by specifying that pipeline_uuid and step_uuid come from `get_pr_pipeline_status`, adding meaning beyond the schema's basic type descriptions.

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

  Purpose5/5

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

  The description clearly states the action ('Fetch the log output') and the specific resource ('a specific pipeline step'), which distinguishes it from sibling tools like get_pr_pipeline_status (which returns status, not logs).

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

  Usage Guidelines4/5

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

  It explicitly instructs users to obtain pipeline_uuid and step_uuid from `get_pr_pipeline_status`, providing clear context on prerequisite data. While it doesn't explicitly state when not to use it, the usage context is obvious and well-referenced.

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

• get_pr_pipeline_statusA
  4.5/5.0
  Behavior4/5

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

  Annotations already document readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds behavioral context such as result ordering (most recent first) and the granularity (per-step pass/fail state), which is valuable beyond the annotations without contradicting them.

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

  Conciseness5/5

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

  Two sentences, front-loaded with purpose and key details, followed by actionable guidance. Every sentence earns its place with zero waste.

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

  Completeness5/5

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

  For a read-only tool with no output schema, the description sufficiently conveys what the user will get (statuses and step states) and how to proceed. It is self-contained and works well with the annotations and sibling context, leaving no critical gaps.

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

  Parameters3/5

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

  Schema description coverage is 100%, with all three parameters (repo, pr_id, workspace) already documented. The description does not add additional parameter semantics, so it carries no extra burden beyond the schema. Baseline of 3 is appropriate.

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

  Purpose5/5

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

  The description uses a specific verb ('Get') and resource ('status of pipelines triggered by this PR') and adds scope details ('most recent first', 'each step's pass/fail state'). It clearly distinguishes from sibling tools by focusing on pipeline status rather than PR details or logs.

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

  Usage Guidelines5/5

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

  Explicitly states when to use ('to find failing steps') and directs to the follow-up tool ('then use get_pipeline_step_log to read logs'). This provides clear contextual guidance and differentiates from alternatives.

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

• update_prA
  4.6/5.0
  Behavior5/5

  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.

  Conciseness5/5

  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.

  Completeness4/5

  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.

  Parameters4/5

  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.

  Purpose5/5

  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.

  Usage Guidelines4/5

  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.

• add_pr_inline_commentA
  4.7/5.0
  Behavior4/5

  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.

  Conciseness5/5

  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.

  Completeness5/5

  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.

  Parameters4/5

  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.

  Purpose5/5

  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.

  Usage Guidelines5/5

  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.