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 markdown support and per-action required parameters, but stops short of describing side effects, permissions, return values, or error behavior. It adds some context beyond the schema, but not complete safety/behavioral disclosure.

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 concise and well-structured: a one-line summary, a bullet list of actions, and a note on markdown. No fluff.

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 two-action tool, the description covers the actions and required inputs. However, it lacks details on list behavior (ordering, pagination), response format, and any error or authorization context. Without an output schema, more explanation of return values would improve completeness.

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 all 4 parameters with descriptions. The description repeats which parameters are needed for each action, which is useful but not additive 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?

The description identifies the resource (work item comments) and lists specific actions (add, list), distinguishing it from sibling tools that manage other aspects of Azure DevOps. 'Manage' is slightly generic, but the action list provides clear 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 managing comments but doesn't offer explicit guidance on when to use this versus alternatives or when not to use. It gives action-specific requirements but no exclusions or alternative tool references.

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 does not mention whether credentials are stored persistently, whether the connection is validated, or whether it affects subsequent calls. This is a significant gap for a configuration tool with side effects.

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 efficiently communicates the action and the key inputs, 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?

The tool has 3 parameters and no output schema, and the schema covers parameters well, but behavioral context is missing. The description does not explain the result of configuration, whether it is reversible, or that it should be run before other ado_* tools, leaving the agent with incomplete operational understanding.

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 all three parameters, with pat and organization clearly described and defaultProject noted as optional. The description adds no extra semantic detail beyond what the schema already provides, 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 tool's purpose: configuring an Azure DevOps connection using PAT and organization URL. The verb 'configure' is specific, and the resource 'connection' distinguishes it from the operational sibling tools like doing work item queries or updates.

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 as a setup prerequisite before other ado_* tools, but it does not explicitly say 'use this before any other tool' or provide any when-not-to-use guidance. The context makes it the obvious configuration step, yet the guidance is only implied, 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 carries the full burden of behavioral disclosure. It reveals non-obvious behaviors: automatic assignment to the configured Area Path, sprint assignment via parameter, and hierarchy creation. It does not mention permissions or failure modes, but the disclosed behaviors are significant beyond 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?

The description is two sentences, starting with the core purpose and followed by key behavioral details. Every word earns its place, with no filler or repetition of schema 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?

The tool has a nested structure and no output schema, so completeness depends on the description. It covers hierarchy, area path, and sprint, but misses mentioning Bug in the hierarchy and lacks any note about prerequisites (e.g., ado_configure) or return values. This leaves some gaps for a complex tool.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by explaining the effect of addToCurrentSprint and the Area Path behavior, which goes beyond merely listing parameters. However, the hierarchy description omits the 'Bug' type present in the schema, slightly reducing clarity.

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 starts with a specific verb and resource: 'Create work items in Azure DevOps'. It also mentions a unique capability: 'optional hierarchy (Epic > Feature > User Story > Task)'. This clearly distinguishes it from sibling tools like update_item or delete_item, establishing a precise 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 clearly indicates the tool's function and provides contextual guidance such as 'Items are assigned to the configured Area Path' and 'Use addToCurrentSprint=true to add items to the active sprint'. While it doesn't explicitly mention alternatives or exclusions, the usage context is clear and implies this is for creating new items.

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 disclose behavior. It does state the default move-to-recycle-bin behavior and mentions permanent hard delete. However, it does not mention permissions, response format, or other side effects, leaving some gaps for a destructive 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 one compact sentence that front-loads the verb and resource, then clarifies the default and option. No wasted words.

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

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

For a simple two-parameter tool with no output schema, the description covers the essential behavior: what deleting does by default and how to make it permanent. It could mention return/error behavior, but it is sufficiently complete for an agent to invoke 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 100%, giving a baseline of 3. The description adds value by explaining the default behavior (recycle bin) and how to trigger hard delete with 'permanent=true', which goes beyond the schema's field descriptions.

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

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

The description uses a specific verb ('Delete') and resource ('a work item'), clearly distinguishing it from sibling tools like update/create/query. It also explains the default recycle-bin behavior and the permanent option, adding useful scope.

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

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

The description provides clear context on when to use it: deleting a work item, with guidance on the default soft-delete vs hard-delete via 'permanent=true'. It does not explicitly say when not to use it or name alternatives, but for a delete operation this is not strictly necessary.

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 fully disclose behavioral implications, but it only states the action itself. It does not mention that linking is a mutating operation, whether it is reversible, permission requirements, or any side effects on existing links. This leaves significant uncertainty about the tool's impact.

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, compact sentence that immediately states the action and scope. There is no redundant wording or repetition of schema information, making it highly efficient.

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

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

