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

Annotations already mark this as destructive, and the description adds meaningful behavioral context by explaining the consequence (next API call will re-acquire tokens). It does not detail the scope of what is cleared (e.g., all accounts, current tenant) or potential side effects like forced re-login, but for a zero-parameter utility the transparency is solid.

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, front-loaded sentence with no filler. It states the action, the target, and the outcome without wasting words.

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

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

For a simple, parameterless, destructive-but-explained utility, the description plus annotations provide enough information for an agent to select and invoke it correctly. The absence of an output schema is not a significant gap for this kind of action.

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 and 100% schema coverage, the description doesn't need to explain any parameters. It fully conveys the operation's purpose, so the baseline for 0-parameter tools 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 ('Clear') and a clear resource ('cached authentication tokens'), stating exactly what the tool does. It also distinguishes itself from sibling auth tools (get current account, list accounts, switch tenant) by targeting a different operation entirely.

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 'to force re-acquisition on next API call' implicitly provides the primary use case: invalidate stale or unwanted cached tokens. It does not explicitly mention alternatives or when not to use it, but no sibling offers a comparable token-clearing behavior, so the guidance is clear enough.

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, and the description adds meaningful behavioral detail beyond that: it decodes the Fabric JWT and surfaces identity, tenant, and token expiry. This tells the agent it is a local inspection operation with no write side effects, which is consistent with 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 a single front-loaded sentence that names the action, the resource, and the returned information without filler. Every part 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 zero-parameter, read-only introspection tool, the description is complete: it states what the tool returns (identity, tenant, token expiry), how it obtains that (decoding the JWT), and the annotations cover the safety profile. No output schema is present, so describing the shown fields directly is sufficient.

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 the schema fully covers the input side. Per the baseline for zero-parameter tools, the description does not need to add parameter detail, and it correctly avoids inventing any.

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 ('Show') and a clear resource: the current Azure identity, tenant, and token expiry. The 'current' qualifier distinguishes it from sibling tools like auth_list_available_accounts, and the mechanism ('decoding the Fabric JWT') makes it an obvious introspection call.

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

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

The description implies when to use it — whenever current Azure identity/tenant/token expiry is needed — but offers no explicit guidance about alternatives such as auth_list_available_accounts, auth_switch_tenant, or auth_clear_token_cache. Given the sibling set, a sentence clarifying what this tool is not for would strengthen 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 state readOnlyHint=true and destructiveHint=false, so the safe-read nature is known. The description adds valuable context about reading local CLI state only, not making live Entra ID queries, and not listing other users — which clarifies side effects and data source beyond 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?

Two sentences, no filler. The main action and scope are in the first sentence, and the important scoping boundary ('local CLI state only') is upfront in the second. Every phrase earns its place.

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

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

For a zero-parameter, read-only list tool with annotations covering safety, the description is complete: it tells the agent what is listed, under what condition, and what it does not do. No output schema is needed for invocation, and the description covers the key selection criteria.

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

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

The tool has zero parameters and 100% schema description coverage, so there is nothing for the description to add about parameter semantics. The baseline of 4 applies for parameterless tools, and the description's reference to 'az login' clarifies the underlying prerequisite context.

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

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

The description opens with a specific verb (List) and resource (Azure subscriptions and tenants), and further scopes it to accounts the local user logged into via 'az login'. It also distinguishes itself from other auth tools by noting it reads local CLI state only and does not query Entra ID or list other users.

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: use this tool to enumerate locally authenticated Azure subscriptions and tenants. It states a when-not ('does not query Entra ID or list other users'), implicitly indicating this is not for live directory queries or user enumeration, but it does not name an alternative sibling tool explicitly such as auth_get_current_account.

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

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

The description goes beyond the annotations by disclosing that switching acquires a new token to verify access and rolls back on failure. This is useful side-effect and failure semantics. It stops short of mentioning broader impact on cached tokens or subsequent tool calls, but the rollback detail is meaningful.

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 tightly written sentences with no filler. The main operation is front-loaded, and the behavioral detail is placed directly after it, making the definition easy to scan and parse.

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

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

For a single-parameter tool with no output schema, the description is largely complete: it states the action, the verification behavior, and rollback safety. A minor gap is that it does not describe what the caller should expect on success or how the switch affects future sibling tool calls, but the low complexity and clear schema reduce the risk.

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 tenantId parameter is already documented as 'The Azure AD tenant ID (GUID) to switch to.' The description does not need to add parameter-level details and does not provide any 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 names a specific verb and resource: 'Switch to a different Azure tenant.' It also adds unique behavioral detail (acquiring a new token and rolling back on failure) that clearly distinguishes this from the sibling auth tools like auth_get_current_account and auth_clear_token_cache.

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 'Switch to a different Azure tenant' provides clear context for when the tool applies: when the current tenant must be changed. It does not explicitly list alternatives or exclusions, but no sibling tool performs this same tenant-switching function, so the implied usage is straightforward.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=true, so the safety profile is clear. The description adds that it targets a 'running' copy job, which is useful, but it does not disclose whether cancellation is graceful or forceful, whether it affects only the specified jobInstanceId, or what happens if the job is already finished. With annotations covering the destructive nature, 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 short sentence with no wasted words. It is front-loaded and clearly states the action. It could add a conditional phrase like 'if the run is still in progress', but as-is it is concise and direct.

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 cancel operation with no output schema, the description is minimally viable: it names the action and the required scoping identifiers exist in the schema. However, it omits behavioral details such as whether the cancellation is asynchronous, how to check completion afterward, or any error conditions. Given the destructiveHint annotation, extra context about safety and next steps would improve completeness.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters (workspaceId, copyJobId, jobInstanceId). The description adds no additional parameter-specific meaning beyond identifying the operation as cancelling a run; the schema's field descriptions are sufficient.

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 'Cancel a running copy job' clearly states the verb (cancel) and resource (copy job run), and the name copy_job_cancel_run makes the intent explicit. It is distinguishable from copy_job_run and copy_job_get_run_status among siblings, though it does not explicitly contrast with them.

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

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

