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

No annotations are provided, so the description carries the burden. It discloses the mutation nature ('Requires write tools'), the confirm=true requirement, and the 10 MiB size limit. However, it does not mention what happens on success, whether the attachment replaces existing attachments, or any side effects beyond attaching the file.

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 no filler. The core action, size limit, and critical preconditions are all front-loaded. 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?

For a mutation tool with no annotations and no output schema, the description covers the essential preconditions (write tools, confirm=true) and a key constraint (10 MiB). However, it does not describe the return value, error conditions, or how the attachment is identified afterward. Given the tool's complexity (7 params, 4 required), a bit more context would help, but the description is not severely 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 43%, so the schema documents some parameters (workItemId, confirm, project) but not others (fileName, contentBase64, comment, expectedRevision). The description adds the 10 MiB size limit and the confirm=true requirement, but does not explain the meaning of contentBase64, comment, or expectedRevision beyond what the schema provides. It partially compensates for the coverage gap but not fully.

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 ('Upload'), a resource ('base64 file'), a target ('work item'), and a size limit ('up to 10 MiB'). It clearly distinguishes this from sibling tools like add_work_item_comment or create_pull_request_comment by naming the exact operation and target.

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

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

The description explicitly states the requirement 'Requires write tools and confirm=true', which tells the agent when this tool is appropriate and what precondition must be met. It does not explicitly name alternatives or exclusions, but the context is clear enough for a mutation tool among many read-only siblings.

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

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

With no annotations, the description carries the behavioral disclosure burden. It usefully discloses that write tools and confirm=true are required, signaling a guarded mutation. However, it does not describe side effects, return value, or behavior when the work item does not exist, so it only partially covers behavioral transparency.

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

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

Two short sentences with no filler. The action is front-loaded, and the prerequisite is stated immediately after. 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?

For a simple create operation, the description plus a fully documented schema is nearly complete: it covers required params, confirmation, and permission prerequisite. It does not state the return type or error cases, but those are not necessary for selecting and calling the tool correctly.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters. The description's only parameter-related addition—Markdown or HTML—mirrors the format enum. It adds no meaningful semantics 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 uses a specific verb and resource: 'Add ... comment to an Azure Boards work item,' and specifies supported formats (Markdown or HTML). This clearly distinguishes it from sibling tools like update_work_item_comment, delete_work_item_comment, and create_pull_request_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 action phrase and target resource give clear context for when to use it: when a new comment should be posted to a work item. It also states the confirmation prerequisite ('confirm=true') and write-tool requirement. It does not explicitly enumerate alternatives such as update/delete, but the context is unambiguous enough.

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

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

With no annotations provided, the description carries the full burden. It discloses that the tool is a write operation requiring confirmation, but it does not mention side effects, reversibility, or behavior on existing relations. The confirm requirement is already in the schema, so the only added context is 'write tools,' which is vague. This is minimal but not misleading.

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

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

The description is a single sentence with two clauses, front-loading the primary purpose and then stating the key prerequisite. There is no fluff, and it is appropriately concise for the information it conveys.

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 7 parameters and no output schema, the description is sparse. It does not explain the meaning of expectedRevision (likely optimistic concurrency), comment, or the specific behavior of each relation type. It also does not describe the response or error conditions. An agent would need to infer too much to call it correctly, making this 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 57%, leaving comment, expectedRevision, and relation without descriptions (though relation has an enum). The description clarifies the relation parameter by listing values, but that is redundant with the enum. It does not explain the purpose of comment, expectedRevision, or project beyond schema defaults. The description adds little semantic value beyond the schema.

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

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

The description states a specific action: 'Link two work items' and enumerates the relation types (parent, child, related, dependency, duplicate). This clearly differentiates it from other work-item tools like update_work_item or create_work_item, which handle different operations. The purpose is unambiguous.

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

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

The description provides a prerequisite ('Requires write tools and confirm=true') but does not mention when to use this tool versus alternatives, nor does it contrast with sibling tools. It implies usage for linking work items but offers no exclusions or alternative routing, which is a gap given the large sibling set.

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 adds an important safety guarantee ('without exposing credentials') and implies a read-only check, but it does not disclose what happens on success or failure, whether the call is non-mutating, or what the returned status looks like.

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

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

The description is a single, front-loaded sentence with no filler. It states the core action first, adds the optional scope, and closes with a relevant safety qualifier. Every word contributes.

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 such a simple, one-parameter tool this is mostly adequate, but the lack of an output schema and annotations means there is no explanation of the return value or typical failure modes. An agent can invoke it safely given the schema, but would be guessing at how to interpret the result.

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

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

Schema description coverage is 100% for the only parameter, so the schema fully documents 'project' including the default-project fallback. The tool description's phrase 'optional project access' weakly reinforces the parameter's meaning but adds no new semantic detail.

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

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

The description uses a specific verb 'Verify' and clearly names the resource being checked: authentication plus optional project access. This distinguishes it sharply from the sibling tools, none of which are authentication checks.

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 'Verify' – an agent can infer this should be used to validate Azure DevOps credentials before other API calls. However, it does not explicitly state when to use it versus alternatives or mention any prerequisites.

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 states the output categories (ahead/behind counts, common commit, changed items) but does not disclose whether the operation is read-only, whether it requires specific permissions, how pagination works, or what the response format looks like. The description adds some value but leaves significant behavioral gaps.

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

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

The description is a single sentence that is concise and front-loads the main action and output. It earns its place with no filler, though it could be slightly more structured by separating the output list. Overall, it is appropriately sized.

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 5 parameters, 0% schema coverage, no annotations, and no output schema, the description is too thin. It does not explain parameter semantics, return value structure, or edge cases (e.g., branches with no common ancestor). An agent would need to guess or call the tool to learn its 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 description coverage is 0%, so the description must compensate for undocumented parameters. It does not explain the meaning of 'baseBranch' vs 'targetBranch' (which is the reference and which is the comparison), nor does it explain 'top', 'project', or 'repositoryId'. The description only mentions 'two branches' generically, leaving the agent to guess parameter roles.

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 ('Compare') and resource ('two branches') and lists the return values (ahead/behind counts, common commit, changed items). It is clear what the tool does, though it does not explicitly distinguish itself from sibling tools like get_pull_request_diff or list_commits, which also deal with branch/commit comparisons.

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

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

No guidance is provided on when to use this tool versus alternatives. The description does not mention that this is for branch-to-branch comparison, nor does it exclude cases where a pull request diff or commit list would be more appropriate. An agent must infer usage from the name and description 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 behavioral burden. It discloses that this is a mutating merge, requires confirmation, works only on active non-draft PRs, and respects policies. It does not spell out failure modes or irreversibility, but provides strong behavioral constraints 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?

A single, front-loaded sentence that captures the essential eligibility, policy, prerequisite, and confirmation requirements with no filler. Every phrase 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 complex mutation with no annotations and no output schema, it covers the critical prerequisites: active non-draft status, reviewed commit, write tool access, confirm=true, and policy non-bypass. It does not describe return values or all possible side effects, but the schema covers branch deletion and work item transitions as parameters.

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 78%, so the schema already documents most parameters. The description adds meaning by tying expectedSourceCommitId to the reviewed source commit and emphasizing confirm=true, but it does not explain mergeStrategy or mergeCommitMessage 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?

Description clearly states it merges an active, non-draft pull request, which is a specific verb-resource pairing. It distinguishes itself from siblings like update_pull_request and set_pull_request_auto_complete by making the merge action explicit and immediate.

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 context: use for active, non-draft PRs, with a reviewed source commit and confirm=true, and notes it will not bypass policies. It does not explicitly name alternatives or state when not to use it, so it lacks full exclusion 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 provided, the description carries the full burden. It discloses the 'failing safely if the branch already exists' behavior, which is valuable, and the 'exact source commit' constraint. However, it does not disclose whether the operation is destructive, whether it requires special permissions, or what happens on other failure conditions. The description adds some behavioral context but leaves significant gaps.

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

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

The description is a single sentence that is concise and front-loads the core action and key constraints. Every word earns its place, and it avoids unnecessary detail.

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

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

For a mutation tool with no annotations, no output schema, and only 20% schema description coverage, the description is too thin. It does not explain the confirm parameter, the meaning of sourceObjectId, or the failure behavior beyond branch-exists. An agent would need to inspect the schema carefully and may still be uncertain about the exact semantics of the required parameters.

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

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

Schema description coverage is only 20%, and the description does not explain the parameters beyond the general notion of creating a branch. The 'confirm' parameter is critical for a mutation but is not mentioned in the description. The description does not compensate for the low schema coverage, leaving the agent to infer the meaning of sourceObjectId, repositoryId, and confirm from the schema alone.

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 ('Create') and resource ('branch'), and adds the key constraint 'at an exact source commit' and the safety behavior 'failing safely if the branch already exists.' It is clear and distinguishable from sibling tools like delete_branch, list_branches, and compare_branches, though it does not explicitly name those alternatives.

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

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

