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

Beyond the annotations (readOnly=false, idempotent=false, destructive=false), the description discloses critical behavior: there is no batch endpoint, requests are fanned out with bounded concurrency, and results are reported per-item. This informs the agent of partial-failure semantics and non-atomicity, which is genuinely valuable context.

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

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

Two sentences with zero waste: the first front-loads the core purpose, the second adds the essential behavioral caveat (fan-out, bounded concurrency, per-item results). Every phrase earns its place.

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

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

For a mutation tool with no output schema, the description compensates by disclosing per-item result format (comment ids/errors). Combined with schema-covered parameters and annotations, the definition is nearly complete; the only minor gap is an explicit pointer to the single-item sibling for one-off comments.

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

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

Schema description coverage is 100%, so the schema itself documents all three parameters. The description only loosely maps 'one comment text' to the text parameter and 'many work items' to ids, adding no detail beyond the schema's existing parameter descriptions. Baseline 3 is appropriate.

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

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

The description states a specific verb+resource+scope: 'Add one comment text to many work items.' It clearly differentiates from the sibling add_work_item_comment (single item) by emphasizing 'many'/'multiple' work items, so an agent can distinguish it without opening schemas.

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

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

The description gives clear context for when to use the tool (adding the same comment text across multiple work items) and signals batch intent. However, it never explicitly names the single-item alternative (add_work_item_comment) or states when-not-to-use, leaving the exclusion to inference.

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

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

The description adds useful behavioral context beyond the annotations: plain text is converted to HTML, HTML is accepted as-is, and the new comment id is returned. This is especially valuable because there is no output schema and the annotations only state read-only/idempotent/destructive hints.

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, no filler, and the core action is front-loaded. Each sentence contributes a distinct fact: the operation, the text handling behavior, and the return value.

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

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

For a simple create-with-comment tool, the description is nearly complete: all parameters are documented in the schema, the return value is specified, and the conversion behavior is disclosed. The only gap is not addressing the closely named sibling 'add_comment_to_work_items', but the singular phrasing mitigates this.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds semantic value by explaining how the 'text' parameter is processed (plain text converted to HTML, HTML accepted as-is), which goes beyond the schema's simple 'plain text or HTML' note.

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 ('Add') and a clear resource ('discussion comment to a work item'). It distinguishes from read/update siblings by the action, and from 'add_comment_to_work_items' by singular vs. plural scope, though it does not explicitly name the sibling.

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 tells what the tool does but not when to use it versus alternatives. It does not mention the sibling 'add_comment_to_work_items' or any conditions, prerequisites, or exclusions, leaving usage decisions to inference.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the safety profile is known. The description adds non-obvious behavioral context by disclosing that it returns basic server info and a derived `assignedToValue`, which an agent could not infer from the tool's name or annotations alone.

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 with no filler. It front-loads the primary purpose, then lists the returned fields and the practical `assignedToValue` use case, making every sentence informative.

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 read-only tool with no output schema, the description provides a complete picture: it names the identity attributes, the derived assignment value, and the server info fields. An agent can confidently call this tool and know exactly what to expect.

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 and the empty input schema is fully covered, so there are no parameter semantics to clarify. The description correctly focuses on what is returned instead, which is the relevant semantic information for an agent.

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

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

The description names a specific verb ('Identify') and a specific resource ('the user behind the configured PAT'), and enumerates what is returned: id, display name, account, descriptor, assignedToValue, and server info. This clearly distinguishes it from sibling tools like search_identities, which searches, rather than returns the configured identity.

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

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

The description gives a clear usage context: it identifies the PAT's user and specifically calls out the `assignedToValue` for update_work_item(s), signaling when this tool is useful. It does not explicitly mention alternatives or when not to use it, but the provided integration hint is strong enough guidance for the main use case.

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?

Beyond the readOnlyHint and idempotentHint annotations, the description discloses output encoding (text inline vs binary base64), the default ref behavior, and detailed error diagnostics when the file is missing. This gives agents actionable expectations for both success and failure modes.

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 targeted sentences with no filler: core operation, encoding behavior, and error behavior. The most important information is front-loaded, and every sentence 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?

