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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, covering the safety profile. The description adds valuable behavioral context: it is a preprocessing step that returns a 'signed URL plan' rather than the file itself, and it requires an existing file_url from specific commands. This goes beyond the annotations, though it doesn't detail the plan's contents or potential 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 two sentences, front-loaded with the primary purpose and followed by a crisp usage guideline. Every sentence earns its place; there is no redundancy or filler.

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

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

The tool is low-complexity (3 params, 1 required) and well-annotated. The description explains the return type (signed URL plan) and the prerequisite (file_url from other commands), which is sufficient for an agent to select and invoke the tool. It lacks a detailed structure of the signed URL plan, but with no output schema and given the simplicity, the description is adequately 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?

Schema description coverage is 100%, so the schema fully documents all three parameters. The description's mention of 'file_url from workitem_get or comment_list' adds contextual meaning that the file_url is opaque and sourced from specific commands, which is also in the schema. Since the schema already does the heavy lifting, the description adds only marginal value, consistent with the baseline of 3.

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 function: 'Preprocess an attachment download and return the signed URL plan.' It uses a specific verb ('preprocess') and resource ('attachment download'), and distinguishes from siblings by explicit focus on download versus upload (attachment_prepare_upload) and by referencing file_url from other commands.

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 explicit when-to-use guidance: 'Use this when you already have a file_url from workitem_get or comment_list and need the backend-generated download plan.' This clearly indicates the prerequisite and the intended alternative scenario, though it does not explicitly name upload as an alternative, the sibling tool name and context make it clear.

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, idempotentHint, and destructiveHint, providing a safety profile. The description adds value by explaining that the tool returns a signed upload plan and is intended for external byte management, without contradicting the 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, front-loaded with the core purpose, and contains no redundant information. Every word 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 appropriately mentions the return type ('signed upload plan' / 'signed upload metadata'). It also explains the workflow context (managing bytes outside CLI). However, it does not elaborate on how the 8 parameters interrelate, though the schema covers individual parameter meaning.

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%, with each of the 8 parameters having a description. The description itself adds no additional parameter-level context, so the baseline of 3 is appropriate; the schema carries the parameter semantics.

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 function: 'Preprocess an attachment upload and return the signed upload plan.' It uses a specific verb ('preprocess') and resource ('attachment upload'), and differentiates from the sibling tool attachment_prepare_download by focusing on upload rather than download.

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 context: 'Use this when a caller wants to manage the upload bytes outside meegle CLI but still needs backend-generated signed upload metadata.' This tells the agent when to use it, though it does not mention when not to use it or name specific alternative tools.

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 provide the safety profile (readOnlyHint, openWorldHint, idempotentHint true, destructiveHint false). The description adds context about checking local CLI state and reusing login, but does not detail return format or other behavioral aspects. This is adequate but not rich.

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

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

The description is two sentences, front-loaded with the main purpose, and contains no superfluous information. Every clause 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 zero-parameter, read-only status tool with no output schema, the description is complete: it explains what the tool does and when to use it, without needing to specify return values or prerequisites.

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

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

The tool has zero parameters, so schema description coverage is trivially 100%. The baseline for no parameters is 4; the description doesn't need to explain parameter semantics.

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: 'Check whether the local meegle CLI is already authenticated.' This is a specific verb and resource, and it distinguishes the tool from the many business/sibling tools by focusing on authentication 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 gives explicit usage guidance: 'Call this first when any business tool unexpectedly fails, or when you need to confirm the server can reuse the user's local login state.' This tells the agent exactly when to invoke it.

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, so the description does not need to restate safety. It adds the workflow hint ('after resolving chart_id from chart_list') which is helpful context, but does not disclose return format, error behavior, or any additional behavioral traits beyond what annotations provide.

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, no fluff. The description is front-loaded with the core purpose and ends with a practical workflow tip. Every word earns its place.

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

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

For a simple get-by-ID tool with one required parameter, the description is adequately complete. It provides the key workflow step and relies on strong annotations. The lack of an output schema is mitigated by the simplicity of the operation and the sibling chart_list reference.

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%: chart_id is described as 'Chart ID' and project_key as 'Optional project key for the chart context.' The description does not add meaning beyond the schema, so the baseline of 3 applies.

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

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

The description states 'Get chart details by chart ID' with a specific verb and resource, clearly distinguishing it from the sibling chart_list tool (list vs. details). It also provides a workflow hint ('Use this after resolving chart_id from chart_list') that reinforces its specific role.

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 advises to use this tool after resolving chart_id from chart_list, offering clear sequencing context. It does not name alternative tools or exclusions, but the workflow hint is sufficient for a simple get-by-ID 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is well covered. The description adds minimal behavioral context beyond the list scope and usage sequence, providing no additional details about pagination, return format, or special behaviors.

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, front-loaded with the core action and followed by a usage hint. Every word earns its place, and it is easy to parse quickly.

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

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

For a simple list operation with good annotations and a schema that covers most parameters, the description adequately covers purpose and usage. It does not describe return values, but no output schema exists and the operation is straightforward, so it is sufficiently 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?

