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

With no annotations provided, the description carries the full burden and does well by disclosing key behavioral traits: it explains the immediate effect ('child work item will immediately appear under the parent'), impact on views ('affects how items are displayed in backlogs and boards'), and system constraints ('a work item can have only one parent but multiple children'). It also mentions the return format. However, it lacks details on error conditions or permissions required.

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

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

The description is well-structured with clear sections (purpose, usage guidelines, important notes, args, returns). Each sentence adds value: the opening statement defines the tool, bullet points clarify usage, the IMPORTANT section explains behavior, and parameter/return details are concise. No wasted words.

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

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

Given no annotations and no output schema, the description does a strong job covering purpose, usage, behavior, and parameters. It explains the return value as a formatted string. However, for a mutation tool with system constraints, it could benefit from mentioning error cases or authentication needs, keeping it from a perfect score.

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 description coverage is 0%, so the description must compensate. It provides clear semantics for all three parameters: 'parent_id' and 'child_id' are described as IDs of work items, and 'project' is noted as optional with name or ID. This adds meaningful context beyond the bare schema, though it doesn't specify format details for 'project'.

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 specific action ('Adds a parent-child relationship between two work items') and distinguishes it from siblings like 'create_work_item' or 'update_work_item' by focusing on establishing hierarchy rather than creating or modifying individual items. The verb 'adds' and resource 'relationship between two work items' are precise.

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

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

The description explicitly lists four use cases (e.g., 'Establish hierarchy between work items', 'Organize epics, features, user stories, and tasks') and provides context on when to use it. It also implicitly distinguishes from siblings by focusing on relationship management rather than data retrieval or modification of individual items.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key traits: comments are permanent and cannot be edited/deleted, authentication attribution to the Personal Access Token user, and that the return includes confirmation with author info and timestamp. This goes beyond basic functionality to cover important operational implications.

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 well-structured and appropriately sized. It starts with the core purpose, then usage guidelines, important behavioral notes, and parameter details. Every sentence adds value—no wasted words—and it's front-loaded with essential information.

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

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

Given the complexity (a mutation tool with permanent effects), no annotations, and no output schema, the description is remarkably complete. It covers purpose, usage, behavioral constraints (permanence, attribution), parameter semantics, and even hints at the return format. This provides sufficient context for safe and effective use.

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

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

Schema description coverage is 0%, so the description must compensate fully. It adds meaningful semantics for all three parameters: 'id' as work item ID, 'text' as comment text with markdown support, and 'project' as optional name with fallback behavior. This provides clear context beyond the bare schema types.

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

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

The description clearly states the tool's purpose: 'Adds a new comment to a work item.' It specifies the verb ('adds') and resource ('comment to a work item'), distinguishing it from sibling tools like update_work_item (which modifies fields) or get_work_item_comments (which retrieves 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 description provides explicit usage guidelines with a bulleted list of scenarios: 'Provide feedback or clarification,' 'Document decisions,' 'Add context without changing fields,' and 'Communicate with team members.' It also implicitly distinguishes from alternatives by noting comments don't change work item fields, unlike update_work_item.

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

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

With no annotations provided, the description carries the full burden and does well by disclosing key behavioral traits: it's a write operation ('creates'), has immediate effects ('created immediately'), impacts visibility ('visible to all users'), and triggers notifications/automation. It could improve by mentioning authentication needs or error handling.

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 well-structured with clear sections (purpose, usage guidelines, important notes, parameters, returns) and front-loaded key information. It could be slightly more concise by reducing redundancy in bullet points, but every sentence adds 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 complex creation tool with 13 parameters, 0% schema coverage, no annotations, and no output schema, the description is remarkably complete: it explains purpose, usage, behavior, all parameters, and return format, leaving no significant gaps for the agent to operate effectively.

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?

Given 0% schema description coverage and 13 parameters, the description compensates fully by providing detailed explanations for each parameter in the 'Args' section, adding meaning beyond the schema (e.g., clarifying 'parent_id' establishes hierarchies, 'tags' as comma-separated string).

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 'Creates a new work item in Azure DevOps' with specific examples of what can be created (task, user story, bug) and distinguishes this from sibling tools like 'update_work_item' or 'get_work_item' by focusing on creation rather than modification or retrieval.

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

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