With no output schema, the description adequately explains return value format (inline vs base64) and exceptional cases. Combined with full schema parameter descriptions and readOnly/idempotent annotations, an agent has enough information to call this tool correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds some ref-selection context (branch/commit/tag alternatives and default behavior), but does not materially improve on the parameter docs for path, project, or maxBytes. Therefore no upgrade beyond baseline is warranted.

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 ('Read') and resource ('a file from a Git repository'), clarifies ref selection with a default branch, and is distinguishable from siblings like get_files_content and list_directory because it targets a single file's contents. This clearly separates it from the plural and directory-oriented tools.

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

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

The description conveys a clear usage context: retrieving one file's content from a repo at a chosen branch/commit/tag. It doesn't explicitly mention alternatives or exclusions, but the single-file scope is unambiguous, so an agent can identify when this tool is appropriate.

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

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

Annotations already declare readOnlyHint and idempotentHint, which cover the main behavioral transparency. The description adds implementation details (one itemsbatch request, parallel fetch) that don't contradict or undermine safety, and it explains error reporting for missing files, providing extra clarity.

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

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

The description is concise and well-structured, using three sentences to convey the batch operation, the process, and the error handling. No redundant information, and it's easy to scan.

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

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

For a batch read operation, the description is complete: it specifies what the tool does, how it behaves (including missing file reporting), and refers to the singular tool's diagnostics for consistency. No output schema is needed, and the description provides enough context for an agent to invoke it correctly.

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

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

Schema description coverage is 100%, with each parameter clearly explained. The main description doesn't add additional meaning beyond the schema, 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?

Description clearly states it reads several files from one repository at a specific branch/commit/tag in a single call. It differentiates from the singular get_file_content by emphasizing the batch nature, making the tool's purpose unambiguous.

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

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

The description implies usage when multiple files need to be fetched simultaneously and contrasts with the singular counterpart via 'in a single call'. It also mentions how missing files are reported, giving practical guidance, though it doesn't explicitly state when not to use it (e.g., for a single file).

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

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

Annotations already declare readOnlyHint and idempotentHint, and the description's 'Read' phrasing is consistent with those. It adds meaningful behavioral detail beyond annotations by specifying the output fields and the folder behavior, including that children are listed at depth 1. It does not go into error behavior, but the safety profile is already covered.

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, information-dense sentence with no fluff. It front-loads the core operation and lookup method, then adds return-value details and the folder edge case in a logical order.

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

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

With no output schema, the description adequately explains what the tool returns, including name, path, type, columns, WIQL text, and folder children behavior. Combined with 100% parameter schema coverage and safety annotations, nothing critical is missing for an agent to call this tool correctly.

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

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

Schema description coverage is 100%, so the schema fully documents queryId and project. The description adds a helpful path example ('Shared Queries/Team/Open Bugs') but does not materially expand on the parameter meanings beyond what the schema already provides. Baseline 3 is appropriate.

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

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

The description clearly states the action ('Read'), the resource ('a saved work item query'), and the lookup mechanism (GUID or path). It also lists the returned fields, which helps distinguish this tool from sibling tools like run_query and run_wiql that execute queries rather than retrieve their definitions.

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 is for reading saved query definitions rather than executing them, but it does not explicitly say when to prefer this over run_query or run_wiql. The path example gives useful context, but the 'when vs. alternatives' 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.

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

Annotations already declare read-only and idempotent behavior, so the bar is lower. The description adds useful behavioral context by listing what the response will include: metadata, rich-text content, relations, and optionally comments. It does not discuss auth, rate limits, or default expansions, but for a read-only getter this is adequate.

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, well-structured sentence that leads with the core action ('Get a single work item') and then organizes the response details into clear categories. There is no filler or redundant restatement of the title.

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

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

With no output schema, the description carries the burden of explaining return values, and it does so at a useful level of detail. It covers metadata, rich-text fields, relations, and comments, though it could have briefly noted default behaviors or the expand/fields relationship. Overall, it is sufficient for an agent to understand what this tool provides.

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?

Input schema coverage is 100%, so the schema already documents all six parameters clearly. The description adds minimal parameter-level meaning beyond mentioning rich-text content and optional comments, which maps loosely to format and includeComments. This matches the baseline of 3 for well-covered schemas.

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

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

The description states a specific verb ('Get') and resource ('a single work item'), and enumerates the returned content: metadata, rich-text content, relations, and optional comments. This clearly distinguishes it from plural sibling tools like get_work_items and from comment-specific tools like get_work_item_comments.

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

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