The tool is relatively simple and the schema documents the parameters well, but the description lacks practical context such as examples, the relationship between linkType and target formats, or any conditions for successful linking. It is adequate for a basic understanding but does not fully equip an agent to use the tool correctly in nuanced 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?

All four parameters are fully described in the schema, so the baseline is 3. The description does not add any extra meaning beyond the schema, such as explaining how linkType constrains the target format or how comment is used in the link context.

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 ('Link') and clearly identifies the resource ('a work item') and the range of valid targets ('another work item, pull request, commit, or branch'). This distinguishes it from sibling tools like create_items or update_item, which perform different 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 the tool's purpose (creating links) but provides no explicit guidance on when to use this tool versus alternatives, nor does it mention any exclusions or prerequisites. The context is clear enough for basic understanding, but there is no directional advice for an AI agent.

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 what actions do, not side effects, permissions, or return values. The word 'Manage' could imply write operations, but only read actions are listed, creating ambiguity. No mention of read-only nature or required configuration is provided.

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 concise and front-loaded with the tool's purpose, then uses a clear bullet list for actions. Every sentence serves a purpose, and there is no redundant 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?

The description covers both actions and their parameter requirements, but it omits return value descriptions (given no output schema) and prerequisites such as prior configuration via ado_configure. It is minimally adequate but leaves notable gaps for a tool with multiple actions.

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 clarifies conditional requirements: planId is required for the get action, while startDate and endDate are optional. This adds meaning beyond the schema, which only marks 'action' as required. Although the schema already includes 'for get' in property descriptions, the explicit requirement/optional distinction is valuable.

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 identifies the tool as managing delivery plans (roadmaps) and enumerates two specific actions (list and get) with concise descriptions. This distinguishes it from sibling tools focused on other Azure DevOps resources like sprints or projects.

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

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

The action list implies when to use the tool, but there is no explicit guidance about when to choose this over sibling tools like ado_sprints or ado_projects. It does not state exclusions or mention alternative tools, leaving the decision solely to the agent's 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions that 'set' requires a project and 'areas' operates in the active project, but it does not disclose side effects of setting the active project (e.g., persistence, global state), error behavior, or authentication requirements. This is minimal disclosure.

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 concise bulleted list with a clear header, no redundant filler. Each action is described in a single line, making it easy to scan and understand the tool's capabilities.

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 and no annotations, yet the description does not describe return values, error conditions, or the meaning of 'active project' beyond the bare minimum. While all actions are listed, the overall context for how this tool integrates with the suite and what to expect from each call 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 100%, and the description only restates that 'project' is required for 'set', which is already in the schema. No additional meaning is added beyond what the schema provides, 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 identifies the tool as managing Azure DevOps projects and enumerates three distinct actions (list, set, areas) with specific verbs. It distinguishes itself from sibling tools focused on work items, comments, sprints, etc., by focusing on project-level and area-path 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 action list provides clear context for when to use each action: listing projects, setting the active project, and listing area paths. It does not explicitly mention exclusions or alternative tools, but the action descriptions are self-explanatory and convey the intended 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 carries the full burden. It only states 'Query existing work items,' which implies a read-only operation, but it does not disclose result format, pagination, default limit behavior beyond the schema, authentication needs, or any side effects. This is minimal disclosure for a tool with no annotation safety net.

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 names the action, object, and scope. It is concise and contains no filler or redundant 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?

The tool is simple, with only optional parameters and no nested objects, but the lack of an output schema means the description should mention what is returned. It does not, leaving the return shape unspecified. The description is adequate but not fully complete for a query tool with no output schema.

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

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

Schema description coverage is 100%, with all three parameters ('type', 'limit', 'state') fully documented in the input schema, including enums, defaults, and constraints. The description adds no parameter-specific meaning, but given the high schema coverage, that is acceptable.

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 'Query' and names the resource 'existing work items' in 'the active Azure DevOps project,' making the tool's purpose unmistakable. It clearly distinguishes from sibling tools like ado_create_items, ado_update_item, and ado_delete_item.

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 retrieving existing work items, but it does not explicitly state when to prefer this tool over alternatives or include any exclusions. No alternative tools or when-not-to-use conditions are mentioned, though the verb 'Query' gives a reasonable implicit signal.

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 burden of behavioral disclosure. It does reveal that delete requires a path and optionally a reclassifyId, hinting at work item reclassification, but it does not explain side effects, permissions, or what happens on deletion without reclassifyId. This is minimal behavioral context, 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 bulleted list with short, scannable lines. The heading 'Manage sprints/iterations' front-loads the purpose. Every sentence is necessary and adds specific info or examples. There is zero wasted wording.

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 covers all four actions and their parameter requirements, which is good for a multi-action tool. However, it lacks return value descriptions (e.g., what list returns), error scenarios, or usage examples. Since there is no output schema and no annotations, these omissions leave gaps for an agent trying to predict tool behavior.

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

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

