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

No annotations are provided, so the description carries the full behavioral burden. It usefully discloses HTML-formatting support for the comment body, but says nothing about permissions, whether the comment triggers notifications, whether it is reversible/editable, or what the call returns. For a mutation tool with zero annotation coverage this is a meaningful 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?

Three short sentences, zero waste, with the core action front-loaded and the two non-obvious constraints (HTML support, required project) following. Nothing redundant.

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 3-param mutation tool with no annotations and no output schema, the description covers the essential action and the HTML/project requirements but omits the return payload and any auth or side-effect context an agent might need before writing a comment.

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

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

Schema description coverage is 100%, so all three params are already documented in the schema. The description only restates HTML formatting (also in the schema) and reiterates that project is required and must be discovered from context. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

States a specific verb and resource: 'Add a comment to an existing Azure DevOps work item.' An agent can distinguish this from create_work_item or update_work_item. It does not, however, explicitly contrast itself with those siblings, so it stops just short of 5.

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

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

Usage is implied by the resource (commenting on an existing item), but there is no explicit when-to-use guidance or exclusion relative to update_work_item, which also mutates a work item. The only routing-level advice is about obtaining the project, which is parameter guidance rather than tool-selection guidance.

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

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

No annotations are provided, so the description carries the full behavioral burden. 'Create' implies a mutation, but it discloses nothing about required permissions, validation of the type field, whether creation is idempotent, or what happens on failure. Only the project-required prerequisite is noted.

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

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

Two short sentences, front-loaded with the core action, with no filler. The second sentence largely duplicates the schema's project description, which is mild redundancy but not bloat.

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

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

For a creation tool with no output schema, the description never states what is returned (e.g., the new work item ID), which agents typically need for follow-up calls like add_comment or parent linking. With no annotations and 11 parameters, more behavioral context was warranted, though full schema coverage limits the damage.

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

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

Schema description coverage is 100%, so every parameter is already documented in the schema, including the type enumerations and tag/areaPath formats. The description only restates the work item types and the project requirement, adding no syntax or constraint detail beyond the schema. Baseline 3 applies.

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

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

States a specific verb and resource ('Create a new Azure DevOps work item') and enumerates the work item types it handles. The create-vs-read-vs-update distinction from siblings like get_work_item and update_work_item is easy to infer, but no sibling is named explicitly, so it stops short of full differentiation.

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

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

The only guidance is 'Project is required - discover it from project context,' which is a prerequisite hint rather than when-to-use guidance. It never says when to choose this over update_work_item, add_comment, or how it relates to search_work_items, and offers no 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 supplied, so the description carries full disclosure burden. 'Get' implies a read-only operation and the project-discovery note addresses a prerequisite, but it says nothing about permissions/scopes, rate limits, or behavior of the expand/fields options. It adds modest value beyond a bare verb.

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

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

Two tight sentences with the core action front-loaded and the prerequisite stated second. Nothing is wasted or buried.

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

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

For a single-item read tool with no output schema, the description tells the agent what is returned at a high level ('detailed information') and which keys identify the item. The enum semantics of expand are left to the schema, which is acceptable, but the description could say more about what 'detail' includes.

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

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

Schema description coverage is 100%, so all four parameters are documented by the schema itself. The description only restates that ID is numeric and project is required/discoverable, adding no syntax or semantic detail beyond the schema — the baseline 3 for high 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?

States a specific verb (Get), resource (Azure DevOps work item), and lookup key (numeric ID), which readily separates it from search_work_items, create_work_item, and update_work_item. It doesn't explicitly name a sibling alternative, keeping it just short of the top band.

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

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

Usage is implied: fetch details for a work item whose ID is already known, in contrast to search_work_items. The line 'Project is required - discover it from project context' offers procedural guidance, but there is no explicit when-to-use/when-not framing or named alternative.

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

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

With no annotations, the description carries the burden but only asserts read-oriented discovery intent. It doesn't disclose return shape (names vs. ids), auth/permission requirements, or pagination behavior — the latter is only implied by the schema's top/skip. Also, 'List all projects' sits awkwardly against a hard 100-item cap, though the schema itself makes that limit explicit.

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

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

Two tight sentences, zero filler, with the core operation front-loaded before the routing guidance. Every clause 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 no-argument read tool with fully documented params and no output schema, the description covers purpose and usage motivation adequately. It could mention auth expectations or the 100-result cap, but nothing essential to invoking it correctly is missing.

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

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

Schema description coverage is 100%: both 'top' and 'skip' are documented with defaults, bounds, and pagination purpose. The description adds no syntax or format detail beyond the schema, so the 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?

States a specific verb ('List') and resource ('all projects in the Azure DevOps organization'), which is unambiguous. The sibling tools all operate on work items, so this project-discovery tool is trivially distinguishable without opening any schema.

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

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

Explicitly says when to use it: 'when the project name is not known or to verify a project exists.' No alternatives are named, but no sibling competes for this job, so the guidance is effectively complete rather than needing 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. It does disclose the return shape ('Returns a list of work items matching the query') and the hard project requirement, which is useful. It says nothing about read-only safety, permissions/scopes needed, or behavior on malformed WIQL, 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?

Three short sentences with the core action front-loaded and no filler. The project prerequisite is placed after the core statement rather than first, but the ordering is still logical and readable.

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

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

For a three-parameter search tool with no output schema, the description covers the action, the return type, and the mandatory prerequisite, so an agent can call it correctly. Missing operational detail (auth scopes, WIQL error behavior) is the only shortfall.

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

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

Schema description coverage is 100%, so all three parameters are already documented with examples and bounds (maxResults min/max/default). The description only restates the project requirement, adding no syntax or format detail 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?

States a specific verb and resource ('Search for Azure DevOps work items') plus the mechanism (WIQL), which clearly separates it from create_work_item or add_comment. It does not explicitly differentiate from get_work_item, but the query-language framing makes the distinction inferable.

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

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

Gives a concrete prerequisite ('Project is required') and names an alternative route to satisfy it ('use azuredevops_list_projects'), which is exactly the kind of routing guidance an agent needs. No when-not-to-use condition is stated, so it falls short of 5.

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

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

No annotations exist, so the description carries the full burden. It usefully discloses that it operates via JSON Patch and can touch any field, including state transitions, but says nothing about permission requirements, whether removals are destructive/irreversible, revision/concurrency expectations, or the response shape. Partial behavioral disclosure only.

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, no filler, and the highest-value constraint (project required, discover from context) is front-loaded after the core purpose. Every clause 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 zero annotations and no output schema, the description is adequate but thin: it omits error/failure behavior, revision or concurrency semantics, and permission needs. The fully-documented input schema covers the mechanics, which keeps this at a viable minimum rather than a gap-free definition.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds nothing about the operations array or path syntax beyond what the schema already documents, and its note about the project parameter duplicates the schema's own text verbatim.

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 ('Update') plus resource ('Azure DevOps work item') and names the mechanism ('JSON Patch operations'), immediately separating it from the create/get/search/list/comment siblings. It also scopes capability ('any field including state transitions'), so an agent knows the blast radius without opening the schema.

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

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

It surfaces one real prerequisite ('Project is required - discover it from project context'), which is the most common selection/call failure mode. However it never states when to reach for this over siblings (e.g., when the item exists vs create_work_item) nor any exclusions, so usage is only implied.

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