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

No annotations exist, so the description carries the full burden. It usefully discloses platform limitations (task/attachments are 'Server only') and the auto-resolution behavior of code_snippet, which are real behavioral traits. But it omits permissions, idempotency, and whether the operation is reversible, leaving meaningful gaps 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?

Two dense sentences front-load the mode enumeration, which is the most decision-relevant information, then add the code_snippet fallback. No filler and no repetition of structured data.

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 15-parameter tool with nested objects and no output schema, the description covers the essential mode-selection logic and the notable code_snippet behavior. It is largely complete, though the unaddressed manage_comment relationship and mutation side-effects are minor omissions.

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 93%, so the schema already documents most parameters (baseline 3). The description goes beyond it by mapping parameter combinations to comment modes and explaining that code_snippet auto-resolves line_number when it is unknown, adding genuine semantic glue the schema cannot express.

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

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

States a specific verb+resource ('Add a PR comment') and enumerates the comment modes it supports (general, threaded reply, inline, suggestion, task). The agent knows precisely what operation is performed. It does not, however, distinguish itself from the sibling manage_comment, leaving ambiguity about which tool owns comment mutations.

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 mode enumeration effectively doubles as usage guidance by mapping each comment type to its triggering parameters (parent_comment_id for reply, file_path+line_number for inline, suggestion for suggestions, severity BLOCKER for tasks). It gives clear selection conditions among modes but offers no when-not-to-use guidance and never references the manage_comment alternative.

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 for a mutation tool, and it discloses none of it. It does not state auth/permission requirements, whether the created PR is a draft, how branch conflicts are handled, or whether the operation is reversible. This is a serious gap for a 9-parameter write 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 short but that brevity reflects under-specification rather than tight writing. There is no front-loaded structure or prioritization of information because there is almost no information at all.

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 high-complexity mutation tool with 9 parameters, 5 required, 44% schema coverage, no annotations, and no output schema, the description is completely inadequate. An agent has no way to know the return value, side effects, or how to correctly populate several fields.

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 44%, and the description adds no parameter meaning at all. Key parameters like source_branch, destination_branch, title, and close_source_branch are bare strings/booleans in the schema with no explanation in either place, so the description fails to compensate for the coverage gap.

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

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

The description states a clear verb and resource ('Create a pull request'), so an agent knows the basic operation. However, it adds nothing beyond the tool name and provides no differentiation from siblings like update_pull_request, merge_pull_request, or decline_pull_request. It is the minimum viable statement of 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?

There is no guidance on when to use this tool versus the other PR-related siblings, no prerequisites (e.g., branches must exist), and no exclusions. The single sentence offers nothing about selection 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 full burden but says nothing about the consequences of declining (state transition, reversibility, notifications) or auth requirements. The version note hints at server-side concurrency handling, but that nuance is already elaborated in the schema, not the description.

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

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

Two short sentences with the core action front-loaded and no filler. The parenthetical '(Server)' is slightly cryptic, but overall it is efficiently sized for the tool's scope.

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

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

For a mutation tool with no annotations and no output schema, the description is too thin: it omits what declining actually does, whether it is reversible, and any permission or state preconditions. The rich schema compensates on parameters, but the behavioral picture remains 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 description coverage is 100%, so both the comment and version semantics are already fully documented in the schema. The description adds no meaning beyond it, and 100% coverage establishes the baseline 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?

Names a specific verb (decline) and resource (pull request), plus the optional comment capability. It is distinguishable from merge_pull_request or set_review_status, though it does not explicitly contrast itself with those 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 decline versus merge, close, or update a PR, and no stated prerequisites (e.g., PR must be open, required permissions). The only hint at usage is the passing mention of the optional comment.

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

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

With no annotations, the description carries full behavioral disclosure burden. It notes that expected_head skips a server lookup, which is useful context. However, it does not state that deleting a branch is destructive, irreversible, or permission-sensitive, nor what happens on a SHA mismatch.

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

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

Two short sentences, front-loaded with the core action and immediately followed by the most useful optional-parameter hint. No wasted words.

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

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