Schema description coverage is 75%, with view_id, page_size, and project_key already described in the schema; only page_num lacks an explicit description. The tool's description does not add parameter-level meaning beyond the schema, leaving the baseline at 3.

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 charts under a view'), clearly indicating the operation and scope. It distinguishes from sibling chart_get (get one chart) and view_search/view_get by focusing on listing charts under a resolved view.

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 states when to use the tool ('after resolving a view_id through view_search or direct user input'), providing clear context. However, it does not mention when not to use it or directly contrast with chart_get, so it falls short of a full 5.

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

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

Beyond the annotations (readOnlyHint=false, destructiveHint=true), the description adds valuable behavioral context: defaulting to dry_run=true for safety, which is not apparent from the schema or annotations. It also clarifies the prerequisite for file_token use. This adds meaningful transparency for the agent.

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

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

The description is concise and front-loaded: the first sentence states the purpose, followed by two short sentences that add essential usage details. Every sentence earns its place with no unnecessary 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 mutation tool with 5 parameters and no output schema, the description covers the key behavioral aspects (dry_run, file_token condition). The schema handles project_key guidance, and annotations cover destructiveness. It is complete enough for the agent to invoke the tool safely, with only minor gaps like explicit return-value expectations.

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?

While the schema already covers all parameters (100% coverage), the description enriches understanding of two key params: file_token (when to use it) and dry_run (default behavior and purpose). This goes beyond the schema definitions and helps the agent use the params correctly.

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 the specific action with a clear verb+resource: 'Add a comment to a work item.' This directly distinguishes the tool from sibling tools like comment_list and workitem_update. No ambiguity about the tool's core function.

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?

Provides clear usage context with instructions for file_token ('only when an attachment was uploaded separately') and the dry_run safety default. However, it does not explicitly mention when to use this tool versus alternatives like comment_list, though the name and description make this fairly obvious.

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 destructiveHint=false, so the safety profile is known. The description adds the time-window filtering behavior but does not disclose pagination or response structure. With annotations covering safety, this is adequate but not rich.

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

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

The description is two sentences, front-loaded, and contains no redundant information. It is highly concise and efficiently conveys the core purpose and primary usage.

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

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

The description is minimal. It does not mention pagination (page_num) or the project_key requirement, and there is no output schema, so the agent may be unsure about return format. Given 5 parameters, this is an incomplete description.

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 80%, so the baseline is 3. The description reiterates the time filter parameters but does not add meaning for page_num or project_key beyond what is already in the schema.

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

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

The description clearly states the tool lists comments on a work item, which is a specific verb+resource action. It is distinguishable from siblings like comment_add and workitem_get, though it does not explicitly name alternatives.

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?

There is no guidance on when to use this tool versus alternatives such as workitem_get or comment_add. The only usage advice is about optional time filters, which is parameter-level guidance, not tool selection 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=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds minimal behavioral context beyond 'latest' (implying versioning) and that it returns a schema. No contradiction with annotations, but no significant additional 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?

A single, clear sentence with no unnecessary words. It is front-loaded with the action and resource, serving its purpose efficiently.

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 tool with one parameter, no output schema, and strong annotations, the description sufficiently states the tool's purpose. It could optionally clarify the return format, but it is not a complex tool.

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

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

Schema description coverage is 100%: the single parameter 'command' is documented with examples ('workitem.create or workflow.transition'). The description does not add meaning beyond the schema, so 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 'Inspect the latest meegle CLI command schema' uses a specific verb ('Inspect') and resource ('meegle CLI command schema') with scope ('latest'). It clearly distinguishes from sibling tools like 'meegle_command' (which likely executes) and other command-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?

No guidance is provided on when to use this tool versus alternatives. It doesn't mention that it complements 'meegle_command' (e.g., to check schemas before executing) or any exclusions. The usage context is entirely 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?

Annotations already indicate destructiveHint=true and readOnlyHint=false, so the safety profile is known. The description adds a useful detail: "Uses spawn without a shell," which clarifies that arguments are passed directly without shell interpolation. However, it does not elaborate on potential side effects or output behavior, so it does not significantly exceed what annotations already convey.

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, front-loaded with the primary purpose and followed by a key technical implementation detail. Every word adds value, and there is no redundancy or filler.

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

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

The tool is structurally simple with only one parameter, well covered by the schema and annotations. However, given the open-ended nature of a raw command execution, the description lacks context about what the command returns (e.g., raw stdout/stderr), and it does not caution about the broad destructive potential despite the destructiveHint annotation. It is minimally complete but leaves gaps for an agent to anticipate behavior.

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

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

The schema already provides a clear description of the only parameter `args` with an example: "Argument vector after the meegle binary, for example [\"project\",\"search\"]." The tool description merely repeats "argv array" without adding new meaning. Since schema coverage is 100%, the baseline of 3 is appropriate.

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

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

