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

No annotations are provided, so the description carries the full burden. It explicitly discloses a critical side effect: 'Any credential already entered is destroyed.' This is valuable transparency for a destructive mutation. However, it doesn't mention other effects like whether cancellation is reversible or requires special 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 two sentences long, highly concise, and front-loaded with the core action ('Cancel a pending request') followed by a key consequence. There is no fluff or redundancy.

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

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

With no output schema, the description doesn't explain return values or error conditions. While it covers the key destructive behavior, it lacks guidance on when to use the reason parameter, potential side effects beyond credential destruction, and any prerequisites. For a security-related tool, more context would be helpful, but the essential purpose is clear.

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

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

The input schema has 0% description coverage, and the description does not explain the parameters at all. It doesn't mention that request_id is required or that reason is optional. The schema itself provides clear names, but the description adds no additional meaning, leaving the agent to infer that request_id identifies the request and reason is for audit 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 clearly states 'Cancel a pending request' which is a specific verb (cancel) and resource (request). It distinguishes from siblings like secret.store and secret.revise, as it focuses on cancellation and the destruction of already-entered credentials.

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

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

The description implies the tool is for pending requests ('Cancel a pending request') but gives no explicit guidance on when to use it versus alternatives, nor exclusions. It lacks context like 'use secret.revise to modify instead' or 'do not use for completed requests'.

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 include readOnlyHint: true, and the description does not contradict it. It adds context about the content (target fields) which is useful for the agent. Given the annotation already covers safety, the description provides adequate extra behavioral context.

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

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

Single sentence, front-loaded with the verb and resource, no fluff.

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 tool with no parameters and no output schema, the description fully explains what it does and includes the key detail about target fields, which is likely sufficient for an 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?

The tool has zero parameterswing schema coverage is 100% (vacuously). Baseline for 0 params is 4, and the description clarifies that the output includes target fields per destination, which adds contextual meaning beyond the empty 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 action (List) and the specific resource (destinations this Veil instance can write to), and adds the detail about target fields. It distinguishes itself from sibling tools like store, cancel, revise, which involve mutations.

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 (to discover available destinations and their required fields), but does not explicitly contrast with alternatives. Since it's a simple listing tool, the purpose clarity implicitly covers usage, though no exclusions are 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?

With no annotations, the description carries the full burden and does so well. It discloses that the original authorization is invalidated, the human must reauthorize from scratch, and authorized operations cannot be edited in place. This covers the key side effects and workflow consequences of a mutation tool.

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

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

The description is two sentences with no filler. The first sentence states the core action, and the second provides the key behavioral consequence and an important invariant. Every sentence earns its place.

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

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

For a 7-parameter tool with nested objects and no output schema, the description explains the compound nature and authorization consequences sufficiently. It could additionally mention that all parameters must be resubmitted for the new request, but the schema and existing wording make the required inputs inferable.

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 71%, so most parameters have descriptions already. The tool description adds context around request_id by referring to 'pending request' and 'new operation from scratch,' but it does not explain parameter interactions or destination-specific requirements beyond what the schema provides. This is adequate but not enhanced.

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 compound operation: 'Cancel a pending request and create a new one.' The title, 'Replace a credential request with a corrected one,' further specifies the resource and intent, distinguishing this from sibling tools like secret.cancel and secret.store.

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

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

It gives clear context for when to use the tool: when a pending request must be corrected, and specifically notes that 'an authorized operation can never be edited in place.' It doesn't explicitly contrast with secret.cancel or secret.store, but the described workflow makes the intended use case unambiguous.

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

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

The description adds valuable behavioral context beyond the readOnlyHint annotation by guaranteeing that no credential material is ever returned. This safety guarantee is a key trait not covered by annotations, though it does not disclose blocking behavior or error handling.

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

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

The description is two concise sentences that front-load the core purpose and add a critical safety note. There is no unnecessary detail or 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?

The tool is simple with two parameters and a read-only annotation, but the description omits key behavioral details such as the optional blocking behavior via wait_seconds and what the response actually contains (e.g., status list, error scenarios). Without an output schema, the description should describe the return value format more fully.

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

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

The description provides no explanation of the parameters. request_id is self-explanatory from its name, but wait_seconds is already described in the schema. With only 50% schema description coverage, the description fails to compensate for the missing request_id semantics or clarify how to obtain such an ID.

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

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

The description clearly states the tool returns the status of a credential request and explicitly mentions it never returns credential material. This distinguishes it from siblings like secret.cancel or secret.store, making the purpose unambiguous.

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

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

The description implies usage for checking status but provides no explicit guidance on when to use it versus alternatives. There is no mention of 'use when you need to check status' or exclusions like 'do not use to cancel requests'.

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 explicitly discloses that the credential value never passes through the tool, is never returned, and never becomes visible to the model—a key behavioral trait. It also outlines the multi-step process involving an authorization_url and polling. Annotations already signal destructive and open-world behavior, and the description complements these without contradiction.

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

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

The description is two sentences, front-loaded with the core action, and includes essential security and workflow context. Every sentence earns its place, and there is no redundant or extraneous text.

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

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

Given the tool's complexity (nested target, multiple destinations, write modes, environment), the description covers the critical workflow and security aspects, and points to secret.destinations for detailed contracts. It does not explain write_mode or environment semantics, but those are well-documented in the schema. Overall, it is reasonably complete for a tool of this intricacy.

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

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

The description does not directly elaborate on any input parameters, but the schema provides extensive descriptions for 83% of fields. It directs users to secret.destinations for the target contract, which covers the remaining nuance. Since the schema already carries the semantic load, the description adds little beyond baseline.

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

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

The description clearly states the tool's action: asking the human for a credential and having Veil write it to a specified destination. It distinguishes itself from siblings like secret.status and secret.cancel by focusing on the store action and includes critical security context (credential not visible to model) and subsequent steps (share authorization_url, poll status).

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

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

The description provides clear workflow guidance: ask the user, share the authorization_url, and poll secret.status. It implies this tool is for new credentials but does not explicitly contrast with secret.revise or specify when not to use it. The flow is described well, but alternative exclusions are missing.

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