PredictionScan

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

Annotations already establish readOnly/idempotent semantics, yet the description adds substantial non-obvious behavior: the day/week/month profit figures include open positions at current prices whereas all-time is realized only, and per-category volume is null because Polymarket doesn't publish it. Those are exactly the caveats an agent would otherwise misinterpret when reporting numbers.

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 triggering use cases before the return details and caveats, so an agent can decide early. It runs long, and the two closing prohibition sentences overlap with each other and partly restate readOnlyHint, which is the only wasted space.

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 4-parameter, all-optional, enum-driven read tool with an output schema, everything needed to call and interpret it is present: defaults, return fields, period definitions, and the category/volume caveat. Nothing material 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?

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning well beyond the schema: it explains the accounting difference between period values (open positions at current prices vs realized-only all-time) and the null-volume consequence of category boards. Limit and metric are only restated from the schema, so it stops short of a 5.

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 verb and resource: ranks Polymarket traders by profit or volume. It distinguishes itself from siblings like get_trader_profile and get_trader_positions by scoping to the aggregate leaderboard, and the concrete example queries remove any ambiguity about the resource.

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?

Explicit when-to-use triggers are given with example phrasings ("top Polymarket traders this month", "highest-volume traders this week"), and there are explicit when-not clauses: don't use it to pick a market/trader to invest in, and don't call it for buy recommendations. The alternative for choosing markets is implied by the sibling set rather than named, but the exclusions are unusually clear.

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?

Beyond the readOnly/idempotent annotations, it discloses non-obvious behavior: dollar totals count each fill once so they run roughly half of headline two-sided volume, and small fills may be dropped in busy markets with the text saying so. It also confirms read-only semantics and warns that flow is descriptive rather than predictive.

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 usage triggers are front-loaded before the mechanics, and each sentence carries information (input forms, aggregation rule, truncation caveat, read-only note). It is long and dense, but it is not padded or repetitive.

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 input forms, resolution fallbacks, time window, return contents (net per outcome, trade count, up to 8 largest trades, up to 5 holders), and known data caveats. With an output schema present, nothing an agent needs in order to call it correctly 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?

Schema coverage is 100%, so the baseline is 3, but the description goes further: it enumerates the accepted 'market' forms (slug, supported market/event link, condition id, plain words) and explains the multi-outcome and ladder-rung resolution rule, plus the 1-168 hour window with a 24 default. This is genuinely additive over the schema text.

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 (Polymarket market money flow) with four concrete user-question examples that pin down the exact intent, including 'who is buying Yes on the Fed October decision' and 'who holds the most of this market'. It is clearly separable from siblings like get_market_odds or get_price_history, which answer price rather than flow questions.

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 opening clause gives explicit triggering conditions tied to user phrasings ('who is buying or selling', 'why its odds moved', 'where the money is going'), which is strong guidance. It does not, however, say when to prefer siblings such as get_whale_trades or get_trader_positions, so a bit of overlap remains unaddressed.

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/idempotent/non-destructive, but the description goes well beyond them: it discloses the ranking metric and unit (24-hour change in points), the cap of 20 results and at most two outcomes per event, the coverage universe (300 most-traded markets with ≥$10K 24-hour volume), and exclusion thresholds (markets at ≤1% or ≥99%, individual sports/esports games, mature topics, uncategorized Up-or-Down and tweet-count markets). These constraints materially change what an agent should expect to see and cannot be derived from the structured fields.

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 activation condition and example queries, then moves to return shape, then to inclusion/exclusion rules — a sensible order. The exclusion clauses (sports games vs futures, mature topics, Up/Down and tweet-count markets) are individually informative but accumulate into a dense block, and the "not advice" and "do not use this to choose a market" sentences partly overlap.

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 an output schema exists (so return values need no explanation) and annotations cover the safety profile, the description still supplies everything an agent needs to call and interpret it correctly: what is ranked, the unit of change, the result cap, the deduplication rule, and the universe/exclusion boundaries. No material gap remains for a read-only, three-optional-parameter listing 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 100%, so limit, category and direction are already self-documenting, and the description only restates them collectively as "Optional filters: direction and category." It adds no extra syntax, interaction, or default behavior beyond what the schema and enums already convey, 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?

