Election Odds Desk

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

The annotations already establish read-only, non-destructive, closed-world behavior, so the description builds on that by disclosing the live Kalshi source, the exact data breakdown (strike breakdown, days-until, rate path, current fed funds rate, cross-venue check with gap in pp), and that it is free with no key. It omits update frequency and rate limits, but adds substantial operational context beyond annotations.

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 two tight sentences: the first front-loads when to use it, the second enumerates the payload. Every clause adds useful scope or content detail with no filler.

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 no-parameter, read-only data tool with an output schema, this description provides ample context: what it returns, which meetings are covered, the cross-venue comparison, and the free/no-key access condition. Nothing an agent needs to select or call it is missing.

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 tool has zero parameters, so the schema needs no parameter semantics. The baseline for a no-parameter tool is 4, and the description appropriately does not invent parameter details.

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 states a specific resource (Fed/FOMC rate odds) and a clear retrieval action, with example queries that pin down the exact intent. No sibling tool covers Fed policy odds, so it is trivially distinguishable.

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 explicitly gives two when-to-use triggers: 'will the Fed cut, hold or hike' and 'next FOMC meeting odds'. It does not state when-not to use it or name an alternative, but no sibling offers competing Fed-rate coverage.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful access context beyond that: the composite and regime are always free without a key, two category scores are free, one email returns four, and Pro returns all six. It says nothing about refresh cadence or staleness, which keeps it from a 5.

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 sentences, front-loaded with what the tool returns, followed by access tiers and then usage triggers. Every sentence carries information; the only mild redundancy is restating the category names already implied by 'six category scores'.

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, the description carries the return-value burden and does it well by enumerating the composite, regime, and six categories. Access tiering is disclosed, and a read-only macro data call needs little else for correct invocation.

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 single optional topic parameter is fully documented in the schema as 'macro = the US macro-health composite (the only topic)'. The description adds no syntax or format detail about the parameter, so the baseline 3 applies.

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 the exact resource (US macro-health composite 0–100, regime, and six named category scores), so an agent knows precisely what data comes back. No verb is stated, but for a retrieval tool the resource identity is unambiguous. None of the sibling tools cover macro, so there is nothing to confuse it with.

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 explicit trigger phrases ("how is the US economy", "macro regime", "risk-on or risk-off") that map directly to the tool's domain. There are no competing siblings to route away from, so no exclusions are needed. It does not state when NOT to use it, keeping this just below a 5.

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

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

Annotations already establish read-only, non-destructive, open-world behavior. The description adds meaningful context beyond them: prices are live and "never estimated," the data is free and needs no key, and it enumerates the payload (each leg's price, volume and link, seat holder and rating, forecaster bands, race page) in the absence of an output 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?

Front-loads the use case, then the data scope, then the payload and cost guarantees. Dense but every clause carries information; the long enumeration of returned fields is the only mildly run-on element.

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 one-parameter, no-output-schema tool this covers everything an agent needs: what it fetches, the accepted race identifiers, the races in scope, that prices are live rather than modeled, and that no key is required.

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% and the single parameter's description already lists state name/code, slug, and district formats. The description repeats the same examples ("TX-34") without adding syntax, matching, or ambiguity-resolution rules, so it neither compensates nor regresses — baseline 3.

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?

States a concrete verb and resource: live Kalshi odds for one 2026 Senate, governor, or competitive House race. Scoping to a single race clearly separates it from map-level siblings like senate_map, and the sample queries ("who wins the Kansas Senate race") make the intent unambiguous.

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?

Opens with explicit "Use for" trigger phrases, giving clear context for when this tool is the right pick. It stops short of naming alternatives or exclusions (e.g. when to use senate_map instead of a single-race lookup), which is the only missing piece.

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

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

Annotations already declare readOnly/openWorld/non-destructive, so the safety profile is covered. The description adds genuinely new behavior: prices are never estimated, unpriced seats return null, results are sorted closest race first, and no key is required. That is meaningful context beyond the annotations, though return pagination or rate limits are unmentioned.

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?

Front-loaded with the trigger phrases, then a compact enumeration of returned fields, the null-pricing rule, sort order, and free/no-key status. Every clause carries information; no filler.

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, the description carries the burden of explaining return shape, and it does: field list, closest-race-first ordering, null for unpriced seats, and per-seat URLs. An agent has everything needed to call and interpret the result.

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 tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. No parameter-level guidance is needed or missing.

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?

States a specific resource (2026 Senate map, every seat) and enumerates exactly what each seat carries: holder/role, structure rating, forecaster bands, live Kalshi price, and a per-seat page URL. It is immediately distinguishable from adjacent tools like race_odds by being a full-map enumeration rather than an odds lookup.

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?

Gives explicit trigger phrases ("2026 Senate map", "which Senate seats are toss-ups") that map intent to tool cleanly. It stops short of naming an alternative or exclusion (e.g., when to prefer race_odds for a single market), so it is clear context without routing rules.

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