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

Annotations only declare destructiveHint and idempotentHint; the description adds critical behavior the annotations cannot express: the call never executes directly, it returns an approval URL that only the signed-in user can act on, pending is not execution, and expiry must be reported. It also warns that client-rendered cards may not exist, preventing false claims of confirmation UI.

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 risk warning and confirmation precondition are correctly front-loaded, but the middle section sprawls into client-specific rendering instructions (Codex/Claude/Cursor, card vs. button) that restate the same idea several ways. The content is useful but could be tightened by roughly a third without losing signal.

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 usefully explains that the return is an approval URL plus an expiry window, and it names the status-check follow-up. The only real gap is the undocumented idempotencyKey, which is a meaningful omission for a destructive, idempotent-flagged operation.

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

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

Schema coverage is 0%, so the description carries the full burden, yet it only implies that a target deployment is identified. The idempotencyKey parameter — the one that matters most given idempotentHint — is never mentioned, and there is no guidance on UUID format or when to reuse a key versus generate a new one.

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 verb and resource ("stops an existing BotSpot live deployment") and scopes it to a running trading system, which separates it cleanly from start_deployment, run_deployment_once, and update_deployment_revision. The risk framing immediately tells an agent this is a production mutation, not a dry run.

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?

Gives an explicit precondition (user must confirm stop action, broker mode, and target deployment in the current conversation) and an explicit follow-up (check get_deployment_action_status after approval). It also rules out the tempting wrong path — chat-only approval or reusable grants — so the agent knows what does not count as authorization.

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