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

No annotations are provided, so the description carries the full burden of disclosing behavior. It states that a comment is added and can be inline, but it does not mention permissions, side effects, whether replies are supported via parent_id, or how the inline modes affect request 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 a single, front-loaded sentence with no filler. It states the core action first and appends the important scope distinction in a parenthetical.

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 8 parameters, no annotations, and no output schema, the description is too sparse. It does not explain when inline parameters are required, how replies work, or how this tool relates to the comment lifecycle, leaving the agent to infer important invocation rules.

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 75% schema description coverage, most parameters are already documented. The description adds some useful context by mentioning 'general or inline on a specific file/line,' which maps to the inline_* parameters, but it does not clarify the relationships among inline_from, inline_to, and inline_path, or explain the undocumented repo_slug and workspace parameters.

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 ('Add') and a concrete resource ('a comment to a pull request'), and it differentiates the two modes: general comments versus inline comments on a specific file/line. This clearly distinguishes it from sibling tools like getPullRequestComments, updatePullRequestComment, and deletePullRequestComment.

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 no guidance on when to choose this tool over alternatives or what conditions apply. It does not mention that this creates a new comment while updatePullRequestComment modifies an existing one, nor does it clarify requirements for inline vs. general comments.

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?

There are no annotations, so the description carries the transparency burden. It clearly conveys the core state change (open PR → draft) but does not mention error conditions, permissions, or what happens if the PR is already draft or not open.

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, focused sentence that immediately states the action and target state. It is concise and easily parsed, with no extraneous 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?

The tool is simple and the description communicates the main conversion behavior clearly. However, with no annotations or output schema, the description should ideally mention preconditions (e.g., the PR must be open and not merged) and basic caveats, which are only implied by the word 'open.'

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 33%, with only pull_request_id described. The description adds context to the general purpose but does not clarify the relationship between workspace, repo_slug, and pull_request_id, nor does it explain where to find these identifiers.

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—converting an open pull request to draft—with a clear verb and resource. It is distinct from the sibling tool publishDraftPullRequest, but it does not explicitly name alternatives or contrast itself, so it stops short of full differentiation.

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 this tool is for open pull requests that should be moved back to draft status, but it provides no explicit guidance on when to choose it over updatePullRequest or createDraftPullRequest. No exclusions or alternative recommendations 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 exist, so the description carries the full behavioral burden. It only restates the creation action and does not disclose whether the PR remains unpublished, what 'draft' means in this workflow, or what side effects occur. This is especially ambiguous given the sibling publishDraftPullRequest.

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, short sentence with no fluff, but it is under-specified and mostly restates the tool name. It is concise rather than informative.

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 creation tool with six parameters, no annotations, and no output schema, this description is too minimal. The schema supplies required fields and some parameter descriptions, but the description does not explain how draft PRs behave, when they need publishing, or how this endpoint relates to its siblings.

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 description adds no parameter meaning. The schema covers 67% of parameters, but repo_slug and workspace lack descriptions, and the description does not clarify their role, defaults, or relationship to one another.

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 clear action and resource: 'Create a draft pull request.' The word 'draft' differentiates it from the sibling createPullRequest, though it does not explicitly contrast against publishDraftPullRequest or convertToDraft.

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 guidance on when to use this tool instead of createPullRequest, publishDraftPullRequest, or convertToDraft. The description does not mention prerequisites, context, or exclusions, leaving the agent to infer the appropriate scenario.

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 is the only source of behavioral context. It only restates the creation action and does not disclose side effects, prerequisites, permissions, or behavior such as default destination branch handling. This is below what is needed for a mutation tool.

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

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

The description is short and free of filler, which is good, but it is underspecified for an 8-parameter tool and adds no structure beyond the tool name. It is minimal rather than optimally concise.

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 8 parameters, no annotations, no output schema, and a closely related draft-PR sibling, a six-word description is inadequate. It omits guidance on repository/workspace needs, default branch behavior, and when the draft variant should be used.

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 75%, so the schema itself documents most parameters well. The description adds no parameter semantics, but the high coverage supports the baseline score of 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 names a specific action and object ('Create a new pull request'), clearly identifying the operation. It does not distinguish this from the sibling createDraftPullRequest, so it misses full sibling differentiation.

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 verb 'create' implies this should be used when a new pull request is needed, but there is no explicit guidance about when to prefer it over createDraftPullRequest or when not to use it. No alternatives 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It only states 'delete a comment' without mentioning that deletion is irreversible, whether special permissions are required, what happens if the comment does not exist, or any side effects. This is a significant gap for a mutating operation.

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

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

