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

Beyond the readOnly/openWorld annotations, it discloses genuinely useful behavior: results are ordered closest race first, every seat carries a page URL, and prices are never estimated — an unpriced seat returns null rather than a fabricated value. That null-versus-value contract is the kind of detail annotations cannot express. It does not cover rate limits, caching, or freshness of the prices, leaving a small gap.

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?

Two sentences, front-loaded with the trigger phrasing and then a single dense but readable inventory of returned fields, ordering, and null semantics. No sentence restates the tool name or title, and nothing could be cut without losing information.

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?

With no output schema and only one optional parameter, the description carries the return-shape burden itself and does so: field list, sort order, per-seat URL, and null handling are all stated. An agent can call this tool and interpret its output without further documentation.

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 100%, and the schema already explains that limit means seats returned, closest first, with a default of the 8 closest lacking forecaster detail. The description only echoes the ordering and adds no syntax, bounds, or format guidance for accepting a number versus a string. Baseline 3 applies since the schema is doing the explanatory work.

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 names a specific resource and scope ("Every 2026 Senate seat") and enumerates exactly what is returned: holder and role, structure rating, forecaster bands, and live Kalshi price. This cleanly separates it from general market tools like market_pulse or best_price, but there is no explicit acknowledgment of the closest sibling, race_odds, so the agent must infer that this is the full-map view versus a single-race view.

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 opens with concrete trigger phrasing for two query shapes ("2026 Senate map" and "which Senate seats are toss-ups"), which gives the agent a clear signal for when this tool is the right pick. It stops short of stating when to prefer race_odds or the pricing tools instead, so exclusions are left implicit.

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