The description explicitly lists four specific use cases in bullet points (e.g., 'Add a new task...', 'Create work items with specific field values...') and includes an 'IMPORTANT' section detailing immediate visibility and notification triggers, providing clear guidance on when to use this tool versus alternatives.

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

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

With no annotations provided, the description carries full burden and does well by explaining access control behavior ('return all teams the user has read access to'), pagination behavior (top/skip parameters), and return format ('formatted as markdown with each team clearly separated'). It doesn't mention rate limits or authentication requirements, but covers key behavioral aspects.

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 well-structured with clear sections (purpose, usage scenarios, parameters, returns) and front-loaded information. The bullet points could be slightly more concise, but overall it's efficient with minimal waste.

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 operation with no annotations and no output schema, the description provides comprehensive context: clear purpose, usage guidelines, parameter explanations, and return format details. It doesn't explicitly mention error conditions or performance characteristics, but covers most essential aspects.

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

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

With 0% schema description coverage, the description fully compensates by explaining all three parameters: 'user_is_member_of' clarifies filtering logic, 'top' specifies maximum return count, and 'skip' explains pagination offset. This adds substantial meaning beyond the bare schema.

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

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

The description clearly states the tool's purpose with specific verb ('Retrieves') and resource ('all teams in the Azure DevOps organization'). It distinguishes this tool from siblings like get_team_members or get_team_iterations by focusing on team listing rather than team-specific details.

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 explicit usage scenarios in bullet points: 'Get an overview of all teams across projects', 'Find team IDs for use in other operations', 'Determine which teams exist', and 'Locate specific teams by name'. This gives clear guidance on when to use this tool versus alternatives.

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

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

No annotations are provided, so the description carries the full burden. It implies a read-only operation ('Gets detailed information'), which is appropriate, but doesn't disclose behavioral traits like authentication requirements, rate limits, error conditions, or response format details. The description adds value by specifying what information is returned but lacks operational context.

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

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

The description is well-structured with a clear purpose statement, bulleted usage guidelines, and separate sections for Args and Returns. Every sentence earns its place by adding specific value without redundancy, and it's front-loaded with the core functionality.

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

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

Given the tool's moderate complexity (single parameter, read operation) and lack of annotations or output schema, the description is fairly complete. It covers purpose, usage, parameters, and return information, but could improve by adding more behavioral details like error handling or response structure to fully compensate for missing structured data.

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 description coverage is 0%, so the description must compensate. It documents the single parameter 'process_id' with a brief explanation ('The ID of the process'), which adds meaning beyond the schema's title 'Process Id'. However, it doesn't provide format examples or constraints, leaving some ambiguity.

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

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

The description clearly states the verb ('Gets detailed information') and resource ('about a specific process'), distinguishing it from siblings like 'list_processes' (which lists processes) and 'get_work_item' (which focuses on work items). It specifies the scope of details including properties, configuration, work item types, and default status.

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

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

The description explicitly provides usage scenarios in a bulleted list: 'View process properties and configuration', 'Get a list of work item types defined in a process', and 'Check if a process is the default for the organization'. This gives clear context for when to use this tool versus alternatives like 'list_processes' or 'get_work_item_types'.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It states this is a 'get' operation (implying read-only), and mentions the return format includes 'name and ID', which adds useful context. However, it doesn't address potential error conditions, authentication requirements, or rate limits that would be helpful for a tool with no annotation coverage.

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

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

The description is well-structured with clear sections: purpose statement, usage guidelines bullet points, Args, and Returns. Every sentence earns its place by providing specific guidance or information without redundancy. The formatting makes it easy to scan and understand.

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

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

For a single-parameter tool with no annotations and no output schema, the description does a good job covering purpose, usage, parameters, and return format. The main gap is the lack of error handling or edge case information, but given the tool's apparent simplicity, the description provides sufficient context for effective use.

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

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

