Server Quality Checklist

Tool Scores

• ado_work_items_queryC
  2.7/5.0
  Behavior2/5

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

  With no annotations, the description carries the full burden, but it only says 'bounded' and 'query'. This hints at a read-only operation with a limit, but it does not disclose authentication needs, error behavior, pagination behavior, or whether any mutation occurs. 'Bounded' adds limited context but not enough 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.

  Conciseness4/5

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

  The description is a single efficient sentence with no redundant wording. 'Bounded' and 'in a project' are meaningful qualifiers, and the core purpose is front-loaded. It is concise, though it sacrifices informative detail.

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

  Completeness2/5

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

  The tool has an output schema and only three parameters, so complexity is moderate, but the description is still incomplete. It omits any practical usage context, parameter semantics, or behavior around the optional project and top values. An agent would need to open schemas or rely on assumptions to invoke this correctly.

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

  Parameters2/5

  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. It adds minimal meaning by indicating that the query is WIQL-based and occurs within a project, which loosely maps to the wiql and project parameters. However, it does not explain the top parameter, WIQL syntax, or the behavior of optional/nullable parameters.

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

  Purpose4/5

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

  The description clearly identifies the action ('run') and the resource ('a bounded WIQL query in a project'), which distinguishes it from single-item get/create/update tools. It does not explicitly state that the result is a list of matching work items, but 'WIQL query' is specific enough for an agent to infer the purpose.

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

  Usage Guidelines2/5

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

  No guidance is given about when to use this tool instead of siblings like ado_work_item_get, ado_work_item_create, or ado_work_item_update. The description implies a querying/read use case but does not state exclusions or provide a decision rule.

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

• ado_work_item_types_listC
  2.7/5.0
  Behavior2/5

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

  With no annotations present, the description carries the full burden of disclosing behavior, but it only says what the tool lists. It does not disclose whether project is optional, whether null means all projects, pagination behavior, or any read-only/listing side effects. The return behavior is only partially implied by 'List.'

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

  Conciseness4/5

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

  The description is a single front-loaded sentence with no filler or repetition; every word contributes to the core action and scope. It is not penalized for being short, though additional behavioral context could be added without hurting structure.

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

  Completeness2/5

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

  Despite low complexity and an output schema, the description leaves the optional project parameter ambiguous: the text implies a project is required while the schema says it is optional with a null default. An agent cannot tell from the description what omitting the project does or which sibling to use for a single type, so the tool is not fully contextualized.

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

  Parameters2/5

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

  Schema description coverage is 0% and the only parameter, project, has no description beyond its title. The phrase 'in a project' weakly ties the parameter to the tool scope, but it does not explain the null default, what happens when omitted, or the expected project identifier format. The description does not meaningfully compensate for the missing schema documentation.

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

  Purpose4/5

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

  The description states a clear action ('List') and a clear resource ('work item types') scoped to a project, which distinguishes it from siblings like ado_work_item_type_get (singular retrieval) and ado_work_item_fields_list (different resource). It could be more explicit about how it differs from the singular type-get sibling, but the plural/listing verb and resource are unambiguous.

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

  Usage Guidelines2/5

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

  There is no guidance on when to choose this tool over ado_work_item_type_get or ado_work_items_query, and no mention of conditions, prerequisites, or exclusions. The verb 'List' implies a simple enumeration use, but the description never states a decision rule.

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

• ado_pull_request_createC
  2.8/5.0
  Behavior2/5

  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 create action and the write-mode prerequisite, but does not disclose side effects, permission requirements, failure behavior, or what happens on success. The write-mode hint is useful but underdeveloped.

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

  Conciseness4/5

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

  The description is a single short sentence with no wasted words, and the main action is front-loaded. It could be slightly more informative without bloat, but as a concise statement it works well.

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

  Completeness2/5

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

  Given no annotations, a nested request object with 7 properties, and only a terse one-line description, the definition is under-specified. An agent does not know how to construct the required request body or handle the write-mode precondition. The output schema exists, but the description still fails to provide enough context for correct invocation.

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

  Parameters1/5

  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 compensate at all. It does not mention the required fields (repository, source_ref, target_ref, title) or the optional fields (project, is_draft, description). The agent must infer parameter meaning entirely from names and structure, which is insufficient for a nested request object.

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

  Purpose4/5

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

  The description clearly states the action and resource: 'Create a pull request'. This distinguishes it from sibling tools that list, get, or query pull requests, though it does not explicitly name any alternative. The qualifier 'when write mode is enabled' adds a condition but does not obscure the core purpose.

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

  Usage Guidelines3/5

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

  The description provides a usage condition: only create a pull request when write mode is enabled, implying the tool should not be used otherwise. However, it does not explain what write mode is, nor does it offer alternatives or explicitly say when to choose this tool over sibling tools.

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