The description is a single concise sentence that front-loads the core action. While it is appropriately brief for a simple delete operation, it sacrifices essential context in favor of brevity, making it less informative than ideal.

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 four parameters, two undocumented, and no output schema, the description is inadequate. It does not explain the purpose of each parameter, how to identify the comment, expected success/failure behavior, or any prerequisites. An agent would have to rely on external knowledge to call this tool correctly.

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%—repo_slug and workspace have no descriptions in the schema, and the tool description adds no information about any parameter. The description does not explain how to obtain or use the IDs, nor does it clarify optional parameters. With low coverage, the description should compensate but does not.

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 (delete) and the specific resource (a comment on a pull request), which unambiguously distinguishes it from sibling tools like addPullRequestComment and updatePullRequestComment. The verb-object structure leaves no doubt about the tool's purpose.

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 name and description—use this tool when a comment needs to be removed from a PR—but there is no explicit guidance on when not to use it or which sibling tool to prefer in alternative scenarios. No alternatives are mentioned, so the agent must infer context from the action alone.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It does not state whether the operation is read-only, whether any side effects occur, or any authentication or rate-limit requirements. For a simple getter this is a notable omission, especially without annotations to cover safety.

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, efficient sentence that front-loads the action and resource. No filler or redundant wording; it 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?

The tool is relatively simple, but with no output schema, no annotations, and incomplete parameter descriptions, the description leaves many gaps. It does not mention return format, optional vs required parameters, or any usage context. An agent would need to inspect the schema and infer behavior from the name alone.

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 33% (pipeline_uuid has a description; repo_slug and workspace do not). The tool description does not compensate by explaining what repo_slug and workspace are for, nor does it clarify that only pipeline_uuid is required. The description adds no parameter-level meaning 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 verb 'Get' and the resource 'details of a specific pipeline run', and lists the key fields (state, duration, result). This distinguishes it from siblings like listPipelineRuns (which lists runs) and getPipelineSteps (which gets steps). No 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 implies this tool is for fetching a single run, but it does not explicitly state when to use it over listPipelineRuns or mention alternatives. No exclusions or when-not-to-use guidance is provided, so it relies on inference from the name and 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?

With no annotations, the description carries the safety burden; the verb 'Get' and 'stdout/stderr logs' imply a read-only retrieval of step output. However, it does not disclose whether logs can be paginated or truncated, whether the step must be completed, or any permissions, so transparency is adequate but 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?

One short sentence conveys the action, subject, and target scope with no filler or redundancy. 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?

For a simple getter, the description plus schema is enough to know what to call, but there is no output schema and no mention of response format, pagination, or optional parameter roles. The required IDs are defined, so it is minimally complete rather than fully self-contained.

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 documents the two required parameters (pipeline_uuid, step_uuid), and the description maps them to 'logs from a specific pipeline step.' However, the optional repo_slug and workspace parameters are undocumented in both the schema and the description, and the description adds no extra meaning for them, so parameter semantics are only adequate.

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 action ('Get') and a specific resource ('stdout/stderr logs from a specific pipeline step'), which clearly distinguishes it from pipeline run and PR sibling tools. Even without a title, an agent can identify exactly what this tool returns.

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 'from a specific pipeline step' wording gives clear retrieval context: use when you have a pipeline run and step and need logs for that step. It doesn't explicitly name alternatives or exclusions, but no sibling tool returns step logs, so the selection context is clear enough.

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

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

With no annotations provided, the description carries the full burden for disclosing behavior. It only states that it lists steps and results, but provides no information on read-only vs. mutating behavior, rate limits, required permissions, or what the response structure looks like. It also doesn't mention whether the steps are ordered or if pagination is involved, leaving important behavioral aspects undisclosed.

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, concise sentence with no unnecessary words, making it easy to read and process. It is appropriately sized for the intended purpose, though it could front-load a bit more detail about the scope, but overall it fits the expected 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?