The schema has 0% description coverage, so the description must compensate. It provides the Args section explaining that 'project' accepts 'Project ID or project name', which adds meaningful semantics beyond the bare schema. However, it doesn't provide examples or format specifications for the project parameter.

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

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

The description clearly states the verb 'gets' and the resource 'process ID associated with a project', making the purpose specific and unambiguous. It distinguishes this tool from siblings like 'get_process_details' or 'list_processes' by focusing specifically on the project-process relationship.

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 explicit bullet points for when to use this tool: 'Find out which process a project is using', 'Get the process ID for use in other process-related operations', and 'Verify process information for a project'. This gives clear context and distinguishes it from alternatives like 'get_process_details' which might provide broader process information.

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

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

No annotations are provided, so the description carries the full burden. It discloses that it retrieves 'all projects accessible to the authenticated user', implying authentication needs and scope limitations. It also describes the return format ('formatted as markdown'), adding useful behavioral context beyond basic functionality. However, it doesn't mention rate limits, pagination, or error handling.

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 well-structured with distinct sections (purpose, usage guidelines, args, returns), front-loading key information. Each sentence earns its place by providing specific details without redundancy, and the bullet points enhance readability while maintaining efficiency.

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

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

Given no annotations, 0% schema coverage, and no output schema, the description does an excellent job compensating by explaining parameters, return format, and use cases. It covers the core functionality comprehensively. A slight deduction because it doesn't address potential limitations like authentication errors or large result sets, but overall it's highly complete for this tool's complexity.

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

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

Schema description coverage is 0%, so the description must compensate. It provides clear explanations for both parameters: 'state_filter' is described with examples ('WellFormed', 'Deleting'), and 'top' is explained as 'Maximum number of projects to return'. This adds significant meaning beyond the schema's minimal titles.

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

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

The description clearly states the verb ('Retrieves') and resource ('all projects accessible to the authenticated user in the Azure DevOps organization'), making the purpose specific. It distinguishes from siblings by focusing on project retrieval rather than work items, teams, or processes, which are covered by other 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 explicitly lists four use cases (e.g., 'Get an overview of all available projects', 'Find project IDs for use in other operations'), providing clear guidance on when to use this tool. It implicitly distinguishes from alternatives by not mentioning other project-related tools, but the specific use cases offer practical direction.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively explains what the tool returns (formatted string with default area path, all assigned paths, and sub-area indicators) and provides important context about how area paths function in Azure DevOps. However, it doesn't mention potential errors, authentication requirements, or rate limits.

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 well-structured with clear sections (purpose, usage guidelines, important context, parameters, returns) and every sentence earns its place. It's appropriately sized for a tool with 2 parameters and no annotations, providing comprehensive information without unnecessary verbosity.

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

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

Given the tool's moderate complexity (2 parameters, no annotations, no output schema), the description provides complete coverage. It explains what the tool does, when to use it, the parameters, the return format, and the broader system context. The Returns section effectively substitutes for a missing output schema.

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

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

With 0% schema description coverage, the description fully compensates by clearly documenting both parameters (project_name_or_id and team_name_or_id) in the Args section. It explains what each parameter represents and provides the important detail that they accept either names or IDs, adding significant value beyond the bare schema.

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

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

The description clearly states the specific action ('Retrieves the area paths') and resource ('assigned to a specific team'), distinguishing it from sibling tools like get_all_teams or get_team_members. It provides a precise verb+resource combination that leaves no ambiguity about what the tool does.

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

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

The description explicitly lists four specific use cases (understanding areas of responsibility, checking default assignments, determining classification/routing, setting up configurations) and includes an IMPORTANT section explaining the broader context of area paths in Azure DevOps. This provides clear guidance on when to use this tool versus alternatives.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes what the tool does (retrieves iterations), explains the Azure DevOps context, and specifies the return format (formatted string as markdown). However, it doesn't mention potential limitations like authentication requirements, rate limits, or error conditions.

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 well-structured with clear sections (purpose, usage scenarios, important context, parameters, returns) and every sentence adds value. It's appropriately sized for a tool with 3 parameters and no annotations, with no redundant information.

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

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