States a specific verb and resource — returns Polymarket markets ranked by 24-hour change in market-implied probability — and the example user questions ("biggest movers", "what odds are dropping in crypto") pin down the intent precisely. It never names its closest sibling get_trending_markets, so the agent must infer the trending-vs-movers boundary from the ranking metric alone, which keeps it short of a 5.

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 opening "Use this when the user asks..." clause plus four concrete example utterances give clear activation conditions, and the closing lines explicitly exclude using it to pick a market or trader to invest in. However, the exclusions are about financial advice, not about routing to alternatives — no sibling tool (get_trending_markets, get_market_flow, get_price_history) is named for cases this tool does not cover.

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 cover the safety profile (readOnly, idempotent, non-destructive, openWorld), and the description adds substantive context beyond them: a 14-day freshness window, max 10 / default 5 results, ranking by key-name and term overlap with newest-first tiebreak, and the outlet/time/link payload. It also discloses the feed's coverage limits (politics, economy, crypto, sports, entertainment) and that no article text is returned.

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 routing condition, then parameters, then return shape, then limitations — a sensible order with no filler sentences. The four quoted example queries are helpful for matching but make the opening more verbose than a shorter trigger summary would be.

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 a read-only, open-world retrieval tool with three optional parameters and an output schema, the description covers trigger conditions, input forms, result count and ranking, freshness window, and the main failure mode (no results for niche markets). Nothing an agent needs to call it correctly or set expectations 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?

Schema coverage is already 100%, so this is a bonus: the description clarifies that market accepts a slug, a supported market or event link, and that plain words are treated as a topic, and that query combined with market narrows that market's news rather than searching globally. The default of 5 for limit is repeated from the schema rather than added to.

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 verb and resource ('get news/headlines for a prediction market or topic') and enumerates the trigger phrasings an agent would hear. No sibling tool does news retrieval, so intent separation from search_markets, get_market_odds etc. is 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 an explicit 'Use this when the user asks for news, headlines or recent developments' condition plus four realistic example utterances, and names search_markets as the source of slugs. It also states the when-not: it is not a full web search and may return nothing for niche markets.

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?

Adds substantial behavior beyond the annotations: works for open/closed/resolved markets, caps at up to 40 outcomes with mutually exclusive ones ranked, and falls back to up to 3 nearest open markets on no match. Also discloses framing caveats (crowd forecasts, not advice) that the readOnlyHint alone would not convey.

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 condition, then inputs, then returns, then exclusion — a logical order with no filler sentences. It is dense and long for one parameter, and the return-field enumeration partially duplicates the output schema.

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 resolution rules, status, fallback behavior, and limits (40 outcomes), so an agent knows what it will get and what to do when a query misses. Slightly over-complete on return fields given an output schema exists, but nothing an agent needs 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?

Schema coverage is 100% and the schema already enumerates slug, link, condition id, and question-in-words for the single `market` parameter, so the description largely restates it. Baseline 3 applies; no new syntax or normalization detail is added.

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 verb+resource (get current odds / details of one market or event) and scopes it to a single market, which clearly separates it from sibling list/aggregate tools like search_markets, get_trending_markets, and get_market_flow.

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 concrete trigger phrasings ("what are the odds for the Fed decision", "show me this market", "did the 2024 election market resolve") and an explicit exclusion ("Do not call this when the user asks which market to buy"). It stops short of naming the alternative sibling tools for the excluded cases, so routing is implied rather than explicit.

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 read-only, idempotent, non-destructive behavior, but the description adds meaningful operational context: data comes from Polymarket's order-book history, quiet markets can have gaps that are left unfilled, and closed/resolved markets end at trading close. It also states that the output includes a chart in the card and clarifies the tool is informational, not advice.

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 front-loaded with the primary use case, followed by input forms, return values, and caveats in a logical order. Despite being one dense paragraph, every sentence contributes useful selection or invocation context and there is 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?