Given that there is no output schema and the tool is related to pipeline steps, the description should elaborate on the return format, such as whether results include status, timing, or logs. It also lacks information about any required authentication or workspace context. The description is minimal and does not fully equip an agent to invoke the tool correctly without additional 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 only 33%, with only pipeline_uuid having a description. The description does not add any additional meaning to the parameters; it doesn't explain what repo_slug and workspace are for, nor does it clarify the format of pipeline_uuid beyond what the schema says. Since the coverage is low, I rate this at 3 because it doesn't compensate for the missing parameter descriptions.

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

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

The description clearly states the verb 'list' and the resource 'steps within a pipeline run and their results', effectively distinguishing it from related tools like listPipelineRuns and getPipelineRun. However, it doesn't explicitly differentiate from getPipelineStepLogs, but the focus on steps and results is clear enough for selection.

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

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

The description implies it should be used to list pipeline steps, which is evident from the name and context. It doesn't explicitly state when to prefer this over getPipelineStepLogs or other pipeline tools, but the context of 'listing steps and results' is a clear enough usage context, though it lacks explicit exclusion of alternatives.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It only states that the operation fetches details; it does not mention response format, authorization requirements, error behavior, or whether any side effects occur. 'Get' weakly implies read-only, but that is minimal.

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, front-loaded sentence with no filler. It is concise, though the vague 'details' limits its informational 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 no annotations, no output schema, and a large sibling set, the description is insufficient for an agent to confidently invoke the tool correctly. It does not clarify the return value, required context, or how it differs from related PR detail tools.

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 33%: repo_slug and workspace are undocumented, and the description does not compensate. It never explains how parameters identify the pull request or when the non-required slugs are needed, leaving the agent to guess.

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 ('Get') and resource ('details of a specific pull request'), which distinguishes it from list, diff, commit, and comment siblings. However, 'details' is broad and does not specify what is included, so it stops short of full clarity.

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 guidance on when to use this tool versus alternatives like getPullRequestDiff, getPullRequestActivity, or getPullRequestComments. The description provides no context, prerequisites, or exclusions.

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

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

There are no annotations, so the description carries the behavioral burden. The verb 'get' implies a read-only operation, and the parenthetical lists the kinds of events returned, which is useful. However, it does not disclose pagination behavior, ordering, response shape, or any edge-case 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 a single focused sentence with no filler. The activity types in parentheses add useful scoping without bloating the text.

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?

The description is adequate for a simple read operation, but with no output schema, no annotation, and no mention of pagination or parameter scoping, an agent has limited information about the return envelope or request boundaries. This is not severe for a getter, but still incomplete.

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 low: only pull_request_id has an inline description, and page, pagelen, repository, and workspace are left unexplained. The description names the broad activity-log concept but does not clarify how the parameters control or scope the request.

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 names a specific action ('get') and a specific resource ('activity log for a pull request'), and the parenthetical examples clarify what kinds of events are included. This is enough for an agent to distinguish it from sibling tools like getPullRequest or getPullRequestComments.

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?