The description implies when to use the tool: when creating a branch at a specific commit, and it implies a safe failure mode if the branch exists. However, it does not explicitly state when not to use it or mention alternatives such as creating a branch from a default branch or using a different API. The context is adequate but not fully 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 of behavioral disclosure. It does state that the tool requires write tools and confirm=true, indicating it is a mutation requiring explicit confirmation. However, it does not describe side effects, idempotency, or success behavior, leaving behavioral transparency limited.

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

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

The description is a single sentence with no filler, front-loading the core purpose and the key confirm requirement. It is efficient and well-structured, though extremely terse given the tool's complexity. Still, it earns a high score for conciseness.

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 11 parameters, no output schema, and no annotations, the description is insufficient. It does not explain return values, edge cases, or typical usage scenarios like project defaulting or branch handling. The schema covers some parameter details, but the description lacks the broader context needed for correct invocation.

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

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

Schema coverage is 73%, so most parameters have descriptions. The description adds no new parameter information; it repeats the confirm requirement already present in the schema. Thus it provides no additional value beyond what the schema already documents.

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 'Create a same-repository Azure Repos pull request,' which clearly identifies the verb (create), resource (pull request), and scope (same-repository). It is specific enough to distinguish from update/complete operations, though it does not explicitly name sibling tools. The purpose is unambiguous.

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

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

The description provides no guidance on when to use this tool versus alternatives like update_pull_request or complete_pull_request. It mentions 'Requires write tools and confirm=true,' which is a prerequisite, not a usage guideline. There is no decision criteria for selecting this over siblings.

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 behavioral disclosure burden. It usefully identifies this as a write operation requiring confirmation, which is important for an agent. However, it does not disclose side effects, whether new threads are created, or any result/return behavior, leaving meaningful gaps.

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

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

Two short sentences with no wasted words. The core action and scoping qualifier are front-loaded, and the required permission/confirmation is stated immediately after.

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 and no annotations, the description covers the most critical operational facts: it is a top-level PR comment, requires write tools, and requires confirm=true. The remaining context is already provided by the schema; it could be more complete by mentioning outcome or effects, but nothing essential is missing for invoking it.

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 parameter schema already fully documents repositoryId, pullRequestId, content, project, and confirm. The description adds invocation-level guidance ('confirm=true') but no additional per-parameter meaning, so the baseline of 3 is appropriate.

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

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

The description states a clear action ('Create') and a precise resource ('top-level pull request comment'), which distinguishes it from sibling tools like create_pull_request_inline_comment. The word 'top-level' adds scope beyond the title and prevents confusion with inline-comment tools.

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

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

The description provides an important precondition: 'Requires write tools and confirm=true.' However, it does not explicitly state when to prefer this tool over alternatives such as create_pull_request_inline_comment or reply_to_pull_request_thread. The usage context is implied by 'top-level' but not fully articulated.

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

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

With no annotations, the description carries the full burden of disclosing behavior. It states that it requires write tools and confirm=true, which indicates a mutation and a confirmation gate. However, it doesn't disclose what happens on validation failure, whether the comment is attached to a thread, or what the response contains. The 'current' iteration phrase is ambiguous given an iterationId parameter.

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 no filler. The purpose is front-loaded, followed by the critical requirement (confirm=true). It is efficient and to the point, earning every word.

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 11 parameters, 5 required, no output schema, and no annotations, the description is insufficient. It doesn't clarify line range semantics, the difference between fromLine/toLine and startFromLine/startToLine, or the meaning of 'current' versus iterationId. An agent would be uncertain about how to specify the target line range or which iteration is used.

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

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

Schema description coverage is 45%, so the description should compensate for the undocumented parameters. It does not: it only mentions 'file/line comment' without explaining the line range parameters (toLine, fromLine, startToLine, startFromLine) or iterationId. The schema already describes confirm, content, project, repositoryId, and pullRequestId, but the description adds no extra meaning for the remaining parameters.

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

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

The description states a specific action: validate and create a file/line comment on the current pull request iteration. It clearly distinguishes from sibling tools like create_pull_request_comment (general comment) and validate_inline_comment_target (validation only) by combining validation with creation.

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 does not provide any guidance on when to use this tool versus alternatives. It doesn't mention the separate validate_inline_comment_target for validation-only use, nor how it differs from create_pull_request_comment. No exclusions or prerequisites beyond the confirmation requirement.

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 disclosure burden. It does disclose that this is a mutating operation requiring write tool access and a confirmation flag. However, it doesn't mention side effects like notifications, validateOnly behavior, or project defaulting, and the confirm requirement is already present 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 short, front-loaded sentences with no filler. The action, resource, and key prerequisite are all stated efficiently.

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 12-parameter mutation tool with no annotations and no output schema, this description is too sparse. It omits return behavior, project defaults, notification defaults, and validateOnly semantics. The prerequisites help, but the overall specification is under-informative.

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 42%, so the description should compensate for undocumented parameters. It adds only the phrase 'standard or custom fields' and repeats the confirm requirement. It does not clarify tags, areaPath, assignedTo, iterationPath, description, or suppressNotifications.

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

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

The description states a specific action ('Create'), a concrete resource ('Azure Boards work item'), and a scope ('standard or custom fields'). This clearly distinguishes it from siblings like update_work_item, query_work_items, and add_work_item_comment.

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

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

It clearly communicates when to use the tool: to create a work item, and it adds an important prerequisite ('Requires write tools and confirm=true'). It doesn't explicitly contrast with alternatives like update_work_item, but the creation context is unambiguous.

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

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

No annotations are provided, so the description must carry the full burden of behavioral disclosure. It states the conditional nature but omits the confirm parameter requirement, the outcome when the branch does not match the expected commit, and any permission or side-effect details. As a destructive mutation, more disclosure is expected.

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

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

One concise sentence that front-loads the action and condition. No wasted words, and the structure is efficient for an agent to parse quickly.

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 destructive operation with no annotations and low schema coverage, this description is insufficient. It lacks return behavior, failure semantics, confirmation requirement, and prerequisite details, leaving critical information missing for correct invocation.

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

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

Schema description coverage is only 20% (only confirm has a description). The tool description does not explain repositoryId, branchName, or expectedObjectId beyond the phrase 'expected commit'. It fails to compensate for the low schema coverage, leaving parameter meanings ambiguous.

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

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

The description clearly states the verb (delete), resource (branch), and a distinguishing condition (only if it still points at the exact expected commit). This differentiates it from create_branch and other branch-related operations.

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

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

The description implies when to use (when safe, conditional deletion is needed) and provides a clear context for the operation. However, it does not explicitly mention alternatives or when not to use it, but the condition gives enough guidance for an agent to select it appropriately.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It discloses that the delete is a 'soft-delete' (implying reversibility or non-permanent nature), notes permission rules, and requires confirmation and write tools. This conveys the mutation nature and safety requirements. It does not detail the exact outcome or return value, but the provided behavioral traits are valuable and go beyond a simple 'deletes a comment'.

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 three sentences with no waste. The primary action is front-loaded, followed by necessary constraints. Every sentence contributes information: the action, the permission context, and the confirmation requirement. It is concise and well-structured.

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

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

Given the tool has six parameters, no output schema, and no annotations, the description covers the core purpose and key constraints but omits some context. It does not mention what happens after the soft-delete (e.g., whether the comment is hidden or recoverable), nor does it describe the response format. However, the essential information for an agent to decide to call the tool is present. The description is adequate but not exhaustive.

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 83%, so most parameters are already documented. The description reinforces the 'confirm' parameter by stating confirm=true is required, adding context to its purpose. However, it does not add meaning to other parameters like threadId or commentId beyond what the schema provides. The description's mention of 'top-level or reply' implies the commentId is a specific comment within a thread, but this is already implied by the schema. The added value is minimal, consistent with the high schema coverage.

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

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

The description clearly states the action: 'Soft-delete a top-level or reply comment inside a pull request thread.' It identifies the resource (comment) and scope (top-level or reply, within a PR thread), which distinguishes it from other comment tools like delete_work_item_comment or update_pull_request_comment. The purpose is specific and unambiguous.

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

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