Given that an output schema exists and annotations cover safety traits, the description is complete: it explains the use case, accepted inputs, default range/outcome behavior, returned metrics, data provenance, gap behavior, and closed-market edge cases. An agent has enough information to select and call 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 description coverage is 100%, so the schema already documents market, outcome, and range thoroughly, including defaults and enum values. The description reinforces accepted market forms and time ranges, but adds little parameter-level detail beyond the schema; 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 states a specific resource and operation: it retrieves a prediction market's price/odds history over time, and it explains exactly what the return contains (start/end probability, change, high/low, chart). The examples and scope make it clearly distinguishable from siblings such as current-odds or market-flow tools.

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 an explicit triggering condition — 'Use this when the user asks how the odds ... have changed over time' — and illustrates it with several concrete query examples. It does not explicitly name when not to use it or point to alternative siblings for current odds versus historical odds, so it falls short of a full 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 only declare the read-only, idempotent, non-destructive profile; the description adds substantive behavior: cap of 50 with default 20, sort semantics, exclusion of sub-$1 and resolved positions (with a note in the text), and inclusion of totals and portfolio value. That is well beyond annotation coverage.

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 usage trigger is front-loaded and the sentences are dense with concrete facts. The return-value sentence is long and enumerates fields already covered by the output schema, which is mild redundancy, but nothing is 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 three-parameter read tool, the description covers triggering, input forms, result shape, size limits, sorting, and exclusions. An agent can call it correctly without inspecting the schema or output schema.

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, but the description adds value by enumerating the accepted trader identifier forms (0x address, profile URL, @username, username) and by tying natural-language intents like 'biggest position' and 'up the most' to the sort options. It still doesn't add formatting rules or edge-case handling 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?