No when-to-use or alternative routing guidance is provided. The description does not explain when to choose this tool over getPullRequestComments or getPullRequestCommits, leaving the agent to infer usage from the tool name alone.

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 full disclosure burden. It conveys read-only intent through the verb 'List', but it fails to disclose pagination behavior, ordering, authorization requirements, or whether comments are in-line review comments versus general PR comments.

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, front-loaded sentence with no wasted words. It is appropriately short, but it errs on the side of under-specification.

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 five parameters, pagination options, and no output schema, the description is thin. It does not explain how pagination works, what workspace/repo_slug are used for, or how this differs from similar list-style siblings, leaving agents to infer critical call details.

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 only 20% schema description coverage, the description needed to compensate but adds no explanation beyond what the schema already shows. page, pagelen, repo_slug, and workspace are left undefined, despite being essential for correctly constructing the request.

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 pair ('List all comments on a pull request') that clearly identifies the operation. It distinguishes itself from add/update/delete comment siblings, though it isn't explicitly differentiated from getPullRequestActivity.

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 guidance on when to use this tool versus alternatives or on prerequisite context. The description implies usage ('when you need comments'), but it doesn't mention closer siblings like getPullRequestActivity or explain when chosen over them.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It only says 'List commits' and does not mention pagination behavior, ordering, response shape, required context like workspace/repo, or any read-only guarantees, which are important for a list operation with page and pagelen parameters.

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 short sentence that is front-loaded with the key verb and resource. It contains no filler or redundancy, although it may be too sparse to fully support the tool's usage.

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 there is no output schema, no annotations, and low parameter coverage, the description is far too minimal. It does not explain pagination, required identifiers, or what the returned commit list contains, so an agent likely cannot invoke the tool correctly without additional information.

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 20%, with only pull_request_id described. The description adds no meaning for page, pagelen, repo_slug, or workspace, so it fails to compensate for the low coverage and leaves most parameters unexplained.

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') and the resource ('commits on a pull request'), so an agent can immediately understand what the tool does. It does not explicitly differentiate from siblings like getPullRequestDiff or getPullRequestActivity, but the resource 'commits' is distinct enough to avoid major confusion.

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 no guidance on when to use this tool versus alternatives. It does not mention scenarios or exclusions such as 'use getPullRequestDiff for changed files instead,' leaving the agent to infer usage purely from the tool name.

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

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

With no annotations provided, the description must carry the behavioral burden, but it only states 'Get the raw diff.' It doesn't disclose read-only nature, potential size, pagination, or any side effects. The verb 'Get' implies read-only, but nothing more is added beyond that hint.

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, front-loaded sentence with no wasted words. Every word earns its place: 'Get' is the verb, 'raw diff' is the resource, and 'pull request' scopes it. Conciseness is ideal.

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 three parameters, a large sibling family, no annotations, and no output schema, the description is too sparse to be complete. It does not explain the role of repo_slug and workspace, nor what 'raw diff' means as a return value. The agent gets just enough to identify the tool but not to safely invoke it without looking elsewhere.

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 33% (only pull_request_id is described), and the description offers nothing about repo_slug or workspace. The description fails to compensate for the schema gap, leaving the role of these optional parameters ambiguous, especially since only pull_request_id is required.

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 and resource: 'Get the raw diff of a pull request.' The term 'raw' helps distinguish it from the sibling getPullRequestDiffStat, though it does not explicitly contrast with any related tool. This is clear enough for an agent to select it.

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

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

No guidance is given about when to use this tool over alternatives like getPullRequestDiffStat or getPullRequestCommits, nor any context about when a raw diff is appropriate. The agent must infer usage from the tool name and minimal description, so this dimension falls short.

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 behavioral disclosure burden. It does convey that the tool returns aggregate file-level statistics rather than raw diff content, which is useful. However, it does not mention pagination behavior, default page sizes, or explicitly confirm read-only behavior, though 'Get' implies it.

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, front-loaded sentence with no filler. It is concise and readable, though it could have added a brief note about pagination without becoming bloated.

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?

The tool has five parameters, no annotations, and no output schema, so the description must do more than this. It explains the output type but omits how page/pagelen affect results, which repository context might be needed, and how this relates to getPullRequestDiff. An agent could call it with the required parameter, but handling pagination or choosing the right sibling would be uncertain.

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 20% because only pull_request_id has a description. The tool description adds no meaning for page, pagelen, repo_slug, or workspace, which is a significant gap given the low coverage. The description needed to compensate for undocumented parameters but does not.

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

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

The description states a specific verb and resource ('Get file-level change statistics for a pull request') and clarifies the output scope with 'files added/modified/removed, lines changed'. This helps distinguish it from getPullRequestDiff, though it does not explicitly name or contrast siblings.

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 guidance on when to use this tool versus getPullRequestDiff, getPullRequest, or getPullRequestCommits. The word 'statistics' implies a use case, but no explicit conditions or alternatives are provided.

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

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

No annotations are provided, so the description carries the transparency burden, but it only says 'List recent pipeline runs.' It doesn't mention default behavior, pagination, result ordering, error cases, or that no mutations occur. This is thin for a real API 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?