For a destructive mutation with no annotations and no output schema, the definition is too thin. It omits permissions, irreversibility, side effects, error behavior when expected_head mismatches, and any return information an agent might need.

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 75%, so the schema already documents workspace, repository, and expected_head. The description adds meaning for expected_head by explaining that passing it avoids a lookup call. It does nothing for branch_name, which lacks a schema description.

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

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

The description states a specific verb and resource: 'Delete a branch.' That is clear and unambiguous. It does not explicitly distinguish itself from siblings like get_branch or list_branches, though the verb makes the distinction obvious.

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 only guidance given is a performance tip for expected_head: pass it to skip a lookup call. There is no indication of when to use this tool versus alternatives, no prerequisites, and no exclusions or warnings about branch deletion.

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 disclosure burden. It does add real behavioral context: the default response includes open PRs only, and merged PRs are pulled in when include_merged_prs is set. However, it says nothing about read-only nature, permissions needed, or behavior when the branch does not exist.

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

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

A single clause-dense sentence with the core action front-loaded and the modifier explained inline in parentheses. Nothing is wasted.

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

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

With no output schema and no annotations, the description does the important work of stating what is returned (branch, latest commit, open/merged PRs), which is what an agent most needs here. It stops short of failure modes or ordering guarantees.

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 75%, and the description's parenthetical is what actually explains what include_merged_prs toggles (merged PRs are added to the result), which the schema's bare 'Default false' does not. The undocumented branch_name parameter and the workspace/repository params get no additional meaning from the description.

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

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

The description gives a specific verb+resource ('Get a branch') and enumerates the payload (latest commit, open PRs). It implicitly separates itself from list_branches and list_branch_commits by being a single-branch detail fetch, but it never names a sibling to make the boundary explicit.

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

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

There is no when-to-use guidance, no prerequisites, and no mention of alternatives such as list_branches or list_branch_commits. The agent must infer the use case from the word 'Get' 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?

With no annotations, the description carries the full behavioral burden. It does disclose the return format (raw unified diff text) and what the "files" mode omits, which is genuinely useful. However, it says nothing about permissions, diff-size limits/truncation for large commits, or how include/exclude patterns interact with file_path.

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 compact sentence, front-loaded with the primary output format and then the alternate mode. Minor awkwardness in the quoted "detail:"files"" fragment, but no wasted 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?

For an 8-parameter tool with no annotations and no output schema, the description covers the two output shapes but omits how context_lines, file_path, and include/exclude_patterns affect the result, and says nothing about limits on large diffs. Adequate but with clear gaps given the parameter count.

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 already high at 75%, so the baseline is 3, and the description earns a bump by explaining the meaning of the detail enum: "files" yields the changed-file list without diff bodies while the default produces the full diff. That adds behavioral meaning to the enum beyond the terse schema text "Default diff".

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 verb and resource ("Get a commit diff") and immediately distinguishes its two output modes (raw unified diff vs. file-only list). It is clearly the commit-level counterpart to the sibling get_pull_request_diff, though it never names that sibling explicitly to complete the 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?

It states the condition for the "files" mode ("no diff bodies"), which is useful selection guidance, but gives no direction on when to prefer this over get_pull_request_diff, get_file_content, or list_branch_commits. Usage is implied rather than stated.

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

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

With no annotations, the description carries the full burden and does well: it discloses that windows are applied server-side, the 5000-line-per-call cap, and that negative start_line triggers a tail fetch of the whole file. It omits error behavior, defaults for line_count, and auth/permission requirements.

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

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

Two tight sentences with the default behavior and the 5000-line limit front-loaded, followed by the exception and a preference hint. Dense but not wasteful; the parenthetical tail note is slightly compressed but readable.

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

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

For a 7-param read tool with no annotations and no output schema, the description covers the important fetch-mode semantics and limits. Remaining gaps (return format, error cases, line_count defaults) are minor relative to what is disclosed.

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 71%, and the description adds real meaning beyond it: the server-side nature of start_line/line_count, the 5000-line ceiling per call, and the tail semantics of negative start_line. It still doesn't clarify how line_count behaves without start_line or default values.

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

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