For a read operation with 3 parameters and no output schema, the description provides good completeness: clear purpose, usage guidelines, parameter explanations, and return format specification. The main gap is the lack of behavioral details like authentication or error handling, but given the tool's relative simplicity, it's mostly adequate.

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?

With 0% schema description coverage, the description compensates well by explaining all three parameters in the Args section, clarifying their purpose and providing the 'current' parameter's filtering behavior. It adds meaningful context beyond the bare schema, though it doesn't specify format details for project/team identifiers.

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

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

The description clearly states the tool's purpose with a specific verb ('Retrieves') and resource ('iterations (sprints) assigned to a specific team'), distinguishing it from sibling tools like get_all_teams or get_team_members. It explicitly defines what iterations are in Azure DevOps context.

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

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

The description provides explicit usage scenarios in a bulleted list (view sprint schedule, find date ranges, determine active iteration, plan work) and includes an IMPORTANT section explaining the broader context of iterations in Azure DevOps. This gives clear guidance on when to use this tool versus alternatives.

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

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

No annotations are provided, so the description carries full burden. It discloses that the tool retrieves data (implied read-only) and describes the return format (markdown with specific fields), which is helpful. However, it doesn't mention potential limitations like permissions needed, rate limits, pagination behavior beyond top/skip, or error conditions. For a read operation with no annotations, this is adequate but leaves gaps.

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

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

The description is well-structured with clear sections (purpose, usage guidelines, args, returns) and uses bullet points efficiently. It's appropriately sized for a 4-parameter tool, though the usage guidelines could be more concise (e.g., combining points). Every sentence adds value, with no redundant information.

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

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

Given no annotations, no output schema, and 4 parameters with 0% schema coverage, the description does a good job: it explains purpose, usage, parameters, and return format. However, it lacks details on authentication, error handling, or example outputs, which would help an agent use it correctly in complex scenarios. For a read tool, this is mostly complete but not exhaustive.

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

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

Schema description coverage is 0%, so the description must compensate. It provides clear semantics for all four parameters: project_id and team_id as identifiers (with name/GUID clarification), and top/skip for pagination control. This adds significant value beyond the bare schema, though it doesn't detail default values or constraints (e.g., top/skip being optional/nullable).

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

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

The description clearly states the tool's purpose with a specific verb ('Retrieves') and resource ('membership roster for a specific team'), distinguishing it from siblings like get_all_teams (which lists teams rather than members) and get_team_area_paths/get_team_iterations (which focus on other team attributes). The title is null, so the description fully carries this burden.

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

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

The description explicitly provides four bullet points detailing when to use this tool: to see team membership, find administrators, check user assignments, and determine team composition. This gives clear context for selection, though it doesn't explicitly state when not to use it or name alternatives (like querying users directly if available).

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It describes the return format ('formatted string... as markdown') and scope ('comprehensive information... all system and custom fields'), which is helpful. However, it doesn't mention potential limitations like pagination, rate limits, authentication requirements, or error conditions for invalid IDs.

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 well-structured and efficiently organized: purpose statement, usage guidelines bullet points, parameter explanation, and return format description. Every sentence adds value with zero redundant information, and the most important information (purpose and usage) 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 single-parameter read operation with no output schema, the description provides excellent context: clear purpose, usage guidelines, parameter semantics, and return format details. The only minor gap is the lack of behavioral constraints (rate limits, auth needs) which would make it fully complete for a tool with no 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?

The schema has 0% description coverage (no parameter descriptions in schema), so the description must fully compensate. It provides a clear 'Args' section explaining that 'id' can be either a single integer or a list of integers, adding crucial semantic meaning about single vs. batch retrieval that the schema alone doesn't convey.

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

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

The description clearly states the tool's purpose with specific verbs ('retrieves detailed information') and resources ('work items'), distinguishing it from siblings like query_work_items (which likely searches/filters) or get_work_item_comments (which focuses on comments). The opening sentence provides a precise, standalone purpose statement.

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

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

