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

Annotations already declare readOnly=false, idempotent=false, destructive=false, and the description is consistent with a write operation. It adds meaningful operational detail beyond the annotations: Server-only gating for task/attachments, whitespace-sensitivity of code_snippet, and the strict/best match fallback, though it doesn't warn that repeated calls create duplicate 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?

A single compact sentence that front-loads the modes and puts the code_snippet fallback last. It is dense but every clause carries signal; the only slight cost is that the parenthetical detail makes it feel packed.

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 mutation with nested objects and no output schema, the description covers the mode-selection logic and the trickiest parameter interaction (snippet-to-line resolution). Remaining detail like attachments is well handled by the 93% schema coverage, so nothing essential is missing.

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

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

Schema coverage is 93%, so the baseline is 3, but the description genuinely adds semantics: severity BLOCKER creates a task, suggestion requires file_path + line_number, and code_snippet auto-resolves line_number from exact diff text. These are cross-parameter relationships the schema alone doesn't make explicit.

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 (Add) and resource (PR comment) and then enumerates the five distinct comment modes it supports, so an agent can immediately tell this is the creation tool versus the sibling manage_comment.

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

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

The mode list effectively explains when to use each variant (general vs threaded reply vs inline vs suggestion vs task) and when to prefer code_snippet over line_number. It stops short of explicitly saying to use manage_comment for editing/deleting an existing comment, which would have fully closed the loop.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, and destructiveHint=false, so the safety profile is covered. The description adds nothing beyond that: no mention of required permissions, whether the source branch must exist, side effects, or error behavior for a five-required-parameter 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?

It is a single short sentence, so there is no bloat, but this is under-specification rather than conciseness. The one sentence fails to earn its place by conveying anything not already in 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?

For a nine-parameter mutation tool with five required fields, no output schema, and incomplete schema documentation, the description is wholly inadequate. It provides no information about branch handling, reviewers, attachments, or the result of the call.

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 mentions no parameters at all. Critical fields like title, description, source_branch, destination_branch, and close_source_branch have no schema descriptions and receive no clarification from the description, leaving the agent to guess semantics.

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 sentence restates the tool name almost verbatim ('Create a pull request' for create_pull_request), giving no scope, target system, or distinguishing detail. It does convey a write action on a pull request resource, but nothing separates it from siblings like update_pull_request or merge_pull_request.

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

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

There is no guidance on when to use this versus update_pull_request, merge_pull_request, or decline_pull_request, nor any prerequisite conditions such as branch existence or permissions. The agent must infer everything 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?

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered. The description adds only a minor note that passing version saves a fetch, without explaining side effects such as notification or state transition.

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

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

The description is two short sentences with no wasted language. The core action is front-loaded, and the optional-parameter guidance follows immediately.

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 complete schema coverage and annotations covering destructive/idempotent behavior, the description is sufficient to invoke the tool correctly. It could do slightly more to describe the consequence of declining a pull request, but no output schema exists and the core call semantics are covered.

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 schema already documents all five parameters thoroughly, especially the conditional-write behavior of version. The description reinforces that comment is optional and version saves a fetch, but adds little beyond the schema.

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

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

The description states a specific verb and resource: 'Decline a pull request.' This clearly distinguishes it from sibling operations such as merge_pull_request, update_pull_request, and create_pull_request.

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

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

The usage is implied by the verb 'Decline,' but the description does not explicitly say when to use this versus merge_pull_request or update_pull_request. It also gives no exclusions or prerequisites beyond 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?

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds a genuinely useful behavioral detail — that expected_head is a compare-and-swap that avoids an extra lookup — but says nothing about irreversibility, required permissions, or what happens to open pull requests on the deleted branch.

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, action first, optimization hint second — well front-loaded. The trailing "(Server)" is cryptic noise that slightly undercuts an otherwise lean statement.

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 output schema, the description omits failure modes (e.g., what a stale expected_head returns), protection/permission requirements, and consequences for related resources. Annotations carry the safety signal, but an agent still lacks enough to handle errors 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?