The phrase 'Get a single work item' gives clear context for when to use this tool versus list-style or comment-only tools. However, it does not explicitly name alternatives or state when not to use them, so it falls short of a perfect score.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the description doesn't need to restate safety. It adds useful behavior context: results are paged and the returned comment ids feed into update_work_item_comment, which goes beyond the structured metadata.

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, purposeful sentences with no filler. Pagination is front-loaded, and the second sentence explains why the tool matters by linking to update_work_item_comment.

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

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

For a read-only list operation with strong annotations and mostly self-documenting parameters, the description covers the key context: what is listed, pagination, and downstream use. A fully explicit output shape is absent, but the stated purpose of returning comment ids is sufficient for correct invocation.

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

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

The description itself does not explain individual parameters, but the input schema already covers 71% of them with meaningful descriptions for id, top, format, project, and continuationToken. The description adds no parameter-level meaning beyond the schema, landing at the baseline.

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

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

The description uses a specific verb ('List') with a clear resource ('discussion comments of a work item') and notes pagination. It also explains the practical purpose by stating it returns comment ids needed for update_work_item_comment, which distinguishes this tool from sibling comment-related tools.

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

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

The description gives clear context: this tool lists comments and returns IDs needed for updating a comment. It does not explicitly name alternatives or say when not to use it, but the purpose statement makes the primary use case evident.

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?

Adds valuable behavior beyond the readOnlyHint/idempotentHint annotations: chunking by 200 ids and partial failure reporting via the 'failed' field. This gives the agent realistic expectations about batch limits and error behavior.

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

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

The description is two concise sentences with the core purpose front-loaded and technical details following. Every sentence adds useful information and there is no filler.

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

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

For a batch-read tool with rich schema and safety annotations, the description provides the key behavioral details: API name, chunk size, and partial-failure semantics. It doesn't describe the return shape, but no output schema exists and the description is otherwise sufficient to call correctly.

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

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

Schema description coverage is 100%, so the baseline 3 applies. The description mentions errorPolicy=omit, but this is already encoded in the schema; it adds no new meaning beyond what the parameter descriptions provide.

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

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

States a specific verb ('Read'), resource ('work items'), and scope ('many in one call'), using the workitemsbatch API. This clearly distinguishes the tool from the singular 'get_work_item' sibling without ambiguity.

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

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

The phrase 'many work items in one call' clearly signals the intended use case over fetching items individually. It does not explicitly name alternatives or exclusion conditions, but the context is sufficient for an agent to pick the right tool.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds useful behavioral context beyond annotations: recursion modes, inclusion of metadata, and the fact that each entry carries the latest commit that touched it. This helps the agent predict output richness without contradicting the safety hints.

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

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

A single, well-structured sentence that front-loads the core action and resource, then adds scoping and output details. There is no filler or 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?

With 8 parameters, no output schema, and read-only/idempotent annotations, the description gives enough context for selecting and invoking the tool. It names key return metadata but not the full response shape; however, the schema covers parameter usage sufficiently.

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 high (88%), so the schema already documents parameters like path, recursion, branch, and includeMetadata. The description only restates recursion behavior and metadata, adding little parameter-level meaning beyond the schema.

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

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

The description states a specific verb ('List') and resource ('files and folders under a directory path in a Git repository'), and adds precision with 'one level or full recursion' and metadata details. This clearly distinguishes it from work-item siblings and file-content tools.

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

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

The description implies when to use the tool — when you need to enumerate repository contents — but it does not explicitly mention alternatives such as get_file_content or list_repositories. There is no when-not-to-use guidance, leaving the agent to infer the appropriate context.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description adds behavioral value by stating the scope behavior ('when no project is given') and the return contents ('default branch and URLs'), which is useful since there is no output schema. This is beyond what the annotations alone provide, though it does not discuss pagination or permissions.

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

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

A single sentence conveys purpose, scope, conditional behavior, and expected output fields with no filler. The key information about scope is front-loaded before the output note.

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, read-only, idempotent list operation with one optional parameter, the description together with the schema and annotations is complete. It addresses what is returned, how scope is controlled, and the operation's non-mutating nature via annotations.

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

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