The description explicitly provides four bullet points detailing when to use this tool ('Use this tool when you need to...'), covering specific scenarios like viewing complete details, examining state/properties, handling multiple items, and accessing descriptions/custom fields. This gives clear contextual guidance without needing to reference alternatives.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes the tool's behavior: it retrieves comments, includes author names, timestamps, and content, organizes them chronologically, and returns them as a formatted markdown string. This covers key aspects like output format and organization, though it doesn't mention potential limitations like pagination, rate limits, or authentication needs.

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 well-structured and appropriately sized. It starts with a clear purpose statement, followed by a bulleted list of use cases, then details parameters and returns in labeled sections. Every sentence adds value without redundancy, making it easy to scan and understand.

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

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

Given the tool's moderate complexity (2 parameters, no annotations, no output schema), the description is largely complete. It covers purpose, usage, parameters, and return format. However, it doesn't address potential behavioral aspects like error conditions (e.g., invalid ID), pagination for many comments, or authentication requirements, leaving minor gaps in full context.

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

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

The schema description coverage is 0%, so the description must fully compensate. It provides clear semantics for both parameters: 'id' is described as 'The work item ID', and 'project' is explained as 'Optional project name. If not provided, will be determined from the work item.' This adds essential meaning beyond the bare schema, clarifying the optional nature and default behavior of the 'project' parameter.

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

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

The description clearly states the verb ('retrieves') and resource ('all comments associated with a specific work item'), making the purpose explicit. It distinguishes this tool from siblings like 'add_work_item_comment' (which creates comments) and 'get_work_item' (which retrieves the work item itself, not its comments), providing specific 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 includes a bulleted list of specific use cases (e.g., 'Review discussion history', 'See feedback or notes', 'Check if specific questions have been answered'), giving explicit guidance on when to use this tool. While it doesn't explicitly mention when not to use it or name alternatives, the detailed context scenarios effectively guide appropriate usage.

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

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

No annotations are provided, so the description carries the full burden. It describes the tool as a read operation ('Gets'), which implies it's non-destructive and likely read-only, but doesn't explicitly state permission requirements, rate limits, or error behaviors. The description adds some context about what information is returned, but lacks comprehensive behavioral disclosure for a tool with no annotation coverage.

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

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

The description is well-structured with a clear purpose statement, bulleted usage guidelines, and separate Args/Returns sections. Every sentence earns its place, though the bullet points could be slightly more concise. It's appropriately sized and front-loaded with the core purpose.

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

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

Given no annotations and no output schema, the description does a good job covering purpose, usage, and parameter semantics. It explains what information is returned ('Detailed information... including default field values'), though could benefit from more detail about the return structure. For a read-only tool with 2 parameters, it's reasonably complete but not exhaustive.

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

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

Schema description coverage is 0%, so the description must fully compensate. It provides detailed semantics for both parameters: 'team_context' is explained as a dictionary with specific optional keys and their relationships, and 'template_id' is clearly defined. This adds significant meaning beyond the bare schema, fully documenting parameter purposes and usage.

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

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

The description clearly states the specific action ('Gets detailed information') and resource ('about a specific work item template'), distinguishing it from siblings like 'get_work_item_templates' (plural) which likely lists templates rather than providing details for one. The verb 'Gets' is precise and the scope is well-defined.

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

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

The description explicitly provides three bullet points for when to use this tool ('View default field values', 'Understand what a template pre-populates', 'Get complete details'), offering clear context. While it doesn't explicitly state when not to use it or name alternatives, the specificity of these use cases effectively guides selection among siblings like 'get_work_item_templates' or 'get_work_item_type'.

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

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

No annotations are provided, so the description carries the full burden. It describes the tool as a read operation ('Gets') and mentions filtering and return format, but lacks details on permissions, rate limits, pagination, or error handling. It adds some behavioral context but is incomplete for a tool with nested objects and no output schema.

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

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

The description is well-structured with clear sections (purpose, usage guidelines, args, returns) and uses bullet points efficiently. It's appropriately sized but could be slightly more concise by integrating the purpose into the usage section or trimming redundant phrasing.

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 complexity (2 parameters with nested objects, no output schema, no annotations), the description is partially complete. It covers purpose, usage, and parameters well, but lacks details on behavioral aspects like authentication, errors, or output structure beyond a brief mention, leaving gaps for an AI agent.

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

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

