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

With no annotations, the description carries the full burden. It discloses several behavioral traits: returns snapshots with yes/no bids/asks in cents and dollars, timestamps in milliseconds, data availability starting October 29, 2025, and limit being ignored when fetching latest. This is thorough for a read-only fetch, though it does not discuss error handling or pagination.

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 efficiently structured with front-loaded purpose, followed by boundary conditions, return content, units, and a note about limit. Each sentence earns its place with no redundancy or fluff.

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 lacking an output schema, the description adequately explains the return contents (yes/no bids/asks, price units) and adds key context about time range handling, timestamps, and data history. It could mention ordering or pagination behavior, but overall it is sufficiently complete for invoking this tool correctly.

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 already covers 100% of parameters with clear descriptions, including the optionality of start_time/end_time and the limit behavior. The description adds minor context (millisecond timestamps, data start date) but mostly reiterates schema content. Thus, baseline 3 is appropriate.

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 the tool fetches historical orderbook snapshots for a specific Kalshi market (ticker) over a time range, with a fallback to the latest snapshot. This specific verb+resource+scope accurately distinguishes it from sibling tools like dome_orderbook_history and dome_market_price.

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 is used for historical orderbook data for a specific ticker, and if no time range is provided it returns the latest snapshot. It also notes that limit is ignored in the latest-snapshot case. However, it does not explicitly mention when not to use it or name alternatives, so it falls short of full guidance.

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