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

Annotations already establish readOnlyHint and idempotentHint, so the safety profile is covered. The description adds meaningful behavioral context by emphasizing that execution is an optional simulation for a given size)Skip, clarifying that no live order is placed despite the trading-economic terms, and by detailing the analytical outputs 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?

The description is dense but efficient, front-loading the core purpose and then listing specific, non-redundant breakdown elements. It is a long single sentence, but every item adds useful semantics; slight restructuring into a shorter introductory sentence plus details could improve scannability.

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 rich output schema, complete parameter descriptions, and thorough annotations, the description covers every significant capability an agent needs to decide if this tool is appropriate. It mentions fees, payoff, breakeven, ROI, ladder, depth, and optional simulation, with no critical usage context 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 each parameter already has a clear description, especially 'size' being an optional order size to simulate walking the book. The description reinforces the size-to-simulation relationship but adds no additional parameter meaning beyond what the schema provides, so 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 opens with 'Full spread + fee + payoff breakdown for one market,' naming a concrete resource and action. The itemized outputs (bid/ask/mid, spread, taker/maker economics, breakeven probabilities, ROI, ladder, depth, optional simulation) clearly distinguish it from simpler sibling tools like pmus_get_bbo or pmus_get_order_book.

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 makes it clear this is for a single-market, comprehensive analysis and implies it covers more than basic BBO or order-book tools. However, it never explicitly names alternatives such as pmus_line_ladder_check or says when not to use this tool, leaving the routing decision somewhat inferential.

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/idempotent annotations, the description discloses meaningful calculation behavior: fees are included, overround is computed, and locked P&L assumes buying every YES or shorting every market only when outcomes are mutually exclusive. This caveat is exactly the kind of behavioral nuance an agent needs.

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 with no filler: the first front-loads the action and outputs, the second states the purpose. Every clause earns its place.

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 output schema, annotations, and complete parameter descriptions, the definition is fully adequate. It states the scope, the core calculations, and the key validity condition, leaving no critical gap 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 coverage is 100%, and both event_slug and refresh_quotes already have clear schema descriptions. The tool description does not add parameter-specific semantics, 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?

Description opens with a specific action-resource pair ('Price the whole outcome set of an event') and then enumerates concrete outputs (sum of asks/bids after fees, overround, locked P&L). This distinguishes it from sibling tools that focus on single markets, order books, or settlements.

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 establishes a clear context: use for pricing an entire outcome set and surfacing mispricing across a spread family. It includes the important precondition that outcomes be mutually exclusive, though it does not explicitly name alternatives or state when not to use the tool.

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, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds the snapshot nature and lists the data fields, which gives some behavioral context beyond annotations. However, it does not elaborate on details like whether the data is real-time or delayed, or how 'depth counts' are calculated. It neither contradicts annotations nor adds substantial behavioral depth.

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 a single, front-loaded sentence that immediately states the tool's purpose and then lists the returned components. It is efficient and scannable, with no filler. The structure is clear and easy to parse.

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 an output schema present (not shown but indicated), the description need not detail return values. It lists the key data categories, making it clear what the snapshot contains. For a simple tool with one parameter and safe annotations, this is sufficient. Potential edge cases (e.g., nonexistent market) are not mentioned but are likely handled by errors.

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 for the only parameter (slug) is 100%, so the schema fully describes it as 'Market slug'. The description does not add any extra meaning to the parameter, but since coverage is complete, the baseline of 3 applies. No ambiguity is left.

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 returns a 'Best bid/offer snapshot' and enumerates the included fields (bid, ask, last trade, depth counts, open interest, long/short display quotes, market state). This is a specific verb-resource pairing that conveys the tool's function. It does not explicitly contrast with siblings like pmus_get_order_book, but the term 'best bid/offer' implies top-of-book vs full depth, so it is reasonably 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?

The description provides no guidance on when to use this tool versus alternatives such as pmus_get_order_book or pmus_get_settlement. There is no mention of scenarios, prerequisites, or exclusions. The agent must infer usage from the tool name and schema alone.

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, idempotentHint=true, and destructiveHint=false, so safety is fully covered by structured metadata. The description adds useful payload context ('all of its markets, rules excerpt, tags, and quotes') but does not disclose behaviors such as handling of invalid slugs, truncation of the rules excerpt, or absence of data.

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?