• ado_work_item_createC
  2.8/5.0
  Behavior2/5

  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 reveals only that this is a creation action gated by write mode, but it does not disclose permissions, side effects, prerequisites beyond write mode, or failure behavior.

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

  Conciseness4/5

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

  The description is a single, front-loaded sentence with no filler, so it is efficient. It is appropriately concise, though its brevity creates substantive gaps already scored elsewhere.

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

  Completeness2/5

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

  The tool has a nested request schema and no annotations, and the description only covers the write-mode precondition. It does not clarify required field semantics, project defaulting, or expected behavior, so an agent is left to infer too much. The presence of an output schema reduces the need for return-value detail but does not fill the other gaps.

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

  Parameters1/5

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

  Schema description coverage is 0%, so the description needed to explain the request object, required title and work_item_type, and optional fields/project/description; it mentions none of them. The schema names fields but provides no descriptions, so the burden is unmet.

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

  Purpose4/5

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

  The description uses a specific verb and resource, 'Create a work item,' which clearly identifies the operation. It does not explicitly distinguish itself from the sibling ado_work_item_update tool, so it stops short of full sibling differentiation.

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

  Usage Guidelines3/5

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

  The phrase 'when write mode is enabled' provides a concrete precondition, so an agent knows this tool is not available for read-only calls. However, it gives no alternative routing or when-not guidance, leaving the choice between create and update mostly to inference from the tool name.

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

• ado_pull_requests_listC
  2.9/5.0
  Behavior2/5

  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 a basic list operation and says nothing about whether the call is read-only, whether results are paginated, how the 'top' limit behaves, or what happens when neither project nor repository is provided. The agent is left without important behavioral context.

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

  Conciseness5/5

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

  A single sentence that states the verb, resource, and scope with no filler. The core action is front-loaded, and every word contributes to the meaning. It is appropriately concise for a list operation.

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

  Completeness3/5

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

  The description is adequate for a straightforward list tool but leaves important gaps: whether project and repository are mutually exclusive or cumulative, what defaults apply, and how the results are limited. The presence of an output schema partially compensates, but given zero annotations and zero parameter descriptions, more detail is needed for fully confident invocation.

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

  Parameters2/5

  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. It adds some meaning for 'project' and 'repository' by framing them as scoping filters, but it does not explain the 'top' parameter, the relationship between the filters (e.g., can both be used together), or what default null values imply. This is insufficient for full parameter understanding.

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

  Purpose4/5

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

  The description uses the specific verb 'List' with the resource 'pull requests' and adds a scoping phrase 'in a project or repository'. This clearly communicates the core operation and distinguishes it from sibling tools like ado_pull_request_get (fetch a single PR) and ado_pull_request_create. It does not explicitly name a sibling, but the operation is unambiguous.

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

  Usage Guidelines2/5

  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 that this is the listing entry point, when to prefer ado_pull_request_get for a single PR, or how the optional project/repository filters interact. Usage is only implied by the verb 'List'.

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

• ado_work_item_getC
  2.9/5.0
  Behavior3/5

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

  No annotations are present, so the description carries the behavioral burden. The verb 'Get' implies a read-only operation, and the description discloses that the response includes fields, relations, and revision. However, it does not mention permissions, error behavior, or how revisions are represented.

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

  Conciseness5/5

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

  The description is a single concise sentence with no filler or redundant phrasing. It front-loads the core purpose and adds useful specifics about what is returned.

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

  Completeness2/5

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

  For a get-by-id tool this is close to minimal viable, but it lacks usage orientation among siblings and fails to explain the project parameter. Even with an output schema present, an agent has little guidance on when to choose this tool over ado_work_items_query or how the optional project context affects the call.

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

  Parameters1/5

  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 mention work_item_id or project at all. While work_item_id is somewhat self-evident from its name, the optional project parameter's role is completely unexplained, and the description adds no parameter-level meaning.

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

  Purpose4/5

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

  The description clearly identifies the operation ('Get'), the resource ('a work item'), and the retrieval scope ('fields, relations, and revision'). This distinguishes it from sibling tools like ado_work_items_query and the create/update tools, though it does not explicitly say 'by ID' or name the distinguishing sibling.

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

  Usage Guidelines2/5

  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 such as ado_work_items_query. It does not state any exclusions, prerequisites, or preferred selection context, leaving the agent to infer usage from the tool name alone.

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