States a specific verb+resource ('Read a file') and immediately frames the core behavioral model: windowed reads by default with a full-content escape hatch. It is clearly distinguishable from siblings like list_directory_content or get_pull_request_diff, though it doesn't explicitly name what it is not.

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

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

Gives clear guidance on mode selection ('prefer windows', use full_content or negative start_line only when the whole file is needed). It lacks explicit when-not guidance or named alternatives, but the default-mode guidance is actionable.

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

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

No annotations, so the description carries the full burden. It usefully discloses that the response carries `version` for follow-up mutations and explains the flag-driven payload options, but omits permissions/auth requirements, pagination behavior, and comment_limit semantics already hinted at only in the schema.

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

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

Two dense sentences, front-loaded with the core purpose, then the flag/behavior notes and the version field. Nothing is wasted.

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

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

With no output schema and no annotations, the description adequately covers the returned payload categories, the key toggles, and the version field needed for mutation follow-ups. Minor gaps around auth and pagination keep it from being fully complete.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds real interpretive value: it explains the effect of include_comments/include_file_changes (a lean 1-call metadata read) and what include_tasks surfaces. Only comment_limit is left unexplained in prose.

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

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

Specific verb (Get) + resource (pull request) with an enumeration of the returned data (metadata, reviewer status, merge info, comments, changed files). This distinguishes it from list_pull_requests and get_pull_request_diff without naming them, so it stops just short of explicit sibling routing.

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

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

Gives concrete when-to-use guidance: set include_comments/include_file_changes false for a 1-call metadata read. It does not, however, explicitly name alternative tools (e.g., get_pull_request_diff for diffs) or state exclusions, so it lacks full routing guidance.

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

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

With no annotations, the description carries the burden and does add genuine behavioral context: the output is unified diff text, line numbers come from @@ headers, and +/- prefixes mean added/removed. It also flags that file_path filtering and ignore_whitespace happen server-side. It omits large-diff/truncation behavior, binary file handling, and whether the raw text is paginated, which are notable gaps for a diff-returning read tool but not disqualifying.

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

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

Two dense sentences, front-loaded with the verb, resource, and output format, then scoping options. No filler, no repetition of the schema.

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

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

For an 8-parameter read tool with no annotations and no output schema, the description covers the essentials: what is returned and how to scope it. The absence of output schema is largely compensated by the explicit format description, though size/truncation behavior on large diffs remains unaddressed.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds meaning beyond the schema by framing file_path as the server-side single-file scope versus include/exclude globs, clarifying how the three scoping parameters relate. It does not explain precedence when file_path and patterns are combined, so it falls short of a 5.

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

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

States a specific verb and resource ('Get a PR diff') plus the exact return format ('raw unified diff text'), which cleanly separates it from siblings like get_pull_request or get_file_content. An agent can identify the tool without opening the schema.

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

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

It explains how to narrow results ('Scope with file_path (server-side) or include/exclude glob patterns'), which is real usage guidance, but it never states when to prefer this tool over get_pull_request or get_file_content, nor any exclusions or preconditions. Usage is implied rather than explicit.

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

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

With no annotations, the description carries the full burden and does disclose non-obvious behavior: since-as-rev and include_merge_commits are filtered server-side, while author/until/search and date-valued since are filtered client-side over a bounded page walk. It also notes when more pages exist, which sets pagination expectations. It stops short of describing result shape or permission requirements.

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

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

Two dense sentences with the core purpose front-loaded and no filler. The second sentence is information-packed but slightly compressed, packing four filter behaviors into one clause chain.

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

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

For an 11-parameter read tool with no output schema, the description covers the filtering semantics that matter most and signals pagination. It could say more about the returned commit fields, but the operational behavior an agent needs to call it correctly is present.

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 already 82%, so the schema supplies most parameter meaning. The description still adds real value by clarifying the dual nature of `since` (rev means server-side, date means client-side) and the server-side treatment of include_merge_commits, resolving an ambiguity the schema leaves implicit.

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

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

States a specific verb and resource ("List commits on a branch"), which separates it from get_commit_detail and list_pr_commits by scope. However, it never explicitly contrasts itself with those siblings, so the differentiation is inferable rather than stated.

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

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