With 0% schema description coverage, the description fully compensates by detailing both parameters: 'team_context' is explained as a dictionary with specific keys and optionality rules, and 'work_item_type' is described as an optional filter. This adds significant meaning beyond the bare schema.

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

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

The description clearly states the tool 'Gets a list of all work item templates for a team' with a specific verb ('Gets') and resource ('work item templates'), and distinguishes it from sibling tools like 'get_work_item_template' (singular) and 'get_work_item_type'. However, it doesn't explicitly differentiate from 'get_work_item_types' or other list-like tools, keeping it from a perfect score.

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 explicit usage scenarios ('Use this tool when you need to') with three bullet points, including finding templates, getting IDs, and filtering by type. It doesn't mention when not to use it or name specific alternatives among siblings, but the context is clear and helpful for guiding 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?

No annotations are provided, so the description carries the full burden. It states this is a read operation ('Gets'), which implies non-destructive behavior, but doesn't mention authentication requirements, rate limits, error conditions, or whether it returns all details in one call. It adds some context about what information is returned, but lacks comprehensive behavioral disclosure.

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

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

The description is well-structured with a clear purpose statement, bulleted usage guidelines, and separate Args/Returns sections. Every sentence adds value without redundancy. It's appropriately sized for a tool with two parameters and no output schema.

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

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

Given the tool's moderate complexity (2 required parameters, no output schema, no annotations), the description is largely complete. It covers purpose, usage, parameters, and return details. However, it lacks information about authentication, errors, or pagination, which could be relevant for API interactions.

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 description coverage is 0%, so the description must compensate. It explains both parameters: 'project' as 'Project ID or project name' and 'type_name' as 'The name of the work item type', adding meaningful context beyond the schema's basic titles. However, it doesn't provide examples or format specifics (e.g., case sensitivity).

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

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

The description clearly states the verb ('Gets') and resource ('detailed information about a specific work item type'), distinguishing it from siblings like 'get_work_item_types' (plural) which likely lists types, and 'get_work_item' which retrieves individual work items rather than type definitions. The purpose is specific and unambiguous.

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

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

The description explicitly lists three use cases: getting complete details, understanding states/transitions, and learning about color/icon. This provides clear guidance on when to use this tool versus alternatives like 'get_work_item_types' (for listing) or 'get_work_item' (for item data).

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions the tool 'gets' information, implying a read-only operation, but does not explicitly state whether it requires authentication, has rate limits, or other behavioral traits. The description adds some context about what information is retrieved (e.g., 'allowed values', 'constraints'), but lacks details on error handling, permissions, or response format. For a tool with no annotations, this is a significant gap.

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

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

The description is well-structured and appropriately sized. It starts with a clear purpose statement, follows with a bulleted list of usage guidelines, then details parameters and returns. Each sentence earns its place by adding value, with no redundant or wasted information. The front-loaded purpose and organized sections make it easy to scan and understand.

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

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

Given the tool's complexity (3 parameters, no output schema, no annotations), the description does a decent job but has gaps. It covers purpose, usage, and parameters well, but lacks details on behavioral aspects (e.g., authentication, errors) and does not fully explain the return value beyond a vague statement. Without an output schema, more specifics on the return structure would be helpful. It's adequate but not complete for a tool with no structured support.

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 description coverage is 0%, so the description must compensate. It provides an 'Args' section that lists and describes all three parameters: 'project: Project ID or project name', 'type_name: The name of the work item type', and 'field_name: The reference name or display name of the field.' This adds clear meaning beyond the schema, explaining what each parameter represents and offering guidance (e.g., 'reference name or display name'), fully compensating for the lack of schema descriptions.

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

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