The description implies usage when a copy job run is running and needs to be cancelled, but it does not state when NOT to use it or mention alternatives such as copy_job_get_run_status for checking status first. The sibling naming pattern provides context, but the description itself lacks explicit routing 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 convey that this operation is not read-only and not destructive. The description adds no further behavioral detail such as side effects, required permissions, idempotency, or what happens on success. There is no contradiction with 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 entire description is one short, front-loaded sentence with no filler or redundancy. It efficiently communicates the core operation without wasting 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?

With no output schema, the description does not mention what the API returns after creation, such as a copy job ID or full job object. It also omits any indication of follow-up operations or prerequisites beyond the schema, leaving the agent with an incomplete picture for invoking and using the result.

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 workspaceId, displayName, and description adequately. The tool description does not add any extra parameter meaning, which keeps this at the baseline score 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 action ('Create'), the resource ('a new copy job'), and the scope ('in a workspace'). This distinguishes it from sibling tools like copy_job_update, copy_job_delete, and copy_job_list by indicating it creates rather than modifies, deletes, or 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?

No explicit guidance is provided about when to choose this tool over alternatives such as copy_job_update or copy_job_create_definition. The word 'new' implies creation of a non-existent job, but no exclusions or routing cues are given.

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 declare destructiveHint=true and readOnlyHint=false, and the description adds no behavioral context beyond restating the delete operation. It does not mention irreversibility, cascading effects, whether running jobs are affected, or any required permissions.

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

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

The description is a single, focused sentence with no wasted words. It immediately conveys the operation and is appropriately sized for a simple delete tool.

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

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

For a simple two-parameter delete operation with full schema coverage and destructive annotations, the description is minimally adequate. However, it does not describe what the return value or success/failure behavior looks like, and there is no output schema to fill that 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%, so the input schema already fully documents both required parameters (workspaceId and copyJobId). The description adds no additional parameter semantics, but the schema carries the burden effectively, yielding the baseline score.

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 ('Delete') and resource ('a copy job'), making the operation unambiguous. It is easily distinguished from the many sibling tools that operate on other resource types and from non-delete copy_job 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?

No guidance is provided about when to use this tool versus alternatives such as copy_job_cancel_run or copy_job_update. The description states only what it does, not the context or conditions for choosing 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?

The annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds little behavioral context beyond the operation name, and it does not mention return format, error behavior, or any other runtime traits.

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

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

The description is a single clear sentence with no filler. It is appropriately front-loaded and conveys the essential operation in the fewest necessary words.

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

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

For a simple read operation with fully documented parameters and safe annotations, the description is minimally adequate. However, with no output schema, the return content is unspecified, and the ambiguity against copy_job_get_definition leaves a 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?

Schema description coverage is 100%: both copyJobId and workspaceId are described in the schema. The description adds no additional parameter meaning beyond 'specific', 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 states a clear verb ('Get') and resource ('details of a specific copy job'), and the singular 'specific' distinguishes it from list operations like copy_job_list. However, it does not differentiate from the sibling copy_job_get_definition, since 'details' and 'definition' overlap.

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 copy_job_list or copy_job_get_definition. The context signals and sibling list imply usage, but the description itself provides no explicit selection criteria or exclusions.

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

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

The annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds that the operation is long-running and writes definition files to a specified directory. This is useful beyond the annotations because it reveals latency and a side effect. No contradiction exists between the read-only annotation and writing output files.

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 no filler. 'Get the definition of a copy job' is front-loaded, and the second sentence gives the key behavioral detail about writing files. Each 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?

The description explains the destination of files and notes the operation is long-running, but with no output schema it does not say what the call returns or how an agent knows when the definition files are ready. Given the 'long-running' qualifier, some completion or response detail would make it more 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 documents all three parameters with 100% coverage, so the description does not need to add much. It does reinforce that outputDirectoryPath is where definition files will be written, but it adds no new parameter-level meaning beyond the schema.

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

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

The description clearly states the verb and resource: get the definition of a copy job. It also distinguishes itself from siblings like copy_job_get by noting it writes definition files to an output directory, and from copy_job_update_definition by being a get operation. The 'long-running' parenthetical adds useful operational context.

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

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

The description implies usage when someone needs the definition files of a copy job, but it does not explicitly say when to prefer this over copy_job_get or compare against related get_definition tools. It gives no exclusions or alternative routing guidance. The 'long-running' note is a mild usage caution but not enough to fully guide selection.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, which covers the safety profile. The description adds no further behavioral detail beyond the obvious read-only status lookup, so it is consistent but not enriching.

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

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