Schema coverage is 75%, with branch_name entirely undescribed in the schema; the description implicitly identifies it as the target. More importantly, it explains the practical benefit of expected_head (skip the lookup) beyond the schema's terse "Known head SHA (compare-and-swap)", which is real added meaning.

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?

"Delete a branch" is a precise verb+resource statement that cleanly separates it from read-oriented siblings like list_branches and get_branch. It does not explicitly name alternatives, but the operation is unambiguous.

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

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

The only usage guidance is conditional: pass expected_head to skip a lookup call. There is no statement of when to prefer this over other branch operations, no prerequisites (e.g., branch protection, permissions), and no caution about the destructive nature of the call.

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

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

Annotations already declare readOnlyHint=true, so safety is covered. The description adds genuine behavioral detail: the payload includes the latest commit and open PRs, and merged PRs are excluded by default unless include_merged_prs is set. It still does not mention result caps, ordering, or behavior when the branch is absent.

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

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

A single sentence with no filler, and the core purpose is front-loaded before the parameter note. The trailing parenthetical is slightly compressed but costs nothing in 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?

With no output schema, the description usefully previews the return contents (latest commit, open PRs, merged toggle), which is the main thing an agent needs. Gaps remain around branch_name format and failure behavior, but for a read-only single-entity getter this is close to sufficient.

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 include_merged_prs. The description adds only that include_merged_prs widens results to merged PRs, and says nothing about branch_name (e.g., slashes or default-branch handling), which the schema leaves bare. Baseline 3 applies when the schema carries most of the load.

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 adds scope beyond the name: it returns the latest commit and open PRs. That distinguishes it from list_branches (plural listing) and list_branch_commits without needing the schema. It stops short of naming a sibling alternative, so not 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?

Usage is only implied: an agent can infer this is the single-branch detail lookup versus the plural list_branches. There is no explicit when-to-use statement, no prerequisites (e.g., branch must exist), and no mention of alternatives such as get_pull_request for PR-level detail.

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

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

Annotations already declare readOnlyHint=true. The description adds useful behavioral context by specifying that the default result is raw unified diff text and that detail:"files" omits diff bodies. It does not mention truncation, size limits, or error behavior for missing commits.

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 front-loaded sentence with no wasted text. It states the main output and the key mode switch immediately.

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 8 parameters and no output schema, so the description should carry more burden. It covers the core return format and the files-vs-diff distinction, but leaves filtering options, context-line behavior, and file-list output structure 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 description coverage is 75%, so the baseline is 3. The description usefully clarifies the detail enum and default diff behavior, but it does not explain file_path, context_lines, include_patterns, or exclude_patterns beyond what the schema names provide.

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 a commit diff. It clearly distinguishes the two output modes, raw diff vs. changed-file list, but does not differentiate this tool from sibling tools such as get_pull_request_diff or list_pr_commits.

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 implies when to use detail:"files" by saying it returns just the changed-file list with no diff bodies. However, it gives no explicit guidance on when to choose this tool over get_pull_request_diff, list_pr_commits, or list_branch_commits.

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?

readOnlyHint=true already covers the safety profile, so the description adds real value by disclosing a hard cap (≤5000 lines per call), server-side windowing semantics, and tail behavior via negative start_line. It omits error/binary-file behavior and the default window size, which keeps it at 4 rather than 5.

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 front-loaded, then the mode switches, then the recommendation. Every clause carries information; nothing is redundant with the schema or annotations.

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 read tool with no output schema, the description covers the critical decision points (window vs. full, size limit, tail mode). The main residual gap is the unspecified default window size when neither start_line nor line_count is given.

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 the baseline is 3; the description earns above that by explaining parameter interaction the schema does not — that start_line/line_count fetch only that window server-side, and that full_content or a negative start_line both trigger whole-file retrieval. It still doesn't define a default line_count or the meaning of edge 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?

"Read a file" is a specific verb+resource, and the description immediately qualifies scope with the windowing model, distinguishing it from list_directory_content by making clear it returns file contents rather than listings. It stops short of naming siblings explicitly, so a 4 rather than 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 an explicit preference rule ("prefer windows") and states the exact conditions that switch modes: full_content=true or negative start_line. There are no explicit when-not cases against sibling tools, but the mode-selection guidance is concrete and actionable.

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

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

