Parlay

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

Annotations already provide readOnlyHint=true and openWorldHint=true. The description adds useful behavioral context (e.g., returns match confidence buckets, explains mismatches) without contradicting annotations. However, it could further detail the matching algorithm or data freshness.

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 three sentences long, with no redundant phrases. It efficiently states the action, usage scenarios, and key exclusions, making it easy to scan.

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?

The description covers what the tool does, when to use it, and what it returns (confidence buckets, explanations). However, given the absence of an output schema, more detail about the exact fields in the response (e.g., probability values, liquidity numbers) would improve completeness.

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 has 0% description coverage, so the description must compensate. While 'query' is implicitly tied to the event being compared, and 'limit' has schema constraints, neither parameter is explicitly described in the description. This omission reduces clarity for an agent unfamiliar with the tool.

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 uses a specific verb ('Compare') and clearly identifies the resource (event contracts across Polymarket, Kalshi, and Limitless). It details what is compared (probability, liquidity, etc.) and distinguishes from siblings by explicitly excluding Manifold and mentioning real-money venues only.

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 explicitly states when to use the tool ('when the user wants to know spread...') and provides an exclusion criterion ('Manifold is excluded because play-money pricing isn't comparable'). This gives clear guidance on appropriate use cases.

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 openWorldHint=true. The description adds value by specifying the types of markets returned (trending, high-volume, etc.) and the platforms included (Polymarket, Kalshi, etc.). No contradiction with 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?

Highly concise with three sentences. The first sentence states the core purpose, the second gives usage context, and the third lists filters/sorts. Every sentence earns its place with no wasted words.

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?

Covers the purpose, usage, platforms, and filter/sort options. Missing explicit mention of the return format, but given the readOnlyHint and openWorldHint, this is a minor gap. Overall well-rounded for a browsing tool.

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 must compensate. It mentions category filtering and sort options (volume, newest, ending_soon), adding meaning to 'category' and 'sort_by' parameters. However, it does not explain 'limit' or 'real_money_only', leaving some gaps.

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 browses trending, high-volume, fast-moving, or high-disagreement markets across multiple platforms. It includes specific user intent examples and distinguishes from specific topic search, which is handled by sibling search_markets.

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?

Explicitly says 'Use when the user wants to explore what's happening — rather than search a specific topic,' providing clear context. However, it does not explicitly name the alternative sibling tool (search_markets) in the description, though it implies it.

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 openWorldHint=true. The description adds value by specifying the return type: 'available capabilities, market data for the query, and metadata quality flags.' This goes beyond the annotations. However, it does not cover edge cases like missing venues or error behavior, but the annotations cover the core safety profile.

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 three sentences, with the first sentence immediately stating the action and output. Every sentence contributes: output, usage guidance, and alternative tools. 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?

The tool has 3 parameters and no output schema. The description covers purpose, usage, and high-level output. It lacks parameter explanations and details about response structure, but given the annotations and the clear use case, it is largely sufficient for an agent to select and invoke the 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?

Schema coverage is 0% (no parameter descriptions in the schema), and the description does not elaborate on any parameters. The tool name and description imply 'platform' and 'query' are needed, but 'limit' is not mentioned. Given the 0% coverage, the description should provide more detail, but it does not.

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 uses the specific verb 'inspect' and identifies the resource as a 'single named venue.' It clearly distinguishes the tool from siblings by stating it is for single-venue queries, which is reinforced by the examples. This is a strong, specific purpose statement.

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 explicitly tells when to use the tool: 'when the user explicitly names a venue.' It provides concrete example queries and directly contrasts with alternatives ('For cross-venue queries use search_markets or compare_markets'). This is excellent guidance.

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 provide readOnlyHint=true and openWorldHint=true. Description adds useful behavioral details: returns top markets by volume, cross-venue divergences, venue coverage, and risk flags. No contradiction with 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?

Two sentences, front-loaded with purpose, then usage examples, then output summary. Every word adds value, no 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?

No output schema, so description must describe return structure. It covers top markets, divergences, coverage, risk flags. Missing details like pagination or ordering, but sufficient for most use cases given the complexity.

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 only 25% (only min_volume has a description). Description does not explain limit, topic, or real_money_only beyond what the schema provides. For example, it doesn't specify that topic is the query string or that real_money_only filters out Manifold.

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?

Description clearly states the tool generates a synthesized brief by combining signals from multiple venues (Polymarket, Kalshi, Limitless, Manifold). It distinguishes itself from sibling tool search_markets by explicitly noting the difference.

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 examples (analytical queries like 'what do markets think about the 2028 election') and when-not (for raw market lists use search_markets), giving clear guidance on alternative tool selection.

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?

Goes beyond annotations (readOnlyHint, openWorldHint) by explaining that results are indicative, not trade recommendations, that pairs with missing volume are flagged 'volume_unconfirmed', and that orderbook depth is not confirmed in Phase 1. No contradiction with 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?

Description is appropriately sized and front-loaded with core purpose. Every sentence adds value—threshold explanation, parameter guidance, limitations, flags. No fluff or repetition.

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?

Given 4 parameters, no output schema, but annotations present, the description is highly complete. It covers all parameters, explains result nature, flags, limitations, and provides enough context for correct tool 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?

Adds significant meaning beyond schema descriptions: explains default spread relative to fees, raises threshold for tradability, clarifies query is a post-filter, describes volume_unconfirmed flag for min_volume. Schema coverage is 75%, and description compensates thoroughly.

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?

Clearly states it surfaces cross-venue price discrepancies between specific venues (Polymarket, Kalshi, Limitless) as a discovery feed for price discovery and divergence detection. Distinguishes from siblings like 'discover_markets' and 'search_markets' which are for topic-driven retrieval.

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?

Explicitly explains default threshold (0.5% spread) and that most results are informational, not tradable. Advises raising min_spread to 0.03+ for after-fee opportunities. Warns that the query parameter is a post-filter, not a topic search, and directs to alternatives for topic-driven retrieval.

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 (readOnlyHint, openWorldHint) are present; description adds return field details (title, probability, volume, etc.) and scope across venues, but no contradictions.

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 concise sentences front-loaded with purpose, each sentence adds value; no redundancy.

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?

No output schema, but description details return fields and use cases; lacks pagination or error handling but sufficient for a search tool.

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 has 0% description coverage; description does not explicitly explain each parameter (query, limit, real_money_only) beyond what schema implies, leaving gaps for an AI agent.

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?

Description clearly states it searches prediction markets across multiple venues, lists example queries, and distinguishes siblings (market_brief, discover_markets).

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?

Explicitly specifies use cases (election odds, political markets, etc.) and provides alternatives: use market_brief for synthesis, discover_markets for trending.

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