paper_trade_evaluate

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

With no annotations provided, the description carries full responsibility for behavioral disclosure. It richly details execution semantics: buys use ask, sells use bid, latency and size enforced, fees itemized, fill time calculation (submitted_at + latency or session open), quote_as_of significance, and the 16-minute historical delay when as_of is omitted. It also warns against assuming a fill from indeterminate outcomes, adding exceptional transparency.

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 five sentences, but each sentence carries critical, non-redundant information. The first sentence is front-loaded with the core purpose and scope, followed by execution details and usage cautions. There is no fluff or repetition; it is appropriately sized for the tool's complexity.

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?

Despite having an output schema (not shown), the description still guides the agent on what to inspect (outcome_reason, state_after, next_action, warnings) and how to interpret results. It covers default time behavior, fill timing, and safety caveats. For a tool with this complexity, the description is remarkably complete and leaves few unanswered questions.

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 67% (top-level), with as_of's description nested in anyOf. The description adds value by explaining how as_of affects fill evaluation and position marking, and reiterates the default behavior (now minus 16 minutes) clearly. It also ties trade_id to paper_trade_record and request_id to idempotency, though those are also in the schema. The added context on quote_as_of and execution time goes beyond the schema, so a 4 is warranted.

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 opens with a specific verb+resource: 'Evaluate a pending simulated entry/exit or mark an open position using delayed historical consolidated SIP top-of-book quotes; no order is sent.' This clearly distinguishes it from siblings (record, get, list, close) by focusing on evaluation of hypothetical fills and position marks, and explicitly notes no real order is placed.

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 indicates when to use it (evaluate pending order or mark open position) and provides a caution about reading outcome fields and not inferring fills from indeterminate results. However, it does not explicitly name alternatives or state 'when not to use,' only implying the context. This is clear context without explicit exclusions, so a 4 is appropriate.

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