A single, front-loaded sentence conveys the verb, resource, and payload content without filler. Every word contributes to the agent's ability to select the tool, and the payload list is compact but informative.

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 a rich annotation set and an output schema present, the description does not need to explain return values in depth. It adequately identifies the resource and key data included, though a brief note about the meaning/usage of description_chars would make it fully complete.

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 50%: slug_or_id is documented in the schema, but description_chars has no description there. The tool description does not clarify how description_chars interacts with the returned data, even though 'rules excerpt' hints at a text-length control. The description therefore fails to compensate for the undocumented parameter.

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 starts with a specific verb ('Get') and a specific resource ('one event'), and enumerates the payload: markets, rules excerpt, tags, and quotes. This distinguishes it from siblings like pmus_get_market (a single market), pmus_list_events (plural), and pmus_get_order_book (market depth).

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 implies the right context: use this when you need a single event's full detail set (markets, rules, tags, quotes). However, it does not explicitly state when to prefer it over alternatives such as pmus_get_market or pmus_list_events, nor does it mention any exclusions.

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 convey readOnly, idempotent, openWorld, and non-destructive behavior, so the description only needs to add context. It mentions the bundled contents but does not explain side effects, rate limits, or truncation behavior around description_chars; this is an adequate supplement, not a rich one.

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?

A single succinct sentence with a colon-delimited list. The main action is front-loaded, and every phrase contributes content about scope or returned fields; no filler or 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?

Given the low parameter count, full schema coverage, safe annotations, and presence of an output schema, the description covers the essential selection and invocation context. It could be slightly more complete by noting that description_chars controls truncation of the rules text, but this is already in the parameter 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 description coverage is 100%, so the schema already documents both parameters. The description adds little beyond the schema: 'one market' reinforces slug_or_id scope and the output list hints at description_chars effect, but no extra format or behavioral parameter details are supplied.

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 verb and resource ('Get one market') and enumerates its returned contents (rules/settlement text, tick size, fee coefficient, sides, quotes). The singular 'one market' distinguishes it from list/search siblings, and the content list differentiates it from focused siblings like get_settlement or get_bbo.

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?

No explicit guidance on when to use this tool versus alternatives is provided. The description only implies use for fetching a single market's detailed static data; it does not name exclusions or direct the agent to a sibling such as pmus_get_settlement or pmus_list_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?

Annotations already establish readOnly/idempotent/non-destructive behavior, so the description only needs to add context. It adds useful output-ordering context ('best first') and field composition, but it does not describe any auth/permission or rate-limit traits, nor does it clarify the vague 'market stats' beyond the 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?

Single front-loaded sentence with no filler. It delivers the core purpose and output composition in under 20 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?

For a read-only two-parameter tool with a full output schema and annotations, the description is largely complete. It leaves some room by not saying when to prefer this over pmus_get_bbo, but the structured signals carry the rest.

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 documents slug and depth, including default, min, max, and per-side meaning. The description adds no extra parameter semantics beyond this, so the baseline of 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 names the resource ('order book') and the payload details (bids/offers, per-level price/quantity, cumulative size, market stats), so an agent can tell what it returns. It does not explicitly contrast it with sibling tools like pmus_get_bbo, so it stops short of full sibling differentiation.

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?

There is no explicit when-to-use or when-not-to-use guidance, and no alternative tool is named. The only signal is the content description, which implies full order book depth versus BBO or history, but leaves the selection decision to inference.

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 the operation read-only, idempotent, and non-destructive. The description adds important behavioral context by explaining how short prices are calculated and by warning that the gateway currently returns empty history for many markets, which helps set expectations.

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 sentences with no filler. The core purpose is front-loaded, and the caveat about empty history is presented separately without cluttering the primary definition.

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 annotations cover safety and idempotency, and an output schema exists, the description provides enough context for calling the tool: what it returns, how prices are defined, and a key practical caveat. It does not fully explain parameter selection trade-offs, but those are reasonably documented in the 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 description coverage is 67%, so the schema already documents most parameters. The tool description does not add meaningful detail about param semantics beyond the schema, though it does clarify the nature of the returned price series.

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 retrieves historical long and short prices, with specific definitions of how they are derived from best ask and best bid. This distinguishes it from current-quote siblings like pmus_get_bbo and order book 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?

