prepare_create_spot_grid

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

With no annotations, the description carries the full burden. It discloses two major behavioral traits: it does NOT create anything (deferred execution) and it returns a confirmation token. It also enumerates the validation dimensions (bounds, row 2-200, grid_type whitelist, notional cap, exchange checkParams endpoint). This is honest and actionable. Could add what happens on failure (error message? no token?), which is a minor gap.

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?

Two sentences, front-loaded with the key fact 'STEP 1 of 2'. Each clause carries weight: validation types, the checkParams endpoint, the token, and the explicit negation of creation. No fluff, no 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?

The tool is a complex two-step creation flow with 7 params and no output schema. The description covers the essential flow (prepare → confirm) and the validation scope. Missing: parameter constraints details (beyond row 2-200), default for grid_type not explained, exchange-specific API requirements not mentioned. Given its complexity, would benefit from a 'see check_spot_grid_params for details' pointer. Slightly short of a 5.

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?

Input schema covers 0% of parameters. The description mentions 'row 2-200' and 'notional cap' and lists validation types but not the semantics of each parameter. It names base, quote, top, bottom, row, quote_investment as the required set (implicitly by listing them) but doesn't explain what top/bottom mean (price bounds?), what grid_type does (arithmetic vs geometric), or the format of quote_investment. The description helps a bit but doesn't fully compensate for 0% coverage.

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?

Clearly identifies itself as STEP 1 of a two-step creation process, names the specific resource (spot grid bot) and its actions (validates locally and against exchange). The phrase 'Nothing is created until confirm_action with that token' disambiguates it from its sibling prepare_cancel_spot_grid and the actual creation step confirm_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?

The description clearly states when to use it: as the first step before confirm_action. It implicitly says not to use it if you only need to check parameters (sibling check_spot_grid_params exists) or to cancel (prepare_cancel_spot_grid). However, it doesn't explicitly state alternatives like check_spot_grid_params. It does provide clear procedural sequencing which is highly useful.

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