getPredictionOrderBook

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

The readOnlyHint and openWorldHint annotations already mark this as a safe read, so the description only needs to add context. It adds the return shape ('all price levels with available quantity') and the batch limit of 20 tokenIds, which are not inferable from annotations or the input schema.

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 purpose is front-loaded, but the agent hint repeats the earlier sentences almost verbatim: full order book depth, price impact estimation, and the 20-tokenIds limit. Condensing these into one paragraph would make the description tighter.

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 simple read-only, one-parameter tool with no output schema, the description covers purpose, return content, a critical request limit, and the main sibling distinction. The only substantial gap is tokenId provenance/format, which prevents a perfect score.

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%, so the description carries the parameter-documentation burden. It clarifies that tokenIds are prediction outcome token IDs and caps the array at 20, but it does not explain where valid tokenIds come from or what format they take, leaving an agent to infer that from external context.

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: 'Query the full order book (bid/ask depth) for prediction outcome tokens', and states that it returns all price levels with available quantity. It is clearly distinguishable from broad siblings like getOrderbook because of the 'prediction outcome tokens' qualifier, and it names the closest alternative, getPredictionTokenPrice, for best-price lookups.

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?

It gives concrete use cases: estimating price impact before a large order or displaying market depth to users. It also supplies an explicit alternative and selection condition: 'For just the current best price, use getPredictionTokenPrice instead', and highlights the 20-tokenIds per request limit.

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