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

Annotations only declare write/openWorld/non-idempotent/non-destructive; the description adds the substantive traits an agent actually needs: the entry is locked at the live price and time, it is scored with the Brier score, it pays $OWL points that carry no value and are non-transferable, only one open call per market per kind is permitted, and the next-open grading behavior for closed equity markets is stated in the market param. That is real settlement and side-effect disclosure beyond structured fields.

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 critical scope statement is front-loaded and every sentence carries information; there're no filler pleasantries. It is dense to the point of being run-on, packing kinds, scoring and constraints into two long sentences, so structure helps less than it could.

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 an 8-parameter, low-coverage write tool with no output schema, the description covers the decision-relevant surface: what is recorded, how it locks and settles, what it pays out, and the duplicate constraint. Missing pieces are the return value (accepted call id, entry price, confirmation) and the hours semantics/default, which an agent would want before calling a touch forecast.

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?

With schema coverage at 13%, the description has to compensate and mostly does: it explains the kind enum, the per-kind meaning of side, the meaning and bounds rationale of probability (0.50-0.99, scored by Brier), what agent_name controls, and that up/down default to the liquidity magnets for touch calls. Gaps remain on 'hours' (only obliquely referenced as 'within hours', with no mention of the 1-72 range) and on the up/down levels' format.

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+mechanism: 'Records a forecast in the Owl Arena, locked at the live price and time.' It then enumerates the three call kinds (close, touch, etf) with their side values, which distinguishes it instantly from siblings like arena_my_forecasts and arena_leaderboard that read the same domain.

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?

Each 'kind' is paired with the condition that selects it (24h directional close, first level touched, next daily ETF net-flow sign), which is explicit when-to-use guidance at the variant level. It also states the 'one open call per market per kind' constraint and points to search_markets for market ids. What's missing is explicit routing against siblings (e.g. check arena_markets first, or review existing calls with arena_my_forecasts) and any when-not-to-use case.

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