prepare_order

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It transparently states that the tool only validates (no order is sent) and returns a confirmation token, and it also conveys important behavior like requiring the agent to present the summary and await approval. It does not detail failure modes, auth requirements, or rate limits, but the core behavior of validation-only is clearly conveyed, which is more than many tool descriptions do.

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 well structured: it starts with the step indicator and core behavior, then provides parameter-specific guidance in a clear, bullet-like format. Every sentence adds value—there is no fluff. It is slightly longer than average but appropriate given the complexity of order types, and the information is front-loaded with the safety-critical note that no order is sent.

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 tool's complexity and the existence of an output schema, the description covers the essential context comprehensively: it defines the two-step flow, specifies validation behavior, details parameter conditions, and instructs the agent on the follow-up action (calling confirm_action after user approval). It does not mention prerequisites like prior balance checks, but those are part of validation, and with an output schema present, return-value details are not required. Overall, the description is sufficient for an agent to call this tool correctly in the intended flow.

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 description compensates for the 0% schema coverage by explaining the key parameters: side, order_type, and the conditional requirements for price, size, and amount across LIMIT, MARKET BUY, and MARKET SELL. It also clarifies that all numeric values should be provided as strings exactly as they should reach the exchange. While it does not explain symbol, ioc, or client_order_id, the most complex and interdependent parameters are well described, and the string-format warning is particularly valuable.

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 states it is 'STEP 1 of 2 to place a spot order' and clarifies that it validates against live exchange data and returns a confirmation token, with the crucial note that 'NO order is sent.' This clearly differentiates it from sibling prepare tools (e.g., prepare_dual_invest for dual products) and from confirm_action, so an agent understands exactly what this tool accomplishes versus other preparation steps.

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 provides explicit usage guidance: it is step 1 of 2 for placing a spot order, and it directs the agent to 'show the summary to the user and only call confirm_action with the token once they explicitly approve.' This establishes the when-to-use context and the sequential relationship with confirm_action, leaving little ambiguity about when this tool should be invoked.

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