Schema coverage is 100%, providing baseline of 3. The description adds value by grouping parameters per action and marking required vs optional (e.g., 'requires: id, sprint'), which the schema itself does not (only 'action' is listed as required). This helps the agent understand parameter interplay for each action.

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

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

The description opens with 'Manage sprints/iterations' and then lists specific actions (list, set, create, delete), clearly indicating the tool's scope. It distinguishes from siblings like ado_query_items or ado_update_item by focusing exclusively on sprint/iteration management. A higher score would require more precise phrasing than 'Manage', but the action list makes the purpose 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?

Each action includes its required and optional parameters, giving clear context for when to use which action. For example, 'set: Assign work item to sprint (requires: id, sprint)' tells the agent exactly what is needed for assignment. No explicit alternatives or exclusions are provided, but the action list itself guides selection.

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

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

There are no annotations, so the description must disclose behavioral traits. While 'check' implies a read-only operation, the description does not explicitly state that it makes no changes, does not require special permissions, or describe any side effects. This lack of explicit safety disclosure 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, concise sentence with no redundant wording. It front-loads the verb and resource, making it easy to parse and understand 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?

For a zero-parameter status tool, the description is minimally sufficient, but it lacks details about what the status includes or the format of the return value. Since there is no output schema, the agent is left guessing about the exact output structure, making the description incomplete for full contextual understanding.

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 tool has zero parameters, so there is nothing for the description to clarify. The schema coverage is 100% vacuously, and the description adds no parameter-related information, which is acceptable given the absence of parameters.

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

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

The description uses a specific verb 'check' and identifies the resource as 'current Azure DevOps configuration status'. This clearly distinguishes it from sibling tools like ado_configure or ado_projects, which focus on other actions or resources.

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 prerequisites, exclusions, or which sibling tools might be more appropriate for related tasks, leaving the agent without decision-making support.

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. It distinguishes read actions (list, query) from write actions (add, remove) and specifies required parameters per action, which is helpful. However, it does not disclose side effects, idempotency, return formats, or error behavior, leaving gaps in 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?

The description is concise and front-loaded with the purpose statement, followed by a clean bulleted list of actions. Each line is purposeful and adds necessary information without redundancy.

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

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

This is a multi-action tool without an output schema or annotations, and the description covers the main action-parameter mappings. However, it does not explain return values, error handling, or edge cases for each action, which are important for the agent to fully anticipate tool 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?

The schema has 100% description coverage, so the baseline is 3. The description adds meaningful value by mapping each action to specific required/optional parameters (e.g., 'query: requires tag, optional: limit'), clarifying conditional dependencies that the schema does not express since only 'action' is required overall.

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 'Manage work item tags in Azure DevOps' with a specific verb and resource, then enumerates four distinct actions (list, add, remove, query). This distinguishes it from sibling tools like ado_create_items or ado_query_items, which focus on other aspects of work items.

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 clear context for when to use the tool by breaking down each action and its required parameters (e.g., 'add: requires id, tags'). However, it does not explicitly mention alternatives or when not to use this tool, so it falls short of full 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, and the description does not disclose behavioral traits such as partial update semantics (whether omitted fields are preserved), required prerequisites (existing item ID), or response format. For a mutation tool, 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, clear sentence with no redundant content. It efficiently communicates the core purpose and scope.

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

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

With no output schema and no annotations, the description does not explain return values, failure modes, or behavior when only some fields are provided. Given the tool's complexity (8 parameters), the description is too sparse to fully prepare 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?

The schema covers 100% of parameters with descriptions, so the baseline is 3. The description merely lists the same field names without adding extra meaning or clarifying relationships, providing no added value over the schema.

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

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

The description clearly states the tool updates a work item's fields, listing specific fields (title, state, assignee, etc.). This distinguishes it from siblings like ado_create_items, ado_delete_item, and ado_query_items.

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 verb 'update' and the sibling context, but no explicit guidance is given on when to use this tool versus alternatives (e.g., 'use for existing items, not for creation'). The description provides field options but no scenarios.

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