Schema coverage is 100%, so the baseline is 3. The parameter description already contains the omit/unset TFS_DEFAULT_PROJECT behavior, and the tool description mostly rephrases this rather than adding new semantic meaning. No additional parameter syntax, format, or constraint details are introduced beyond the schema.

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

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

The description uses a specific verb and resource: 'List Git repositories' with a clear scope ('in a project or in the whole collection'). It explicitly mentions the output fields ('default branch and URLs'), which further distinguishes it from sibling tools like get_file_content or list_directory.

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

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

The description gives clear context on when to use: list repositories in a project, or when no project is given, in the whole collection. It does not explicitly name alternatives, but there are no repository-listing siblings, so the exclusion criteria are less necessary. It stops short of a 5 because it does not state when not to use this tool versus another.

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

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

The description adds behavioral context beyond the readOnly/idempotent annotations by explaining that extraWhere is 'passed as-is and AND-ed' with the saved query's WHERE clause, plus a concrete example. No side effects or contradictions are present; the readOnly annotations align with the execution semantics.

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

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

Two sentences carry the core purpose, the optional filtering behavior, and a useful example. There is no redundant repetition of schema fields, and the most important scoping information is front-loaded.

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

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

For a read-only query execution tool, the description is sufficient: it identifies the resource, the result type, and the key extension mechanism. The remaining details (field selection, formatting, top count) are well covered by the input schema, and no output schema exists to describe return shape further.

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

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

Schema coverage is 100%, so the schema already documents all parameters. The description adds value by explaining queryId accepts either a GUID or path and by giving a concrete WIQL example for extraWhere, including the 'passed as-is' caveat.

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

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

The description states a specific action ('Execute a saved query') and a clear resource ('by GUID or path'), and specifies the result ('return the matching work items'). It is distinct from sibling tools like run_wiql or get_work_item because it explicitly targets saved queries.

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 establishes when to use it: when a saved query exists and needs execution, optionally with an extra WIQL filter. It does not explicitly name alternatives such as run_wiql, but the saved-query focus is clear enough to guide 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?

Annotations already declare the tool read-only and idempotent, covering the safety profile. The description adds meaningful behavioral context by stating that the query is executed as-is and that results are returned flat for flat WIQL queries or as a link tree for tree/oneHop queries. No contradiction with annotations.

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 with the core purpose front-loaded, followed by one illustrative example and a compact note about return shape. There is no filler, repetition, or unnecessary detail.

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

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

The schema fully covers parameter semantics, annotations cover read-only and idempotent behavior, and the description states the return shape. Since there is no output schema, the explicit mention of flat versus tree/oneHop results is valuable; the only notable gap is the absent routing guidance for choosing between run_wiql and run_query.

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

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

Schema coverage is 100%, so the schema already documents all five parameters with descriptions. The tool description does not explain individual parameters beyond the schema, and its WIQL example only lightly illustrates the wiql parameter. This matches the baseline for full schema coverage.

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

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

The description states a specific action ('Execute'), a precise resource ('arbitrary WIQL query string'), and provides a concrete example with a SELECT query. It also distinguishes itself from siblings like run_query by emphasizing raw, as-is WIQL execution rather than saved-query execution.

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

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

The phrase 'arbitrary WIQL query string as-is' implies that this tool is for raw query text rather than saved queries, but it does not explicitly mention when to use it versus alternatives such as run_query. No exclusions or routing guidance is given, 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.

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

No annotations are present, so the description carries the behavioral burden. It discloses the return fields (id, display name, unique account name, assignedToValue) and the search purpose. However, it does not explain search matching semantics (prefix/substring/exact), whether groups are included by default, or any auth requirements. No contradictions with annotations exist since there are none.

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

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

Two sentences with no filler: purpose is front-loaded, followed by the return fields. 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?

The tool has three parameters, no annotations, and no output schema, so the description is the only guidance. It adequately covers purpose and return shape, but the undocumented includeGroups parameter and the ambiguity around group search leave a notable gap. It is viable for basic user lookups but not fully complete for all advertised uses.

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

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

The schema already documents query and filter with examples and meaning, but includeGroups appears in the schema with no description. The description adds nothing about includeGroups and does not clarify how 'users or groups' maps to that flag. With roughly 67% schema coverage, the description should compensate for the missing parameter, and it does not.

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

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