The description explains which filters run server-side vs client-side, which implicitly tells the agent when a filter is cheap, but it offers no explicit when-to-use guidance or exclusions relative to siblings like list_pr_commits or get_commit_detail. Usage is implied by the branch-scoped framing.

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 disclosure burden. It does note the sort order ('most recently modified first on Server'), which is genuine behavioral context, but the cryptic 'on Server' qualifier is unexplained and it says nothing about read-only nature, pagination behavior, or result shape.

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

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

A single short sentence with the resource front-loaded and no padding. The parenthetical ordering hint is arguably worth keeping, though 'on Server' is vague enough to verge on noise.

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 paginated list tool with full schema coverage and no output schema, the description covers the essentials minimally. It omits any mention of pagination semantics or how branch listing relates to the sibling branch tools, leaving a real gap given the tool's role in a large PR-management suite.

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

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

Schema description coverage is 100%, with limit, start, filter, workspace, and repository all self-documented, so the schema already does the heavy lifting. The description adds no parameter-level meaning beyond what the schema provides, which is the expected baseline here.

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

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

States a specific verb and resource ('List branches') and adds an ordering note, so an agent knows it returns a collection rather than a single branch. It does not explicitly differentiate itself from siblings like get_branch or list_branch_commits, but the verb choice makes the distinction reasonably inferable.

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 when-to-use guidance: no indication of when to prefer this over get_branch (single branch) or list_branch_commits (commits within a branch). The workspace/repository scoping it requires is only discoverable from the schema.

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. 'List' implies a read, but it says nothing about whether the listing is recursive, how results are ordered or paginated, permission requirements, or output size limits.

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

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

A single front-loaded sentence with zero filler. Every word 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?

Parameters are fully covered by the schema and the operation is a simple read, but with no annotations or output schema the description should disclose recursion behavior, result ordering, and the shape of the listing. It is minimally adequate rather than complete.

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

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

Schema coverage is 100%, so all four parameters (path, branch, workspace, repository) are already documented in the schema, including defaults. The description adds no format or syntax detail beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb (list) and resource (files and directories) scoped to a repository path. It is implicitly distinguishable from siblings like get_file_content or list_branches, though it never names them 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 when-to-use guidance, no exclusions, and no pointer to alternatives such as get_file_content for reading a specific file. The agent must infer context entirely from the 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?

No annotations are provided, so the description carries full behavioral burden. 'List' implies a read-only, non-destructive operation, but nothing is said about pagination defaults, result ordering, permissions, or the server-only nature of include_build_status beyond what the schema already notes.

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

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

A single, front-loaded sentence with zero filler, which is appropriately efficient. It is arguably under-specified for a six-parameter tool, but not verbose or wasteful.

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

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

There is no output schema and no annotations, so the description is the only place return shape and pagination behavior could be explained, and it says nothing about them. The 100% schema coverage compensates for the parameter side, keeping this at a minimum-viable 3.

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

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

Schema description coverage is 100%, so all six parameters (including limit, start, and include_build_status) are already documented in the schema. The description adds no syntax or format meaning beyond that, making the baseline 3 appropriate.

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

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

States a specific verb (List), resource (commits), and scope (in a pull request), so an agent can distinguish it from get_commit_detail or list_branch_commits. It is clear but does not explicitly name or contrast the nearest sibling (list_branch_commits), leaving that inference to the agent.

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 when-to-use guidance, prerequisites, or alternatives. It does not tell the agent when to prefer this over list_branch_commits or get_pull_request_diff, so selection relies entirely on the 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?

No annotations are provided, so the description carries the full burden. It implies a read-only, permission-scoped listing via 'accessible' but says nothing about pagination behavior, result counts, ordering, or what happens with the permission filter.

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

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

A single front-loaded sentence with no wasted words. However, the extreme brevity edges into under-specification rather than optimal conciseness for a 4-parameter tool.

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 optional parameters, no required params, and no output schema, the description omits pagination guidance, the meaning of the permission filter, and any result shape hints. It is too thin to fully guide invocation.

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

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

Schema description coverage is 100%, so the four parameters (name, limit, start, permission) are already documented in the schema. The description adds no extra meaning such as filter matching semantics or how permission interacts with 'accessible'.

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

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