The description provides context about Azure DevOps author and permission rules and requires confirm=true, which are usage constraints. However, it does not explicitly name alternative tools or state when not to use this tool. It implicitly tells the agent when to use it (to delete a PR comment) but lacks exclusions or comparisons with siblings. This is clear context but not fully explicit 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 full burden. It discloses the soft-delete behavior and the confirm flag, and notes permission rules. However, it doesn't elaborate on what 'soft-delete' means in terms of visibility, recoverability, or side effects, nor does it mention rate limits or authentication specifics. It adds some value but leaves behavioral details unstated.

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, no wasted words. The primary purpose is front-loaded, and the conditional requirement is stated succinctly. It's an efficient definition that communicates everything essential without padding.

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 delete operation, the description covers the key aspects: soft-delete, permission rules, and the confirm flag. It doesn't describe return values or error handling, but for a mutation without an output schema, that's acceptable. The inclusion of permission rules and confirm adds context that helps an agent decide when and how to invoke it.

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 parameters are already well documented. The description doesn't add extra meaning beyond what the schema provides, aside from reiterating the confirm requirement. It meets the baseline for high schema coverage but doesn't elevate it.

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

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

The description clearly states the action (soft-delete) and the resource (Azure Boards work item comment). It distinguishes from sibling tools like delete_pull_request_comment by specifying 'work item comment', and 'soft-delete' adds precision beyond a generic 'delete'.

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 provides relevant usage context by mentioning Azure DevOps author and permission rules and requiring confirm=true. It doesn't explicitly name alternatives or exclusions, but the resource specificity makes usage clear. The confirm requirement is a practical guideline for when this tool should be invoked.

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

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

With no annotations, the description carries the safety/behavior burden. 'Summarize' and the tool name indicate a read-only aggregation, and the 50-PR cap is stated too. However, it does not disclose output shape, grouping, or whether unresolved threads include comments, leaving some behavior unexplained.

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

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

One sentence, front-loaded, with no filler. Every phrase contributes: summarizes, votes/unresolved threads, batch limit.

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 four-parameter tool with no output schema and zero schema parameter descriptions, this definition is too thin. It omits how parameters select PRs, what 'summary' contains structurally, and when to prefer it over single-PR alternatives, leaving an agent to guess invocation 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 0%, so the description must compensate, but it never maps top, status, project, or repositoryId to how the batch is formed. Parameter names and the status enum provide limited self-evident meaning, but the important relationship between project/repositoryId/top and the summary is undocumented.

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

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

The description uses a specific verb ('Summarize') and names the exact outputs (votes and unresolved threads), with a clear scope ('across up to 50 pull requests'). This distinguishes it as a batch aggregation tool from single-PR siblings like get_pull_request_reviewers or get_pull_request_threads.

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

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

The phrase 'across up to 50 pull requests' implies a batch use case combined with filter parameters, but the description does not explicitly say when to choose this over single-PR review tools or what selection criteria apply. Usage context is present but only by implication.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It only mentions that URLs are returned, but does not address potential authentication requirements, error scenarios (e.g., repo not found), or whether the 'project' parameter is ever required. This is minimal for a read 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?

A single, precise sentence that front-loads the action and output. There is zero redundancy or filler.

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

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

For a simple getter, the description covers the primary purpose and return content. However, it omits clarification on the optional project parameter's role and does not mention any edge cases (e.g., ambiguous repositoryId). Given the lack of output schema, the description is mostly adequate but leaves minor 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?

The description makes no mention of parameters. Schema coverage is 50% (repositoryId is documented as 'Repository name or ID', but project has no description). The description does not compensate for the undocumented project parameter, leaving the agent without clarity on its purpose or when it is needed.

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

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

The description states a clear action ('Return') and specific resource ('Azure Repos repository') and enumerates the exact output types (HTTPS, SSH, web URLs). It naturally differentiates from siblings like get_repository (which would return metadata) and list_repositories (which lists repos).

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

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

No guidance is given on when to prefer this tool over get_repository or list_repositories. The description only states what it does, not the conditions that make it the right choice, nor does it mention any alternative tools.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It mentions configurable point field and completed states, but does not disclose whether the operation is read-only, what the output format is, what happens if no items match, or any error conditions. This is insufficient for a tool with five parameters and no output 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?

The description is a single, front-loaded sentence with no extraneous words. It states the core action and the key configurable aspects efficiently.

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

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

For a tool with five parameters and no output schema, the description is incomplete. It does not explain the return structure (e.g., what fields are returned), the meaning of 'delivered item' versus 'story-point totals', or default behavior when pointsField or completedStates are omitted. No examples or edge-case handling are provided.

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

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

The description adds meaning to pointsField and completedStates by referring to 'configurable point field and completed states', clarifying their purpose. However, iterationId, project, and team are not addressed in the description beyond what the schema provides (team has a description, the others do not). Given the low schema coverage (20%), the description partially compensates but leaves gaps.

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

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

The description clearly states the tool calculates delivered item and story-point totals for a sprint, with configurable fields and states. This distinguishes it from sibling tools like get_iteration_work_items, which likely return individual items, and get_team_capacity, which focuses on capacity. The verb 'calculate' and resource 'iteration velocity' are specific and unambiguous.

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

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

The description implies usage for computing velocity but does not explicitly state when to use this tool versus alternatives such as get_iteration_work_items or get_team_capacity. No when-not conditions are provided, so the agent must infer from the action itself.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It only states what is returned (work items assigned to an iteration) but doesn't disclose whether it's read-only, what filtering or pagination behavior exists, or what the response structure looks like. For a read operation this is a moderate 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?

The description is a single concise sentence that front-loads the core action and resource. It earns its place with no wasted words, though it could add a bit more context without becoming verbose.

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

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

Given the tool has no annotations, no output schema, and only 33% schema description coverage, the description is too thin. It doesn't explain the return format, the meaning of the 'project' parameter, or any behavioral details like whether it returns only assigned work items or includes child items. An agent would need to infer too much to call this correctly in all cases.

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

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

Schema description coverage is only 33% (only 'team' has a description). The description adds context that the tool returns work items for an iteration, which clarifies the purpose of iterationId, but it doesn't explain the 'project' parameter or how 'team' interacts with the default context beyond what the schema already says. The description partially compensates but doesn't fully cover the undocumented parameters.

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

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

The description states a specific verb ('Get') and resource ('work items assigned to a team iteration/sprint'), which clearly identifies the tool's function. It doesn't explicitly differentiate from siblings like get_work_item or query_work_items, but the iteration/sprint scoping provides enough distinction.

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

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

The description implies usage context (retrieving work items for an iteration) but provides no explicit guidance on when to use this tool versus alternatives like query_work_items or get_work_item. No exclusions or alternative routing are mentioned.

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. 'Get' implies a read-only operation, but the description does not disclose any behavioral traits such as authentication requirements, error scenarios, rate limits, or what exactly constitutes 'state/result'. It adds minimal context beyond the obvious read nature.

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

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

The description is a single, efficient sentence with no redundant words. It front-loads the core action and resource, making it easy to parse quickly.

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 get-by-ID tool, the description is terse but incomplete. It does not explain the parameters (0% schema coverage), does not describe the output format (no output schema), and provides no usage context beyond the minimal statement. An agent would need to infer parameter semantics and expected return structure from the tool name and typical Azure conventions.

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 0%, and the description provides no explanation of the parameters (pipelineId, runId, project). The parameter names are somewhat self-explanatory, but the description does not clarify required vs optional, relationships, or value formats. It fails to compensate for the lack of schema descriptions, leaving the agent to guess.

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

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

Description states a specific verb ('Get') and a specific resource ('one Azure Pipeline run') plus what is returned ('its current state/result'). This clearly distinguishes it from list_pipeline_runs (multiple runs) and get_pipeline_run_logs (logs), even though siblings are not named 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 explicit when-to-use or when-not-to-use guidance is provided. The singular 'one' implies retrieval of a specific run rather than a list, but there is no mention of alternatives or conditions (e.g., when to use get_pipeline_run_logs instead). The agent must infer usage from the tool name and sibling list.

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 mentions 'bounded plain-text log' which hints at a size limit, but it doesn't disclose pagination behavior, ordering, whether logs are truncated, authentication requirements, or what happens when no logs exist. For a read tool with zero annotation coverage, this is a notable 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?

The description is a single efficient sentence that front-loads the primary action and then adds the bounded-text variant. Every word earns its place, though it could be slightly more explicit about parameter roles.

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, no annotations, and 0% schema description coverage, the description is too thin. An agent doesn't know the return format, how the two modes differ in output, whether maxChars applies to both modes, or what error conditions exist. For a 4-parameter tool with no structured safety or output metadata, this is 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 0%, so the description must compensate for the four parameters. It only clarifies that logId selects a single log and maxChars bounds the plain-text output; runId and project are left entirely to the schema's bare type definitions. The description adds some meaning but doesn't fully 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 specific verb ('List'/'fetch') and resource ('log records for a pipeline run'/'bounded plain-text log'), which clearly distinguishes the two modes of operation. It doesn't explicitly name a sibling alternative, but the resource is specific enough that an agent can tell it apart from list_pipeline_runs and get_pipeline_run.

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

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

