Create Combo

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

Annotations already declare destructiveHint=true, idempotentHint=false and openWorldHint=true, but the description adds genuinely non-derived behavior: a 1,000-per-week creation quota per exchange participant, a Monday 00:00 UTC reset, and the fact that returning an existing canonical combo is quota-free. The explicit warning that the operation may affect real funds or account state is useful reinforcement. Slight tension with idempotentHint=false is resolved by the quota framing, so it is not a contradiction, but the description could state more clearly what the returned instrument represents.

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-loads the live-account warning and the core verb, then layers quota rules in a logical order. Five sentences with no filler, though the quota detail could be trimmed to two sentences without losing decision-relevant information.

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?

Rich annotations plus no output schema mean the description need not restate the safety profile, and the quota disclosure is exactly the kind of context an agent needs before a destructive call. Still missing for a nested-payload mutation: what a 'combo instrument' actually is (a multi-leg combined position), what the response contains, and whether legs must be from the same event.

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 description coverage is 0% and the single parameter is a nested object with a required 'legs' array (2-50 items, each with symbol and side). The description only says 'for the supplied legs' and adds no meaning about leg ordering, weighting, or what constitutes a valid combination — the schema alone carries all of that. For a nested payload at 0% coverage, this is a clear gap.

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: 'Creates or returns the combo instrument for the supplied legs.' That is clearly distinguishable from get_combos (read-only retrieval) and from create_order. It falls short of a 5 because the create-vs-return duality, which is the tool's most consequential distinction, is only clarified later in the quota paragraph rather than in the opening sentence.

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?

Usage context is implied through the quota rules and the 'LIVE ACCOUNT ACTION' label, so an agent knows this is a live-account mutation with a weekly budget. However, the description never routes the agent explicitly, e.g. 'use get_combos to read existing combos' or 'use create_order for single-leg orders,' leaving sibling selection to inference.

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