States a specific verb and resource ('a Polymarket trader's open positions or holdings') and backs it with concrete user-style queries. It is clearly distinct from siblings like get_trader_profile (identity/aggregate) and get_whale_trades (market-wide activity).

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 strong when-to-use signal via four representative example questions, including 'biggest position' and 'up the most'. It does not name a sibling alternative or state when not to use it (e.g., profile/summary requests should use get_trader_profile), so it falls short of the top mark.

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?

Beyond the read-only annotations, it discloses important behavior: username matching prefers exact matches and falls back to the closest public profile with explanatory text. It also clarifies that the data is public on-chain data and does not identify wallet controllers, which is valuable operational context.

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 front-loaded with the primary usage condition and then lists accepted inputs and return contents. It is longer than necessary in places, but the examples and matching caveat are relevant to correct invocation.

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 the single well-documented parameter, rich annotations, and an output schema, the description is complete enough for an agent to select and call the tool correctly. It covers accepted inputs, return contents, matching behavior, and key limitations.

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 parameter is already documented. The description still adds useful semantics by restating accepted identifier formats and explaining the exact-vs-fallback username matching behavior.

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 verb and resource: it retrieves a Polymarket trader profile from a wallet, URL, or username. It is clear about what it does, but does not explicitly differentiate itself from the sibling get_trader_positions tool, even though it returns a limited positions summary.

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 concrete user-intent examples for when to use the tool, such as asking about a wallet, a profile link, or a username. However, it does not explicitly say when to prefer alternatives like get_trader_positions for deeper position data.

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 well beyond the readOnly/openWorld annotations by disclosing result size (up to 20), ranking basis (24h volume), outcome truncation logic (up to four outcomes, leaders or price-ladder rungs nearest 50%), and multiple exclusion rules (settled-looking events at 99%+, game prop sheets, sports/esports singles unless that category is requested, Up or Down and tweet-count markets). It also frames the output as crowd forecasts, not advice.

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 conditions before the mechanics, which is the right order. It is dense and slightly repetitive at the end (the 'not advice' and 'do not use to choose a market' sentences overlap), but nearly every sentence carries filtering or scope 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?

Despite an output schema existing, the description still tells the agent what each returned event contains (probabilities, 24h change, volume) and what is deliberately absent, which is exactly the context needed to interpret a filtered feed. Nothing an agent needs to call or trust the result 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?

Schema coverage is 100%, so the baseline is 3, but the description adds real semantics: the category filter is optional and materially changes what is included (sports/esports singles appear only when that category is selected), and the limit is bounded at 20. It doesn't restate the enum values or the default of 8, but it does explain the behavioral effect of category.

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 verb+resource (returns trending Polymarket events ranked by 24h volume) and immediately scopes it against siblings like search_markets and get_market_movers by emphasizing 'trending/popular/hot' and a 24-hour volume window. An agent can distinguish it from get_market_movers and search_markets without opening any schema.

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 concrete trigger phrases ('what's trending on Polymarket', 'top crypto markets right now') plus explicit exclusions: do not use it to pick a market or trader to invest in, or when the user asks which market to buy. This is a full when/when-not contract.

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/idempotent/non-destructive, yet the description adds substantial context beyond them: fills at >=99¢ or <=1¢ are excluded, individual sports and esports games are excluded, each fill is counted once, and dollars equal shares times price. It also preempts misuse with 'a large trade is not a forecast, and these tools cannot place trades.'

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 use case and examples, which is the right ordering. It is a single dense paragraph that repeats defaults already present in the schema (limit 15, hours 24), which costs some tightness but nothing is genuinely off-topic.

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 filtered read tool with an output schema, all decision-relevant information is present: trigger conditions, exclusions, dedup and dollar accounting, filter formats, and the read-only guarantee. The return fields are described as well, so the agent can predict the response shape even without opening the output schema.

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 each parameter is documented, so the baseline is 3. The description goes slightly beyond by restating defaults and ranges in context (min size $1K–$1M default $10K, window 1–168 hours default 24) and by explaining that the market filter accepts slugs, supported links, condition ids, or plain words.

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 verb and resource ('Scans Polymarket.com's public trade feed and returns... largest fills') and scopes it with a minimum-size threshold. The four quoted example queries make the target intent unmistakable and separate it from siblings like get_leaderboard and get_market_flow.

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 an explicit 'Use this when the user asks about large or notable recent trades' trigger and gives concrete phrasings that should route here. It also names the inverse condition ('name a market to see its trades') that overrides the default exclusion of sports/esports and mature topics, so the agent knows how to escape the filter.

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 and non-destructive, and the description reinforces this while adding substantive context beyond the annotations: result cardinality (up to 10, default 5), outcome-selection ordering logic, inclusion of 24h change and volume, and the caveat that probabilities are crowd forecasts, not advice.

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 core trigger and the tool's output shape, with exclusions at the end. The eight worked examples are genuinely useful for routing but take considerable space; the definition could be trimmed without losing clarity.

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 two-parameter, read-only search with an output schema and full annotation coverage, the description covers triggers, output shape, sibling routing, and safety caveats. Nothing an agent needs in order to call it correctly 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?

Schema coverage is 100%, so the baseline is 3: the schema already documents both parameters, including the default of 5 for limit. The description adds modest value by clarifying the query should be an event/person/team/asset in plain words and by implicitly linking named outcomes to result ordering.

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 verb (search) and resource (Polymarket prediction markets), and explicitly distinguishes itself from the sibling that handles deep single-market lookups (get_market_odds). An agent can route between the two without opening a schema.

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 concrete trigger phrases ('odds', 'chances', 'what does the market say'), names the alternative for a different need (get_market_odds for full outcome lists, rules, resolution status), and states two explicit exclusions: don't use it to pick a market to buy or to advise on profit.

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