The description implies usage context: use this when you need logs for a specific pipeline run, and the two modes (list vs fetch bounded text) give some selection guidance. However, it doesn't state when to prefer this over get_pipeline_run or list_pipeline_runs, nor does it mention any exclusions or prerequisites.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It does reveal the return payload ('with commits and linked work item references'), which is genuinely useful, and 'Get' implies a read-only operation. However, it omits any mention of authentication requirements, error conditions, or the return shape beyond those two inclusions, leaving notable gaps for a tool with zero annotation coverage.

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

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

The description is a single efficient sentence that front-loads the verb and resource before the payload details. There is no wasted wording. It earns a 4 rather than a 5 only because, given the absence of annotations and output schema, a few more clauses about usage or behavior could have been added without harming conciseness.

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 carries the burden of explaining what the agent receives and needs. It partially does so by stating the payload, but it does not disclose return format, possible errors, or the relationship to get_pull_request_by_url. For a relatively simple single-PR fetch the definition is adequate, but for a tool with this sibling set it is not 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 description coverage is 100%, so the input schema already documents all three parameters (project, repositoryId, pullRequestId) with their meaning. The description adds no additional parameter-level detail, which keeps this at the baseline of 3. The description's mention of 'commits' and 'work items' maps to expected output, not to input parameter 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 description uses a specific verb and resource: 'Get one Azure Repos pull request' with a scoping qualifier ('one') that distinguishes it from list-type siblings. Mentioning the payload ('with commits and linked work item references') also separates it from dedicated tools like get_pull_request_commits and get_pull_request_work_items, though it never names these siblings explicitly, which prevents 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?

No guidance is given on when to choose this tool over alternatives. In particular, it does not distinguish itself from get_pull_request_by_url (a close cousin that fetches a PR via URL), nor does it note that list_pull_requests should be used to discover pullRequestId values first. The usage context is only implied by the verb and resource, so an agent must infer the selection criteria on its own.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions 'Parse' which implies URL parsing and retrieval, but does not disclose whether authentication is required, what happens on invalid URLs, rate limits, or error handling. It also doesn't mention if the operation has side effects (it is a read operation, but not stated as read-only). The description provides minimal behavioral context, leaving the agent uncertain about edge cases.

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

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

The description is a single sentence with no unnecessary words, but it is very brief. It is front-loaded with the key action 'Parse' and the resource, but lacks detail that would be helpful. It is concise but under-specifies, so it's not a 5 but it's efficiently short.

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

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

Given the tool has one parameter and no output schema, the description could do more to explain what is returned (e.g., the PR object properties), how the URL is parsed (expected format), and any failure scenarios. The sibling tools suggest a rich PR context, so the description is incomplete for an agent to fully predict the outcome. It is minimally complete for simple use but lacks depth.

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

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

The input schema documents the 'url' parameter with a description 'Azure DevOps pull request web URL' and format 'uri'. The description adds the context that the URL is parsed half-way, but the schema already covers the meaning of the parameter well. Since schema coverage is 100%, the baseline is 3, and the description adds 'parse' behavior which is a slight bonus, bringing it to a 4.

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

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

The description clearly states the verb 'Parse' and resource 'pull request URL', with the purpose of retrieving a pull request. It is distinguishable from sibling tools like 'get_pull_request' which likely takes an ID rather than a URL, though it does not explicitly differentiate. The description is specific about the input type (URL) and the operation (retrieve), making the purpose clear enough.

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

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

The description implies that this tool is used when you have a pull request URL to retrieve the pull request, but it does not explicitly state when to use this compared to 'get_pull_request' or other related tools. There is no direct mention of alternatives or exclusions, so an agent would need to infer the use case based on the URL versus ID distinction, which is not 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 provided, the description must disclose behavioral traits on its own. It mentions 'locally computed line statistics,' which hints at the output nature, but it does not disclose that this is a read-only operation, any permission requirements, or the effect of optional parameters like maxFiles or iterationId. The description lacks sufficient behavioral detail for a tool with no annotation support.

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

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

The description is a single, direct sentence that conveys the core action and scope without any unnecessary words. It is appropriately front-loaded with the verb and resource, making it easy to scan and understand.

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

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

For a tool with five parameters and no output schema, the description is too minimal. It does not explain the structure of the return value (e.g., file paths, line additions/deletions), the meaning of 'locally computed line statistics,' or the defaults for optional parameters. An agent would need to infer these details from the tool name and schema, leaving room for misinterpretation.

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

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

The schema already provides descriptions for project, repositoryId, and pullRequestId, but not for maxFiles or iterationId. The description adds no parameter-specific meaning, such as clarifying that iterationId defaults to the latest iteration or that maxFiles caps the number of files returned. With schema coverage at 60%, the description does not compensate for the missing parameter documentation.

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

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

The description clearly states a specific action ('Return') and a specific resource ('changed files and locally computed line statistics') for a pull request iteration. It distinguishes from sibling tools like get_pull_request_diff_stats and get_pull_request_diff by emphasizing 'locally computed' and 'iteration', making the tool's scope unambiguous.

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

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

The description implies usage from its purpose but provides no explicit guidance on when to use this tool versus alternatives such as get_pull_request_diff_stats or get_pull_request_file_diff. It does not state conditions, exclusions, or when to prefer one over another, leaving an agent to infer based on the tool name and context.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It fails to mention pagination via continuationToken, the return format of commits, or any side effects. The minimal text does not convey important behavioral traits beyond the basic listing operation.

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

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

The description is a single, front-loaded sentence with no unnecessary words. It clearly conveys the core function efficiently.

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 5 parameters, pagination support, and no output schema, the description is notably incomplete. It does not mention that results are paginated, what fields each commit contains, or how to use the continuationToken. An agent would lack critical information to correctly handle large result sets.

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

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

The description adds no parameter semantics beyond the schema. While schema coverage is 60% (project, repositoryId, pullRequestId have descriptions), the top and continuationToken parameters remain undocumented, and the description does not clarify their purpose or usage.

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

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

The description clearly states the tool lists commits included in a pull request, using a specific verb and resource. It distinguishes from the sibling list_commits by scoping to pull request commits, though it does not explicitly name the alternative.

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

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

No guidance is given on when to use this tool versus alternatives like list_commits or get_pull_request. The description only states the function without any context on selection criteria or typical use cases.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It only states the core action and does not mention important behaviors such as truncation based on maxFiles/maxLines, handling of iterationId, or any limits on the diff size. The description omits potential side effects or output formatting details, leaving agents guessing.

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

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

The description is a single, front-loaded sentence with no wasted words. It is concise and follows a clear verb-object structure. However, given the tool's complexity (8 parameters, no output schema), it is arguably too sparse, but the dimension rewards conciseness and front-loading, which are achieved.

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

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

The description is inadequate for the tool's complexity. With no output schema, no annotations, and multiple undocumented parameters, the agent lacks essential context about return format, limits, or how to use optional parameters. The description does not mention pagination, truncation, or what constitutes a 'unified diff', making it incomplete for correct invocation.

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

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

Schema description coverage is only 38%, and the tool description does not compensate. Parameters like maxFiles, maxLines, startLine, iterationId, and contextLines have no descriptions in the schema or the description, leaving their semantics ambiguous. For example, iterationId and contextLines are not self-explanatory, and the description provides no clarification.

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

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

The description clearly states a specific verb ('Build and return') and a specific resource ('unified diff for an Azure Repos pull request'). It distinguishes itself from sibling tools like get_pull_request_diff_stats and get_pull_request_file_diff, which have different outputs, so an agent can identify its purpose without confusion.

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

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

The description provides no guidance on when to use this tool versus alternatives. There are many related PR diff tools (diff_stats, file_diff, changed_files), but the description does not mention any of them or suggest conditions for choosing this one. An agent would have to infer usage from the 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?

With no annotations, the description carries full responsibility for disclosing behavior; it only states the return content. It does not mention that this is a read-only operation, authentication requirements, defaults for optional parameters, or error/edge-case behavior.

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

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

A single sentence with no filler; output categories are front-loaded and every word contributes. The brevity is appropriate to the simple stated purpose.

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

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

For a 6-parameter tool with no annotations and no output schema, this is incomplete: it omits defaults, optional-parameter behavior, and return shape, and does not route the agent to the right sibling tool.

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

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

Schema covers only 3 of 6 parameters; the description adds no parameter semantics. 'Largest changed files' hints at largestFilesLimit, but maxFiles and iterationId remain unexplained, and the description doesn't clarify relationships between parameters.

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

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

