Production Pod Exec — canary simulation

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.