The description is a single compact sentence with no filler or redundant wording. It is front-loaded with the action and resource, making it appropriately sized for a simple status lookup tool.

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 three-parameter read-only status tool, the description combined with the fully documented schema is nearly complete. The only minor absence is a note about polling behavior or status values, but the annotations and unambiguous name make this a small 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%, with workspaceId, copyJobId, and jobInstanceId each described. The tool description itself adds no additional parameter semantics, so the schema is doing the heavy lifting and the baseline 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 a specific verb ('Get') and resource ('status of a copy job run'), which clearly distinguishes it from sibling tools like copy_job_get, copy_job_list_runs, and copy_job_run. An agent can tell what this tool does at a glance.

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

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

The description implies usage after a copy job run has been started, especially because the schema notes that jobInstanceId comes from copy_job_run, but it does not explicitly state when to use this tool versus alternatives like copy_job_list_runs. Usage is inferable but not directly guided.

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. The description adds that the tool returns all copy jobs in a workspace, which is useful, but it does not disclose pagination behavior, ordering, or the shape of the returned list.

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

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

A single sentence with no filler. The action, resource, and scope are all front-loaded, making it easy for an agent 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 one-parameter read-only list tool, the description and schema are sufficient for correct invocation. The lack of an output schema or explicit pagination note is a minor gap, but 'List all copy jobs' conveys the expected behavior clearly enough.

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 workspaceId with 100% coverage, so the description does not need to add much. It only loosely repeats the workspace scope and provides no additional format or semantic detail beyond the schema.

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

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

The description uses a specific verb ('List'), a specific resource ('copy jobs'), and a clear scope ('in a workspace'). It clearly distinguishes this from siblings like copy_job_get, copy_job_run, and copy_job_list_runs.

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

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

The description implies the enumeration use case but does not explicitly state when to use this tool over alternatives. It does not mention copy_job_get for single-job details or copy_job_list_runs for run history, leaving selection partly to the tool name.

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 the 'all run instances' scope but does not disclose pagination, ordering, or returned fields, which remains a gap for a list operation.

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

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

A single focused sentence with no filler or redundancy. It front-loads the verb and resource, earning every word.

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 low-complexity, two-parameter read-only tool, the description plus schema and annotations is sufficient for an agent to invoke it correctly. The only notable omission is return-value details, but no output schema exists to make that a hard requirement.

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 descriptions for workspaceId and copyJobId. The tool description adds no further parameter semantics, 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 states a specific verb ('List') and resource ('run instances for a copy job'), making the core operation clear. It does not explicitly distinguish this from sibling tools like copy_job_get_run_status or copy_job_list, though 'run instances' helps narrow the meaning.

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 intended use is implied by 'List all run instances for a copy job' – an agent can infer when to call it. However, it offers no explicit guidance about when to prefer copy_job_get_run_status for a single run or copy_job_list for the jobs themselves.

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 indicate this is not read-only, but the description adds no behavioral context. It doesn't disclose whether the tool blocks until completion, returns a run ID asynchronously, or requires the copy job to be in a certain state before running. Without an output schema, the agent is left guessing about the operation's behavior.

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

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

The description is extremely concise and front-loaded, with no wasted words. It earns a 4 for efficiency, though the brevity contributes to the lack of behavioral and usage context noted in other dimensions.

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 an action-oriented tool with no output schema, the description is too sparse. An agent cannot tell whether the tool returns a run ID, whether it should be followed by a status poll, or how long the run might take. Sibling tools like copy_job_get_run_status suggest this is a multi-step workflow, but the description doesn't explain that.

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 both copyJobId and workspaceId are already documented in the schema. The description adds no additional meaning about how these parameters interact or what values are expected.

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 'Run a copy job on demand' states a specific verb (Run), a resource (copy job), and a qualifier (on demand), making the tool's core purpose clear. It doesn't explicitly distinguish from sibling tools like copy_job_get_run_status or copy_job_cancel_run, but the action of triggering a run is distinct enough.

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 no guidance on when to use this tool versus alternatives. It doesn't mention that this is for ad-hoc execution while scheduled runs might be managed elsewhere, nor does it point to copy_job_get_run_status for monitoring the resulting run.

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 this is a non-read-only, non-destructive operation, and the description's 'Update' aligns with that. However, the description adds no additional behavioral context such as partial-update semantics, permission requirements, or what happens when only one field is provided. It is adequate but not enriching.

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 wastes no words. It front-loads the action, resource, and the specific fields involved, making it efficient and easy to parse.

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 update tool with 100% schema coverage, no output schema, and annotations covering the mutation safety profile, the description is largely complete. The only notable gap is the absence of guidance distinguishing this from copy_job_update_definition, but the overall clarity of the operation compensates for that.

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 all parameters are already documented in the schema. The description's reference to 'name or description' aligns with the displayName and description parameters, but it does not add meaningful detail beyond what the schema already provides. 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 uses a specific verb ('Update') and resource ('copy job') and narrows the scope to 'name or description', which clearly distinguishes it from sibling tools like copy_job_update_definition. It is immediately obvious what this tool does and what it does not do.

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

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