States a clear verb ('List') and resource ('projects/workspaces') with the scope qualifier 'accessible'. It does not distinguish itself from the nearest sibling (list_repositories) or explain how projects differ from workspaces.

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 indication of when to use this tool versus list_repositories or any other listing tool, nor any mention of prerequisites or when the result would be empty. The agent is left to infer usage entirely from the 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?

No annotations are provided, so the description carries the full burden. It usefully discloses the dual-mode behavior (cross-repo aggregation gated on omitting repository, which is Server-only), but says nothing about return format, pagination, ordering, or auth requirements for a 7-param list tool.

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

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

Two sentences with strong front-loading: the primary action leads, and the conditional cross-repo mode follows. Dense but no wasted words; could be marginally clearer about defaults.

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

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

With 100% schema coverage and 7 params, the schema handles parameter mechanics. The description covers the key mode split but omits return shape and result ordering; for a moderately complex list tool with no output schema, an agent still lacks some context on what comes back.

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

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

Schema coverage is 100%, so every parameter is already documented in the schema (including `role` as 'Cross-repo mode only' and `repository` omission). The description mostly restates the schema's cross-repo interaction, adding emphasis rather than new semantics — baseline 3 fits.

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

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

States a specific verb+resource ('List pull requests') plus a scope variant (repo-scoped vs cross-repo dashboard), which cleanly separates it from get_pull_request. It never names a sibling explicitly, but the resource and mode distinction make its role obvious.

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

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

Gives real when-to-use guidance: omit `repository` to aggregate YOUR PRs across all repos and refine with `role`. It does not name alternative tools (e.g., get_pull_request for a single PR) or state exclusions, so it stops short of a 5.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It adds one useful trait (host-dependent scoping: project-scoped or all accessible on Server), but says nothing about pagination behavior, permission requirements, result ordering, or authentication. For a 5-parameter listing tool with zero annotation coverage, this is a substantial gap.

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

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

A single front-loaded sentence with no filler; the core purpose arrives immediately. The parenthetical is slightly compressed but still earns its place by conveying the Server-scope behavior.

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?

All parameters are optional and there is no output schema, so the description need not explain returns. However, with no annotations and a Cloud/Server distinction that changes required parameters, the definition should say more about defaults, pagination, and platform-dependent behavior than one clause.

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

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

Schema description coverage is 100%, so all five parameters are already documented in the schema, and the description adds no parameter-level meaning beyond the host qualifier. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb (List) and resource (repositories) with a scope qualifier distinguishing project-scoped from all-accessible-on-Server. No sibling tool shares this resource, so differentiation is largely unnecessary, but the description never says how it relates to list_projects. Clear and specific, just short of a 5.

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

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

Gives no when-to-use guidance, no alternatives, and no prerequisites. The parenthetical hints that behavior differs by host, but it never states which condition (project vs Server-wide) the caller should choose or that `workspace` is required on Cloud. The agent must infer all of this from the schema.

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 full burden and it partially delivers: it discloses the Server-only restriction on to_task/to_comment and hints that version makes writes faster. However, it omits whether delete is reversible, what permissions are required, and what happens to concurrent edits beyond the schema note. Adequate but incomplete for a mutation tool.

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

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

Two compact sentences that front-load the action set before the constraint and version note. No obvious filler, though the parenthetical Server annotations are slightly terse.

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 multi-action mutation tool with no output schema, the description covers the operation set and the version/Server constraints but leaves return values, error behavior, and permission requirements unaddressed. It is minimally sufficient rather than complete.

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

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

Schema coverage is 71%, so most parameters are self-documented. The description adds the source of version ('from get_pull_request output'), which the schema does not state, but contributes nothing else beyond the schema for text/action/workspace. Baseline 3 is appropriate.

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

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

The description enumerates the specific operations (edit, delete, resolve, reopen, convert) applied to a concrete resource (PR comment or task). This cleanly separates it from siblings like add_comment (which creates) and the update_pull_request family. An agent can identify the tool's role without opening the schema.

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

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