States a specific verb ('Return') and resource ('pull request diff statistics'), and enumerates the output categories (additions, deletions, file counts, largest changed files). However, it does not explicitly distinguish itself from sibling tools like get_pull_request_diff or get_pull_request_changed_files.

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

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

Provides no guidance on when to choose this tool over get_pull_request_diff, get_pull_request_changed_files, or get_pull_request_file_diff. The word 'aggregate' implies a stats use case, but no condition, exclusion, or alternative is named.

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

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

With no annotations provided, the description must disclose behavioral traits itself. It only says 'locally generated unified diff,' which hints at generation but does not explain error behavior, authentication requirements, or how it differs from a server-side diff. It lacks any mention of potential failure modes, rate limits, or the meaning of 'locally generated.' This is a significant gap for a tool with zero annotation coverage.

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

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

The description is a single, front-loaded sentence with no wasted words. It achieves brevity but may be too terse for a tool with many parameters. Still, it is structurally clean and gets to the point immediately, so a 4 is appropriate for conciseness.

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

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

Given the tool's complexity (8 parameters, no output schema, no annotations), the description is far too thin. It does not explain the return format, parameter semantics, or usage context relative to siblings. An agent would struggle to call this correctly without external knowledge, especially regarding optional parameters like iterationId and contextLines. The description is inadequate for the tool's complexity.

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 38%, and the description adds no parameter explanations. It does not elaborate on 'path', 'maxLines', 'startLine', 'iterationId', or 'contextLines', which are all likely to affect the diff output. Since the schema alone is insufficient and the description does not compensate, the parameter semantics are poorly conveyed.

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

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

The description clearly states the action (Return) and the specific resource (locally generated unified diff for one file in a pull request). The phrase 'for one file' differentiates it from the sibling get_pull_request_diff, which likely returns diffs for all files. This is a precise and unambiguous 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?

The description implies usage for a single-file diff but does not explicitly contrast with alternatives like get_pull_request_diff or get_pull_request_changed_files. There is no guidance on when to prefer this tool over siblings, leaving the agent to infer the scope. A clear 'use this when you need a diff for one specific file' statement would improve it.

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 states the operation is a read ('List') but does not disclose pagination behavior, whether includeCommits affects response size, what an 'iteration' contains, or any rate-limit/auth considerations. For a list-type tool with no annotation coverage, this is a notable 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 that states the resource and scope without waste. It earns its place, though it could add a brief note on includeCommits without becoming bloated.

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

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

With no output schema and no annotations, the description is thin for a tool that lists potentially complex iteration objects. It does not explain what an iteration is, how includeCommits changes results, or what the response shape looks like. An agent would need to infer too much before calling this tool 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 description coverage is 75%, so the schema already documents project, repositoryId, and pullRequestId. The description adds no parameter-level meaning beyond the schema. The includeCommits parameter is undocumented in the schema and the description does not compensate, leaving its effect unclear. 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 'List reviewable iterations created by pushes to a pull request' uses a specific verb ('List') and resource ('iterations created by pushes to a pull request'). It clearly distinguishes from sibling tools like get_pull_request_commits or get_pull_request_reviewers, though it doesn't explicitly name a sibling alternative.

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

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

The description implies usage context: it is for listing iterations tied to pushes on a pull request. However, it does not state when to prefer this over related tools like get_pull_request_commits or get_pull_request_review_context, nor does it mention any exclusions or prerequisites.

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. It discloses that the tool is read-only ('without merging') and that it aggregates multiple signals (draft/status, mergeability, votes, threads, policies, status checks). This is useful behavioral context. However, it doesn't disclose whether the tool performs any side effects like caching, whether it requires special permissions beyond read access, or what happens if the PR is not found. The read-only nature is the key behavioral trait and it is disclosed.

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

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

The description is a single sentence that front-loads the action ('Evaluate') and the resource, then lists the evaluated dimensions compactly. It ends with the key non-mutating qualifier. Every word earns its place, though the list of dimensions is a bit dense and could be structured with commas more clearly.

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 aggregation tool with no output schema and no annotations, the description gives a good sense of what the tool checks, but it doesn't explain the return value shape, how the readiness result is expressed (boolean? summary object? reasons?), or how to interpret the evaluation. Given the tool's complexity (multiple signals aggregated), an agent would benefit from knowing what the output looks like to decide if this tool answers its question.

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 0%, so the description must compensate for the three parameters. It does not mention repositoryId, pullRequestId, or project at all. The parameter names are somewhat self-explanatory, but the description adds no meaning about how they relate to the readiness evaluation, such as whether project is optional or how pullRequestId is used. This is a clear gap given the 0% coverage.

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 ('Evaluate') and resource ('pull request merge readiness'), and enumerates the dimensions it covers: draft/status, mergeability, votes, unresolved threads, policies, and PR status checks. It clearly distinguishes itself from mutation tools like complete_pull_request or set_pull_request_vote by explicitly noting it does not merge. However, it doesn't explicitly name a sibling alternative, so it doesn't fully differentiate from other read-only PR tools like get_pull_request or get_pull_request_review_context.

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

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

The description implies when to use this tool: when you need a comprehensive readiness assessment without performing the merge. The phrase 'without merging' provides an implicit exclusion against complete_pull_request. However, it doesn't explicitly state when to prefer this over get_pull_request, get_pull_request_threads, or get_pull_request_reviewers, nor does it mention any prerequisites like repositoryId/pullRequestId being valid or auth requirements.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly describes the output contents, which is useful, but it does not disclose behavior around optional parameters, truncation limits (e.g., maxFiles, diffMaxLines), authentication requirements, or whether any defaults suppress parts of the bundle.

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, well-structured sentence that front-loads the action and result, then lists the contents of the bundle without filler. Every part adds 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?

Given 9 parameters, no output schema, no annotations, and a large sibling set, this one-sentence overview is not complete. It fails to clarify how include flags affect the response, what maxFiles/diffMaxLines limit, or how this tool relates to the individual get_pull_request_* siblings. An agent would need additional reasoning to invoke it correctly with confidence.

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

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

Schema description coverage is only 33%, and the description does not compensate sufficiently. It mentions the output components that map to includeCommits, includeThreads, includeReviewers, and includeWorkItems, but it does not explain how those flags control the bundle or what maxFiles and diffMaxLines do. An agent cannot infer parameter behavior from this 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?

The description names a specific verb ('Return'), a distinct resource ('PR review context'), and enumerates exactly what the bundle contains: metadata, diff summary, unified diff, commits, threads, reviewers, and work items. This clearly differentiates it from the many granular sibling tools like get_pull_request_diff and get_pull_request_threads.

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

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

The phrase 'in one review bundle' implies this is a convenience aggregation tool meant for fetching everything in a single call rather than using separate sibling calls. However, it does not explicitly state when to choose this over the granular alternatives, nor does it mention any exclusions or prerequisites.

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. The description only states the action and result but does not explicitly confirm that this is a read-only operation, nor does it mention any potential errors, side effects, or prerequisites. While 'List' implies a non-destructive read, the lack of explicit behavioral context is a notable 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?

The description is a single, concise sentence with no filler words. It front-loads the action and resource, making it immediately scannable. 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?

The tool has no output schema, so the description must convey return structure. It states the tool 'List[s] pull request reviewers and their current votes,' which implies a list of reviewer objects with vote information, but it does not specify the exact shape or any edge cases (e.g., no reviewers, error handling). For a simple read tool, this is adequate but not comprehensive.

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

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

The input schema provides 100% coverage with descriptions for all three parameters (project, repositoryId, pullRequestId). The tool description adds no additional semantic meaning beyond what the schema already documents, so the baseline score of 3 is appropriate.

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

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

The description clearly states the verb 'List' and the resource 'pull request reviewers' with the additional detail 'their current votes,' which precisely defines the tool's function and distinguishes it from sibling tools like manage_pull_request_reviewer or get_pull_request. It is specific and unambiguous.

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

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

The description implies when to use it (when you need reviewer information), but it does not explicitly mention when not to use it or provide alternatives. There is no guidance on choosing this over related tools such as get_pull_request_review_context or manage_pull_request_reviewer. The usage context is inferable but not explicitly 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 burden of behavioral disclosure. 'List comments' conveys a non-mutating read operation, but it does not mention ordering, pagination, whether system comments are included, or authorization requirements. It is adequate for a simple read, but not rich.

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

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

The description is a single front-loaded sentence with no redundant words. Every part earns its place, and the key information appears 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 is a simple read operation with four parameters already documented in the schema. However, with no output schema and no annotation context, the description does not explain what the returned comments look like, how they are ordered, or how errors are surfaced. It is minimally sufficient but leaves some invocation-relevant details implicit.

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

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

