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

Annotations already establish readOnly, idempotent, open-world, non-destructive behavior, so the bar is lower. The description adds genuinely new context: the tool returns live quotes rather than executed fills, the settlement criteria are exposed via rules_primary, and pagination is cursor-based. This enriches the agent's model of what the invocation produces without contradicting any annotation.

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?

Three tight paragraphs with clear structure: purpose/usage first, return shape second, alternatives third. Every sentence earns its place. The middle paragraph listing return fields is slightly redundant with the existing output schema, which costs a point, but the overall organization is strong and front-loaded.

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 read-only, zero-required-parameter list tool with a rich schema, annotations, and output schema, the description covers everything an agent needs: purpose, regulatory framing, when-to-use vs alternatives, filtering strategy, return fields, settlement criteria, and pagination. No critical gap remains; rate limits and error cases would be marginal additions.

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 100%, so the baseline is 3. The description adds organizational value by grouping the 15 parameters into use-case clusters (fetch specific markets via tickers, scope via event_ticker/series_ticker, narrow via status/search/timestamp ranges), which helps an agent pick the right filter for its goal. This exceeds the baseline but does not add per-parameter detail beyond the schema.

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 — 'List markets on Kalshi' — and adds distinguishing qualifiers ('CFTC-regulated US prediction exchange', 'live bid/ask quotes in dollars') that separate it from the other market venues in the sibling list. It also explicitly names what it is not ('For executed fills rather than quotes, use get_kalshi_trades'), so an agent can disambiguate without opening schemas.

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?

Provides explicit when-to-use guidance ('Use this when you need odds from a regulated venue, or to cross-check a Polymarket price against a second market') and names both alternatives with the exact conditions that select them (get_kalshi_trades for fills, get_polymarket_markets for the crypto-native venue). Nothing is left to inference.

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