The definition is a single short sentence with the main intent front-loadedcars. It loses a point because the misleading 'status or branch' clause could have been clarified or omitted.

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 annotations and no output schema, the description must carry the operational context. It fails to specify the likely-required workspace/repo_slug context, sort defaults, pagination behavior, and output shape. The mismatch between the described filters and the actual schema makes it unsafe for an agent to use confidently.

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

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

The schema description coverage is only 20%, and the description's 'status or branch' filter hint is not represented in the schema at all—there are no status or branch properties. Meanwhile, the actual parameters (workspace, repo_slug, page, pagelen) are left unexplained, so the description actively adds confusion rather than clarifying inputs.

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 operation: 'List recent pipeline runs' with optional status/branch filtering. It is a specific verb+resource and the plural 'runs' distinguishes it from single-run tools, but it never names or contrasts with siblings explicitly.

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

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

No guidance on when to use this tool versus alternatives like getPipelineRun or runPipeline, and no context about required parameters (e.g., workspace/repo_slug) or scenarios where the status/branch filter is appropriate.

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 behavioral disclosure, but it only restates the basic listing behavior. It does not mention that this is a read-only operation, that results are paginated via page/pagelen, that state defaults to OPEN, or what the returned pull request objects look like. Important operational behavior is left undisclosed.

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, front-loaded sentence with no filler or repetition. It is appropriately concise, though it is so brief that behavioral and usage context must be gathered from the schema and sibling tool names.

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 list tool, the schema fully documents all parameters, including default state and page size cap, which covers the invocation essentials. However, the absence of annotations, an output schema, and any mention of return contents or pagination behavior leaves the definition only minimally viable.

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 3 applies; each parameter has a description, and the state parameter has an enum. The tool description adds no semantic value beyond naming 'filtered by state,' but with the schema fully covering all five parameters, no compensation is required.

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 ('List'), a resource ('pull requests'), and a filtering criterion ('by state'), making the core purpose clear. It does not explicitly differentiate itself from sibling tools like getPullRequest, but the plural 'pull requests' and the 'list' verb imply a collection operation.

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?

No guidance is given on when to choose this tool over alternatives such as getPullRequest or getPullRequestActivity, nor on when the optional workspace/repo_slug defaults are sufficient. The only usage signal is the generic purpose statement, so an agent gets no exclusions or selection criteria.

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

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

No annotations are provided, so the description carries the full behavioral burden. It does disclose the core state change ('mark it as ready for review'), but it omits any additional behavioral context such as permissions, idempotency, whether the operation can be reversed, or what happens if the pull request is already non-draft.

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 concise sentence with no filler. The parenthetical adds immediate clarifying value without redundancy, and the core action 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?

With three parameters, no annotations, no output schema, and a rich set of sibling tools, this description is too thin. It explains what the tool does but not the prerequisites (e.g., the PR must be a draft), the roles of the location-related parameters, expected return values, or error behavior, leaving significant gaps for an agent choosing and invoking the tool.

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

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

Schema description coverage is only 33%, with only pull_request_id documented. The description adds no parameter-level detail and does not compensate for the undocumented repo_slug and workspace fields, leaving their meaning and optionality ambiguous for the agent.

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 and resource ('Publish a draft pull request') and the parenthetical clarifies the exact operation ('mark it as ready for review'). It clearly distinguishes this from the sibling createDraftPullRequest and convertToDraft by stating the direction of the state change.

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: an existing draft pull request should be marked ready for review. However, it does not explicitly state alternatives, exclusions, or the typical workflow context, so the agent must infer the intended usage from the action itself.

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

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

With no annotations provided, the description carries full responsibility for behavioral disclosure, yet it only states the trigger action. It does not mention that starting a pipeline is asynchronous, has side effects (consumes CI resources), may require authentication, or what the response will be.

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, front-loaded, waste-free sentence that immediately communicates the core action. It is concise, though brevity comes at the cost of omitting important context.

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 7 parameters, no annotations, and no output schema, a one-sentence description is insufficient. An agent would still need to infer the role of workspace and repo_slug, when selector_pattern is required, and what happens after the call succeeds.

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 71%, so most parameters already have descriptions. The description adds light meaning by mentioning 'branch, tag, or custom pipeline', which maps to ref_type and selector_type, but it does not help with the undocumented repo_slug or workspace parameters, nor does it clarify variables.

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 and resource ('Trigger a new pipeline run') and distinguishes the tool from read-only siblings like listPipelineRuns, getPipelineRun, and stopPipeline. The modifier 'on a branch, tag, or custom pipeline' further narrows the tool's scope.

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

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

