Suspend Grid Order

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

Annotations carry only flags (readOnlyHint=false, idempotentHint=true, destructiveHint=false), but the description reveals the critical behavioral trait the annotations cannot: this tool is a dry run unless given a confirmation_code, which is single-use, expires in 10 minutes, and binds to the exact request. It also discloses the real-world risk ('A grid strategy keeps placing orders on its own once live'). This is exactly the kind of context that goes beyond structured data.

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?

Front-loaded: the purpose verb-object lands in sentence one, the sibling routing in sentence two, and the safety protocol follows in a clearly flagged section. Every sentence earns its place — even the warning about grid strategies is essential for safe use. Slightly longer than average, but the density of mandatory procedural information justifies it.

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 two-parameter tool with a mandatory confirmation protocol and no output schema, the description is complete: it covers the operation, the resume counterpart, the exact two-step call sequence, the confirmation_code constraints (single-use, expiry, request binding), and the guardrail against self-initiated quoting. Nothing an agent needs to invoke and confirm this safely 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?

Though schema coverage is 100%, the description adds deep meaning beyond the schema for the execute parameter: it explains the confirmation_code's derivation from the order, single-use behavior, 10-minute expiry, and change-any-field-invalidation. The order_id param is clarified as belonging to a *running* grid order. This substantially exceeds what the bare schema strings provide.

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?

Opens with a specific verb-resource pair: 'Suspend (pause) a running grid order by order_id.' It names the distinguishing scope (a *running* grid order) and explicitly differentiates from the resume sibling in the very next sentence ('Resume with grid_restart'). An agent can tell it apart from grid_cancel and grid_restart without opening the schema.

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?

Names the alternative tool (grid_restart) and gives explicit when-to-use guidance plus a mandatory call sequence: 'Call it first without execute, show the returned preview to the user, and only call it again with execute="<confirmation_code>" after the user has explicitly confirmed it.' It even states a hard when-not ('Never quote it back on your own initiative'). Nothing is left to inference.

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