Annotations already declare readOnlyHint=true, so safety is covered. The description adds genuinely new behavioral context: the response carries `version` for follow-up mutations (optimistic concurrency), defaults are togglable for a single-call metadata read, and include_tasks is Server-only. It does not describe pagination behavior for comments beyond the schema's default.

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

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

Two dense sentences, zero filler. Content discovery is front-loaded, followed by the cost-saving mode and the `version` follow-up hint, which is an efficient ordering for an agent scanning for both payload shape and next-step affordance.

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, seven parameters and heavy return payload, the description does enough: it names the payload sections and flags the `version` field agents need for mutations. It leaves return-shape structure and comment pagination unstated, which is a modest remaining gap for a read this rich.

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. The description earns a notch above by explaining the effect of the two include_* flags (a cheaper metadata-only read) and clarifying that include_tasks surfaces open/resolved tasks rather than a raw boolean, which the schema does not convey.

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?

A specific verb-plus-resource opener ('Get a pull request') immediately followed by an enumeration of what comes back: metadata, reviewer status, merge info, comments, changed files. That enumeration distinguishes it from list_pull_requests, but the relationship to get_pull_request_diff is left implicit.

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 actionable usage direction: 'Set include_comments/include_file_changes false for a 1-call metadata read' tells the agent exactly how to switch into a cheap mode. It never names an alternative tool or an exclusion case (e.g. when to prefer get_pull_request_diff), so it stops short of 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?

readOnlyHint=true already declares the safety profile, so the description's job is to add context beyond that, and it does: it discloses the return format and how to interpret '@@' headers and +/- prefixes. It omits limits such as truncation on very large diffs or the cost of fetching an unscoped diff, which would matter operationally.

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 no filler; the output-format fact leads and the scoping options follow. Every clause carries information an agent needs.

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-only fetch tool with no output schema, the description covers purpose, format interpretation, and scope control. It leaves unaddressed what happens on very large PRs (truncation, pagination) and how include/exclude and file_path interact when combined.

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

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

With 100% schema coverage the baseline is 3, and the description earns an extra point by distinguishing file_path as 'server-side' scoping versus glob patterns, implying the globs are applied after retrieval. That is a meaningful semantic distinction the schema's one-line property descriptions do not convey.

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') and pins down the exact output form ('raw unified diff text'), which is more precise than a generic 'get' would be. It never names a sibling such as get_pull_request (metadata) or get_file_content, so the boundary is inferable but not explicit.

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

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

The second sentence explains how to narrow scope via file_path or include/exclude globs, which is genuinely actionable. It never says when this tool is preferred over get_pull_request or when a diff would be too large to fetch this way, so 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?

Annotations only supply readOnlyHint=true, so the description carries real weight and delivers: it discloses which filters execute server-side vs client-side over a bounded page walk, and that truncation is signalled when more pages exist. That is meaningful behavioral context an agent could not derive from the schema. It stops short of describing ordering or what a result row contains.

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 no filler, and the core purpose is front-loaded ahead of the filtering caveats. The second sentence is compressed to the point of being slightly telegraphic, but every clause carries information.

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

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

For an 11-parameter tool with no output schema and only a readOnly annotation, the description covers the trickiest semantics (server vs client filtering, page-walk bounds) well. It leaves gaps on result ordering, how limit/start interact with the bounded walk, and what include_build_status returns, which an agent would have to guess.

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 82%, so the baseline is 3, but the description adds genuine meaning by clarifying that 'since' doubles as a rev/SHA (exclusive) or an ISO date and that only the rev form is server-side, while author/until/search are applied client-side. That distinction changes how an agent should combine filters and is not spelled out per-parameter in 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 opening clause 'List commits on a branch' gives a specific verb and resource, and the required workspace/repository/branch_name trio is implied by the schema. It does not explicitly name siblings like list_pr_commits or get_commit_detail, so the agent must infer that this is branch-scoped rather than PR-scoped, but the resource 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?