Schema description coverage is 75%, so the schema already documents most parameters. The description does not add meaning beyond the schema; it only restates the concept of a thread. The baseline of 3 applies because the schema already carries the parameter documentation 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 names a specific verb ('List'), a specific resource ('comments'), and a precise scope ('inside one pull request thread'), which clearly distinguishes it from sibling tools like get_pull_request_threads or create_pull_request_comment. The tool name and title reinforce but do not replace the description.

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

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

The phrase 'one pull request thread' implies the context: use this when you already have a threadId and need its comments. However, the description does not explicitly say when to prefer this over sibling tools such as get_pull_request_threads or comment-creation tools, nor does it state that it is read-only or give exclusions.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It only states that the tool lists top-level and inline threads; it does not mention pagination behavior, iteration filtering, response shape, or any side effects. This is minimal and leaves important behavior unknown.

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

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

The description is a single, front-loaded sentence that earns its place. It has no filler, repetition, or irrelevant detail, making it easy for an agent to parse quickly.

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 7 parameters, no output schema, and many related siblings, yet the description only gives the basic listing scope. Missing context includes pagination handling, iteration semantics, and how this differs from thread-comment retrieval. An agent would likely need to inspect the schema or guess to invoke it correctly in non-trivial cases.

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

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

Schema description coverage is only 43%, and the description adds no explanation of the undocumented parameters like top, iteration, baseIteration, or continuationToken. It also does not clarify how the 'top-level and inline' scope maps to those parameters, so it does not compensate for the low coverage.

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

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

The description uses a specific verb ('List') and identifies the resource ('comment threads on a pull request'), plus clarifies the scope ('top-level and inline'). It is clear on its own, though it does not explicitly distinguish itself from the closely named sibling get_pull_request_thread_comments.

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

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

No guidance is provided about when to use this tool versus alternatives such as get_pull_request_thread_comments, create_pull_request_comment, or update_pull_request_thread_status. There are no exclusions, prerequisites, or context signals to steer an agent toward the correct sibling.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It only restates the basic operation without mentioning whether it is read-only, what types of links are included, whether pagination is involved, or any permissions required.

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

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

The description is a single, focused sentence with no filler or redundant wording. It conveys the essential operation efficiently and is immediately scannable.

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 straightforward read operation with all parameters documented in the schema, the description is mostly complete. It names the resource and the linking relationship, though it could additionally note what fields or item types are returned since no output schema exists.

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 fully documents all three parameters. The description adds little semantic context by clarifying that only work items 'directly linked' to the pull request are returned, but it does not describe the parameters beyond what the schema already provides.

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

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

The description clearly states a specific verb ('Get'), a resource type ('work items') and a precise scope modifier ('directly linked to a pull request'). It distinguishes this tool from the many PR-related sibling tools by targeting linked work items rather than comments, commits, threads, or reviews.

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

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

The description gives no guidance on when to use this tool versus alternatives like query_work_items, get_work_item_delivery_trace, or get_work_item. There is no mention of when this should be preferred or when another tool should be used instead.

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

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

With no annotations, the description carries the behavioral disclosure burden. 'Get...metadata' communicates a read-only, non-mutating intent, which is useful. However, it does not address authentication requirements, not-found behavior, or what metadata fields will be returned.

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

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

The description is a single sentence with no filler, and the core verb and resource are front-loaded. 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?

For a tool with no annotations and no output schema, the description is thin: it omits the optional project context, repositoryId resolution behavior, and return-value expectations. It works as a label but not as a complete call guide.

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 50%: repositoryId is documented as 'Repository name or ID,' but project has no schema description, and the tool description adds no parameter-level explanation. An agent is left to infer how project relates to repositoryId and when project is needed.

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 Azure Repos repository metadata.' It clearly identifies this as a read operation for a single repository. It does not explicitly distinguish itself from siblings like list_repositories or get_clone_links, so it stops short of full differentiation.

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

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

No guidance is provided about when to use this tool instead of list_repositories, get_clone_links, or other repository-related siblings. The description is only a purpose statement and does not mention prerequisites or exclusions.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. The description states it reports old branches and PRs but does not clarify whether this is a read-only operation, what the output format looks like, whether it has side effects, or how the 'shared age threshold' is applied. It lacks any disclosure about potential rate limits, required permissions, or the nature of the report. For a tool with no annotations, this is a significant 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?

The description is a single sentence, which is concise and avoids verbosity. However, it is too sparse to be effective. It front-loads the action (Report) but lacks structure or elaboration. While brevity is a positive, the description is under-specified, so it is not appropriately sized for the tool's complexity. It earns a middle score for not wasting words but loses for not providing necessary details.

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

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

Given the tool has 5 parameters, no annotations, and no output schema, the description is severely incomplete. It does not explain the return format, parameter usage, behavioral traits, or any prerequisites. An agent would be unable to correctly call this tool without external knowledge. The description is far from complete for a tool of this complexity.

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 0%, meaning the schema provides no descriptions for any of the 5 parameters. The description must compensate by explaining parameter meanings, but it does not. It mentions a 'shared age threshold' but does not link it to the staleDays parameter, and it does not explain top, project, repositoryId, or protectedBranches. The agent receives no semantic help beyond the parameter names and types, which is insufficient.

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 purpose: reporting old branches and open pull requests using a shared age threshold. It is specific about the resource (old branches and open PRs) and the action (report). It implicitly distinguishes from siblings like list_stale_branches (which only lists stale branches) and list_pull_requests (which lists all PRs), though it does not explicitly name alternatives. The combination of branches and PRs with a shared threshold is unique enough to be 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?

There is no guidance on when to use this tool versus alternatives. It does not mention scenarios, exclusions, or provide context on when this report is preferable to list_stale_branches or list_pull_requests. An agent would have to infer usage from the name and description, which is minimal. No when/when-not guidance is provided.

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

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

No annotations are provided, so the description must carry the full burden of behavioral disclosure. The word 'Get' implies a read operation, but nothing is disclosed about authentication requirements, error handling, or return format. This is a minimal disclosure that adds little beyond the name.

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

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

The description is a single, concise sentence with zero waste. It front-loads the core action and result, making it easy to scan. This is an exemplary level of conciseness.

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

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

The description is incomplete for an agent to call the tool correctly. It does not explain the required iterationId, the optional team and project parameters, or the structure of the returned data (since there is no output schema). An agent would need to infer too much about expected inputs and outputs.

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

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

Schema description coverage is only 33% (only the 'team' parameter has a description). The tool description does not compensate by explaining any of the parameters, such as what iterationId represents or how team/project affect results. The description adds no value beyond the schema's sparse coverage.

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

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

The description clearly states the tool's purpose: retrieving per-team-member sprint capacity, activities, and days off. It is specific about the resource (team capacity), the scope (per member, sprint), and the content, effectively distinguishing it from siblings like get_iteration_velocity.

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

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

The description implies usage for capacity planning but provides no explicit guidance on when to choose this over alternatives such as get_iteration_velocity or get_iteration_work_items. The context is inferred from the wording, not explicitly stated, so it falls short of clear when-to-use 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 provided, the description carries the behavioral disclosure burden. The phrase 'including all fields and relations by default' usefully discloses the default expansion behavior, which is meaningful beyond the schema. However, it does not mention read-only status or response characteristics, but 'Get' makes the read-only intent reasonably clear.

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

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

The description is a single concise sentence that states the tool's core purpose and its default output behavior with no filler. It is appropriately front-loaded and easy to parse.

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

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

For a simple get-by-ID operation, the description is adequate, but with no output schema and no annotations it leaves some contextual omissions, such as return shape and default project behavior. The schema covers parameter details, but the overall description could add more value around invocation context.

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

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

Schema description coverage is 100% and already explains each parameter, so the description adds little extra parameter meaning. The default-expansion note lightly reinforces the expand field's behavior, but no additional semantics beyond the schema are provided.

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

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

The description clearly states a specific action ('Get') and resource ('one Azure Boards work item by ID'), and clarifies scope as a single item fetched by ID. This distinguishes it from list/query tools like query_work_items and get_work_item_delivery_trace without needing to inspect 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 explicit guidance for when to use this tool versus alternatives. It does not mention that query_work_items is for filtering/searching or that get_work_item_delivery_trace exists, so an agent gets no explicit routing guidance beyond the inherent meaning of 'by ID.'

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 bears the full burden of behavioral disclosure. It only states that the tool lists updates and changes, which implies a read-only operation, but it does not mention pagination (top/skip), project scoping, authentication requirements, or the structure of the returned data. An agent cannot anticipate behavior beyond the basic list semantics.

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

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

The description is a single, concise sentence with no wasted words. It is front-loaded with the action and resource, but it lacks any additional structure such as examples or parameter hints. While efficient, it could be slightly improved with a note about pagination or usage context without losing conciseness.

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

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