The word 'Historical' implies this is for past prices rather than current market state, and the sibling list includes plausible alternatives. However, there is no explicit 'use this when' or 'use X instead' guidance, so the agent must infer the appropriate context.

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, and non-destructive behavior. The description adds valuable behavioral detail: it communicates the settled=false case and the exact settlement values, going beyond what annotations alone provide. No contradictions found.

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 short sentences convey the tool's purpose, output values, and unsettled behavior with no redundant phrasing. The settlement value mapping is front-loaded for quick comprehension.

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 simple one-parameter getter with an output schema and safety annotations, the description is complete. It covers the meaningful edge case (unsettled market) and the value semantics an agent needs to 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?

Schema coverage is 100%, with the only parameter 'slug' described as 'Market slug'. The description does not add further detail about slug format or accepted values, but since the schema fully documents the parameter, the baseline of 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 clearly identifies the tool as returning settlement results for a closed market and explicitly defines the three possible values (1, 0, 0.5). This distinguishes it from sibling tools focused on prices, order books, or market discovery.

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 states it applies to a closed market and clarifies behavior when the market has not settled yet, providing clear contextual usage. It does not explicitly name sibling alternatives or exclusions, but the context is sufficient for an agent to select this tool over market data tools.

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, and non-destructive behavior. The description adds valuable context beyond that: the exact pricing rule, the arbitrage execution logic, the after-fee consideration, and the types of reported results. It also discloses that snapshot quotes can lag, supporting the refresh_quotes parameter.

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 concise, front-loaded with the core purpose, and every sentence carries information: the rule, the arbitrage condition, the outputs, and the quote freshness caveat. There is no filler or 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?