Usage is only implied: the description explains filtering mechanics but never says when to pick this over list_pr_commits or get_commit_detail, nor any prerequisites (e.g., that the branch must exist). An agent can reasonably infer 'use for branch history,' but nothing is stated as a selection rule.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds one genuinely useful behavioral detail — results are sorted most-recently-modified-first on Server — but says nothing about pagination behavior, total counts, or whether ordering differs on Cloud.

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?

Single short sentence with the key ordering information front-loaded and no filler. The parenthetical "on Server" is slightly cryptic but does not waste space.

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 five parameters, two required, and no output schema, the definition is minimally sufficient — the schema carries the parameters and the annotation carries safety. It still leaves gaps on pagination semantics and what a branch entry looks like, and the Server-only ordering caveat is not fully explained.

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 limit, start, filter, workspace, and repository are all documented in the schema. The description adds no parameter-level meaning beyond that, which is acceptable at this coverage level.

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 and resource ("list branches"), which is unambiguous. It does not distinguish itself from neighboring tools such as get_branch or list_branch_commits, so an agent must infer the boundary from the schemas.

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

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

There is no guidance on when to use this versus get_branch (single branch) or list_branch_commits, and no mention of prerequisites or typical contexts. Usage is only implied by 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?

Annotations already declare readOnlyHint=true, so the safe-read profile is covered. The description adds the browsing scope but omits useful behavior: whether results are recursive or single-level, how large listings are paginated or truncated, hidden-file handling, and what happens when the path 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 front-loaded sentence with no filler, but it is terse to the point of leaving out information that would help an agent call it correctly. Efficient rather than padding, so it earns a 4 rather than lower.

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 four parameters, no output schema, and no annotations beyond readOnlyHint, the description should at least sketch the shape of the result (flat list vs. tree, entry fields). It covers the core operation but leaves an agent guessing about the response and listing semantics.

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 four parameters (path, branch, workspace, repository) are already documented with defaults. The description only echoes the path concept and adds no format, syntax, or edge-case detail beyond the schema, so the 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 pairs a specific verb (List) with a specific resource (files and directories) and scope (at a repository path), making the operation unambiguous. It does not name or contrast with the obvious sibling get_file_content, so it stops 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?

There is no guidance on when to use this versus get_file_content, list_branches, or list_repositories, and no note that workspace/repository are required while path/branch are optional. The agent must infer the selection criteria 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?

readOnlyHint=true already tells the agent this is a safe read, so the description adds nothing on safety. It says nothing about pagination behavior, result ordering, or the Server-only limitation on include_build_status — all context an agent would want before calling.

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 with no filler. It is concise, but the brevity reflects under-specification rather than disciplined editing.

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

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

With 6 parameters, pagination controls, a platform-conditional flag, and no output schema, the description is too thin. It never mentions pagination defaults, ordering, or what a commit entry contains, leaving the agent to discover behavior at call time.

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 every parameter including limit, start, and include_build_status is already documented in the schema. The description adds no meaning beyond that, which is the baseline for full-coverage schemas.

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 scoped to a pull request. The pull-request scoping implicitly distinguishes it from list_branch_commits and get_commit_detail, though neither sibling is named.

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 choose this over list_branch_commits or get_commit_detail, and no prerequisites or exclusions. The agent must infer selection 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?

readOnlyHint=true already declares the safety profile, so the description's main contribution is 'accessible', which implies results are permission-filtered to what the caller can see. That is a genuine behavioral detail, but nothing is said about result ordering, pagination semantics, or what happens when the caller has no access.

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 zero waste and the core scope front-loaded. It is efficient rather than padded, though it borders on under-specified rather than genuinely 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 read-only list tool with full schema coverage and no output schema, the essentials are present. Missing is anything about how 'projects' relate to the repository tools in the sibling set, or what the returned collection shape/ordering is, which an agent would need to place results 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 100%, with name, limit, start, and permission all documented inline including defaults. The description adds no filter syntax or semantic nuance beyond that, so the 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?

