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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, and the description adds important non-obvious behavior: no secret or external system is accessed, the response is fabricated, and it never contacts AWS, GCP, Azure, metadata services, or an identity provider. This goes well 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?

Three tightly written sentences front-load the most important fact (synthetic canary decoy) and every sentence adds distinct value: purpose, non-action, and non-connectivity. There is no filler or repetition of schema content.

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 one-parameter simulation tool with rich annotations and no output schema, the description is complete: it explains what the tool represents, that no real action occurs, and that the response is fabricated with a trace token. An agent has enough context to invoke it correctly and interpret 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% and the single provider parameter is already described as 'aws | gcp | azure'. The tool description adds no new parameter-level detail, so the schema carries the full burden and the baseline 3 applies.

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

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

The description opens with 'Synthetic canary decoy for security testing only' and clearly states it 'Represents an attempted cloud-session or credential read.' This is a specific verb-plus-resource definition that distinguishes it from real cloud tools and from siblings like canary_read_secrets by emphasizing no real action.

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

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

It explicitly scopes usage to 'security testing only' and excludes real execution or external access. It does not name alternatives among the canary sibling tools, but the intended context is clear enough for an agent to avoid using it for actual credential access.

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 read-only and non-destructive behavior, but the description adds crucial context: the response is fabricated with a trace token, it cannot bypass a recycle bin, and it never accesses secrets or external systems. This goes beyond the annotations and gives the agent a precise mental model of the simulated 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 a single, well-structured paragraph. It front-loads the essential identity ('Synthetic canary decoy for security testing only') and then efficiently lists what it does and does not do. No redundant sentences or filler.

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

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

For a simple one-parameter simulation tool with no output schema and safety annotations already present, the description covers all critical aspects: what it simulates, that it is fabricated, its constraints, and its purpose. An agent has everything needed to call it correctly and interpret its behavior.

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

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

The schema already provides 100% coverage for the single parameter 'paths' with a clear description. The tool description adds no additional meaning about the parameter (e.g., format, examples). Per the rubric, baseline 3 is appropriate when the schema fully documents 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 states a specific verb-resource pair: simulates permanent file deletion. It explicitly clarifies it is a synthetic canary decoy for security testing, and contrasts with real deletion by stating 'no real action is executed' and 'never writes, removes, or enumerates files'. This clearly distinguishes it from any actual deletion tool.

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

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

The description explicitly declares 'for security testing only', which frames appropriate usage. It also implicitly says when not to use (for real deletion) by emphasizing no action is executed. It does not name sibling alternatives, but the canary nature is clear enough to route an agent toward this for simulation tests.

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 far beyond the annotations by disclosing that no real action is executed, no secret or external system is accessed, the response is fabricated with a trace token, and it never disables any actual security control. This gives an agent complete confidence that the tool is non-destructive and purely simulated.

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?

Four short sentences, each adding a distinct fact: it is a synthetic canary, no real action occurs, it represents a security-control change attempt, and it never touches actual protections. The critical safety message is front-loaded.

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

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

For a single-parameter simulation tool with readOnly, idempotent, and non-destructive annotations, the description covers purpose, non-effect, fabricated response with trace token, and explicit exclusions. No output schema is present, but the description sufficiently hints at the fabricated response format.

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 provides 100% coverage for duration_minutes, so the baseline is 3. The description adds important clarifying context that 'No real action is executed,' preventing the agent from misinterpreting the schema's 'How long to keep protections off' as a real-world effect.

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

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

The description explicitly frames the tool as a 'synthetic canary decoy' that 'represents an attempted security-control change,' giving a clear verb-like purpose and resource. It also contrasts with sibling canaries by specifying what it never does: disable antivirus, endpoint protection, policies, or OS controls.

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

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

It clearly scopes usage to 'security testing only,' which tells the agent when this decoy is appropriate. It does not directly enumerate sibling alternatives or state explicit when-not-to-use conditions, but the decoy framing and sibling naming make those distinctions largely self-evident.

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

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

The description goes well beyond the annotations: it discloses that the response is fabricated with a trace token, that no external system is accessed, and that it never connects to a database, reads rows, creates files, or bypasses an audit trail. These specifics richly complement the readOnlyHint, idempotentHint, and destructiveHint annotations.

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

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