The description clearly states the tool's purpose: 'Gets detailed information about a specific field in a work item type.' It specifies the verb ('gets') and resource ('field in a work item type'), but does not explicitly differentiate it from sibling tools like 'get_work_item_type_fields' (plural) or 'get_work_item_type', which might retrieve broader information. This makes it clear but lacks 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 explicit usage scenarios in a bulleted list: 'Use this tool when you need to: - Get complete details about a work item field - Check allowed values for a field - Verify if a field is required or read-only.' This gives clear context for when to use the tool. However, it does not mention when not to use it or name alternatives (e.g., using 'get_work_item_type_fields' for multiple fields), 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes the tool's behavior by specifying that it returns a 'formatted table' with details like names, reference names, types, and statuses, which clarifies the output format and data structure. However, it lacks details on error handling, rate limits, or authentication needs, leaving some behavioral aspects uncovered.

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 appropriately sized and front-loaded, starting with the core purpose, followed by usage guidelines, parameters, and returns in a structured format. Every sentence adds value without redundancy, making it efficient and easy to parse for an AI agent.

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

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

For a tool with 2 parameters, no annotations, and no output schema, the description is largely complete, covering purpose, usage, parameters, and return format. However, it could be more comprehensive by including potential errors or constraints, but given the tool's simplicity, it provides sufficient context for effective use.

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?

Given a schema description coverage of 0%, the description compensates fully by adding semantic meaning beyond the schema. It explains that 'project' is a 'Project ID or project name' and 'type_name' is 'The name of the work item type', providing clarity on what these parameters represent and how they should be used, which is essential for correct tool invocation.

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

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

The description clearly states the tool's purpose with a specific verb ('Gets') and resource ('list of all fields for a specific work item type'), distinguishing it from siblings like 'get_work_item_type_field' (singular) and 'get_work_item_types' (types, not fields). It explicitly defines what it retrieves, avoiding vagueness or tautology.

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 explicit usage guidelines with a bulleted list of when to use this tool (e.g., 'See what fields are available', 'Find required fields', 'Get reference names'), clearly differentiating it from alternatives like 'get_work_item_type' or 'get_work_item_template' by focusing on field-level metadata. It gives direct context for application without exclusions.

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

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

No annotations are provided, so the description carries the full burden. It discloses that the tool returns a 'formatted table' with specific columns (names, reference names, descriptions), which adds useful behavioral context beyond the basic 'get list' purpose. However, it doesn't mention potential limitations like pagination, rate limits, or authentication needs, leaving some gaps.

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

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

The description is well-structured and front-loaded with the core purpose, followed by usage guidelines and parameter/return details. Each sentence earns its place by adding value—no wasted words. It's appropriately sized for the tool's complexity.

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

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

Given no annotations, 0% schema coverage, and no output schema, the description does an excellent job of explaining purpose, usage, parameters, and return format. It's nearly complete for a read-only list tool, though it could slightly improve by mentioning any constraints (e.g., project existence, access permissions).

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 description coverage is 0%, so the description must compensate fully. It clearly explains the single parameter 'project' as 'Project ID or project name', adding essential semantics not present in the schema. This fully addresses the parameter meaning and usage.

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

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

The description clearly states the specific action ('Gets a list of all work item types') and resource ('in a project'), distinguishing it from siblings like 'get_work_item_type' (singular) and 'get_work_item_templates'. It explicitly lists what the tool does without being vague or tautological.

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 explicit usage scenarios with bullet points: 'See what work item types are available', 'Get reference names for other operations', and 'Plan work item creation'. It clearly indicates when to use this tool versus alternatives like 'get_work_item_type' (for a single type) or 'create_work_item' (for creation).

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

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

No annotations are provided, so the description carries the full burden. It discloses that the tool returns a formatted table with names, IDs, and descriptions, which is useful behavioral context. However, it doesn't mention potential limitations like pagination, rate limits, or authentication requirements, leaving some gaps for a tool with organizational scope.

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 well-structured with a clear purpose statement followed by bulleted usage guidelines and return format. Every sentence adds value without redundancy, and it's front-loaded with the core functionality. The formatting enhances readability without being verbose.

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

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