States a specific verb and resource — 'List accessible projects/workspaces' — so an agent knows this is a read/list operation over project entities. It stops short of differentiating from the near-neighbor list_repositories, leaving the project-vs-repo boundary to inference.

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 call this versus alternatives such as list_repositories, and no preconditions stated. The agent must infer usage purely from the tool name and the 'accessible' qualifier.

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

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

The readOnlyHint annotation already establishes safety, so the description appropriately focuses on the non-obvious cross-repo behavior. It discloses the Server-only constraint for omitting `repository` and the fact that this returns your PRs across all repos in one 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 description is two tight sentences with no wasted text. The repository-scoped case is stated first, and the cross-repo exception follows immediately.

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

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

Given the rich schema and readOnly annotation, the description covers the main operational distinction an agent needs: repository-scoped listing versus cross-repo listing. It does not describe the return shape, but for a simple list tool with no output schema that is a minor gap.

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 schema already documents all seven parameters including role, state, limit, start, author, workspace, and repository. The description adds some meaning about repository omission and role filtering, but mostly reinforces what the schema already says.

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: listing pull requests in a repository. It also distinguishes the cross-repo mode from the normal repository-scoped mode, which differentiates it from siblings such as get_pull_request.

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

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

It clearly explains the key usage branch: omit `repository` to list your PRs across all repos, and use `role` to filter that cross-repo view. It does not explicitly name sibling alternatives like get_pull_request, but the main mode selection is clear.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds the meaningful behavioral note that omitting project scope on Server returns all accessible repositories, but says nothing about pagination behavior, filtering semantics, 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 sentence with zero filler, and the scope distinction is front-loaded in the parenthetical. Nothing could be removed without losing information.

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

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

For a five-parameter list tool with full schema coverage and a read-only annotation, the description covers the essentials but leaves pagination, filtering interaction, and result ordering unaddressed. Adequate to call correctly, but thin for an agent deciding how to page through results.

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

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

Schema coverage is 100%, so all five parameters (name, limit, start, workspace, permission) are already documented in the schema. The description adds no parameter-level detail beyond the project/Server scoping hint, so the 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?

States a specific verb and resource (list repositories) and clarifies scope: project-scoped versus all accessible on Server. It does not name any sibling (e.g., list_projects) to disambiguate, but the resource is distinct enough that an agent can tell it apart from the pull-request and branch tools.

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

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

The parenthetical implies usage context — use with a project, or omit one on Server to get everything accessible — but no alternatives are named and no explicit when-not guidance is given. The Cloud-vs-Server distinction that most affects calling behavior lives only in the schema, not the description.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the agent knows delete is irreversible and repeats are safe. The description adds that version enables a conditional write that saves a fetch, but the detailed concurrency behavior (fails on concurrent modification, auto-retry when omitted) lives in the schema, not the description. The parenthetical '(Server)' is unexplained jargon that adds ambiguity rather than clarity.

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 operation list front-loaded, so the agent gets the core capability immediately. The trailing '(Server)' qualifier is compressed to the point of being cryptic and slightly undercuts the otherwise clean structure.

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

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

For a 7-parameter destructive mutation tool with no output schema, the description covers operations and the version/optimistic-concurrency angle but omits consequences: whether delete is permanent, whether task conversion alters linked entities, and what a successful call returns. The recurring, unexplained '(Server)' tag leaves an unresolved ambiguity an agent cannot act on.

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 compensates by mapping each enum value to a concrete operation (edit/delete/resolve/reopen/to_task/to_comment), which the schema does not do since enum values carry no per-value descriptions. It also explains that version should come from get_pull_request output, adding provenance the schema lacks; text and comment_id remain undocumented in the description but are covered by 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 opens with a specific set of verbs (edit/delete/resolve/reopen/convert) applied to a clear resource (PR comment or task), which is far more precise than the tool name alone. It implicitly distinguishes itself from add_comment by framing all operations as mutations of an existing comment, though it never names that sibling 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?

Usage is implied through the action enumeration, and the note that to_task/to_comment are Server-only is a genuine usage restriction. However, there is no explicit guidance on when to reach for this tool versus add_comment or set_review_status, and no preconditions (permissions, comment ownership) are 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?

