buy_event_contract

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

The description adds substantial context beyond annotations: it flags that a real trade executes, specifies the DAY time-in-force, and discloses the non-obvious fallback behavior (ask lookup via event_symbol, rounded up to a whole cent) when limit_price is omitted. It does not state what happens to an unfilled DAY order or warn that retrying a non-idempotent buy could double-execute, which would be valuable for a money-moving tool.

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 purpose, then the risk warning, then the workflow, then parameters — the right order for a destructive-adjacent tool. The Args block is lengthy but every line carries non-redundant constraint detail that the 0%-coverage schema lacks.

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?

An output schema exists, so return values need no explanation; given that, the description covers the risk profile, ordering workflow, symbol provenance, and every parameter constraint. Nothing an agent needs to invoke this correctly 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?

Schema description coverage is 0%, so the description must carry all five parameters — and it does: example symbols for contract_symbol and event_symbol, quantity default and 2-decimal constraint, limit_price as dollars with whole cents bounded 0.01–0.99, the conditional requirement that event_symbol is needed when limit_price is omitted, and account_id's env-var fallback. This adds genuine meaning the bare schema cannot.

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 (Buy), resource (event contract, defined parenthetically as the YES or NO side of a prediction market), and mechanism (DAY limit order). This clearly separates it from preflight_buy_event_contract and the generic place_order siblings without the agent needing to open any 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?

Gives an explicit prerequisite ('Consider running preflight_buy_event_contract first') and a concrete end-to-end workflow for the recurring-market case, naming get_current_event, get_event_details, and wait_for_settlement in sequence. It also states the exclusion case for contract_symbol (not the '-EVENTCONTRACT' symbol used by get_event_contract_bars), so the agent knows which sibling takes which symbol form.

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