The word 'new' implies that this tool is for starting a pipeline rather than listing or inspecting one, but it never explicitly tells the agent when to choose this over alternatives like listPipelineRuns or stopPipeline. The guidance is largely 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?

With no annotations available, the description carries the full burden of explaining behavior. It states the core action but does not mention side effects, irreversibility, whether the stop is graceful, idempotency, or what happens to in-progress pipeline steps.

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, tight sentence with no filler or redundancy. It conveys the essential action and its target without unnecessary elaboration.

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

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

For a simple pipeline-stop operation, the description gives adequate surface-level contextaint. However, with no annotations or output schema, it would benefit from stating expected effects, prerequisites (e.g., workspace/repo context), and what happens after the stop request.

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 documentation only covers pipeline_uuid, leaving repo_slug and workspace undocumented. The description does not explain why these are optional or how they relate to identifying the pipeline, so an agent gets little help beyond the parameter names.

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 pair: 'Stop/abort a running pipeline.' It clearly identifies the operation and distinguishes it from sibling tools like listPullRequests or getPipelineSteps.

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 phrase 'running pipeline' communicates the key precondition and implies it does not apply to completed or non-existent pipelines. It does not explicitly name alternatives like getPipelineRun or runPipeline, but the context is clear enough for basic 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?

No annotations are provided, so the description bears the full burden of behavioral disclosure. It only says 'Update' and lists fields; it does not disclose permissions, whether the update is partial or full, whether reviewers are replaced (though the schema hints at this), or what side effects changing destination_branch may have.

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 sentence with no filler, and it front-loads the action and key editable fields. It earns its place without redundancy.

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

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

For a mutation tool with seven parameters, no annotations, and no output schema, this description is too sparse. It omits the required parameter, does not clarify partial-update behavior, and gives no indication of what the API returns or what conditions might cause failure, leaving an agent to infer critical context from the schema and tool name.

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 documents five of seven parameters, and the description simply re-lists four of those field names without adding new semantic detail. It does not explain the required pull_request_id or the workspace/repo_slug identifiers, both of which lack schema descriptions, so the added value over the schema is minimal but not absent.

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 ('Update') with a clear resource ('pull request') and enumerates the editable fields: title, description, reviewers, destination branch. It is distinguishable from the sibling create/get/comment tools, though it does not explicitly contrast with draft-state mutation tools like convertToDraft.

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 modifying an existing pull request, and the sibling list makes it inferable that createPullRequest is for new PRs and getPullRequest is for reads. However, there is no explicit when-to-use guidance, exclusions, or recommendation against using it for draft/approval state changes.

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

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

No annotations are provided, so the description carries the full behavioral burden. It only indicates mutation via 'Update' but does not disclose whether the update is partial or full, whether permission/ownership is required, whether the change is reversible, or what effect it has on existing content.

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 succinct sentence with no filler words. It is appropriately compact, though slightly under-specified for the tool's complexity; still, it avoids redundancy and front-loads the core action.

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

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

For a mutation tool with no annotations, no output schema, and five parameters (two undocumented), the description is too thin. It omits usage context, behavioral consequences, and return behavior, leaving an agent to infer critical details from names and schema alone.

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 description adds no parameter meaning beyond what the input schema already provides. Schema coverage is 60%: content, comment_id, and pull_request_id have descriptions, but repo_slug and workspace remain undocumented, and the description does nothing to clarify them.

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 ('Update'), resource ('an existing comment'), and context ('on a pull request'). The word 'existing' distinguishes it from add/delete comment siblings, though it does not mention the updated fields or distinguish it from updatePullRequest beyond the resource name.

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

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

There is no guidance about when to use this tool versus alternatives. With siblings like addPullRequestComment, deletePullRequestComment, and updatePullRequest all present, the description offers no explicit when/when-not or alternative routing.

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