get_recent_trades

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

With no annotations, the description carries the full transparency burden. It goes beyond a simple 'get' by disclosing two key behaviors: fallback from a cold buffer to a REST snapshot, and the side effect of 'starts watching' when that fallback occurs. It also explicitly caps limit at 1000, which is not evident from the schema alone.

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 short and front-loaded with the essential purpose. The second sentence adds two high-value behavioral details without verbosity. Every word earns its place, and formatting with backticks on limit aids readability.

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?

The description covers the core behavior, fallback, side effect, and a hard limit, which is strong for a real-time data tool. An output schema exists, so not explaining return values is acceptable. It could be more complete by clarifying what 'cold' means or how the 'watching' side effect interacts with watch_symbol, but overall it is sufficiently complete for an agent to understand the tool's operation.

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?

The input schema has 0% description coverage, so the description must compensate. It adds meaning to the limit parameter by stating it is capped at 1000, which is helpful. However, symbol and exchange parameters are only inferable from their names; no additional semantics such as exchange defaulting behavior or symbol format are provided. Partial compensation only.

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 and resource: 'Get the most recent executed trades (ticks) from the live buffer.' This clearly distinguishes it from sibling tools like get_ticker or get_ohlcv by focusing on executed trades/ticks. The tool's name and description align perfectly.

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 provides clear context: it retrieves recent trades from the live buffer, with a fallback to REST snapshot when the buffer is cold. It does not explicitly contrast with alternatives like get_ohlcv or get_orderbook, but the domain (trades vs. other market data) creates an implied usage boundary. No explicit exclusions are stated.

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