The action list implies when to use each operation, and the '(Server-only)' note scopes to_task/to_comment, but there is no explicit guidance on when to choose this over add_comment or how a caller decides between action values. Usage is inferable rather than stated.

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

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

No annotations are provided, so the description carries the full burden. It does not disclose that merging is an irreversible state change, what permissions are required, what happens to the source branch by default, or how merge conflicts/strategy defaults are handled. The 'Pass version to save a fetch' line merely restates schema 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?

Two short sentences, front-loaded with the action, with no wasted words. The brevity is efficient, though the second sentence spends space duplicating schema detail instead of covering the gaps.

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

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

For a 7-parameter, annotation-free mutation with no output schema, the description is too thin: it omits merge prerequisites, failure modes, and the effect of merge_strategy/close_source_branch defaults. An agent could call it, but without knowing the consequences or preconditions.

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 86%, so the schema already documents `version`, `merge_strategy`, `close_source_branch`, and the identifier parameters thoroughly. The description's `version` sentence is redundant with the schema's own (richer) explanation, so it adds no meaning — baseline 3 applies.

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

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

The description gives a specific verb and resource ('Merge a pull request'), which cleanly separates it from siblings like decline_pull_request, update_pull_request, and create_pull_request. It stops short of naming any sibling or stating scope (e.g., required approvals), but the action is unambiguous.

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

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

There is no guidance on when to merge versus decline or update, nor any prerequisites such as the PR being approved or conflict-free. The only contextual sentence is about the `version` parameter, which is invocation advice rather than usage guidance.

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

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

With no annotations, the description carries full behavioral burden. It usefully discloses that this applies to the calling user ("YOUR") and that the states are mutually exclusive, implying a single overwritten state. However it omits permissions required, whether an existing review is overwritten, reversibility, and notification side effects for what is a mutation.

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

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

Two sentences, front-loaded with the action and target, then the state enumeration. Every clause carries information; no filler or restatement of the name.

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

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

There is no output schema or annotations, so the description must cover enough for a mutation call. It handles the core state semantics well but leaves gaps: whether review state is overwritten, auth/permission requirements, and what the call returns. Adequate but with clear holes.

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 80%, so the baseline is 3, but the description adds real meaning to the enum: NEEDS_WORK is glossed as "request changes" and UNAPPROVED as "clear," which the bare enum values do not convey. It does not explain the optional comment parameter's role beyond the schema text.

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

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

States a specific verb (Set) plus resource (YOUR reviewer status on a PR) and enumerates the three mutually exclusive target states. No sibling tool in the list sets review status, so the scope is unambiguous and an agent can select it without opening the schema.

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

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

"One call; the three states are mutually exclusive" gives implicit usage guidance about how the tool is invoked, but there is no explicit when-to-use/when-not or routing to alternatives (e.g., add_comment for discussion versus NEEDS_WORK for blocking). Usage context is implied rather than stated.

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

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

With no annotations, the description carries the disclosure burden and does so well: it explains that reviewers/approvals are preserved unless `reviewers` is passed, and that supplying `version` makes the write conditional and fails on concurrent modification. It still omits permission requirements and whether all fields are optional.

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

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

Three short sentences, front-loaded with purpose and followed by the two highest-value behavioral caveats. No filler and every sentence earns its place.

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

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

For a 9-parameter mutation tool with no annotations and no output schema, the description covers the trickiest fields (reviewers, version) but never mentions that title/description/destination_branch can be changed, nor whether the write is partial or full-replacement. It is adequate but leaves meaningful gaps.

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

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

Schema coverage is 67% and the schema already documents `version`, `reviewers`, `attachments`, and the required identifiers. The description adds genuine cross-cutting meaning about the reviewer/approval interaction and the version fetch-save behavior, though title, description, and destination_branch remain unexplained in both places.

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

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

States a specific verb+resource ('Update a pull request'), making it immediately distinguishable from create/merge/decline siblings. It does not explicitly name those siblings, but the mutation scope is clear.

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

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

Gives conditional guidance on the `version` parameter (pass to save a fetch, or omit for auto-retry), which implies when each mode is appropriate. However, there is no explicit statement of when to use this tool versus alternatives like merge or set_review_status, and no prerequisites are mentioned.

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