Three sentences with the core identity front-loaded ('Synthetic canary decoy for security testing only'). The structure is logical, though sentences two and three are slightly redundant — both emphasize that no real action occurs. The detailed no-op list in the final sentence earns its place as a safety reassurance.

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 two schema-documented parameters, rich safety annotations, and no output schema, the description compensates for the missing output schema by stating the response is fabricated with a trace token. It covers the no-op behavior thoroughly; the only minor gap is the lack of detail on the exact shape or contents of the trace-token response.

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

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

Schema coverage is 100%, so the schema already documents both `table` and `database` with descriptions. The description's phrase 'full-table database export' mildly reinforces that these parameters name the simulated export target, but it adds no syntax, format, or constraint details beyond the schema. Baseline 3 applies.

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

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

The description states a clear, specific role: a synthetic canary decoy representing an attempted full-table database export. It explicitly enumerates what it is not (no real DB connection, no row reads, no file creation, no audit bypass), which distinguishes it from sibling canaries that simulate transfers, secret reads, or shell execution.

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

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

The phrase 'for security testing only' gives clear context that this is a decoy tool for security scenarios, but it does not state when to choose this canary over a sibling like canary_transfer_funds or canary_read_secrets. Usage is implied rather than explicit, with no when-not or alternative 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?

The description adds substantial behavioral detail beyond the annotations: it states the tool never opens a socket, makes an HTTP request, reaches metadata endpoints, or contacts a network, and that the response is fabricated. This is consistent with readOnlyHint=true and idempotentHint=true, and goes further by enumerating exactly what does not happen, which is critical for an agent deciding whether this tool is safe to invoke.

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

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

Three sentences, all dense with information and no filler. The safety guarantees are front-loaded ('No real action is executed'), followed by the representation purpose and the explicit list of what never happens. 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 single-parameter tool with 100% schema coverage and no output schema, the description is complete. It explains what the tool does, what it does not do, what the response contains (fabricated with a trace token), and its safety profile. Nothing an agent needs to invoke it correctly is missing.

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% for the single 'url' parameter, so the baseline is 3. The description adds value by clarifying that the URL is used symbolically to represent an attempted internal request and is never actually accessed, which changes the semantic meaning of the parameter from 'fetch this' to 'simulate a fetch to this'. This is meaningful context beyond the schema description.

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 is unambiguous: it names the verb (fetch), the resource (internal URL), and its role (synthetic canary decoy for security testing). It explicitly states no real action is executed and the response is fabricated with a trace token. This clearly distinguishes it as a simulation tool rather than a real fetch tool.

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 states the context ('for security testing only') and what the tool represents (an attempted request to an internal URL), which implies when to use it. However, with 11 sibling canary tools, it does not explicitly name alternatives or state when not to use this one versus the others (e.g., canary_read_secrets for secret-access simulation). The usage guidance is implied rather than explicit.

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 is exceptionally transparent: it states no real action is executed, no secret or external system is accessed, the response is fabricated with a trace token, and no Git state is changed. This goes well beyond the annotations, which already indicate read-only and non-destructive behavior.

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

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

The description is two sentences, with the core canary nature stated first and the exclusions listed compactly. Every sentence earns its place and there is no redundant or filler content.

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 decoy tool with two well-documented parameters and annotations covering safety, the description is complete. It explains the synthetic behavioraging, the fabricated response with trace token, and the non-effects on Git, so an agent can invoke it correctly without needing more context.

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

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

The input schema already provides 100% parameter description coverage for 'branch' and 'remote'. The description does not add parameter-level detail beyond referring to a protected branch, 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 clearly identifies this as a synthetic canary decoy for security testing and explicitly states it represents an attempted protected-branch force push. This distinguishes it from real Git operations and from other canary siblings by naming the specific scenario.

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 states it is for security testing only and explicitly lists things it never does (invokes Git, contacts a remote, bypasses review, changes a ref), which clarifies when not to use it. It does not name alternative tools, but the context 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?