Given the tool has four parameters, no annotations, and no output schema, the description is far from complete. It omits pagination details, project usage, return format, and any caveats about historical data. An agent cannot safely call this tool without additional external knowledge about Azure DevOps API conventions.

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 0%, so the description must compensate for the undocumented parameters. It does not explain that 'top' and 'skip' control pagination, that 'project' scopes the query, or even that 'workItemId' is the identifier for the work item. The description adds no semantic value to any parameter, leaving the agent to guess from names alone.

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

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

The description uses the specific verb 'List' and names the exact resource and content: 'revision updates and field/relation changes for a work item.' This clearly distinguishes it from siblings like get_work_item (current state) and get_work_item_comments (comments), even without naming alternatives. The purpose 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?

No guidance is provided about when to use this tool versus the many sibling work-item tools. It does not mention that this is for historical audit data, nor does it suggest using get_work_item for current state or query_work_items for search. The usage context is entirely left to the agent to infer.

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

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

With no annotations, the description carries the behavioral burden. It does disclose that results are pageable, which is useful, but it does not mention authentication requirements, read-only semantics, or handling of deleted comments. The lack of any side-effect warning is tempered because 'List' clearly suggests a non-mutating operation.

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

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

The description is a single, front-loaded sentence with no filler. It communicates the core action and resource efficiently, but it is terse enough that important behavioral and parameter context is absent.

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 seven parameters, no annotations, and no output schema, the description is too sparse to fully guide an agent. It omits usage context, pagination mechanics, ordering behavior, and expansion options, leaving the agent to discover or guess important calling details.

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

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

Schema description coverage is only 29%, and the description adds little beyond the schema. It mentions 'pageable' and 'one Azure Boards work item,' which loosely connects to top, continuationToken, and workItemId, but it does not explain meaning of order, expand, includeDeleted, or continuationToken. The enum-based parameters are left entirely unexplained.

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

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

The description has a specific verb ('List'), a clear resource ('comments for one Azure Boards work item'), and the modifier 'pageable' indicating a paginated read operation. This differentiates it from mutation siblings like add_work_item_comment, update_work_item_comment, and delete_work_item_comment, though it does not explicitly call them out.

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

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

There is no guidance on when to use this tool versus alternatives such as get_work_item or query_work_items, nor any explicit exclusions. The 'List' verb implies a read operation, but the description does not explain when this endpoint should be chosen over related work item or comment tools.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It does convey a read-only relationship-traversal behavior and lists the artifact types returned, but it does not mention output shape, pagination, authentication requirements, or behavior when no linked artifacts 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?

The description is a single front-loaded sentence with no filler. Every word adds specificity about what the tool traces and what the result contains.

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 annotation coverage, so the description must explain both inputs and expected results. It does name the return categories, which is helpful, but it omits project parameter semantics, response structure, and edge cases. For a simple read-only trace tool this is nearly adequate but still has clear 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 description coverage is 0%, so the description must compensate for parameter meaning. It only indirectly implies workItemId via 'a work item' and never explains the optional project parameter or why it might be needed. The schema's raw types do not tell the agent the semantic role of either parameter.

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

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

The description uses a specific verb, 'Trace,' and identifies the exact resource and result categories: linked pull requests, commits, builds, branches, and related work items. This clearly distinguishes it from sibling tools like get_work_item or query_work_items, which retrieve a work item's own data rather than its delivery trace.

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

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

The description implies the right use case: when an agent needs the delivery/link graph around a work item rather than the work item's fields or comments. It does not explicitly name alternatives or state when not to use it, but the context is clear enough for selection among the sibling tools.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It only says 'List branches' with no mention of pagination, filtering, permission requirements, or the structure of the response. It provides no behavioral traits beyond the bare action, leaving the agent without critical context.

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

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

The description is a single, front-loaded sentence with no wasted words. It is appropriately concise in structure, though it lacks the substance needed for other dimensions. The brevity is positive, but it sacrifices necessary detail.

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

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

Given the tool has five parameters, no output schema, and no annotations, the description is severely under-specified. It doesn't explain return values, pagination via 'continuationToken', or any edge cases. An agent would not know what to expect from the call or how to handle the parameters correctly.

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

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

Schema description coverage is only 40% (only 'filter' and 'repositoryId' have descriptions in the schema). The tool description itself adds no parameter information at all, so it does not compensate for the low coverage. The agent must rely on the sparse schema, which is insufficient for five parameters.

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

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

The description clearly states the action ('List'), the resource ('branches'), and the context ('in an Azure Repos repository'), which is a specific verb+resource combination. It distinguishes from list_stale_branches implicitly by not mentioning staleness, but it doesn't explicitly differentiate from siblings like list_repositories. Overall, it's clear enough for a simple read operation.

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

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

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention any conditions, prerequisites, or exclusions. With siblings like list_stale_branches, compare_branches, and list_repositories, an agent has no information to decide when to select this tool over others.

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. It states the operation is a read-only listing, but it does not mention pagination via continuationToken, that top has a default/existence, whether a project is always required, or what fields are returned. This leaves important behavioral behavior undisclosed.

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

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

The description is a single sentence that front-loads the action and lists the key filter dimensions. No wasted words; it is easy to scan.

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 eight parameters, no annotations, and no output schema, the description is under-specified. It misses the pagination parameter, default behavior, required context (e.g., does project need to be supplied for all calls), and differentiation from list_pipeline_runs. An agent would likely need additional help to call it 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 coverage is 0%, so the description must explain parameters. It associates five of eight parameters (status, result, repository, definition, branch) but omits top, project, and continuationToken entirely, and does not clarify filter combination semantics. It adds some meaning but leaves gaps.

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

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

The description uses a clear verb ('List and filter') and names the target resource ('Azure Pipeline build records') plus the filter dimensions (status, result, repository, definition, branch). It clearly indicates a read/query operation and its object type; it doesn't explicitly contrast it with list_pipeline_runs but the resource is specified.

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

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

No guidance is given on when to use this tool over the adjacent list_pipeline_runs or list_pipelines. There are no conditions, exclusions, or pointers to alternatives. The description only restates a generic listing purpose, so an agent must infer selection from sibling names.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It only says 'List', implying a read-only operation, but provides no detail about pagination (top/skip), default ordering, filtering behavior, or failure cases for invalid branch/tag/commit references.

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 of 11 words. It front-loads the core action 'List repository commits' and appends the key optional scoping differentiator with 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?

With 9 parameters, low schema coverage, no annotations, and no output schema, this tool needs more description to be safely invoked. The current text does not explain pagination behavior, date/author filtering, or the default project behavior, leaving significant gaps for an agent.

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 22%, so the description must compensate heavily but does not. It adds meaning for versionType/revision via 'branch, tag, or commit', but leaves top, skip, author, fromDate, toDate, and project unexplained, giving the agent little semantic guidance for these parameters.

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

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

The description states a specific verb and resource: 'List repository commits', and immediately adds the distinguishing scope option 'to a branch, tag, or commit', which maps to the versionType parameter. This clearly separates it from sibling tools like list_branches and get_pull_request_commits without needing to inspect their schemas.

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

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

The phrase 'optionally scoped to a branch, tag, or commit' implies when the tool is useful, but there is no explicit guidance on when not to use it or which sibling to choose instead. It does not mention alternatives like get_pull_request_commits for PR-scoped commit history, leaving the routing decision mostly to inference.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It only states the basic action and resource, but omits any mention of pagination (continuationToken), result limits, read-only nature, or potential side effects. The agent gains no insight into how the tool behaves beyond its trivial purpose.

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

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

The description is a single short sentence, which is efficient in length and front-loaded with the core action. However, it is under-specified to the point of being nearly skeletal; while not a tautology, it lacks any additional structure or detail that would aid an agent.

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

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

Given no output schema, no annotations, and a minimal description, the tool is drastically under-documented. The agent is left without essential context such as required parameters, pagination semantics, or expected return format. The description is far from sufficient for a 4-parameter tool with a required field.

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 0%, so the description must explain parameter meaning. However, it does not mention pipelineId, top, continuationToken, or project at all. The description adds zero semantic value beyond the raw schema, leaving parameters completely unexplained.

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

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

The description clearly states the verb 'List' and the resource 'runs for one Azure Pipeline', making the tool's purpose unambiguous. It distinguishes from siblings like get_pipeline_run (singular) and list_pipelines (pipelines, not runs), though it doesn't explicitly name alternatives.

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

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

The description provides no guidance on when to use this tool versus alternatives. It does not mention related tools like get_pipeline_run or run_pipeline, nor any conditions for selection, leaving the agent to infer usage from 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 provided, the description carries full burden. It fails to disclose important behavior such as pagination (via continuationToken), default ordering, whether results are limited to a specific project (though project is optional), or what the response format is. It is a read-only operation by nature, but that is not stated.

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

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