The description clearly states the tool's purpose: "Run a raw meegle CLI command as an argv array." This uses a specific verb (run) and resource (meegle CLI command), and the mention of "raw" and "argv array" distinguishes it from sibling tools that provide specific high-level operations like workitem_get or project_search.

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 the many specific sibling tools. It does not mention that this is a fallback for unsupported commands, nor does it warn against using it when a higher-level tool exists. The phrase "raw" implies lower-level access, but no explicit when/when-not guidance is provided.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is well covered. The description adds context about the tool's scope ('current user's' personal queue) and the distinction from project-wide queries, which is useful behavioral context beyond the annotations. It does not contradict any 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?

The description is two sentences long, front-loaded with the purpose, and every word earns its place. It is concise yet informative, with no redundant filler.

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

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

For a simple list tool with good annotations and a clear scope, the description is nearly complete. It covers the core action, audience, and usage context. The only minor gap is that it does not explicitly mention pagination behavior or return structure, but these are not critical for a straightforward read-only list 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?

The input schema already documents the 'action' enum and 'asset_key' description, giving 67% coverage. The description reinforces the notion of 'to-dos or completed items' which aligns with the 'action' parameter but adds no new details for 'page_num' or 'asset_key.' Since schema coverage is moderate and the description does not meaningfully compensate for the undocumented 'page_num,' a baseline score of 3 is appropriate.

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

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