The description implies when to use the tool - when a copy job's name or description needs updating - but it does not explicitly state alternatives or exclusions. It does not mention that structural changes should go to copy_job_update_definition, leaving the selection guidance to inference from the tool name and sibling list.

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 'long-running' parenthetical adds a useful behavioral signal beyond the annotations, indicating the operation may not complete synchronously. However, it does not explain how to check completion, whether the update replaces the entire definition, or what the caller should expect after triggering it.

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 compact and front-loaded: it states the operation and the long-running warning first, then the two input modes. Every clause earns its place 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 mutation tool with no output schema, the description covers purpose, long-running behavior, and input modes. But it omits what the operation returns and how a caller should monitor or confirm the definition update, which is a meaningful gap for an asynchronous 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 description coverage is 100%, so parameter names and types are already documented. The description adds value by framing the choice between 'parts' and 'partsDirectoryPath' as inline content versus a directory path, which clarifies how the two modes relate.

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 ('Update a copy job's definition') and the resource being acted on, and it adds input-mode detail (inline parts or directory path). It is distinguishable from siblings like copy_job_get_definition and copy_job_update, though it does not explicitly name or contrast them.

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 no guidance on when to use this tool versus alternatives such as copy_job_update or copy_job_get_definition. The inline-versus-directory distinction is an input-mode choice, not a decision between tools, so usage context must be inferred entirely from the tool name.

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

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

Annotations already indicate a non-read-only, non-destructive operation; the description adds little beyond 'new' and 'workspace'. It does not disclose potential side effects, permission requirements, idempotency behavior, or what happens on duplicate names.

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?

Single sentence, clear, and front-loaded with the key scoping information. There is no filler or redundant explanation.

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

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

For a simple create tool with three flat parameters and no nested objects, the description plus schema is sufficient to invoke it correctly. The lack of an output schema or explicit return-value information is a minor gap but not critical for selecting or calling the tool.

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

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

Schema description coverage is 100%, so workspaceId, displayName, and description are all already documented in the schema. The description does not add parameter-level meaning, but it does not need to because the schema handles it.

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

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

States a specific action ('Create'), a specific resource ('Dataflow Gen2 item'), and the target location ('in a workspace'). This clearly distinguishes it from sibling tools like dataflow_get, dataflow_update, and dataflow_delete.

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 'Create a new...' implies the tool should be used when creating a Dataflow, not when reading, updating, or deleting one. However, it does not explicitly mention alternatives or provide exclusion conditions, leaving usage partly to inference.

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

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

The description simply restates the delete action and adds no behavioral context beyond what the annotations already declare. It does not disclose that deletion is likely permanent, that it cannot be undone, or that it may impact dependent artifacts. The annotations carry the destructiveHint, but the description itself contributes no additional transparency.

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

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

The description is a single, focused sentence with no filler or redundant information. It is front-loaded with the core action and resource, making it easy for an agent 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 two-parameter delete operation, the description together with the destructiveHint annotation and fully covered schema is mostly complete. The main missing context is whether the deletion is permanent or whether there are prerequisites like ensuring the dataflow is not in use, but these are relatively minor gaps for this 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 covers 100% of parameters, each with a basic description ('The dataflow ID', 'The workspace ID'), so the schema is doing the heavy lifting. The tool description adds no additional meaning about how the IDs are used, their format, or any constraints 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 states a specific verb ('Delete') and resource ('Dataflow Gen2 item'), which clearly distinguishes it from sibling tools like dataflow_list, dataflow_get, dataflow_create, and dataflow_update. The name and description align, leaving no ambiguity about what the tool does.

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

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

The description implies the tool should be used when a Dataflow Gen2 item needs to be deleted, so an agent can infer the basic use case. However, it offers no explicit guidance about when not to use it, no prerequisites, and no mention of the destructive nature or confirmation steps before invoking.

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 agent knows this is a safe read operation. The description adds no further behavioral context such as return characteristics or errors, but it does not contradict the annotations and remains adequate for a simple getter.

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

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

The description is a single concise sentence with no filler. It front-loads the core action and resource while remaining immediately scannable.

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

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

For a simple two-parameter read-only get, the description is mostly sufficient, especially with full schema coverage. However, there is no output schema and the description does not clarify what 'details' include or how this differs from dataflow_get_definition, leaving some ambiguity for an agent navigating a large sibling set.

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 self-explanatory parameters 'dataflowId' and 'workspaceId'. The description does not add meaning beyond the schema, so the baseline score of 3 is appropriate.

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

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

The description uses a specific verb and resource: 'Get details of a specific Dataflow Gen2 item.' It distinguishes itself from sibling tools like dataflow_list by emphasizing 'specific' and from dataflow_get_definition by using 'details' rather than 'definition.'

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 word 'specific' implies this is for fetching a single known item, and the required IDs support that inference. However, there is no explicit guidance about when to prefer this over dataflow_list or dataflow_get_definition, or about prerequisites such as knowing the workspace and dataflow IDs beforehand.

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 meaningful behavioral context beyond the readOnlyHint and destructiveHint annotations by stating that the operation is 'long-running' and that it writes definition files to a specified output directory. It does not fully describe file-overwrite behavior or how completion is surfaced, but it does disclose the key side effect and latency trait.

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

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

Two short sentences convey the action, target resource, latency characteristic, and side effect with no wasted words. The most decision-relevant detail ('long-running') is front-loaded, and the file-writing behavior is stated immediately.

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

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

For a read-only export-style operation with full schema coverage, the description is mostly adequate, but it leaves gaps around what 'long-running' means operationally (e.g., whether the agent must poll or wait) and what the tool returns or how success is indicated. There is no output schema, so the description carries more responsibility for explaining the result, and it does not fully do so.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters with clear meanings. The description only reinforces the outputDirectoryPath purpose and adds no deeper per-parameter semantics such as expected path format, directory creation behavior, or file naming conventions.

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 ('Get the definition') and the resource ('Dataflow Gen2 item'), and adds the concrete side effect of writing definition files to an output directory. It is distinguishable from sibling tools like dataflow_get because it targets definition export rather than item metadata, though it does not explicitly name an alternative.

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 no explicit guidance on when to use this tool versus alternatives such as dataflow_get, dataflow_update, or other get_definition tools. Usage is only implied by the verb 'Get the definition'; there are no stated prerequisites, exclusions, or conditions that would help an agent route to this tool confidently.

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 readOnlyHint=true and destructiveHint=false, and the description adds no behavioral detail beyond restating that it gets status. No information about response shape, status values, or polling behavior is disclosed.

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

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

The description is a single, front-loaded sentence with no filler. Every word contributes to the core purpose.

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

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

For a low-complexity read-only getter with fully documented required parameters, the description is minimally viable. However, with no output schema and no mention of the relationship to dataflow_refresh in the description, an agent is missing useful context about the expected return value and the workflow position.

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 parameters are already documented. The description itself adds no parameter-level meaning, but the schema covers this adequately, so 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 states a clear verb ('Get') and a specific resource ('the status of a dataflow refresh job'). It is immediately distinct from siblings like dataflow_refresh, which initiates a refresh, and dataflow_get, which retrieves dataflow metadata.

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 usage guidance is provided. The description does not mention that this tool should be used after dataflow_refresh, how polling might work, or when an alternative like dataflow_get would be more 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=true and destructiveHint=false, so the safety profile is covered by structured data. The description adds modest behavioral context by stating 'all' (no filtering) and 'Gen2' (item-type scope), but it discloses no further traits such as pagination, ordering, response shape, or failure behavior. There is no contradiction with 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?

One eight-word sentence that front-loads the verb and resource, with zero filler or repetition. Every word contributes meaning, and there is no extraneous context.

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 one-parameter list operation with annotations covering the safety profile, the description is nearly complete: it names the operation, resource type, and target workspace. Since there is no output schema, the return format is not stated, but for a list operation the result is self-evident, making this a minor omission rather than a functional 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% — the single required parameter workspaceId is already documented as 'The workspace ID' in the schema. The description adds no additional parameter semantics, so the baseline of 3 applies per the rubric.

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

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

The description uses a specific verb ('List'), names the exact resource ('Dataflow Gen2 items'), and scopes it ('in a workspace'). The 'Gen2' qualifier removes ambiguity about item type and cleanly distinguishes it from sibling tools like dataflow_get, dataflow_create, and dataflow_delete, as well as from other *_list tools targeting different resource types.

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 intended use is inferable — call this to enumerate all Dataflow Gen2 items in a workspace — but the description provides no explicit guidance on when to prefer it over alternatives such as dataflow_get or other *_list siblings. No exclusions, fallback conditions, or alternative-routing hints are stated; the pattern of sibling list tools implies the usage rather than spelling it out.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the description is not responsible for the basic safety profile. It adds that the target is a Dataflow Gen2 item and that the action is a 'trigger', which implies an asynchronous operation, but it does not explicitly disclose returns, side effects, or follow-up status checking.

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

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

The description is a single, front-loaded sentence with no wasted words. It immediately conveys the verb and resource, making it easy for an agent to parse quickly.

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

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

The schema fully covers the two required parameters and the action is simple, but with no output schema, the description leaves the return behavior and asynchronous nature of the refresh unstated. The sibling dataflow_get_refresh_status hints at follow-up, but the description itself does not provide that 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?

Input schema coverage is 100%, and both parameters already have clear descriptions. The tool description adds no additional parameter-level meaning, so the baseline score of 3 is appropriate.

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

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

The description states a specific verb ('Trigger'), a clear resource ('a Dataflow Gen2 item'), and the action ('refresh'). This distinguishes it from related siblings like dataflow_get_refresh_status and dataflow_delete, and from semantic_model_refresh, which targets a different resource type.

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 no guidance on when to use this tool versus alternatives, no mention that the refresh is asynchronous, and no indication that status should be tracked via dataflow_get_refresh_status. It only states the action without context for invocation sequencing.

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 this is a non-read-only, non-destructive mutation. The description confirms the mutation scope (name or description) but adds no deeper behavioral context such as partial-update semantics, permission needs, or whether an update with neither field supplied is a no-op. 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 a single front-loaded sentence with no filler. It efficiently communicates the action, target resource, and affected fields.

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 metadata-update tool with full schema coverage and annotations covering the safety profile, the description is largely sufficient. It omits minor details like return behavior and the expectation of at least one optional field, but an agent can likely make a correct call with the available information.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters. The description only echoes 'name or description' and does not add meaning beyond the schema, such as clarifying that at least one optional field should be provided for a meaningful update.

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

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

The description states a specific verb ('Update'), a specific resource ('Dataflow Gen2 item'), and the exact scope ('name or description'). This clearly distinguishes the tool from siblings like dataflow_create, dataflow_delete, dataflow_refresh, and dataflow_get.

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 no explicit when-to-use guidance, no alternatives, and no prerequisites or exclusions. The intended usage must be inferred from the verb and resource, but no additional context helps an agent decide between this and related dataflow 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?

The description merely restates the core mutation without disclosing behavioral details such as whether an existing workspace assignment is replaced, whether stages must be empty before assignment, or any pipeline state constraints. Annotations already convey that it is a non-read-only, non-destructive operation, so the description adds little beyond them.

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, front-loaded sentence with no wasted words. It conveys the action, object, and target in the most compact useful form.

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 three-parameter mutation, the basics are present: the action is stated and the schema fully documents parameters and required fields. However, the description omits any usage context or exclusions, so an agent gets no help with edge cases like existing assignments or relationship to adjacent pipeline operations.

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 each parameter already has a clear description, so the tool description need not repeat them. It adds no extra meaning, but none is required given the complete schema.

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

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

The description uses a specific verb ('Assign') and states the resource and target ('a workspace to a deployment pipeline stage'), which clearly distinguishes it from the sibling unassign_workspace and deploy operations. It is immediately actionable.

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 given about when to use this tool instead of alternatives; for instance, it does not mention that unassign_workspace removes an assignment or that deploy is needed to push changes. Choosing this over siblings is left to tool-name inference.

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

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

Annotations already indicate readOnlyHint=false and destructiveHint=false, so the tool is known to mutate without being destructive. The description adds only that a new pipeline is created, which largely restates the tool name. It does not disclose what creation entails, what is returned, or any side effects beyond existence of the resource.

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

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

The description is a single, compact sentence with no filler. It is appropriately short for a simple CRUD tool, though it could have included one or two extra clauses about usage context without becoming verbose.

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

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

This is a simple two-parameter create operation with a fully documented schema and no output schema. The description is minimally sufficient for an agent to understand that it creates a deployment pipeline, but it omits any mention of follow-up steps, return behavior, or distinguishing context among the many deployment_pipeline_* siblings.

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 input schema fully documents both parameters: displayName and description. The description adds no parameter-level information, but none is needed because 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 a specific verb and resource: 'Create a new deployment pipeline.' It is clear this is a creation operation, which semantically distinguishes it from sibling operations like update, delete, get, and deploy. However, it does not explicitly name or contrast any sibling, so it stops short of a top score.

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

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

No guidance is provided about when to use this tool versus alternatives such as deployment_pipeline_update, deployment_pipeline_deploy, or deployment_pipeline_get. The create verb implies usage, but there are no conditions, prerequisites, or exclusions stated.

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

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

The annotations already mark this as destructive (destructiveHint=true, readOnlyHint=false), and the description merely restates the delete action without adding behavioral context. It does not disclose irreversibility, cascading effects on stages or workspaces, or any authorization requirements.

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

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

The description is a single, front-loaded sentence with no filler words or redundancy. It is appropriately concise, though it sacrifices potentially useful context in favor of brevity.

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 one-parameter destructive tool, the schema and annotations cover the essential invocation details. However, the description omits clarification about deletion effects, return behavior, and how it differs from the similar-sounding pipeline_delete, leaving moderate gaps.

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

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

The schema has 100% description coverage for the only parameter, pipelineId, documented as 'The deployment pipeline ID'. The description adds no parameter-level meaning 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 states a specific verb ('Delete') and a specific resource type ('deployment pipeline'), which clearly conveys the operation and distinguishes it from sibling tools like pipeline_delete. However, it does not elaborate beyond the action and resource named in the tool itself.

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 such as pipeline_delete or deployment_pipeline_deploy. It neither states selection criteria nor mentions exclusions, leaving the agent to infer context from the tool name alone.

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

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

The description adds the useful behavioral note that the operation is 'long-running', which is not captured by the annotations. However, it does not disclose what the call returns, whether it triggers an asynchronous operation, or what side effects deployment has on target stage items, leaving the agent to infer these aspects.

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

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

A single sentence with no filler, and the most important behavioral qualifier ('long-running') is included parenthetically. Every part of the description 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 an asynchronous mutation-style tool with no output schema, the description is minimal. It mentions long-running behavior but does not reference how to monitor the operation or what the return value represents, which is important context given the sibling tool deployment_pipeline_get_operation exists.

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

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

Schema description coverage is 100%, so the schema already documents all parameters and the description is not required to repeat them. The phrase 'from one stage to another' does add conceptual linkage between sourceStageId and targetStageId, but it does not add deeper 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?

States a specific action ('Deploy'), the resource ('deployment pipeline'), and the operation's scope ('items from one stage to another'). This clearly distinguishes it from reading, creating, or deleting deployment pipeline resources, including the closely named deployment_pipeline_get_operation and deployment_pipeline_list_stages.

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 about when to use this tool versus alternatives, such as checking operation status with deployment_pipeline_get_operation or listing pipeline stages first. The context is implied by the name, but there are no explicit when-to-use or when-not-to-use instructions.

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 no behavioral detail beyond the readOnlyHint/destructiveHint annotations; it simply restates the get operation. It doesn't disclose response contents, error behavior, or any side effects, though the annotations already establish safety.

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, front-loaded sentence with no filler. It conveys the operation and resource in as few words as possible.

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 one-parameter read tool with safety annotations, the description is minimally viable. However, it doesn't clarify what 'details' means, what the response contains (no output schema exists), or how this differs from deployment_pipeline_get_operation, leaving some gaps.

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 pipelineId already described as 'The deployment pipeline ID'. The description adds no additional parameter meaning, so the baseline of 3 applies given the schema fully documents the 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 states a specific verb ('Get') and resource ('details of a specific deployment pipeline'), which clearly indicates a read operation on one pipeline. It doesn't explicitly name sibling tools like deployment_pipeline_get_operation or deployment_pipeline_list, but the 'specific' wording and resource distinction are sufficient to differentiate at a basic level.

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 about when to use this tool versus alternatives. The description does not mention deployment_pipeline_list for enumerating pipelines, deployment_pipeline_get_operation for operation details, or any condition that selects this tool over those siblings.

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 minimal behavioral context by clarifying that it returns details for a specific operation, but it does not describe what the details contain, such as status, progress, or timestamps, especially since there is no output schema.

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

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

The description is a single, direct sentence with no filler or repetition. It is appropriately sized for a simple getter, though it could have been slightly more informative by naming the sibling list operation.

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 operation with fully documented required parameters, the description is adequate. However, with no output schema, it does not clarify what operation details are returned or how this operation relates to deployment_pipeline_list_operations, leaving some ambiguity for the agent.

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

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

Schema description coverage is 100%, and both pipelineId and operationId have clear descriptions. The tool description does not add further parameter-level meaning beyond the schema, which is acceptable given the high schema coverage.

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

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

The description states a clear verb ('Get') and resource ('details of a specific deployment pipeline operation'), so an agent can tell this fetches one operation rather than a list. It is concise and matches the tool name without being a pure tautology, though it does not explicitly contrast with similar sibling 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?

There is no guidance about when to use this tool instead of deployment_pipeline_list_operations for enumerating operations or deployment_pipeline_get for pipeline-level details. The intended use is implied by the required IDs, but no explicit context, exclusions, or alternative routing 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?

The annotations already establish readOnlyHint=true and destructiveHint=false, so the description's job is lighter. It adds the useful behavioral scoping 'accessible to the user' but does not disclose pagination, ordering, or response shape; this is minor for a parameterless list, so 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?

One sentence, eight words, with the action, resource, and scope all front-loaded. There is no filler or redundant restatement of the tool name.

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 listing tool, the definition is nearly complete: an agent knows what will be listed and that the operation is safe. The only missing piece is a description of returned fields, but the verb 'List' plus no output schema still leaves enough for 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?

There are no parameters and schema coverage is 100%, so there is no parameter burden for the description to carry. The baseline for zero-parameter tools is 4, and the description does not attempt to over-explain what does not exist.

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

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

The description names the exact verb ('List') and resource ('deployment pipelines'), with the scoping qualifier 'accessible to the user', which separates it from a detail retrieval sibling like deployment_pipeline_get. This makes the tool's purpose unambiguous.

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

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

The description gives a clear enumeration context but does not explicitly state when to choose it over deployment_pipeline_get or the stage/item list siblings. The sibling naming pattern implies the usage, so guidance is present only by inference.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description aligns with those. It adds the 'deployment history' context, but does not disclose ordering, pagination, or the shape of the returned operation list.

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 with no filler. It front-loads the action and resource, and every word contributes to understanding the tool's purpose.

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

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

For a simple read-only list tool with one required parameter and no output schema, the description is sufficiently complete. It communicates what the tool returns conceptually, though additional detail about the operation list contents would improve it.

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 describes pipelineId as 'The deployment pipeline ID' and coverage is 100%. The description adds no further parameter-level detail, so it meets the baseline but does not go 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 identifies the action (list operations), the resource (deployment pipeline), and scopes the result as deployment history. It is distinguishable from the sibling deployment_pipeline_get_operation by the list vs. get contrast, though it does not explicitly name the alternative.

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 'deployment history' implies when this tool should be used, but the description provides no explicit guidance about alternatives or exclusions. An agent must infer from sibling names that get_operation is for individual operations.

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 the 'all items' scope, but does not disclose other behavioral traits such as pagination, ordering, required permissions, or return value shape. It is adequate but minimal.

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, focused sentence that states the action and resource with no wasted words. The core information is front-loaded, making it easy to scan.

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

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

For a simple read-only list operation with fully documented parameters and safety annotations, the description is complete enough for an agent to select and invoke the tool correctly. No output schema exists, but the expected result is straightforward for a 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 description coverage is 100%, and both stageId and pipelineId have clear descriptions. The tool description does not add meaning beyond the schema, which is acceptable since the schema already documents the parameters fully.

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

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

The description states a specific verb ('List'), a clear resource ('all items in a specific deployment pipeline stage'), and the required scope (pipeline and stage). It distinguishes itself from sibling tools like deployment_pipeline_list_stages, which lists stages rather than items within a stage.

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 does not provide any guidance on when to use this tool versus alternatives, nor does it mention exclusions or sibling tools that might be more appropriate for related tasks. Usage must be inferred entirely from the name and resource 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?

The annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile, but the description adds no behavioral context beyond the name — nothing about what 'all stages' includes, pagination, ordering, or error behavior for an unknown pipelineId. It does not contradict 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?

A single front-loaded sentence with no filler, appropriately sized for a one-parameter read-only tool. It is efficient, though it edges toward under-specification by restating the tool name almost verbatim.

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 1-param read-only list, the core call contract (pipelineId → stages) is conveyed and annotations cover the safety profile. However, with no output schema, the return shape of a stage is entirely unspecified, and no disambiguation from deployment_pipeline_list_stage_items is offered, leaving modest gaps.

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% since pipelineId is documented as 'The deployment pipeline ID', so the baseline of 3 applies. The description only loosely ties to the parameter by mentioning 'a deployment pipeline' and contributes no additional semantic 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 names a specific verb ('List') and resource ('stages in a deployment pipeline'), which is clear and accurately reflects the operation. However, it stops short of explicitly distinguishing itself from the similarly named sibling deployment_pipeline_list_stage_items, so differentiation rests on the resource noun alone.

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 given on when to use this tool versus closely related siblings such as deployment_pipeline_list_stage_items or deployment_pipeline_list_operations. No prerequisites (e.g., needing a valid pipeline ID) or exclusion conditions are mentioned; usage must be inferred entirely from the tool name.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=true. The description clarifies that the destructive action is an unassignment rather than a workspace deletion, which adds useful context, but it does not mention side effects, reversibility, or whether the action is asynchronous. Given the annotation coverage, 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 a single focused sentence with no filler. The verb and object are front-loaded, and every word contributes to the tool's meaning.

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 three-parameter mutating tool with complete schema and annotations, the description is nearly sufficient. However, it omits caveats such as whether a stage must contain the workspace before unassignment, whether unassignment can affect deployment, or how to confirm success. Since there is no output schema, a bit more operational context would improve completeness.

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

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

The input schema has 100% description coverage for all three parameters, so the schema already documents their meaning. The description adds no additional parameter-level semantics, which is acceptable but not additive.

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 precise operation: 'Unassign a workspace from a deployment pipeline stage.' It includes the verb, the object being acted on, and the containing resource, and it clearly differentiates from the inverse sibling deployment_pipeline_assign_workspace.

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 given about when to use this tool versus alternatives such as deployment_pipeline_assign_workspace or deployment_pipeline_list_stage_items. There are no prerequisites, exclusions, or conditions stated, so the agent must infer usage entirely from the tool name.

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

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

The annotations already indicate readOnlyHint=false and destructiveHint=false, so the description adds no new behavioral context beyond the fact that this is an update. It doesn't disclose side effects, whether changes are immediately visible, whether existing settings are preserved, or any permission requirements. No contradiction exists, but there is also no added transparency.

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

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

The description is a single front-loaded sentence that conveys the essential operation with no wasted words. It is appropriately sized for a simple update tool with three well-documented parameters.

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 update operation with three flat parameters and full schema coverage, the description is largely sufficient to understand what the tool does. It could be marginally improved by noting that only the specified fields are changed and others remain intact, but the core invocation context is 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 adds minimal semantic value by mentioning 'name or description', which maps to displayName and description, but it does not provide additional details about formats, constraints, or relationships between parameters.

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

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

The description clearly states the action ('Update') and the resource ('a deployment pipeline'), and identifies the mutable fields ('name or description'). It does not explicitly differentiate from sibling tools like deployment_pipeline_get or deployment_pipeline_create, but the verb and resource scope are 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?

There is no guidance on when to use this tool versus alternatives, nor any mention of when not to use it. For example, it doesn't note that deployment_pipeline_get should be used to retrieve a pipeline, or that creating/deleting pipelines requires different tools. The usage context is only implied by the tool name and 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 indicate destructiveHint=true, so the mutation risk is known. The description adds the 'ongoing' scoping, which is useful, but it does not disclose side effects, failure behavior when no publish is ongoing, or whether cancellation is partial or full. No contradiction with annotations exists.

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

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

The description is a single, front-loaded sentence with no filler. Every word adds meaning, and the key scoping term 'ongoing' is included without extra verbosity.

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

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

For a simple cancellation tool with two well-documented ID parameters and destructive annotations, the description is largely sufficient. It could mention what happens if no publish operation is ongoing or describe the outcome of cancellation, but these are minor gaps given 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?

Schema description coverage is 100%, with both parameters described as 'The workspace ID' and 'The environment ID'. The tool description adds no additional meaning beyond the schema, 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 uses a specific verb ('Cancel') and a specific resource ('environment publish operation'), making the tool's function immediately clear. It also distinguishes itself from related siblings like environment_publish and environment_delete by targeting an in-progress publish 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?

The word 'ongoing' implies the tool should be used only when a publish operation is already in progress, providing some usage context. However, it does not explicitly state when not to use it, nor does it reference alternatives such as checking publish status or waiting for completion.

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 a non-read-only, non-destructive operation, and the description confirms the create behavior. It adds the optional seeding behavior, but does not disclose what is returned, whether creation is asynchronous, or any naming/validation constraints beyond the schema.

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

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

Two concise sentences with the core action front-loaded and no filler. Every word contributes to understanding the tool's purpose and optional seeding capability.

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

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

For a simple create tool with a fully documented input schema, the description is largely complete. It could mention the response shape or post-creation lifecycle, but those are minor gaps given the schema coverage and the presence of sibling tools like environment_publish and environment_get.

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

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

Schema description coverage is 100%, so the baseline is 3. The description highlights definitionDirectoryPath's role but does not add meaning beyond the schema's own parameter descriptions.

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