• ado_pull_request_thread_addB
  3.1/5.0
  Behavior2/5

  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 verb 'Add' signals mutation, but the description does not explain whether a new thread is created, what happens on duplicate attempts, what permissions are required, or what the response will contain. The domain term 'general review comment thread' is also left undefined.

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

  Conciseness5/5

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

  The description is a single concise sentence with no redundant words. It is front-loaded and conveys the core operation immediately.

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

  Completeness2/5

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

  For a mutating tool with no annotations, zero schema description coverage, and a nested request object, this description is far too sparse. It does not explain what a general thread is, how the required fields relate, what response to expect, or any constraints. The presence of an output schema does not reduce the need for behavioral and parameter context here.

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

  Parameters2/5

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

  Schema description coverage is 0%, yet the description adds little parameter meaning. It indirectly references pull_request_id and content, but does not explain repository/project, the required nested 'request' structure, or the distinction between general and code-line threads. The schema property names are self-evident to some degree, but the description does not compensate for the complete lack of schema descriptions.

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

  Purpose5/5

  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 a general review comment thread to a pull request.' This clearly identifies the action and distinguishes it from sibling tools like ado_pull_request_threads_list (listing threads) and ado_work_item_comment_add (adding a 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.

  Usage Guidelines2/5

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

  The description gives no guidance on when to prefer this tool over alternatives, nor does it mention prerequisites such as requiring an existing pull request. Usage context is only weakly implied by the tool's name and one-line description, not explicitly stated.

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

• ado_work_item_comments_listB
  3.1/5.0
  Behavior2/5

  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. 'List' suggests a read-only operation, but the description does not disclose pagination behavior, ordering, limits, authentication requirements, or any response quirks. The 'top' parameter is behaviorally important but unaddressed.

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

  Conciseness5/5

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

  The description is a single clear sentence with no filler or repetition. Every word contributes meaning, and it is appropriately short for a simple list operation.

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

  Completeness2/5

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

  For a tool with three parameters, no annotations, and no behavioral guidance, the descrition is incomplete. It does not explain how top and project affect results, whether project is required, or what the response shape contains. The existence of an output schema helps but is not enough to cover the missing pagination and scoping semantics.

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

  Parameters2/5

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

  Schema description coverage is 0% and the description mentions none of the three parameters. While parameter names like work_item_id and top are somewhat self-explanatory, the description does not clarify how 'project' scopes the call or how 'top' limits the returned comments. The description must compensate for the missing schema descriptions but does not.

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

  Purpose5/5

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

  The description states a specific verb ('List') and resource ('comments') scoped to 'a work item'. This clearly distinguishes it from sibling tools like ado_work_item_comment_add (adds comments) and the pull-request list tools.

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

  Usage Guidelines2/5

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

  There is no guidance about when to use this tool versus alternatives. It does not mention when this should be preferred over ado_work_item_get or how it relates to ado_work_item_comment_add. Usage is only implied by the verb and noun.

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

• ado_work_item_fields_listB
  3.2/5.0
  Behavior2/5

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

  No annotations are provided, so the description carries full behavioral burden. It only says 'List', implying a read-only action, but does not disclose whether system/hidden fields are included, how project scoping works, permission requirements, or any other behavior. It adds no insight beyond the tool name itself.

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

  Conciseness5/5

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

  A single, concise sentence of eight words that is front-loaded with the action and resource. Every word earns its place, and there is no redundancy or unnecessary detail.

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

  Completeness3/5

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

  The tool is simple with one optional parameter and an output schema, so the description need not explain return values. However, it fails to clarify what happens when 'project' is null or whether project is required in practice. The description is minimal but enough for a basic list call, with gaps around parameter behavior.

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

  Parameters2/5

  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. The only parameter, 'project', is mentioned only as 'in a project', which essentially restates the parameter name without explaining expected format, null/default behavior, or how the value is interpreted. This is minimal semantic addition over the raw schema.

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

  Purpose5/5

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

  The description uses a concrete verb ('List') and a specific resource ('work item fields') with a clear scope ('available in a project'). It is naturally distinct from sibling tools like ado_work_item_types_list and ado_work_item_get because it targets fields rather than types or individual work items.

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

  Usage Guidelines2/5

  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 the many sibling tools. It does not name alternatives, mention exclusions, or give preconditions. The only hint is the generic purpose of listing fields, which leaves selection to inference.

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