Annotations already declare destructiveHint=true and idempotentHint=false, so the safety profile is covered structurally. The description adds nothing beyond that — it doesn't mention irreversibility, merge-conflict failure modes, permission requirements, or that the PR will be closed. The one extra sentence merely restates the `version` schema note.

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 action front-loaded, which is good. However the second sentence is redundant with the schema's `version` description, so it doesn't earn its place; the space would be better spent on consequences of merging.

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 7-parameter mutation with no output schema, the description leaves out what an agent needs: what a successful merge returns, how conflicts surface, and whether the source branch is affected. Annotations cover safety but not outcome behavior.

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 86%, so the schema itself documents nearly all parameters including the conditional-write semantics of `version`. The description only echoes the `version` hint, so baseline 3 applies — it neither compensates nor detracts.

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

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

States a specific verb and resource ('Merge a pull request'), which is unambiguous against siblings like decline_pull_request or update_pull_request. It doesn't explicitly contrast with those siblings, but the name and verb make selection straightforward.

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 merge versus decline, when a merge is appropriate (e.g., approved review state), or prerequisites. The only usage-adjacent sentence is about passing `version` to save a fetch, which is a parameter tip rather than tool-selection 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?

Annotations already declare readOnlyHint=false and idempotentHint=true, so the safety profile is covered; the description adds real value by clarifying that UNAPPROVED clears a prior review and that the states are mutually exclusive rather than additive. It stops short of disclosing permission requirements or what happens to an existing review comment when the status is changed.

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, both front-loaded: the action and states come first, the operational caveat second. Nothing is redundant and there is no filler.

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

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

For a 5-parameter mutation with no output schema, the description covers what the tool does and the state model well. It omits the return behavior (e.g., whether the resulting review object is returned) and permission/self-approval constraints, which an agent would still want before invoking.

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 earns an upgrade by glossing the enum: NEEDS_WORK means 'request changes' and UNAPPROVED means 'clear', which the bare enum values do not convey. It says nothing about the optional 'comment' parameter or how it interacts with the status.

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?

Uses a specific verb ('Set') with a precisely scoped resource ('YOUR reviewer status on a PR') and enumerates the three legal states. No sibling tool (update_pull_request, merge_pull_request, decline_pull_request, add_comment) does review-status setting, and the 'YOUR' qualifier makes the personal-reviewer scope unmistakable.

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

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

'One call; the three states are mutually exclusive' is a useful usage rule that tells the agent not to chain calls. However, there is no guidance on when to reach for this versus add_comment or update_pull_request, and no stated preconditions such as being a reviewer or not being the PR author.

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

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

Annotations cover the safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false), and the description adds the operationally important partial-update semantics: reviewers and approvals survive unless `reviewers` is supplied. It still omits what happens to other omitted fields (title/description) and any permission or failure conditions beyond the version note.

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 the core action, then the two behavioral caveats. Slight redundancy with the parameter descriptions (reviewer preservation and version fetching are already in the schema), but nothing is padded or buried.

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 output schema, the definition covers the versioning and reviewer clobbering risks but leaves gaps: no statement of permission requirements, no mention of what the response contains, and no note that omitted fields are untouched. Adequate, but not complete enough to call without any further inference.

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

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

At 67% schema coverage, the schema already documents the two most subtle parameters (`version` concurrency semantics, `reviewers` replacement). The description restates rather than extends these, and says nothing about `title`, `description`, `destination_branch`, or the Server/DC-only `attachments` caveat that sits only in 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?

Names a specific verb+resource (update a pull request) that is clearly distinguishable from read siblings like get_pull_request and list_pull_requests. However, it does not distinguish itself from mutating siblings such as merge_pull_request, decline_pull_request, or set_review_status, so the boundary is only partly drawn.

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 two concrete usage hints: pass `version` (from get/list) to avoid a fetch, and reviewers are preserved unless `reviewers` is passed. That is useful conditional guidance but only about parameters — there is no statement of when to choose this tool over merge/decline/set_review_status, and no prerequisites such as permissions.

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