The description is a single, brief sentence that front-loads the main purpose. It has no fluff, though it could have been structured to include more necessary detail without losing conciseness.

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 4 parameters, no output schema, and zero annotations. The description provides no information about parameters, pagination, return values, or error conditions. Given the complexity and lack of structured supplements, this description is seriously inadequate for an agent to call the tool correctly.

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

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

Schema description coverage is 0%, and the description does not describe any of the 4 parameters. The schema itself only has type constraints, so an agent has no idea what 'orderBy' expects, how 'top' affects results, or what 'continuationToken' is for. The description completely fails to compensate for the missing parameter documentation.

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

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

The description clearly states the verb ('List') and resource ('Azure Pipelines definitions in a project'). It is distinguishable from list_pipeline_runs, which lists runs rather than definitions, so the 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?

The description explains what the tool lists but provides no guidance on when to use it versus alternatives like list_pipeline_runs or list_builds. There is no mention of prerequisites (e.g., project context) or typical use cases.

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

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

No annotations are provided, so the description must carry the full burden of behavioral disclosure. It only states that it lists projects, but does not mention pagination via continuationToken, default page sizes, rate limits, authentication requirements, or whether the operation is read-only. The description offers minimal behavioral context beyond the bare function.

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

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

The description is a single, concise sentence that front-loads the core purpose. There is no redundancy or extraneous content. It is appropriately minimal for a straightforward list operation.

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 three optional parameters, including a continuation token for pagination, the description is incomplete. It does not explain how to handle paginated results, what the default behavior is, or how stateFilter interacts with the results. Without an output schema, the agent lacks essential context about response format and iterative fetching. The description should at least hint at these aspects.

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 67% (top and continuationToken have descriptions; stateFilter does not). The description itself adds no parameter-level detail, relying entirely on the schema. Since the schema already documents two of three parameters adequately, the baseline of 3 applies, and the description contributes no additional semantic value.

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

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

The description clearly states the action ('List'), the resource ('projects'), and the scope ('configured Azure DevOps organization'). It is unambiguous and distinguishes itself from sibling tools that target other resources (pipelines, repositories, etc.).

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

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

The description provides no explicit guidance on when to use this tool versus alternatives. While the purpose is clear, there is no mention of typical use cases, prerequisites, or exclusions. The agent must infer usage solely from the tool name and context, which is suboptimal for routing decisions.

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

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

No annotations are provided, so the description bears the full burden of behavioral disclosure. It conveys only that the tool 'lists' labels, which implies a read operation, but it does not describe authentication expectations, error cases, pagination, output shape, or whether any hidden side effects 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?

The description is a single short sentence with no filler or redundant phrases. The verb and object are front-loaded, and 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?

For a three-parameter tool with no annotations and no output schema, this one-liner is too thin. The agent is left to infer label return format, pagination behavior, the role of the optional project parameter, and any authorization requirements.

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 0%, and the description does not explain repositoryId, pullRequestId, or the optional project parameter. It gives pullRequestId a semantic anchor by mentioning 'a pull request,' but it does not clarify required vs. optional parameters or how identifiers are resolved.

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

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

The description uses a specific verb and resource: 'List labels applied to a pull request.' It is clear and distinct from list_pull_requests and manage_pull_request_label by naming the target resource (labels) and read-only action, though it does not explicitly name a sibling or explicitly contrast itself with alternatives.

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 intended use case is implied: use this tool when you need to retrieve the labels on a pull request. However, the description gives no explicit guidance about when not to use it, no mention of alternatives, and no context about the sibling manage_pull_request_label.

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 only states that it lists PRs, with no mention of pagination, default limits, filtering behavior, or side effects. It does not disclose the return format, whether it returns summaries or full details, or what happens with no parameters. This is insufficient for a tool with no annotation support.

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

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

The description is a single sentence that is efficient and front-loaded. It does not waste words and gets to the point immediately. However, it is so brief that it omits essential details, but for conciseness alone it earns a 4 for not being verbose.

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 9 parameters, no output schema, and no annotations, the description is clearly incomplete. It fails to explain return format, default behavior, or how to use the many filter parameters. The agent would have to rely on parameter names and external knowledge, which is inadequate for correct invocation.

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

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

Schema description coverage is only 22%, with only project and repositoryId described in the schema. The description adds no parameter-specific information; it vaguely references 'repository or project' but leaves the other 7 parameters (top, skip, status, creatorId, reviewerId, sourceRefName, targetRefName) entirely undocumented in both schema and description. The agent must guess their meaning from names alone.

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

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

The description clearly states the verb 'List', the resource 'pull requests', and the scope 'in a repository or project'. This distinguishes it from single-PR retrieval tools like get_pull_request, and the resource is unambiguous. The only minor gap is that it doesn't mention filtering capabilities, but the core purpose is fully 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?

The description implies its use for listing multiple pull requests, but does not explicitly state when to use this over alternatives like get_pull_request or other list tools. With many sibling tools, there is no guidance on exclusions or conditions, leaving the agent to infer the intended scope.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It does not mention whether the operation is read-only, any required permissions, pagination behavior, or the return format. For a listing tool, the absence of even a note on result granularity is a 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?

The description is a single, front-loaded sentence with no filler. It states the action and scope efficiently, earning full marks for conciseness.

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

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

The tool is low-complexity (one optional parameter, no output schema, no nested objects), and the description covers the core action. However, it omits any indication of what the response contains (e.g., repository names, full details) or any limits like pagination. This is a minor but present 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?

The schema provides 100% coverage for the single parameter 'project', including its optionality and fallback to environment variable. The description adds no additional meaning or syntax 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?

The description clearly states a specific verb ('List') and resource ('Azure Repos Git repositories in a project'). It distinguishes from get_repository (single repo) and list_projects (projects) by context, though it does not explicitly name alternatives. The purpose is unambiguous.

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

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

The description implies its use for listing repositories within a project but provides no explicit guidance on when to choose it over sibling tools like get_repository or list_projects. It neither mentions alternatives nor exclusions, leaving the agent to infer 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?

Because no annotations are provided, the description carries the behavioral burden. It does disclose useful behavior: branches are selected by commit age and main/master/develop are protected by default. It does not clarify what 'protected' means in terms of inclusion or exclusion from results, nor does it describe truncation or ordering behavior.

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

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

The description is a single efficient sentence that front-loads the main selection rule and the important protected-branch default. There is no filler or redundant repetition of the tool 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 five-parameter tool with no output schema and no annotations, the description is only partially complete. It captures the core intent but leaves parameter details, output shape, and invocation context largely to the agent's 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?

The schema provides five parameters with 0% description coverage, so the description must compensate. It does map 'older than a configured age' to staleDays and alludes to protected branches, but repositoryId, project, and top receive no semantic explanation.

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 begins with a specific verb and resource: 'Find branches whose latest commit is older than a configured age.' It clearly conveys a stale-branch filter and names protected defaults, making it distinct from the generic list_branches sibling. It does not explicitly name an alternative, but the meaning is clear enough for an agent to identify the tool's purpose.

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

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

The description implies the tool should be used when looking for stale branches, and the protected-branch default gives some contextual signal. However, it never states when to choose this tool over siblings like list_branches or get_stale_repository_report, nor does it give any 'when not to use' 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?

No annotations are provided, so the description carries full responsibility. It only says 'List', implying a read operation, but does not explicitly state that it is non-destructive, nor does it describe the return format, pagination, or any side effects. This is a significant gap for a tool without annotation coverage.

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

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

A single, clear sentence with the verb and scope front-loaded. No unnecessary words; efficient and easy to scan.

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

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

Given no output schema and no annotations, the description should provide more context. It does not mention default behavior when timeframe is omitted, what 'all' means, or the structure of the returned list. It is insufficient for an agent to call it correctly in all scenarios.

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

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

Schema description coverage is only 33% (team has a description, but project and timeframe do not). The description adds the concept of 'all' which is not in the enum, but does not explain how to achieve it (likely by omitting timeframe) or clarify the semantics of project and timeframe. The description fails to compensate for the low schema coverage.

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

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

The description clearly states the verb 'List' and the resource 'sprint iterations for a team', and specifies the filter options (current, past, future, all). This distinguishes it from sibling tools like get_iteration_work_items, which lists work items within an iteration.

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

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

The description implies usage by stating what it lists, but does not explicitly mention when to use it versus alternatives, nor does it note that 'all' is achieved by omitting timeframe. No alternative tools are named, though no direct sibling exists.

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 disclosure burden. It only states the mutation action but does not mention side effects, idempotency, the required confirm flag, or failure behavior when a label 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.