get_order_history

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

With no annotations, the description carries the full disclosure burden. It adds meaningful behavioral detail: default/max limit ('default 50, max 200') and the time format ('epoch-ms'). It omits edge behaviors like how 0-valued time params are handled or whether the list is sorted, but for a simple read operation it discloses the key knobs.

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?

Two sentences, zero fluff, with the core purpose front-loaded and constraints packed efficiently into parentheticals. Every clause earns its place. Minor deduction: the lone detail ordering could be slightly more scannable with explicit param names, but it's already near-optimal.

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 a low-complexity read-style tool (4 params, no nesting, no enums, no annotations, no output schema), the description covers the essentials: what's fetched, the limit bounds, and time format. It leaves a couple of minor gaps — the default behavior when time params are absent (0) and ordering of results — but nothing that critically blocks correct invocation.

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%, but the description compensates substantially: 'default 50, max 200' explains the limit semantics and 'epoch-ms time range' clarifies the unit/format for start_time_ms and end_time_ms. These format hints go beyond what the schema's type/title fields convey, directly answering the most likely agent questions for an otherwise simple 4-parameter interface.

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 names a specific resource ('Historical orders') and scope ('for a symbol'), making the primary function unambiguous despite lacking an explicit verb. It correctly implies this retrieves past orders per symbol, distinguishing it from siblings like get_open_orders, though it doesn't explicitly call out that distinction.

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 rather than stated: 'for a symbol' and 'historical' imply this is for past order lookup, contrasted with get_open_orders and get_order among the siblings. However, there's no explicit guidance on when to prefer this over get_order, get_fills, or get_order_by_client_id, nor exclusions for when not to use it — leaving the agent to infer the decision.

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