The description states a specific action ('Find users or groups') with the search dimensions (display name, account name, e-mail) and the concrete downstream purpose (obtain a valid assignedTo value). This clearly distinguishes it from sibling tools like get_current_identity or work item/query tools.

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

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

It clearly implies when to use the tool: whenever an assignedTo value is needed. It doesn't explicitly contrast with alternatives like get_current_identity or describe when not to use it, but the context is strong enough that an agent can infer the appropriate use case.

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

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

Annotations already establish readOnlyHint=false, idempotentHint=true, and destructiveHint=false. The description adds useful behavioral context beyond those: the update uses JSON Patch, state and assignedTo are mandatory even though other fields are optional, and the tool returns the updated work item. This is meaningful given there is no output schema, though it does not discuss edge cases like failed state transitions.

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

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

The description is two tight sentences with no filler. It front-loads the operation ('Update a work item's metadata'), specifies the method ('via JSON Patch'), states the mandatory fields, and closes with the return value. Every sentence 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 ­17-param­eter mutation tool with no output schema, the descrip­tion covers the return value but does not address the exis­tence of update_work_i­tems (batch) or explain when the single-item update should be preferred. The rich input schema mitigates param­eter gaps, but the missing sibling routing and minimal behavioral caveats leave the descrip­tion function­ally adequate yet 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 82%, so the schema already documents most parameters. The description adds aggregate guidance by naming state and assignedTo as mandatory and calling other fields optional, but it omits the required id from that statement, which could slightly mislead. It does not add per-parameter meaning beyond what the schema provides.

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

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

The description states a specific verb and resource: 'Update a work item's metadata via JSON Patch.' It distinguishes the tool from read/get siblings and from the plural update_work_items by making the singular 'a work item' explicit. However, it does not explicitly name or contrast the sibling update_work_items, 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.

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 update_work_items or other sibling tools. It mentions that state and assignedTo are mandatory, which is a prerequisite rather than usage context. There are no when-to-use, when-not-to-use, or alternative-tool signals.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds no further behavioral context such as permissions, rate limits, or whether the original text is irreversibly overwritten, although 'replace' does convey in-place modification.

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

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

One tight sentence with no filler. The main operation is front-loaded, and the parenthetical adds a useful workflow pointer without bloating the description.

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 four-parameter update tool with a fully-described schema and helpful annotations, the description is nearly sufficient: it covers what the tool does and how to source the required commentId. The only minor gap is that it doesn't explicitly contrast this tool with add_work_item_comment or mention what the operation returns.

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

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

Schema_description_coverage is 100%, so the schema already documents all four parameters. The description adds extra value by telling the agent that comment ids can be obtained via get_work_item_comments, which gives practical meaning to the commentId parameter beyond the schema's simple 'Comment id'.

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

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

The description states a specific action and resource: 'Replace the text of an existing comment.' The parenthetical about get_work_item_comments reinforces that this operates on existing comments, clearly distinguishing it from add_work_item_comment and add_comment_to_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?

It gives explicit prerequisite guidance: use get_work_item_comments to find comment ids. It clearly implies this tool is for existing comments rather than adding new ones, though it does not explicitly name add_work_item_comment as the 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?

The description goes well beyond the annotations by disclosing the batching behavior, the fallback to parallel single PATCH calls, and the per-item result reporting. This gives an agent useful expectations about performance and partial-failure reporting, and nothing contradicts the idempotentHint annotation.

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 sentences deliver the essential purpose, endpoint behavior, and result semantics with no filler. The core statement is front-loaded, making the tool's role immediately clear.

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

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

Given the high parameter count and absence of an output schema, the description covers the key operational aspects: batch updates, fallback behavior, and per-item results. It does not describe the exact result format, but 'Per-item results are reported' provides enough orienting context for selection and invocation.

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

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

Schema description coverage is 81%, so the schema already documents parameters such as tags, fields, reason, comment, and assignedTo. The description adds only a high-level note that state and assignedTo are the core update fields, which is useful but does not significantly expand on the schema.

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

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

The description states a specific verb and resource: applying the same update to many work items, with state and assignedTo called out. It clearly distinguishes the batch tool from the singular sibling update_work_item by emphasizing 'many work items' and 'same update'.

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 implies this tool is for updating many work items with the same update, which distinguishes it from update_work_item. It does not explicitly name the alternative or state when not to use it, but the batch-purpose framing is strong enough for an agent to select it correctly.

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