• ado_pull_request_getB
  3.3/5.0
  Behavior2/5

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

  No annotations exist, so the description is the only behavioral disclosure. It states 'Get,' which implies read-only, but provides no context about behavior for missing IDs, response payload, or side effects; it largely repeats the function implied by the tool name.

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

  Conciseness4/5

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

  One sentence, grammatically simple, and front-loaded with the operation. There is no wasted wording, though it is slightly under-specified for a complete tool definition.

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

  Completeness3/5

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

  With an output schema and low complexity, the description is minimally adequate: an agent knows the input keys and can infer a single-PR return. It remains incomplete in usage guidance and behavioral detail relative to having no annotations.

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

  Parameters2/5

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

  Schema description coverage is 0%, so the description must carry parameter meaning. It names repository and pull_request_id but only restates their roles as lookup keys; the optional project parameter is not mentioned or clarified at all.

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

  Purpose5/5

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

  The description is precise: 'Get a pull request by repository and ID' names the verb, resource, and the two identifying parameters. It clearly distinguishes from sibling list/query tools, which operate over collections rather than a single pull request.

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

  Usage Guidelines3/5

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

  The phrase 'by repository and ID' implies this is the tool to call when a specific pull request is already identified. However, the description never explicitly contrasts it with ado_pull_requests_list or other siblings, so routing guidance is left to inference.

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

• ado_work_item_updateB
  3.3/5.0
  Behavior2/5

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

  There are no annotations, so the description bears the full burden of behavioral disclosure. 'Update' and 'JSON Patch' indicate mutation and selective modification, but the description does not reveal permissions needed, effects of 'remove' operations, partial-failure behavior, or whether unknown fields cause errors.

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

  Conciseness5/5

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

  The description is a single focused sentence with no filler. Its key qualifiers—'explicitly selected' and 'using JSON Patch'—earn their place by conveying scope and method, making this appropriately concise.

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

  Completeness2/5

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

  For a tool with a nested request schema, JSON Patch semantics, and no annotations, this description is too sparse. It omits usage context, behavioral caveats, and any guidance on constructing valid patch operations, leaving an agent to rely entirely on schema structure and outside knowledge.

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

  Parameters2/5

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

  Schema description coverage is 0%, and the description adds essentially no parameter-level meaning. It does not explain work_item_id, operations, paths, or value types; the schema's $defs carry the meaning instead. Since the description must compensate for low schema coverage, this is a clear gap.

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

  Purpose5/5

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

  The description states a specific action ('Update'), a precise resource ('work item fields'), and a distinctive mechanism ('using JSON Patch'). This clearly separates it from siblings like ado_work_item_create, ado_work_item_get, and ado_work_items_query, so an agent can recognize its role without opening the schema.

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

  Usage Guidelines3/5

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

  The phrase 'explicitly selected work item fields' implies the tool is for targeted field updates rather than full replacements, but the description gives no explicit when-to-use guidance or alternatives. It does not state prerequisites such as the work item existing or when to choose this over create or query tools.

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

• ado_pull_request_changesB
  3.4/5.0
  Behavior2/5

  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 conveys that the operation is a read/list, but adds no details about pagination, authentication, scoping, or what exactly counts as a 'changed file'. The description does not go beyond the basic operation.

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

  Conciseness5/5

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

  The description is a single concise sentence with no filler. 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.

  Completeness3/5

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

  The tool is simple, and an output schema exists, so return-value details need not be in the description. However, with no annotations and no usage or parameter guidance, the description is minimally complete rather than fully contextualized for an agent choosing among related pull request tools.

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

  Parameters2/5

  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 any of the parameters. The parameter names and titles are fairly self-explanatory, but the description does not compensate for the lack of schema-level descriptions, such as clarifying the optional project field or how pull_request_id relates to the repository.

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

  Purpose5/5

  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 changed files for a pull request.' This clearly distinguishes it from sibling tools like ado_pull_request_get, which retrieves pull request details, and ado_pull_requests_list, which lists pull requests.

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

  Usage Guidelines3/5

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

  The description makes the core use case clear—use this when you need the files changed by a pull request—but it does not explicitly state when not to use it or name alternatives. The usage context is implied rather than explicitly contrasted with sibling tools.

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