The description clearly states the tool's function: 'List the current user's Meegle to-dos or completed items.' It uses a specific verb ('List') and identifies the resource ('current user's Meegle to-dos or completed items'), and it distinguishes itself from sibling tools by noting 'instead of project-wide query logic.'

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 tells when to use this tool: 'Use this for personal work queues' and contrasts it with 'project-wide query logic.' This provides clear guidance and implies a sibling alternative, making the usage context unambiguous.

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, covering safety. The description adds workflow context beyond annotations by explaining its role as the primary entry tool and the need to resolve project context. It doesn't mention the 'list recently visited' behavior (present in schema) but the annotations lower the burden.

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, front-loaded with the verb and resource, and every phrase earns its place. It is concise and well-structured, with 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 simple search tool with strong annotations and a schema that documents project_key, the description provides adequate context: what it searches, when to use it, and what to do with the result. The absence of pagination details is offset by the schema's page_num defaults and the tool's low 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?

The schema covers project_key with a detailed description, and the tool description largely repeats it. page_num is not mentioned in the description at all, and with 50% schema coverage the description does not compensate for the missing parameter semantics. It adds limited 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 clearly identifies the tool as 'Search Meegle projects' with a specific verb and resource, and enumerates concrete search criteria (keyword, project key, simple name, exact project name). It distinguishes itself from sibling search tools like view_search and user_search by focusing on projects, and positions itself as the primary entry point.

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 explicitly states when to use this tool: 'call it first when project context is missing, ambiguous, or expressed only as a human name' and provides the follow-up action of passing the resolved project_key into later project-scoped tools. This gives clear guidance and excludes use when context is already resolved.

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, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds a dependency on relation_meta_definitions but does not elaborate on response format or error behavior, so with annotations lowering the bar, a score of 3 is appropriate.

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 short sentences, front-loaded with the primary action and no redundant phrasing. It efficiently conveys the core purpose and a key prerequisite.

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 list tool with no output schema, the description provides the essential prerequisite and relies on the schema for parameter details. It could mention pagination or response structure, but the schema includes page_num/page_size with defaults, making it reasonably 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?

Schema coverage is 86%, so most parameters are documented. The description reinforces the roles of relation_id and relation_field_key by directing to relation_meta_definitions, but it does not add significant semantic detail beyond what the schema already 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 clearly states the tool lists work items linked by a relation field, which is a specific verb+resource combination. It distinguishes itself from siblings like workitem_query or workitem_get by focusing on relation-based linking.

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 instructs to call relation_meta_definitions first when relation_id or relation_field_key is unknown, providing a clear prerequisite. It does not explicitly exclude alternatives, but the context is sufficient for an agent to know 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, openWorldHint, idempotentHint, and no destructive action, covering the safety profile. The description adds only the purpose of discovering relation IDs or field keys, which is more about usage than behavior. 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, front-loaded with the action, and contains no redundant information. Every word earns its place.

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

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

For a simple list operation, the description combined with strong annotations and full schema coverage is nearly complete. It does not detail output format or pagination, but that is not critical given the tool's simplicity. The mention of discovering IDs and keys hints at the return value's utility.

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 100% parameter description coverage, with each of the three parameters clearly described. The tool description adds no extra parameter semantics beyond what the schema already provides, so the baseline score of 3 applies.

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

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

The description clearly states the tool's purpose with a specific verb and resource: 'List relation definitions in a project.' It also distinguishes from the sibling relation_list by explaining this tool discovers relation IDs and field keys, which clarifies its niche.

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 instructs when to use this tool: 'Use this before relation_list when you need to discover relation IDs or relation field keys.' This provides clear usage context and differentiates it from the alternative, though it does not explicitly state when not to use it.

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 mark the tool as destructive and not read-only, so the description's main addition is the dry_run=true default, which tempers the destructive expectation by indicating that real execution requires explicitly setting dry_run=false. This is valuable safety-relevant behavior beyond the annotations. 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?

Two sentences: the first leads with the core purpose, and the second gives a prerequisite and safety default. No filler, every clause contributes. Excellent front-loading.

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 (11 params, four actions, no output schema), the description provides the most critical context: the prerequisite workflow_get_node call and the dry_run safety default. It doesn't explain action-specific requirements like task_id for confirm/rollback, but the schema covers those. A bit more guidance on action semantics would elevate it, but it's sufficient for an agent with schema visibility.

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

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

The schema covers all 11 parameters with descriptions, so the baseline is 3. The description's only param-related note is about node_id ('Use workflow_get_node first when node_id...unknown'), which adds a usage hint but not new semantics beyond the schema's 'Template node ID that owns the subtask.' Thus minimal added value.

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 operates on subtasks with four specific actions (create/update/confirm/rollback), distinguishing it from sibling tools like workitem_update which target work items. The resource and verbs are explicit, so the agent knows exactly what this 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 directs calling workflow_get_node first when node_id or existing subtask context is unknown, providing a concrete when-to-use prerequisite. It also notes the dry_run default, implying a safe way to explore the tool without side effects. However, it doesn't explicitly state when not to use this tool vs other tools like workitem_update.

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 as readOnly, idempotent, openWorld, and non-destructive, so the description does not need to repeat these. It adds some behavioral context (project scope and a sequencing hint) but does not disclose pagination behavior or return format. With strong annotations, this is acceptable but not highly revealing.

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 short sentences, with the core action front-loaded. Every word earns its place, providing clear purpose and a usage hint without 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?

For a simple list tool with three optional parameters and rich annotations, the description covers the main purpose and adds a critical usage hint. It does not explicitly explain return format, but 'List teams' implies a list. Overall, it is sufficiently complete for the 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 100%, with each of the three parameters having a descriptive description. The tool description does not add any additional parameter semantics beyond what the schema already documents, so the baseline 3 applies.

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

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

The description clearly states the action: 'List teams in a project' with a specific resource and scope. It also differentiates from the sibling tool team_list_members by mentioning it should be used before it when only a team name is known, establishing a distinct purpose.

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

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

The description provides explicit usage guidance: 'Use this before team_list_members when only a team name is known.' This identifies an alternative tool and a specific condition for using this one. The parameter schema also adds guidance for project_key, though that is outside the description.

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, idempotentHint, and destructiveHint=false, so the safety profile is fully covered. The description adds only a workflow hint (team_list) rather than behavioral traits like pagination, ordering, or error handling. With strong annotations, the description provides minimal additional behavioral context, so 3 is appropriate.

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 extremely concise, with two sentences that front-load the main purpose and then supply the key prerequisite. No filler or wasted words; 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 list tool with no output schema, the description is sufficient given the rich annotated schema. It does not explicitly mention pagination or the query filter, but these are covered by parameter descriptions. The main omission is not stating what the response contains, but this is reasonable for a simple list operation.

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

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

Schema coverage is 100%, providing full descriptions for all four parameters. However, the description adds meaningful context by stating that team_id is 'returned by team_list', linking the parameter to its source. This extra semantic beyond the schema justifies a score above the baseline of 3.

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 'List members of a team by team ID' with a specific verb and resource, and it distinguishes itself from the sibling tool team_list by focusing on members rather than teams. It also includes a direct reference to team_list for resolving team IDs, which removes 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 description explicitly instructs the agent to 'Call team_list first when you need to resolve the team_id from a team name', providing a clear prerequisite and workflow for correct usage. This is direct, actionable guidance that differentiates this tool from the alternative of using team_list alone.

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 readOnly, openWorld, and idempotent behavior. The description adds a small amount of context about canonicalization and use with write tools, but does not disclose edge-case behavior such as what happens when identifiers cannot be resolved or whether partial results are returned. With the safety profile covered by annotations, a 3 is appropriate.

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. It immediately states the core action and purpose, with zero wasted words or redundancy with the 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?

For a simple resolution tool with rich annotations and a fully described schema, the description covers the essential purpose and usage context. However, with no output schema, the description does not explicitly state the return format or behavior for unresolved identifiers, which is a minor gap in completeness.

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

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

The input schema has 100% parameter coverage with clear descriptions for all three parameters. The tool description itself adds no additional parameter semantics beyond what the schema already provides, so the baseline of 3 applies.

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

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

The description uses a specific verb 'resolve' against a clear resource (names/emails/aliases into canonical user_key values). It immediately distinguishes itself from sibling tools like user_search by focusing on canonical key resolution for write tools, not general user search.

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 'so write tools can safely fill user fields and role assignments' clearly implies when to use this tool: before write operations needing user keys. It provides useful context without explicitly naming alternatives, but the purpose inherently points to the right usage scenario.

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 destructiveHint=false, so the safety profile is covered. The description adds that the tool 'resolves' identifiers, implying a lookup/transformation behavior, and clarifies accepted input types. It does not disclose return format or pagination, but given the strong annotation coverage, the description provides adequate additional 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 two sentences long, front-loads the core purpose, and uses the second sentence to direct to an alternative tool. Every word earns its place, with no fluff 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?

The tool has 3 parameters and no output schema, and annotations cover safety. The description explains the primary parameter and gives an alternative, but it omits any mention of the return value behavior or the roles of 'project_key' and 'need_all_status'. For an agent to correctly invoke this tool, it would need additional info about these parameters, making the description 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 0%, so the description must compensate. It clarifies the meaning of 'user_keys' by listing accepted identifier types (user_key, email, or display name). However, it does not explain the other two parameters, 'project_key' and 'need_all_status', leaving the agent without guidance on their semantics. This is a significant gap given the low 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 uses the specific verb 'Resolve' and clearly identifies the resource ('user identifiers into Meegle user records'), stating the exact input types (user_key, email, or display name). It also distinguishes itself from the sibling tool user_resolve_keys, which is explicitly mentioned, so the purpose is clear and 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 provides a clear use case: resolving user identifiers into records. It also gives an explicit alternative ('For normalized mapping output, use user_resolve_keys'), which helps the agent choose between this tool and a sibling. However, it does not specify when not to use this tool beyond that alternative, nor does it mention other contexts like searching vs. resolving.

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 destructiveHint=false, covering the safety profile. The description adds no behavioral details such as pagination behavior, sorting, or return format. With annotations present, a baseline of 3 is appropriate.

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, front-loaded with the main purpose and immediately providing a useful usage hint. Every word earns its place with no 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-only listing tool with 100% schema coverage and safety annotations, the description is complete enough. It tells the agent what the tool does and how to approach it when only the view name is known. Missing pagination/sorting details are already in the schema.

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

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

Schema description coverage is 100%, so the schema documents all four parameters. The description only reinforces that the view is identified by ID, adding no meaningful semantics 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 clearly states the tool's function: 'List work items under a view by view ID.' This is a specific verb and resource that distinguishes it from sibling tools like view_search (which searches for views) and workitem_get (which fetches a single work item).

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

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

The description provides an explicit alternative: 'Use view_search first when you only know the view name.' This gives clear context for when to use this tool versus another, though it doesn't cover other possible alternatives like workitem_query.

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, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is fully covered. The description adds the 'resolve view IDs' purpose, which gives insight into the return value, but doesn't describe additional behavioral traits such as result format or limits. This is similar to the get_calls calibration example, where annotations handle safety and the description adds modest 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 exceptionally concise—two sentences, with the action front-loaded and no wasted words. Every piece of information ('search by title,' 'resolve IDs,' 'use before view_get/chart_list') is directly useful to the 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 simple, read-only search tool with 3 parameters and no output schema, the description covers the core purpose and usage context. It lacks explicit return format details, but 'resolve view IDs' gives a clear hint, and the schema fills in parameter behavior. The usage guidance makes it reasonably complete for an agent to invoke correctly.

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

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

Schema description coverage is 100%, providing clear descriptions for all three parameters (key_word, view_scope, project_key) including examples and usage tips. The description text adds no additional parameter semantics beyond what the schema already provides, so the baseline of 3 applies.

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

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

The description clearly states a specific verb ('Search') and resource ('views by title') with the purpose of resolving view IDs. It also distinguishes this tool from siblings by explicitly recommending it before view_get or chart_list when only a view name is known.

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?

Explicit usage guidance is provided: 'Use this before view_get or chart_list when the user only knows a view name.' This tells the agent exactly when to use this tool and for what purpose, effectively differentiating it from alternatives. The project_key schema description also adds practical guidance for multi-project scenarios.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds minimal extra behavioral context beyond the use-case hint, but does not describe return format, pagination, or default behavior. Since annotations handle the core safety disclosure, a score of 3 is appropriate.

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, first states purpose, second gives usage timing. Every word earns its place; no redundancy or fluff. Perfectly structured and 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 tool with 6 parameters and no output schema, the description gives enough context for selection: it names the purpose and the specific scenario where it is needed. However, it does not explain the return value or configurable options (like subtask inclusion or field filtering), but the schema covers those. Slight gap in return-value information prevents a 5.

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 83%, so the schema already documents most parameters. The description mentions 'node IDs or node-specific fields' which aligns with node_id_list and field_key_list, but adds no new details beyond what the schema provides. Baseline 3 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?

The description uses a specific verb 'Get' with a clear resource 'workflow node details' and scope 'for a work item'. It also distinguishes itself from sibling tools by explicitly mentioning workflow_transition and subtask_update in the usage context, making it clear this is a prerequisite read operation.

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?

Provides explicit when-to-use guidance: 'Use this before workflow_transition or subtask_update when node IDs or node-specific fields are unknown.' This tells the agent exactly when to invoke this tool and identifies relevant alternatives, fulfilling the dimension fully.

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 state readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds no extra behavioral context, such as whether transitions depend on user permissions or project state, or what 'available' means. It merely restates the title without enriching the agent's understanding.

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 sentence that is front-loaded and free of any filler. It earns its place by stating the core function directly. No unnecessary words or repetition.

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 required parameters and no output schema, yet the description omits any detail about parameter usage or return structure. It gives no indication of what 'state transitions' implies, how to specify the work item, or what the response will contain. The description is too sparse to be complete for a tool with this 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%, and the description provides no explanation of the four parameters (user_key, project_key, work_item_id, work_item_type). The agent is left without any semantic understanding of what parameters to supply, making the tool nearly unusable for correct 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 uses a specific verb and resource: 'List available state transitions for a work item.' It clearly identifies what the tool does and the object it operates on. However, it does not differentiate from sibling tools like workflow_transition_state or workflow_smart_transition, though the basic purpose is 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 provides no guidance on when to use this tool versus alternatives. For example, it doesn't say 'Use this to preview transitions before executing one' or direct users to workflow_transition for performing a transition. No context, exclusions, or alternatives are mentioned.

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 annotations already indicate destructive and non-read-only behavior, and the description adds the probing logic (checking workflow_get_node first, then falling back to list-state-transitions). This provides helpful behavioral context beyond the structured annotations, such as the order of operations in auto mode.

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, front-loaded with the core purpose and followed by a concise explanation of the auto-detection mechanism. Every word earns its place with no fluff 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?

While the core mechanism is explained, the description omits return value expectations, failure handling, and the practical implication of the dry_run default. Given the tool's complexity (13 parameters, destructive, no output schema), a bit more context about what 'execute' produces and when it is safe to run would help, though the schema partially covers safety via the dry_run parameter.

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 provides 100% coverage with descriptions for all 13 parameters, so the description adds little beyond what is already structured. It does re-emphasize the 'mode' behavior that is also documented in the enum description, but does not add new parameter-level semantics.

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: automatically detecting the workflow type (node-driven vs status-driven) and executing the appropriate transition. It distinguishes itself from siblings like workflow_transition and workflow_transition_state by emphasizing the auto-detection and fallback mechanism.

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 explicit context on when to use this tool: when the workflow type is unknown and auto-detection is needed. It names the underlying commands (workflow_get_node, list-state-transitions) that it probes, which implies when they might be used directly, though it does not explicitly state when to prefer 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?

The description adds important behavioral context beyond the annotations by stating 'Defaults to dry-run for safety.' This discloses a safety mechanism not captured by destructiveHint or openWorldHint, helping the agent understand that the tool does not make changes by default. It does not contradict the annotations, and while it does not fully enumerate all side effects, the dry-run default is a significant 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 extremely concise, using a single sentence with no filler words. It front-loads the purpose and includes a key safety note. However, its brevity verges on under-specification, leaving out critical details; still, as far as conciseness alone, it is efficient and well-structured.

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 (7 parameters, destructive nature, open-world hint, no output schema), the description is insufficiently complete. It does not explain what a 'workflow node' is, how transition differs from rollback, nor what outputs or errors to expect. The one-sentence description leaves significant gaps that the schema and annotations only partially fill, making it unlikely an agent could invoke this tool correctly without additional 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?

Schema description coverage is 0%, so the description must compensate for parameter details, but it does not. The only parameter-related hint is 'Transition or rollback,' which vaguely suggests the 'action' parameter but does not explain node_id, node_ids, project_key, rollback_reason, or dry_run semantics. The description lacks the depth needed to compensate for the schema's minimal documentation.

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 and resource: 'Transition or rollback a workflow node.' This conveys the core action without excessive ambiguity. However, it does not explicitly distinguish this from sibling tools like workflow_transition_state or workflow_smart_transition, which likely perform similar operations; the focus on 'node' provides some differentiation but not a clear contrast.

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 offers no guidance on when to use this tool versus alternatives. There is no mention of prerequisites, typical scenarios, or exclusions. The only hint is 'Defaults to dry-run for safety,' which implies a cautious approach but does not clarify use cases or contrast with sibling tools.

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 indicate destructiveHint=true and readOnlyHint=false. The description adds valuable behavioral context by stating the default is a dry-run, meaning the tool does not mutate by default. However, it does not disclose what happens when dry_run is false or the likely side effects of a real transition.

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 extremely concise: two short sentences, front-loaded with the core verb and resource, followed by an important safety note. No unnecessary words.

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

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

For a destructive, potentially mutating operation with four parameters and no output schema, this description is too sparse. It lacks context about real transition behavior, return values, error handling, and how to use the tool correctly beyond the dry-run default. The wide set of sibling workflow tools increases the need for clearer contextual guidance.

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% description coverage for its 4 parameters, and the description fails to compensate. It references 'dry-run' generically but does not explain work_item_id, transition_id, project_key, or the exact meaning/effect of the dry_run parameter beyond its default.

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

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

The description clearly identifies the action ('Transition') and the resource ('state-flow status'), making the basic purpose understandable. However, it does not distinguish this tool from closely related siblings like workflow_transition or workflow_smart_transition.

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 mentions 'Defaults to dry-run for safety,' which implies a safe-use context, but it gives no explicit guidance on when to choose this tool over alternatives or what prerequisites are needed. There is no discussion of when a real (non-dry-run) transition 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 this as read-only, idempotent, and non-destructive. The description adds valuable constraints (20-user limit, 3-month max span) and clarifies the canonical user_key requirement, going beyond annotation details.

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 extremely concise with two sentences, front-loading the main purpose and adding a useful tip. Every word earns its place, with no 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?

For a list operation with robust schema descriptions and annotations, the description covers essential limits and input preparation. It does not describe the exact output format, but that is largely inherent for such a tool and not strictly necessary.

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 already describes all parameters, so baseline is 3. The description adds extra meaning by noting the 3-month span limit and recommending user_resolve_keys for parameter preparation, which enhances schema information.

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 function with a specific verb ('List') and resource ('schedule and workload details'), while also specifying scope ('up to 20 users within a 3-month span'). This distinguishes it from sibling tools focused on workitems or views.

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

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

The description provides clear context on when to use the tool (listing schedules/workload for users) and offers practical prerequisite guidance (use user_resolve_keys first). However, it does not explicitly mention alternatives or exclusions, which keeps it from 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=true, idempotentHint=true, and destructiveHint=false. The description adds the 'one request fan-out' behavioral trait, which is useful context beyond the annotations and clarifies that this is a batch operation. No contradictions.

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, front-loaded with the core purpose, and contains no fluff. Every word 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 batch read tool with good annotations and fully described parameters, the description is largely complete. It clearly communicates the use case and basic behavior. However, it does not mention potential partial-failure behavior or default field returns, which could be relevant for a batch operation with up to 200 IDs, but this is a minor gap.

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% (all parameters have descriptions in the schema), so the baseline is 3. The description does not add any extra parameter semantics beyond what the schema already provides; it only mentions work_item_ids by name without additional detail.

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 a specific verb ('Get') and resource ('multiple work items by ID'), and differentiates from siblings like workitem_get by emphasizing batch/fan-out behavior. It is unambiguous and action-oriented.

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 says when to use the tool ('when you already have a set of work_item_ids and need multiple detail reads'), which is clear context. However, it does not explicitly mention when not to use it or name alternative tools (e.g., workitem_get for a single item), so it misses the full 'when-not/alternatives' bar.

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?

Discloses that complex array/object values are automatically JSON-stringified and that dry_run defaults to true for safety. These go beyond the annotations (which already indicate destructive potential) and add useful behavioral context for safe execution.

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, each earning its place: purpose, prerequisite guidance, and safety default. No redundancy or 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?

Given the tool's complexity (7 params, no output schema) and the richness of the input schema, the description covers the essential usage steps and safety behavior. It doesn't discuss return values or error cases, but the schema and annotations mitigate the gap, making it adequately 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 schema already provides detailed descriptions for all parameters (100% coverage), including the JSON-stringification behavior for field_value. The description adds little beyond the schema except the reference to workitem_meta_fields for field_key discovery, which is a minor addition.

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 explicitly states 'Create a work item in Meegle' with a specific verb and resource. It clearly differentiates from sibling tools like workitem_get, workitem_update, and workitem_query by focusing on creation.

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?

Provides clear context by directing users to use workitem_meta_fields for valid field_key discovery and mentions the dry_run default as a safety measure. However, it does not explicitly name alternatives or exclusion scenarios, so it misses the top 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, openWorldHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds useful behavior context by specifying the return format (backend keys and display labels) and the sampling nature. It does not contradict 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, front-loaded with the action and outcome. Every word earns its place; there is no repetition or filler. It is concise while still covering purpose and usage.

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 tool with 3 parameters and no output schema, the description fully explains what the tool does, what it returns, and when to use it. The annotations and schema provide additional safety and parameter details, making the overall package complete for an agent to select and invoke the 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?

The input schema provides 100% coverage with descriptions for all three parameters, including defaults and constraints for sample_limit. The description only indirectly references work_item_type and project_key, adding no new parameter semantics beyond what the schema already defines, so a baseline score of 3 is appropriate.

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

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

The description clearly states a specific action ('sample actual status values') on a specific resource ('work item type') and names the outputs ('backend keys and display labels'). It also distinguishes itself from the sibling workitem_query by framing this as a pre-filter discovery step, making its 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 gives explicit when-to-use guidance: 'Use this before filtering workitem_query by status.' It also instructs the model not to guess generic constants like OPEN or IN_PROGRESS, which effectively identifies the alternative (guessing) and why this tool is better. This is clear context with a direct reference to a sibling 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 cover readOnly/openWorld/idempotent, so the description's added value is moderate. It mentions 'Defaults to the configured test project,' which is useful context, but it fails to clarify how the tool receives an 'ID or name' given the input schema is empty.

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 and every clause adds value: the operation, the usage guidance, and the default project. No fluff 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?

The description conveys the single-item scope, the recommended workflow, and the default project, which is substantial for a simple read tool. However, the empty input schema and missing return-format info leave some ambiguity about how the ID is provided and what exactly is returned.

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 zero parameters in the schema, the baseline is 4. The description adds the concept of 'by ID or name,' providing some semantic meaning about how the target is selected, though it is not formally mapped to a 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?

Description uses a specific verb and resource: 'Get a single work item by ID or name.' It clearly distinguishes from workitem_query (list) and workitem_batch_get (multiple) by emphasizing 'single' and 'detail reads'.

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?

Provides explicit usage context: 'Use this for detail reads after resolving a work_item_id from workitem_query or workitem_batch_get.' Names the alternative tools and defines the sequencing, making it clear when to use this 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 establish read-only, idempotent, and non-destructive behavior. The description adds functional context by explaining that the tool reveals valid field keys, types, and options, which is useful beyond the annotation's safety profile. It does not conflict 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 a single, focused sentence that is front-loaded with the core action and purpose. Every word is informative, with 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 a 5-parameter tool and no output schema, the description explains the tool's role and expected findings ('valid field_key values, field types, and options'). It does not cover pagination or filtering behavior in prose, but the schema covers parameters, and the description is sufficient 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 high (80%), with meaningful descriptions for most parameters. The tool description itself adds no parameter-specific detail, but the schema already carries the semantic weight. 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 uses the specific verb 'List' and identifies the resource as 'field configuration for a work item type in a project'. It clearly distinguishes itself from siblings by stating its role in discovering valid field_key values before create/update operations.

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

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

The description explicitly states when to use the tool ('Use this before workitem_create or workitem_update'), providing clear usage context. However, it does not mention when not to use it or name alternative tools for discovery (e.g., workitem_meta_types), so it falls short of full exclusion guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds useful context about defaulting to the configured test project, which affects behavior when project_key is omitted. 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?

Two sentences, concise and front-loaded with the purpose. Every sentence adds value: the first states what it does, the second gives usage context and default behavior. 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 simple list tool with no output schema and strong annotations, the description is complete. It covers purpose, usage timing, and the default project behavior, which is sufficient for an agent to select and invoke the 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 coverage is 100% and the schema itself provides detailed guidance on the project_key parameter, including when to pass it explicitly and how to resolve it. The description does not add additional parameter semantics 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 clearly states the tool lists available work item types in a project, using specific verb 'List' and resource 'work item types'. It distinguishes itself from sibling tools like workitem_meta_fields by focusing on types specifically.

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

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

Explicitly states when to use: 'before querying, creating, or filtering work items when the type key is unknown'. Also warns about defaulting to the configured test project, which is useful guidance.

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

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

Annotations already declare read-only, idempotent, open-world, and non-destructive behavior. The description adds useful context about MQL syntax requirements and label pitfalls, which helps the agent avoid common errors. It does not contradict annotations and adds value by flagging that generic constants like OPEN or IN_PROGRESS should not be assumed.

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, front-loaded with the action, and contains no superfluous text. Every sentence contributes meaningful guidance: the first states purpose and scope, the second warns about MQL completeness and label usage.

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 has 5 parameters, rich schema descriptions, and no output schema, the description covers the core purpose and key usage pitfalls. It does not explain pagination or session_id, but those are documented thoroughly in the schema. Overall, the description is complete enough for an agent to invoke the tool correctly when combined with the schema.

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

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

Schema description coverage is 100%, so the schema already documents every parameter, including mql's requirement to be a complete query string with label guidance. The tool description reinforces the MQL completeness rule but adds little beyond what the schema already provides, just slight emphasis on 'not just filters or fragments.'

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 runs an MQL query against a project for listing or searching work items, using a specific verb and resource. It distinguishes itself from siblings like workitem_get (fetch a single item) or workitem_create/update by focusing on query-based listing/searching.

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 says 'Use this for listing or searching work items across a project,' which conveys the primary use case. It also provides important guidance on forming a complete MQL string and using project display labels, but does not explicitly name alternative tools or give exclusion criteria.

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 indicate destructiveHint=true and readOnlyHint=false, so the agent knows this is a mutating operation. The description adds useful behavioral context: defaults to dry_run=true for safety and auto-stringification of arrays/objects for CLI compatibility. These are non-obvious behaviors not fully captured by annotations. 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?

Three focused sentences, each delivering value: purpose, key prerequisite guidance, and safety behavior. No redundant words or filler, and it is front-loaded with the main action.

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 and 5 parameters, the description covers purpose, prerequisite metadata lookup, and default safety behavior. It does not mention return values or potential impacts beyond 'update', but annotations plus the dry_run hint mitigate the need. Overall, it is adequately complete for safe 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 100%, and the schema already provides clear descriptions for all parameters, including the field_value auto-stringification note and dry_run semantics. The description does not add material new parameter information beyond what the schema already contains. 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 clear verb and resource: 'Update work item fields or role operations.' This distinguishes it from sibling tools like workitem_get (read), workitem_create (create), and workitem_query (search), while also specifying the two main operations it supports.

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 guidance: 'Use workitem_meta_fields or role metadata first when field keys or role keys are unknown.' This tells the agent to first resolve metadata before calling this tool, which is valuable usage context. It also mentions the dry_run default for safety, implying a safe preview approach.

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