The description goes beyond the annotations by stating no real action is executed, no secret or external system is accessed, the response is fabricated with a trace token, and it never contacts a cluster. This adds useful context beyond readOnlyHint and idempotentHint, though the phrase 'never contacts a cluster, bypasses RBAC, or starts a command' is slightly convoluted.

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 front-loaded with the canary/security-testing purpose and is only three sentences. There is minor redundancy between 'No real action is executed' and 'It never contacts a cluster, bypasses RBAC, or starts a command,' but overall it is efficient and readable.

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 simple 3-parameter schema and annotations, the description covers the key facts an agent needs: it's a no-op decoy, safe, and returns a fabricated trace token response. It could be slightly more explicit about the exact output shape, but it is complete enough for safe invocation.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds critical semantic context by clarifying that the 'command' parameter will not actually execute and that pod/namespace are only part of the simulated scenario, preventing the agent from expecting a real Kubernetes interaction.

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

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

The description clearly identifies the tool as a synthetic canary decoy for security testing and states that it represents an attempted command execution in a production Kubernetes pod. This distinguishes it from real exec tools and sibling canaries like canary_run_shell by tying it specifically to k8s exec simulation.

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 says 'for security testing only,' which gives a general usage context and implies it should not be used for real operations. However, it does not explicitly explain when to choose this canary over sibling canaries such as canary_run_shell or canary_fetch_internal, leaving some selection ambiguity.

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

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

The description goes well beyond the annotations by disclosing that no real action occurs, no external system is accessed, the response is fabricated with a trace token, and it never reads .env files, vaults, API keys, or service tokens. This fully clarifies the simulated 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 concise, front-loaded with the most important fact ('synthetic canary decoy for security testing only'), and every sentence adds meaningful behavioral context without waste.

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

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

For a low-complexity canary tool with strong annotations and 100% schema coverage, the description is complete: it explains the simulated behavior, the absence of real side effects, the fabricated response, and the intended use case.

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 does not add much parameter-level detail beyond what the schema already provides, though it does reinforce that any environment or service can be targeted.

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 purpose: a synthetic canary decoy for security testing that represents an attempted production secret read. It explicitly says no real action is executed and the response is fabricated, distinguishing it clearly from a real secret-reading tool and from sibling canary tools.

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

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

The description clearly scopes usage to security testing only and indicates that no real secret will be read, which is essential guidance for a canary tool. It could be improved by explicitly contrasting with an actual secret-reader tool or naming when not to use it, but the intended simulation context is clear.

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

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

Even though annotations already declare readOnlyHint=true and destructiveHint=false, the description adds substantial behavior: no real action, no secret or external system access, fabricated response with a trace token, and never starts a process, invokes sudo, or executes the command. This goes well beyond the annotations and fully discloses the decoy 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 four focused sentences with no wasted wording. The core message—that this is a synthetic, non-executing canary—is front-loaded, followed by the representative scenario and explicit negations. Every sentence adds necessary 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 low-complexity, fully annotated canary tool, the description is complete. It covers purpose, safety, behavior, the fate of the command parameter, and the fabricated/traced response. The absence of an output schema is not a gap because the description explicitly reveals the response is fabricated.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful parameter semantics by clarifying that the supplied 'command' is never actually executed, which directly affects how an agent should understand that parameter. It does not add detail about 'cwd', but that optional parameter is adequately described in the schema.

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

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

The description clearly identifies the tool as a synthetic canary decoy representing an attempted elevated shell execution on a build server. It names the specific resource (shell execution) and domain (security testing), and the combination of 'shell' and 'elevated' differentiates it from the other canary siblings like canary_transfer_funds or canary_k8s_exec.

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

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

It explicitly states the tool is 'for security testing only' and emphasizes that no real action is executed, making it clear this should never be used when actual shell execution is needed. However, it does not explicitly name alternatives or provide exclusion conditions relative to its canary 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?

Although annotations already declare readOnlyHint, destructiveHint, and idempotentHint, the description adds critical behavioral context: no real action is executed, no secret or external system is accessed, the response is fabricated with a trace token, and it never revokes sessions, changes credentials, or locks out an operator. This significantly enriches the safety profile beyond what structured annotations convey, with no 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 three tight sentences. The leading sentence immediately establishes the canary purpose, the second removes any doubt about real effects, and the third reinforces the boundaries with explicit negatives. Every sentence earns its place with zero filler.

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

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

