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

With no annotations, the description carries the full burden. It discloses that each response is for one exact marketId, warns against mixing dates/prices across markets, and instructs to say so directly if no candles are returned. It also explains the complementary nature of Yes/No shares in binary markets. These are meaningful behavioral traits beyond the bare input schema, though it does not cover rate limits or auth.

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 well-structured with clear headings (When to use, Key fields, Pitfalls, Prerequisites). It leads with a concise one-line summary and each sentence adds distinct value. No filler or redundancy.

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 key data interpretation (Close price, binary complement), common pitfalls, and prerequisites. An output schema exists, so it need not detail return structure. It could mention pagination or ordering behavior, but these are in the input schema. Given the tool's moderate complexity and no annotations, the description is sufficiently complete.

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 coverage is 0% for top-level parameters, and the description adds some meaning by clarifying that marketId is for one exact market and referencing a 'requested window.' It does not explain dateRange tokens, orderBy, or pagination, but those are already described within the nested schema. Thus the description offers modest added value, but is not fully compensating for the low top-level coverage.

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 clearly states it provides 'Historical odds/volume candles for a Polymarket market' and elaborates with 'price history and recent probability changes.' It is specific about the resource (Polymarket market) and the action (loading historical OHLCV), and the mention of 'specific market' alongside the prerequisite to lookup differentiates it from sibling tools like trades or orderbook.

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 'When to use' section identifies clear scenarios (current odds, price history, probability changes). The 'Prerequisites' section explicitly directs to call prediction_market_lookup when marketId is unknown, providing alternative guidance. However, it does not explicitly state when not to use this tool or contrast it with alternatives like prediction_market_trades, so it lacks full exclusionary guidance.

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