With an output schema present and all parameters documented in the input schema, the description covers the key behavioral aspects an agent needs to invoke the tool correctly. It could add an explicit usage note about when to prefer sibling tools, but for the tool's complexity it is essentially complete.

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 parameters are fully documented in the schema itself. The description does not add much parameter-specific meaning beyond the schema, but it reinforces the event context (spread and total lines). It meets the baseline for high schema coverage.

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 identifies the resource (an event's spread and total ladders), the action (checking for impossible pricing), and the specific arbitrage condition (harder line bid above easier line ask). It also names concrete outputs (locked P&L, size at touch, label conflicts), distinguishing it from generic market scan 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?

The description implies when to use the tool (when checking for mispriced ladders and arb opportunities) but does not explicitly mention any alternative tools or when not to use it. There are sibling tools like pmus_analyze_spread and pmus_scan_extreme_markets that overlap in intent, so clearer routing would improve this dimension.

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 provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, which cover safety and side-effect transparency. The description adds useful context by stating that each event includes its markets with best bid/ask and implied probability, which is beyond the schema. It also implies the response includes pagination and filtered data. However, it doesn't disclose pagination limits beyond 'offset' or the default response size, but the schema covers defaults.

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, all relevant. It front-loads the primary purpose, then provides a key output detail (each event includes markets with best bid/ask and implied probability), and ends with a useful pagination hint. No waste.

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 12 parameters, all optional, and an output schema. Given the output schema exists, the description doesn't need to explain return values. The description covers the essential behavior (listing events with filters, pagination, and market data). It is incomplete in that it doesn't explain the relationship to pmus_list_markets or detail the pagination mechanics fully, but for a list tool with rich schema, this is adequate.

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 50%, with 6 out of 12 parameters having descriptions (category, order_by, tag_slug, end_date_max, end_date_min, description_chars). The description adds value by naming the tool's core output (markets with bid/ask and implied probability) but does not explain parameters like active, closed, offset, or series_id beyond what the schema titles provide. Since coverage is moderate (50%), the description partially compensates but not fully.

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 ('List'), the resource ('events'), and the key capability ('filters and pagination'), which distinguishes it from siblings like pmus_get_event (which retrieves a single event) and pmus_search (which likely searches events). However, it doesn't explicitly differentiate from pmus_list_markets, which could be a sibling with overlapping functionality, and the filtering details are only implied.

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 mentions 'filters and pagination' and specifically says to use 'offset to page', which gives some guidance on when to use this tool. However, it doesn't explicitly state when NOT to use it or mention alternatives like pmus_search for more complex queries. The sibling context suggests pmus_search might be the alternative for extensive filtering, but the description doesn't name 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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: the flat (non-grouped) response shape and the unreliability of the eventSlug filter. It doesn't describe pagination or response format, but the output schema exists and the annotations carry the safety burden, so a 4 is appropriate.

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 with no filler. The primary behavior is front-loaded, and the alternative recommendation is placed second. Every word earns its place.

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 list tool with an output schema and rich annotations, the description covers the key decision point (flat vs. grouped) and the known pitfall (eventSlug filter). It doesn't mention pagination or default ordering, but those are partially encoded in the schema defaults. The only real gap is that it doesn't explain what 'flat' means in terms of the response structure, but the output schema likely covers that.

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 carries no parameter-level detail. However, the schema itself is fairly self-explanatory (limit, active, closed, offset, category, order_by, order_direction, description_chars) with defaults and constraints. The description adds no parameter semantics beyond the schema, 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 states a specific verb ('List') and resource ('markets'), and immediately clarifies the flat vs. grouped distinction. It also names the preferred alternative (pmus_get_event) for event-specific markets, which distinguishes it from sibling tools without needing to inspect 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?

The description explicitly says when to use this tool (for a flat list of markets) and when not to (for an event's markets, prefer pmus_get_event). It also warns that the gateway's eventSlug filter is unreliable, which is a concrete exclusion that helps an agent avoid a known failure mode.

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, openWorldHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds only semantic context ('recurring groupings') and examples; it does not disclose any additional behavioral traits such as live data, default pagination, or changes between calls.

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 a single front-loaded sentence with concrete parenthetical examples and no filler. Every phrase earns its place.

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 simple list operation with two conventional optional pagination parameters, an output schema, and rich annotations covering read-only/idempotent/open-world behavior, the description provides enough to call the tool correctly. The main omission is usage routing, but that is already captured in the usage_guidelines score.

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% and neither limit nor offset is mentioned in the description. The names and schema constraints are conventional, and 'List series' implies a paginated collection, but the description does not actually compensate for the missing parameter documentation.

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 and resource ('List series') and clarifies what a series is with concrete examples like 'nfl-2025' and 'fed'. It is clear at the resource level, though it does not explicitly differentiate itself from sibling list tools such as pmus_list_events or pmus_list_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?

No guidance is provided about when to call this tool versus alternatives, no exclusions are given, and there is no mention that list_series can be used as a discovery step before querying events or markets. The intended context must be inferred entirely from the name and examples.

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, openWorldHint, idempotentHint, and non-destructive behavior, so the description carries a light burden. It adds that results include tag and series IDs, but doesn't describe filter behavior, data freshness, or any other runtime traits beyond that.

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 a single, front-loaded sentence with no wasted words. It states the verb, the resource, and the key output fields efficiently.

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 an output schema and strong annotations present, the description covers the core purpose well. However, it leaves the meaning of the operational_only parameter unexplained, which is a meaningful gap for a simple one-parameter 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?

There is one parameter, operational_only, with no schema description and 0% description coverage in the tool description. The property name provides a weak hint, but the description never explains what 'operational_only' controls or how it affects the returned sports/leagues.

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 ('List') and resource ('sports/leagues supported by Polymarket US') and distinguishes this tool from siblings like pmus_list_events and pmus_list_markets by including 'tag and series ids'. This is clear and immediately actionable.

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 makes it clear this tool is for retrieving supported sports/leagues, which implies when to use it. It does not explicitly name alternatives or exclusions, but the resource scope is obvious enough among the sibling list tools.

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, idempotentHint, and non-destructive. The description adds that fetching a single tag includes its subtags, which is behavioral detail not in annotations. However, it doesn't discuss pagination, ordering, or response format beyond what the output schema likely covers. Given annotations cover safety, a 3 is appropriate.

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 with no redundancy. The core purpose is stated first, and the usage hint follows. Every word earns its place. 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?

For a simple list/fetch tool with an output schema and safety annotations, the description is mostly adequate. However, the lack of any mention of limit/offset behavior is a gap, especially since the schema doesn't describe them either. The description also doesn't clarify whether limit applies to list mode only or also to single-tag fetch. More detail on pagination would make it complete.

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?

Only the slug parameter has a schema description; limit and offset have none. The tool description doesn't explain these parameters either. With schema description coverage at 33%, the description should compensate but doesn't, leaving agents to infer pagination semantics from type constraints alone. This is a significant gap.

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's function: list all tags or fetch a specific tag with its subtags. It names the specific resource (tags) and the verbs (list/fetch). It also mentions the downstream consumer pmus_list_events, which distinguishes it from other list tools like pmus_list_sports or pmus_list_series.

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 provides a concrete use case: tag slugs feed into pmus_list_events(tag_slug=...). This tells the agent when to use this tool (to get slugs for events). It doesn't explicitly exclude alternatives, but given the sibling names, it's clear this is the tool for tags. Lacks explicit 'when not to use' but context is sufficient.

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, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: it uses 'event snapshot quotes' (not live order book), computes fee-adjusted annualized yield, and explicitly warns to confirm with pmus_analyze_spread before acting. This goes beyond the annotations and helps the agent understand the data source and the need for verification.

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, each earning its place: the first defines the scan scope and criteria, the second details the computed metrics, and the third gives a critical usage warning. It is front-loaded with the core purpose and avoids fluff. No redundant repetition of schema or annotation 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?

The tool has 9 parameters, an output schema, and rich annotations. The description covers the purpose, the key thresholds, the computation logic, and the confirmation step. It doesn't explain the output schema in detail, but the output schema exists and the description doesn't need to. The only minor gap is that it doesn't explicitly state what the return format is, but the output schema covers that. Overall, it is complete enough 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 description coverage is 67%, so the schema documents most parameters. The description adds meaning by explaining the core thresholds (high_threshold, low_threshold) in terms of 'heavy favorites' and 'long shots', and by clarifying that the scan is over 'event pages of 100' (which maps to the pages parameter). It doesn't document every parameter, but the key ones are given semantic context 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 states a specific verb ('Scan'), a specific resource ('active markets'), and a precise selection criterion ('extreme implied probabilities' with heavy favorites and long shots defined by thresholds). It also names the sibling tool it is not (pmus_analyze_spread) and explains the computed outputs (fee-adjusted yield to settlement, spread width, resting vs crossing). This clearly distinguishes it from the other pmus_* 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?

The description explicitly says to use pmus_analyze_spread to confirm before acting, which is a clear when-to-use/alternative guidance. It also implies this is a scanning/screening tool for finding opportunities, not for execution or detailed analysis. The context of 'active markets' and the thresholds make the intended use case 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?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, so safety is covered. The description adds behavioral context: it returns 'compact' summaries with 'current best bid/ask', which tells the agent the output granularity and live pricing, and scopes to 'US events'. This goes beyond what annotations alone provide.

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 action, and every clause earns its place. The first sentence states the function; the second explains the return format and purpose. No redundancy or 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 the existence of an output schema, the description does not need to detail the return structure. It covers the main parameter (query), the scope (US), the nature of results (compact, with bid/ask), and the follow-up intent. It omits any mention of limit/status nuances, but those are documented in the schema. It is sufficient for an agent to invoke 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 only 33% (only query has a description). The tool description clarifies that query is a free-text search, aligning with the schema example. However, limit and status receive no additional explanation; their defaults and enum are in the schema, but the description does not compensate for the low coverage by explaining their semantics or typical use. This is acceptable but not outstanding.

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 ('Search'), a resource ('Polymarket US events'), and a clear outcome ('returns compact event + market summaries with current best bid/ask'). It also explains the downstream use ('pick a market slug for deeper tools'), which distinguishes it from the list/get siblings like pmus_list_events and pmus_get_event.

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 implies the primary use case: when you have free-text input and need to identify a market slug for further investigation. It does not explicitly name alternatives or exclusions, but the phrase 'so you can pick a market slug for deeper tools' signals it is a precursor, not a terminal analysis tool. This is clear enough for an agent to know when to reach for it.

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