• ado_pull_request_threads_listB
  3.4/5.0
  Behavior3/5

  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. The verb 'List' clearly implies a read-only operation, and 'for a pull request' defines scope. However, it does not mention pagination, ordering, filtering, or whether all thread states are returned, leaving some behavioral ambiguity.

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

  Conciseness5/5

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

  The description is a single, tightly worded sentence that immediately communicates the tool's purpose. Every word contributes meaning, and there is no redundant content.

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

  Completeness3/5

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

  For a simple list operation with an output schema available, the description is minimally adequate: it states the core purpose and implies the key parameter. But it lacks parameter semantics, usage guidelines, and behavioral caveats, leaving clear gaps for an agent attempting to invoke it confidently.

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

  Parameters2/5

  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. It only implies that pull_request_id identifies the PR, but it does not explain repository or project, their relationship, or any constraints on their values. The description adds minimal meaning beyond the raw parameter names.

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

  Purpose5/5

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

  The description uses a specific verb ('List') and a specific resource ('review threads and comments for a pull request'). It clearly distinguishes this tool from siblings like ado_pull_requests_list (lists PRs) and ado_pull_request_thread_add (adds a thread).

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

  Usage Guidelines2/5

  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. It does not mention sibling tools, exclusions, or conditions that would route an agent to a different tool such as ado_pull_request_get or ado_pull_request_thread_add.

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

• ado_work_item_comment_addA
  3.6/5.0
  Behavior3/5

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

  No annotations are present, so the description must disclose behavior itself. It states the write-mode requirement and makes the mutating nature apparent via 'Add', which is useful. But it doesn't say what happens when write mode is disabled, whether permissions are needed, or whether the action is reversible.

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

  Conciseness5/5

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

  A single sentence that front-loads the action and adds only one relevant condition. No filler or repetition of schema fields.

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

  Completeness3/5

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

  For a simple 3-parameter tool with an output schema, the core action is clear and required fields are present in the schema. However, the 'write mode' prerequisite is unexplained and no annotation or description covers error behavior or parameter semantics beyond names, leaving some gaps.

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

  Parameters2/5

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

  Schema description coverage is 0%, and the description mentions none of the parameters. The names work_item_id, text, and project are somewhat self-explanatory, but the description contributes no additional meaning or constraints to compensate for the absent schema descriptions.

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

  Purpose5/5

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

  The description uses a specific verb ('Add') with a clear resource ('comment to a work item'), so an agent can distinguish this from the sibling read tool ado_work_item_comments_list and from work item create/update tools. 'When write mode is enabled' adds a condition but doesn't obscure the action.

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

  Usage Guidelines3/5

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

  It provides one usage condition — write mode must be enabled — which is relevant for deciding whether the tool can run. However, it gives no explicit guidance about when to choose this over ado_work_item_comments_list for reading comments or ado_work_item_update for editing work items, and no exclusions.

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

• ado_work_item_type_getA
  3.7/5.0
  Behavior3/5

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

  With no annotations provided, the description carries the burden of indicating behavior. 'Get' signals a read-only operation, and the described output scope is clear, but no additional behavioral context such as authentication, error conditions, or side effects is disclosed. This is adequate for a simple lookup though 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.

  Conciseness5/5

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

  The description is a single, front-loaded sentence with no filler. It efficiently states the verb, resource, and selection scope while leaving parameter details to the schema.

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

  Completeness4/5

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

  The tool is a simple metadata getter, and an output schema is present to describe the returned shape. The description names the resource and scope, and the input schema covers the required work_item_type and optional project. It is missing explicit usage guidance, but the available structured fields make this reasonably complete.

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

  Parameters2/5

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

  Schema description coverage is 0%, so the description should compensate for missing parameter explanations. It only implies the identity of the work_item_type parameter ('for one work item type') and does not clarify the optional project parameter or meaning of the values. The schema's title and default provide only minimal structure, not semantic depth.

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

  Purpose5/5

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

  The description uses a specific verb ('Get') and names the exact resources returned ('fields, states, and rules') for one work item type. It clearly distinguishes this from sibling tools like ado_work_item_types_list, which would list types rather than retrieve details for a single type.

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

  Usage Guidelines3/5

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

  The phrase 'for one work item type' implies this tool is for retrieving details of a single type, contrasting with a list operation, but it does not explicitly state when to use this versus sibling tools or mention any exclusions. Usage context is present only by implication.

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