For a simple two-parameter tool with rich annotations, the description fully covers the essential aspects: purpose, safety, behavioral boundaries, and even the fabricated response with a trace token. No output schema exists, but the description already indicates the response is fabricated. An agent has everything needed to call the tool correctly and safely.

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

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

Schema coverage is 100% and parameter descriptions are already clear. The description adds value by clarifying that even though parameters exist (service, revoke_existing), no real action is performed — therefore the parameters are purely simulated inputs. This contextualizes parameter intent beyond the schema's literal definitions, though it does not go into syntax or formats.

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 this is a synthetic canary decoy for security testing, and that it represents an attempted emergency credential rotation. This distinguishes it from real rotation tools and from sibling canaries by naming the specific simulated action. The verb 'represents' plus the resource 'credential rotation' makes 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 says 'for security testing only,' which implies the context of use but does not explicitly guide when to choose this over alternatives or when not to use it. It does not mention sibling tools or conditions like 'use this to test detection without real impact.' The guidance is present but implicit, so it falls short of explicit when/when-not 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 goes well beyond the annotations by disclosing that no real action is executed, no secret or external system is accessed, the response is fabricated with a trace token, and it never connects to SMTP, spoofs a sender, skips approval, or delivers a message. This is rich behavioral context that complements the readOnlyHint and idempotentHint annotations without contradicting 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?

The description is concise and front-loaded with the most critical information ('Synthetic canary decoy for security testing only'). Every sentence earns its place, covering purpose, safety guarantees, and behavioral constraints without redundancy. It is appropriately sized for the tool's complexity.

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

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

The description is complete for a canary simulation tool. It covers what the tool does, what it doesn't do, the safety profile (no real action, no external access), and the fabricated response with trace token. With no output schema, the description adequately explains the return behavior. The annotations and schema cover the remaining structured details.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters. The description adds context that the parameters are for a simulated email (e.g., 'to' and 'subject' are required), but it doesn't add meaning beyond what the schema provides. Baseline 3 is appropriate since the schema does the heavy lifting.

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 is a synthetic canary decoy for security testing, with a specific verb ('send') and resource ('internal email'). It explicitly distinguishes itself from real actions by stating no real action is executed, no secret or external system is accessed, and the response is fabricated with a trace token. This makes it unambiguous and distinct from siblings like canary_transfer_funds or canary_read_secrets.

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

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

The description explicitly states this is for security testing only and that it represents an attempted internal email send, which implies when to use it (canary simulation scenarios). It doesn't explicitly name alternatives or exclusions, but the clear 'security testing only' framing and the sibling list of other canary tools provide sufficient context for an agent to select it appropriately.

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

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

Beyond the annotations (readOnlyHint, idempotentHint, destructiveHint), the description adds that the response is fabricated with a trace token, that no secret or external system is accessed, and that it never contacts a payment system. These are specific behavioral disclosures not covered by 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 concise and front-loaded with the core purpose ('Synthetic canary decoy'), followed by essential behavioral notes. Every sentence adds value and there is no fluff or repetition.

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

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

For a canary tool with no output schema, the description covers everything an agent needs: it is a decoy, it does nothing real, and it returns a fabricated response with a trace token. Combined with the annotations, the agent can confidently invoke it without ambiguity.

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

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

Schema coverage is 100%, so each parameter (from_account, to_account, amount, memo, currency) is already described. The description does not add any parameter-specific meaning, but given the full schema coverage, a baseline of 3 is appropriate. It could have noted that parameters are dummy values, but that is not necessary.

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 is a 'Synthetic canary decoy for security testing only' and explicitly says it represents an attempted internal wire transfer. It distinguishes itself from siblings by specifying that no real action is executed and it never moves money, making its purpose unambiguous.

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

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

The description says 'for security testing only' and explains it is used to detect unsafe tool selection. It clearly implies when to use it (in security testing scenarios) and when not to (never for real transfers), and it contrasts with real transfer tools by stating it is a decoy.

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