Given 0 parameters, no annotations, and no output schema, the description does a good job explaining what the tool does, when to use it, and what it returns. However, for a tool that lists organizational resources, it could benefit from mentioning potential scope or permission considerations to be fully complete.

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

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

The input schema has 0 parameters with 100% coverage, so no parameter documentation is needed. The description appropriately doesn't discuss parameters, focusing instead on usage and output. A baseline of 4 is applied since there are no parameters to document.

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 specific verb 'Lists' and resource 'all available processes in the organization.' It distinguishes from siblings like 'get_process_details' (which retrieves details for a specific process) and 'get_project_process_id' (which focuses on a project's process). The purpose is specific and well-differentiated.

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

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

The description explicitly provides three bullet points detailing when to use this tool: to see available processes, find process IDs for project creation/configuration, and check the default process. This gives clear context for usage without needing to mention alternatives, which is appropriate for a list operation.

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

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

No annotations are provided, so the description carries the full burden. It discloses that the tool returns 'detailed information for each matching work item' as a 'formatted string... as markdown,' which adds behavioral context. However, it lacks details on permissions, rate limits, error handling, or pagination beyond the 'top' parameter, leaving gaps for a search tool.

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

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

The description is well-structured with clear sections (purpose, usage guidelines, important notes, args, returns) and uses bullet points for readability. It is appropriately sized, though the 'IMPORTANT' section could be more concise. Every sentence adds value, such as explaining WIQL syntax and return format.

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

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

Given the tool's complexity (search with WIQL syntax), no annotations, and no output schema, the description does a good job by covering purpose, usage, parameters, and return format. However, it misses some contextual details like authentication requirements, error cases, or how results are ordered, which could enhance completeness for a search tool.

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

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

Schema description coverage is 0%, so the description must compensate. It fully explains both parameters: 'query' as 'The WIQL query string' with an example, and 'top' as 'Maximum number of results to return (default: 30).' This adds essential meaning beyond the bare schema, covering syntax, purpose, and defaults effectively.

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

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

The description clearly states the tool's purpose: 'Searches for work items using Work Item Query Language (WIQL).' It specifies the verb ('searches'), resource ('work items'), and method ('using WIQL'), distinguishing it from siblings like 'get_work_item' (single item retrieval) or 'get_work_item_comments' (comments-focused).

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 explicit usage scenarios in a bulleted list: 'Find work items matching specific criteria,' 'Search across projects for related tasks or bugs,' etc. It also includes an 'IMPORTANT' section detailing when to use WIQL syntax, though it doesn't explicitly contrast with alternatives like 'get_work_item' (for single items) or 'update_work_item' (for modifications).

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

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

With no annotations provided, the description carries full burden and does well: it discloses that changes are immediate, visible to all users, trigger notifications/workflows, and require at least one field update. It could improve by mentioning authentication needs or error handling, but covers key behavioral traits adequately.

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 well-structured with clear sections (purpose, usage guidelines, important notes, parameters, returns). It's appropriately sized but could be slightly more concise by integrating the 'Args' list more seamlessly; however, every sentence adds value, and it's front-loaded with key information.

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

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

Given the complexity (12 parameters, no annotations, no output schema), the description is quite complete: it explains purpose, usage, behavioral impact, all parameters, and return format. It could slightly improve by detailing error cases or authentication, but covers most aspects needed for a mutation tool.

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

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

Schema description coverage is 0%, so the description must compensate fully. It provides detailed semantics for all 12 parameters in the 'Args' section, explaining each parameter's purpose (e.g., 'id: The ID of the work item to update', 'story_points: Optional new story points value'), adding significant value beyond the bare schema.

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

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

The description clearly states the tool 'modifies an existing work item's fields and properties' with specific examples like changing status, reassigning work, and updating descriptions. It distinguishes from siblings like 'create_work_item' (for new items) and 'get_work_item' (for reading).

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

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

The description explicitly provides a bulleted list of when to use this tool (e.g., 'Change the status or state', 'Reassign work'), and distinguishes it from alternatives by specifying it's for modifying existing items (vs. 'create_work_item' for new ones). It also includes an 'IMPORTANT' section with usage constraints.

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