predictionguard

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

Discloses delegation to AMLOracle and a usage rule (cite source, never attribute). Without annotations, the description provides some behavioral context but lacks details on errors, limits, 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?

Two concise sentences, front-loaded with the core function, no unnecessary 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?

Adequate for a simple tool with no output schema, but missing details on output format and how results integrate into evidence chains.

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 description adds minimal value beyond the parameter descriptions. The context of adverse media scan gives background but does not explain parameter usage.

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 'adverse media scan' and lists types of negative news. It is distinct from siblings like pep_check_entity or sanctions_screen_entity, but does not explicitly differentiate.

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?

Implied usage as a building block for evidence chains, with a note to cite sources. No explicit when-to-use or alternatives compared to siblings.

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?

No annotations provided, but the description explains the scanning logic (top markets by volume, keyword matching) and output details (severity, categories, volume). It does not specify caching or real-time behavior, but overall is transparent.

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, no wasted words, well-structured with bullet-like listing of categories and return fields.

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 explains return values (severity, categories, keywords, volume). Does not detail error handling or pagination, but sufficient for a simple scan tool with two optional params.

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 covers both parameters with descriptions; description adds context that limit defaults to 25 and max 100, and categories are applied during scanning, enhancing understanding beyond 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 clearly states the tool scans top Polymarket markets by 24h volume and flags those matching sensitive-keyword categories, listing categories and return fields. It distinguishes from siblings by mentioning pairing with pg_insider_signal_scan.

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?

Indicates 'daily compliance triage' usage and recommends pairing with another tool for active surveillance, providing clear context for when to use 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?

No annotations are provided, so the description carries the full burden. It clearly describes the tool as a read-only aggregation (dossier), implying no side effects. However, it does not explicitly state that it is non-destructive, mention authentication needs, or specify rate limits.

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, well-structured sentence that front-loads the core concept ('Complete forensic dossier') and enumerates key components concisely. Every part adds value without unnecessary 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?

Given the tool's complexity (bundling multiple data types) and the absence of an output schema, the description adequately outlines the dossier's components and intended uses. However, it could be improved by hinting at the output format (e.g., structured report or text) to set expectations.

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?

Both parameters ('id' and 'slug') have descriptions in the schema (100% coverage), so the baseline is 3. The description does not add additional meaning beyond what the schema provides, such as which parameter to prefer or their relationship.

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 purpose: producing a 'complete forensic dossier' for a single Polymarket market. It lists specific components (market details, integrity scan, volume anomaly profile, Trust Layer provenance trace), distinguishing it from sibling tools like pg_market_details or pg_market_integrity_scan that provide only individual pieces.

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 use cases ('ready for manual review, press inquiry, or as input to a SAR report'), providing context for when to use the tool. However, it does not explicitly exclude situations where individual tools might be preferred or mention alternatives.

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?

No annotations provided; description compensates by detailing computation (weights, bonuses), output format (letter grade, score 0-100, component scores, interpretation guide), and references to known cases. Good disclosure of statistical nature, though does not discuss permissions or rate limits.

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?

One informative paragraph, front-loaded with purpose, includes essential details without extraneous text. Well-structured for quick parsing.

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 no output schema, the description explains all return elements (grade, composite score, components, guide). Sibling list is dense, but the description doesn't compare explicitly; however, it covers the tool's function sufficiently for selection.

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 descriptions for id (market id/conditionId), slug, wallet (0x+40 hex). The description does not add new parameter details beyond schema, 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?

Clear statement: 'Composite A-F rating for whether a wallet appears to have had non-public information on a specific market.' Identifies constituents, weights, bonuses, and outputs. Distinguishes from siblings by naming aggregated tools (pg_position_timing_anomaly, pg_insider_signal_scan).

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 caveat ('Statistical signal only — not a legal determination') but does not offer explicit when-to-use/avoid or compare to siblings. Implies use for insider signal detection but lacks exclusion criteria.

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?

With no annotations, the description carries the full burden. It discloses combination of evidence_anchor + get_signed_fact, ECDSA signature, and on-chain anchoring on Polygon. However, it does not mention side effects, permissions, rate limits, or error behavior.

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, front-loaded with the main action, and contains no unnecessary words. Every sentence adds value.

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 no output schema and no annotations, the description explains the tool well but fails to mention the return value or output format. It partially compensates by referencing verification tool but lacks 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?

Schema description coverage is 100%, so baseline is 3. The description does not add extra meaning to parameters beyond their schema definitions; it only references market_slug and claim implicitly.

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: issuing a cryptographically signed, on-chain anchored integrity alert for a Polymarket market. It specifies the technical mechanism (ECDSA, Polygon, JWKS) and distinguishes from sibling pg_verify_alert by mentioning external verification.

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 usage for integrity alerting but does not explicitly state when to use this tool versus alternatives like pg_market_integrity_scan. No when-not-to-use or prerequisites are mentioned.

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?

With no annotations, the description fully explains the tool's behavior: real-time scan, 5 signals, output score, triggered signals, top positioners, methodology. It defaults window to 72h. It doesn't cover edge cases or authorization but is fairly transparent.

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 dense paragraph that front-loads purpose then covers signals and output. It is mostly concise, though a slight structural improvement (e.g., bullet points) could enhance readability.

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 tool with no output schema and 4 optional parameters, the description adequately explains the output (score, signals, positioners, methodology) and the signals in detail. It is reasonably 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 the schema already documents all parameters. The description mentions defaults (window, min position) but adds no new meaning 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 clearly identifies the verb 'scan' and the resource 'insider-trading signals for a single Polymarket market'. It enumerates five specific signals, distinguishing it from sibling tools like pg_market_integrity_scan or single-signal 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 states it scans a single market and lists the aggregated signals, implying a comprehensive use case. However, it does not explicitly guide when to use it vs. alternatives or mention 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?

Description discloses behavioral traits: pattern-matches against specific disciplinary cases, returns ALLOW/MONITOR/WARN/BLOCK + score + reference cases, and explicitly states it cannot identify trader identity due to API limitations. No annotations exist, so description carries the full burden and does so comprehensively.

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 four sentences with no wasted words, front-loading the regulatory context and purpose. It efficiently conveys functionality, output, and limitations.

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 no annotations and no output schema, the description fully covers what the tool does, what it returns, and its limitations. It is self-contained for an agent to understand when and how to use it.

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 descriptions already cover all 3 parameters (100% coverage), so baseline is 3. The description adds value by providing context for 'candidate_name' (matching against specific case references like Moran/Klein), which clarifies its purpose beyond the schema description.

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 performs a CFTC conflict-of-interest pre-trade check on Kalshi markets, returning a recommendation and score. It uses specific verbs and resource, and its purpose is distinct from sibling tools (e.g., market details, volume analysis).

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 use for pre-trade compliance by referencing insider-trading liability and specific cases. It provides a clear limitation ('cannot identify actual trader identity') and suggests pairing with internal surveillance, offering context on when not to rely solely on this tool. No explicit differentiation from siblings, but the use case is well-defined.

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?

With no annotations, the description discloses what the tool returns in each mode, including critical details like rules_primary text. It implies a read-only operation. It does not mention mutual exclusivity of parameters or error behavior, but the core behavior is transparent.

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 the first stating the purpose and the second providing parameter guidance and key output features. No unnecessary words, and it is front-loaded with the most important 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 description covers the main use cases and outputs, and highlights the importance of rules_primary. However, it does not mention mutual exclusivity of parameters or differentiate from sibling tools like pg_kalshi_orderbook_analysis. Overall sufficient for an agent to use 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?

The input schema has 100% description coverage for both parameters. The description adds value by explaining the effect of each parameter and the corresponding output, which goes beyond the schema's basic field descriptions.

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 it provides detailed info for Kalshi markets or events, distinguishes between two modes (single market via 'ticker' or event via 'event_ticker'), and lists the specific returned data (bids/asks, last price, etc.). It differentiates from sibling tools by mentioning Kalshi-specific and rules_primary text.

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 the agent when to use each parameter: 'ticker' for a single market, 'event_ticker' for all markets in an event. It does not provide explicit exclusions or alternatives, but the context is clear enough for an agent to decide.

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?

With no annotations provided, the description fully discloses behavioral traits: it is a read-only analysis tool, explicitly states that Kalshi returns bids only and that asks are computed via reciprocity, and describes the output (score, severity, level data). 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?

The description is three sentences long, front-loading the purpose and then listing patterns and return information. It is clear and efficient, though the numbered list could be condensed slightly.

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 one simple required parameter and no output schema, the description provides complete context: what the tool does, specific patterns detected, the computed score and severity, level-by-level data, and the crucial behavioral note about bids-only and reciprocity. No essential information is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The single parameter 'ticker' is already well-documented in the schema (100% coverage). The description adds context by explaining it is for one Kalshi market and how the ticker is used in the analysis, which goes beyond the schema's minimal description.

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 performs 'forensic orderbook analysis' and detects five specific manipulation-vulnerable patterns, using a unique verb-resource combination. It distinguishes itself from siblings like pg_market_details and pg_market_integrity_scan by focusing on orderbook manipulation detection.

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 usage for in-depth orderbook analysis of a single Kalshi market and lists explicit patterns, giving clear context. However, it does not explicitly state when not to use or directly name alternatives, which would be needed for a perfect score.

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?

With no annotations, the description carries full behavioral burden. It mentions bucketing and CFTC-sensitive flags, adding context beyond the schema, but does not disclose performance, error handling, or exact output structure.

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, no fluff. The first sentence front-loads the core purpose, and the second provides usage context. 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?

Lacks output schema or description of return fields (e.g., market names, resolution times). For a compliance tool, this is a gap. No mention of prerequisites or error scenarios.

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%, giving a baseline of 3. The description mentions bucketing which relates to hours_ahead but does not add new semantic detail beyond what the schema provides for any 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 clearly states 'which Kalshi markets resolve in the next N hours' with bucketing and risk flags. It distinguishes this from siblings like market details or searches by framing it as a compliance briefing for resolution timing.

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 'Use for daily surveillance prep' and explains the risk context. However, it does not provide explicit when-not-to-use guidance or name alternative tools for different needs.

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?

With no annotations, the description carries the full burden. It discloses that the tool reads public data (no auth), returns events sorted by volume, and explains the structure of events having child markets. This adequately communicates that the operation is safe and read-only, but it lacks details on rate limits, pagination behavior, or what happens on empty results—leaving moderate gaps for complete transparency.

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 five sentences long, front-loaded with the core purpose, and every sentence adds distinct information (search function, ranking, categories, public nature, event structure). There is no redundancy or fluff, making it highly efficient for an agent to parse quickly.

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 tool has four parameters and no output schema, the description provides the essential context: what the tool returns (events ranked by volume), how to filter (query, category, status), and important background (public, CFTC-regulated, child markets). It does not mention sorting direction (assumed descending), maximum events per page beyond the default, or error scenarios, but it is sufficient for basic usage.

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 schema describes 3 of 4 parameters (query, limit, category) with attributes; the status parameter lacks a description. The tool description adds value by listing example categories and explaining the ranking by volume, but it does not elaborate on parameter usage beyond what the schema already provides. For the undocumented status parameter, no additional guidance is given, so the description only marginally supplements 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 clearly states the tool searches Kalshi prediction markets and returns events ranked by aggregate 24h volume. It specifies the resource (events) and the sorting criterion, distinguishing it from sibling tools like pg_kalshi_market_details (single market details) and pg_kalshi_trending (trending markets). The verb 'search' combined with 'returns events ranked by volume' makes the purpose 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?

The description provides context by stating it searches by query, category, and status, and clarifies that data is public with no authentication needed. However, it does not explicitly tell an agent when to use this tool versus alternatives, such as when to use pg_kalshi_market_details for a specific market. The mention of child markets offers some implicit guidance, but explicit when-not-to-use instructions are missing.

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?

Without annotations, the description fully explains the tool's behavior: it flags markets based on multiple criteria and returns them ranked by risk_score with a threshold of 30. No annotations to contradict.

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 serving a purpose: explaining the scan, noting its daily use, and suggesting a pairing. 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?

Given no output schema, the description mentions returned markets ranked by risk_score. It covers the core behavior but omits details like exact output fields beyond risk_score. Still, it's sufficient for a scanning tool with clear intent.

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 clear descriptions for both parameters (category, max_results). The description adds no significant extra meaning beyond what the schema provides, so baseline score 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 clearly states the tool scans all open Kalshi markets to flag manipulation-vulnerable ones with specific criteria (closing soon, low open interest, etc.). It distinguishes itself from siblings by suggesting a pairing with pg_kalshi_resolution_calendar.

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 identifies this as a daily triage tool and suggests pairing with another tool for a full compliance briefing. It provides context for when to use it, though it doesn't explicitly state when not to use or list alternatives.

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?

With no annotations, the description carries the burden. It discloses ranking by aggregate 24h volume and inclusion of top sub-market but does not mention sorting direction, pagination, or rate limits. Adequate but could be richer.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, front-loaded with key information, no wasted words. Efficiently conveys purpose and key features.

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 simple parameters and no output schema, the description adequately explains output content (trending events, volume, top sub-market). Slightly lacking in precise return format but sufficient for selection.

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 parameter descriptions already present. The tool description adds minimal extra meaning ('Filterable by category' is consistent with schema). Baseline score 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 clearly states the tool retrieves top trending Kalshi events ranked by 24h volume, filterable by category, and includes the highest-volume sub-market. It uses specific verbs and distinguishes from sibling tools like 'pg_kalshi_search'.

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 usage for daily briefings ('Daily-briefing-ready output') but does not explicitly state when to use versus alternatives or provide exclusions. Guidance is present but not directive.

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?

With no annotations provided, the description carries the full burden. It discloses that the tool returns summaries only and does not make accusations, implying it is a read-only information source. However, it does not mention authentication needs, rate limits, or response structure.

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 extremely concise: two sentences that front-load the purpose and then list filters and a behavioral note. Every word earns its place with 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?

For a simple registry lookup with two optional parameters and no output schema, the description adequately covers the tool's purpose, filtering, and a key behavioral constraint. It lacks details on return format or error handling, but given the low complexity, it is sufficiently 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?

Both parameters are fully described in the schema (100% coverage). The description repeats the filtering capability but adds examples of categories (e.g., 'geopolitical', 'oracle') and clarifies the enum values for min_aml_relevance. This adds marginal value beyond the schema, justifying a baseline 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly identifies the tool as a registry of publicly reported prediction-market integrity cases, with concrete examples (e.g., Théo, Hyperliquid whale, Venezuela). It distinguishes itself from siblings by focusing on known cases, not other tools like pg_adverse_media_entity or pg_market_integrity_scan.

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 context that this tool is for known cases and includes the note 'summaries only — no accusations against named parties,' which guides appropriate use. However, it does not explicitly state when to use this tool vs. alternatives like pg_adverse_media_entity.

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?

No annotations are provided, so the description must cover behavioral details. It states it is a 'single call' that 'delegates to AMLOracle.kyc_bundle', but lacks information on auth requirements, rate limits, or what happens on missing data. This is insufficient for a KYC operation.

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 succinct with two sentences, front-loading the core purpose and nesting details. Every sentence adds value, though it could be slightly more structured with a usage hint.

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 tool has no output schema and three parameters, the description should provide more context about the return structure or any limitations. It only mentions the components and delegation, leaving the output format entirely unspecified.

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 schema covers 2 of 3 parameters with descriptions (country and entity_type), but the required 'name' parameter lacks any description. The description adds no additional meaning beyond 'for a named entity', failing to specify input format or constraints for name.

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 specifies the tool's purpose: a 'full KYC bundle' including sanctions, PEP, adverse media, and country risk for a named entity. It distinguishes from sibling tools like pg_sanctions_screen_entity by emphasizing it is a combined single call.

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 use when a comprehensive KYC check is needed, but it does not explicitly state when to avoid this tool (e.g., if only one component is needed). No alternatives are directly compared, though siblings are individual checks.

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?

No annotations, but description lists returned fields (e.g., outcomes, prices, volume). It implies read-only behavior, but doesn't explicitly state side effects, permissions, or rate limits. Adequate for a simple data retrieval.

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 sentence, front-loaded with return info and required parameters. No wasted words; highly efficient.

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 no output schema and no annotations, description covers key returned fields. Lacks mention of error handling, but for a simple info endpoint, it's nearly 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 coverage is 100% and descriptions are clear. Description adds reinforcement ('Provide slug or id') but no additional format, constraints, or precedence detail. Baseline 3 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?

Description explicitly states 'Full market info' and lists specific fields (outcomes, volume, liquidity, etc.), clearly distinguishing it from siblings like pg_market_search (search) and pg_market_trades (trades). The verb is implicit but context makes purpose obvious.

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?

Tells user to provide 'slug' or 'id', which is a basic usage hint. However, no guidance on when to use this vs alternative tools (e.g., searching first, or using other detail tools). Minimal context for 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?

No annotations are provided, so the description carries the full burden. It discloses inputs (via schema) and outputs (score, level, signals, recommendation), but does not mention whether the tool has side effects, authorization requirements, rate limits, or idempotency. As a scan, it is likely read-only, but this is not explicit.

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 a single sentence that efficiently conveys the tool's purpose and output structure. It is front-loaded with the main action and clearly lists the combined signals and return fields without unnecessary 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?

Given no annotations, no output schema, and undocumented parameters, the description is minimally complete. It covers the tool's high-level function and output but lacks parameter details, usage context, and behavioral traits needed for an agent to reliably use it.

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 two parameters (id, slug) with zero description coverage. The description does not mention these parameters or explain their meaning, leaving the agent to guess. Schema provides type-only info, which is insufficient for correct invocation.

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 performs a multi-signal integrity scan combining six signals, returns a score (0-100), level (HIGH/MEDIUM/LOW/CLEAN), triggered signals, and operational recommendation. It uses specific verbs and identifies the resource, differentiating it from siblings like pg_market_details or pg_resolution_risk_score.

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. The description does not mention prerequisites, exclusions, or scenarios where other tools would be more appropriate. Usage must be inferred from the description 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?

No annotations are provided, so the description carries the full burden. It correctly implies a read operation and lists return fields, but does not explicitly declare read-only behavior, rate limits, or prerequisites. It adds moderate behavioral 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 a single sentence that efficiently conveys purpose, examples, and return fields. Every word earns its place with zero 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 tool's simplicity (3 parameters, no output schema), the description is complete. It explains what the tool does, what parameters are used for, and what the output contains. No gaps remain.

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%, but the description adds value beyond the schema by providing search examples, specifying default/max for limit, default for active_only, and listing return fields. This compensates well for schema's minimal descriptions.

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 ('Search Polymarket markets') and resource, with concrete keyword examples and return fields. It clearly distinguishes from siblings like pg_market_details (specific market) and pg_trending_markets (trending), leaving no ambiguity.

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 the tool is for searching by keyword, which guides usage. However, it does not explicitly mention when not to use it or alternative tools. The context of sibling tools implies differentiation, but a brief exclusion note would elevate clarity.

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?

With no annotations, the description covers key behaviors: pagination (max 25 pages of 1000 trades), client-side filters, and return fields. It lacks mention of rate limits or ordering, but is otherwise transparent for a read-only data API.

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-load the purpose and efficiently cover filters, pagination, and output format. No superfluous 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?

Given no output schema, the description adequately lists return fields and pagination constraints. It could mention ordering of results or error handling, but overall it provides sufficient context for a data retrieval 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 coverage is 100%, but the description adds value by explaining the purpose of filters (time range, side, min size, wallet) and how pagination is handled server-side. It also describes the response structure, which is absent from 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 clearly states it provides raw trade access for a Polymarket market, listing specific filters and output fields. It uniquely identifies the tool among siblings which cover different market aspects.

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 details filtering options and pagination limits, giving clear context for when to use it (to access raw trades). However, it does not explicitly contrast with sibling tools or state when not to use 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?

No annotations are provided, so the description carries full burden. It describes the core behavior (comparison and flagging) but does not disclose side effects, authentication needs, rate limits, or idempotency. The calculation approach is mentioned, providing moderate transparency.

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 sentence that front-loads the main purpose and key details. It is concise and avoids extraneous information, though a more structured format (e.g., separating purpose and input) would improve 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?

With no output schema and no annotations, the description fails to explain return values, how to interpret results, or how parameters affect the analysis. The high-level purpose is clear, but operational details are missing, leaving the agent underinformed.

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 the description contains no explanation of the 'id' and 'slug' parameters. The agent cannot infer what values to provide or how they affect the analysis, making the description inadequate for parameter usage.

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 explicitly states that the tool performs a volume anomaly heuristic, comparing 24h volume to average daily volume and flagging thin-book situations. It uses specific terms like 'z-like ratio' and clearly defines the condition, making the purpose distinct from sibling tools such as pg_market_trades or pg_market_details.

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 usage for detecting volume anomalies or thin-book conditions, but provides no explicit guidance on when to use it versus alternatives, no exclusion criteria, and no mention of prerequisites. The usage context is inferred rather than stated.

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?

No annotations are provided, so the description must carry the full burden. It mentions pings (to Polymarket Gamma API and Polygon RPC) but does not disclose potential side effects (e.g., network timeouts, rate limits) or whether the tool is read-only. For a read-only overview, this is acceptable but could be more explicit.

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 sentence that efficiently lists the key components of the overview. Every word earns its place; no redundancy or 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?

Given the tool's simplicity (no parameters, no output schema), the description adequately conveys what it does. It covers the main aspects: platforms, tool inventory, pings, and known-case count. A note on the output format (e.g., 'returns a JSON object with status fields') would push it to 5.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, and the schema coverage is 100% (vacuously). With no parameters to describe, the description adds no param value but also does not need to. Baseline score of 4 per guidelines for 0 params.

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 provides a platform overview including specific components (covered platforms, tool inventory, pings, known-case count). The verb 'overview' combined with the listed items distinguishes this from the many specific sibling 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?

No explicit guidance on when to use this tool versus alternative siblings. While the overview nature is implied, a brief note on using it for a high-level status check before diving into specific tools would improve clarity.

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?

With no annotations, the description should fully disclose behavioral traits. It notes delegation to AMLOracle and Wikidata, but does not specify read-only nature, side effects, error handling, or rate limits, which are important for an external API call.

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 consists of two concise sentences that are front-loaded with the core purpose. Every word contributes meaning, with no extraneous content.

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 lookup tool with no output schema, the description covers the essential context: what it checks, data sources, and use case. Minor gaps exist, such as unspecified return format or error behavior, but these are not critical given the tool's simplicity.

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 schema already provides descriptions for both parameters (name and country). The description adds no additional meaning beyond what the schema offers, so the baseline score 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 explicitly states the tool performs a PEP check via Wikidata and delegates to AMLOracle, specifying its relevance to prediction markets. This clearly differentiates it from sibling 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 mentions relevance for prediction markets but does not provide explicit guidance on when to use this tool over alternatives like pg_sanctions_screen_entity or pg_kyc_bundle_entity. Usage context is implied but not contrasted.

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?

Since no annotations are provided, the description fully carries the burden. It details the scoring methodology (three checks with point values), the output format (score, timestamp, notional, methodology), and implies a read-only operation without side effects. This level of specificity is commendable for a tool without annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, but the first sentence is dense with structured points (three checks with scoring). It front-loads the core purpose and provides detailed breakdown. While effective, a slight restructuring could improve readability without sacrificing content.

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 tool has three parameters, no output schema, and no annotations, the description provides a comprehensive overview: it explains what the tool does, the scoring criteria, and the returned fields (score, timestamp, notional, methodology). This is sufficient for an LLM to decide when and how to invoke the 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?

The input schema has 100% coverage with descriptions for all three parameters (id, slug, wallet). The tool description adds context about the purpose (analyzing a wallet's position on a market) but does not provide additional parameter-level details beyond what the schema already offers. Thus, 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 states the tool performs 'statistical timing analysis of a single wallet's position on a specific market' and enumerates three specific checks with scoring details. It also explicitly distinguishes itself by suggesting pairing with a sibling tool (pg_information_advantage_score), making the purpose very precise and differentiated.

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 usage guidance by stating 'Pair with pg_information_advantage_score for full assessment,' which helps the agent understand when to use this tool in combination with another. However, it does not explicitly state when not to use it or list alternatives, leaving some room for interpretation.

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?

No annotations provided, so description must disclose behavior. It describes the output (decision, risk_level, signed receipt) and sub-checks performed. Lacks explicit statements about side effects, idempotency, or rate limits, but the read-only nature is implied.

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?

Concise single paragraph with front-loaded purpose and bullet-like details. Could benefit from clearer separation of sections, but effectively conveys all needed information without extra 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?

Given complexity and lack of output schema, description covers purpose, inputs, aggregated checks, output, and use context. Missing details about error handling or receipt format, but mostly complete for agent usage.

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%, but description adds significant context: explains optional inputs (wallet, candidate, amount_usd) and how they influence the checks, which goes far beyond the schema descriptions.

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 is a pre-trade integrity gate returning ALLOW/WARN/BLOCK plus risk_level and signed receipt. Aggregates multiple checks and supports both Polymarket and Kalshi, distinguishing it from sibling tools that focus on individual checks.

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 it is designed for x402 paywall pre-trade calls, indicating when to use. However, it does not discuss when not to use or provide direct comparisons to sibling tools for alternative scenarios.

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?

With no annotations, the description takes full responsibility. It transparently lists the analytical steps (aggregate trades, classify wallets, detect clusters, spikes), the risk score scale (CRITICAL/HIGH/MEDIUM/LOW/CLEAN), and outputs (top positioners, new wallets). It does not mention auth requirements, rate limits, or data freshness, but the behavioral core is clear.

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, well-structured paragraph of 4 sentences. Every sentence adds value: first states purpose, second enumerates analyses, third specifies outputs, fourth gives default. No fluff, perfectly concise.

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 tool's complexity (multiple analysis types, risk scoring, top lists) and no output schema, the description covers the main outputs and parameters. It could be more complete by explaining how id and slug differ, or clarifying trigger criteria for signals, but it provides sufficient context for an agent to understand the tool's capabilities and boundaries.

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%: max_pages and days_before_end have descriptions in the schema, but id and slug lack them. The tool description reinforces the 'days_before_end' parameter by mentioning 'N days' and default window, adding context. However, it does not clarify id vs slug, leaving ambiguity for the two required parameters. More value could be 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?

The description clearly states the tool's purpose: analyzing pre-resolution positioning on Polymarket markets. It lists specific analyses (wallet classification, volume concentration, timing clusters, volume spikes) and outputs (risk score with levels, signals, top wallets), making it distinct from sibling tools like pg_market_trades or pg_resolution_risk_score.

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 explains when to use the tool: 'N days before the market's endDate' for pre-event analysis. It specifies a default window of 7 days. However, it does not explicitly contrast with sibling tools or state when not to use this tool, missing a clear alternative 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?

With no annotations, the description carries full burden. It discloses that the tool is read-only (computes score, no side effects mentioned), returns triggered signals with point deductions, and references internal logic (pg_known_cases, UMA adapter). It stops short of specifying idempotency or auth requirements but is fairly transparent.

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 concise sentences, front-loading the score definition and following with a list of signals. No extraneous information, though the second sentence is dense and could be slightly reorganized for 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?

The description explains the tool's purpose and internal signals but lacks details about output format (e.g., JSON structure) and parameter constraints (e.g., whether id or slug is preferred). Given no output schema and the tool's complexity, additional completion about return values would be beneficial.

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 two parameters (id, slug) with 0% schema description coverage. The description mentions 'Polymarket market' but does not explicitly map id and slug to market identifiers or explain their difference. Parameter meaning is largely left to inference, so the description adds minimal value over 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 clearly states it computes a multi-signal resolution-risk score (0–100 with categories) for a Polymarket market, using a specific verb and resource. It distinguishes itself from sibling tools like pg_market_details or pg_uma_market_resolution by focusing on risk scoring.

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 lists the input signals (category priors, proximity, volume, etc.) implying the tool should be used when assessing resolution risk. However, it does not explicitly state when not to use it or name alternatives, though the sibling tools make the context 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?

No annotations provided, so description must cover behavioral traits. It mentions delegation to AMLOracle and target lists but lacks details on output format, permissions, or side effects. Sufficient for basic understanding but incomplete.

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 efficiently convey purpose and usage. No redundant information; each sentence 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?

The description explains what and when, but without output schema or annotations, it lacks details on return values, error conditions, or behavior with absence of threshold. Adequate but not comprehensive.

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 description does not need to add much. It adds no extra meaning beyond schema descriptions for name, threshold, and entity_type. Baseline score 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 states the tool screens a named entity against global sanctions lists, naming specific lists (OFAC, EU, UN, Interpol). It distinguishes from sibling tools like pg_pep_check_entity and pg_adverse_media_entity.

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 advises using after resolving a wallet/trader to a real name, providing clear context. However, it does not explicitly exclude other scenarios or name alternatives for when not to use.

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?

With no annotations, the description carries full burden. It discloses that the tool generates a draft, does not submit, auto-classifies, and outputs markdown marked as draft_for_review. It does not mention error handling or validation, but the core behavior is transparent.

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 approximately 100 words, information-dense, and well-structured. Every sentence adds value, front-loading key purpose and format support. 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?

Given the tool's complexity (8 parameters, nested objects, no output schema), the description is remarkably complete: it covers purpose, supported formats, input sourcing, output nature (markdown draft), and constraints (not submitting). No essential information 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%, baseline 3. The description adds value by explaining how to use the signals parameter (directly pass arrays from other tools) and maps conceptual fields to parameters. It goes beyond the schema in providing usage context.

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 generates a draft SAR from structured inputs, lists supported formats (EU_GENERIC, US_FINCEN, DE_goAML), and uses specific verbs like 'generate', 'auto-classifies', and 'renders'. It distinguishes itself from siblings as the only SAR generation tool.

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 explains what the tool does and that the output is a draft for review, not submitted. It implicitly guides input sourcing by mentioning that signals can come from pg_market_integrity_scan or pg_resolution_risk_score. However, it does not explicitly state when not to use it or alternatives.

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?

No annotations are provided, so the description carries the full burden. It discloses that the tool returns trending markets based on 24-hour volume, which implies a read-only, non-destructive operation. It does not detail rate limits or authentication, but for a simple data retrieval tool, the description gives sufficient behavioral 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 two sentences: the first states the core function, the second adds practical use cases. Every word earns its place; there is no redundant information. It is optimally concise.

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 tool's simplicity (one optional parameter, no output schema), the description adequately covers what the tool does and when to use it. However, it could explicitly state that results are sorted by volume descending, but this is implied by 'top markets by volume.'

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% for the single parameter 'limit,' which already documents its default and maximum. The tool description does not add any extra meaning beyond the schema. Therefore, the description adds marginal value over the structured parameter definition.

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 'Top Polymarket markets by 24h volume,' specifying the verb (get/list), resource (markets), and metric (volume). It further distinguishes itself from siblings like pg_market_search by framing the use case as daily compliance triage and catching news catalysts.

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 it (daily compliance triage, catching news catalysts). While it does not list alternative tools for other scenarios, the context of sibling tools implies that for keyword or specific market searches, one would use pg_market_search or pg_market_details. This provides adequate 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?

No annotations exist, so the description must fully convey behavior. It details the process (fetch metadata, extract address, verify contract, classify phase) and lists phases, offering good transparency. However, it does not explicitly state that the operation is read-only.

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, information-dense sentence that covers key aspects efficiently. Some structure (e.g., listing phases separately) could improve readability, but it remains concise and 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?

For a tool with 2 optional parameters and no output schema, the description adequately explains the function and expected output (phases). It could mention the exact output format or list phases more explicitly, but it is reasonably 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 coverage is 100% with clear descriptions for 'id' and 'slug'. The description adds no additional meaning beyond the schema, meriting the baseline score of 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it identifies resolution source and phase for a Polymarket market, listing specific steps and possible phases. This distinguishes it from sibling tools like pg_market_details or pg_resolution_risk_score.

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 usage for retrieving resolution info but does not explicitly state when to use this tool versus alternatives like pg_resolution_risk_score, nor does it provide exclusions or prerequisites.

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?

With no annotations provided, the description fully bears the burden. It accurately describes the non-destructive, analytical nature of the tool (scanning, tallying, computing) without mentioning destructive actions. However, it could be more explicit about being read-only.

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, well-structured sentence that front-loads the main purpose and efficiently conveys all key aspects without unnecessary 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?

Given no output schema, the description adequately explains the derived outputs (event counts, per-hour rate, ratio). It covers the main behavior but could mention the return format or data structure for 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 100% description coverage, and this description adds meaning by explaining the role of each parameter: 'blocks_back' defines the scanning window and 'include_v1' enables legacy scanning. This enhances understanding beyond the schema alone.

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 specifies the tool's function: scanning UMA OO event logs on Polygon, tallying events by type, computing per-hour rates, and deriving a dispute/propose ratio. It distinguishes itself from sibling tools (e.g., market- or wallet-focused) by focusing on oracle health.

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 usage for assessing oracle health but does not explicitly state when to use this tool versus alternatives or when not to use it. No exclusions or context about prerequisites are provided.

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?

With no annotations, the description carries the full burden. It discloses delegation behavior, return fields (validity, signer, timestamp), and JWKS location. It implies mutual exclusivity of parameters but does not explicitly confirm it, nor does it mention error handling or side effects.

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, front-loaded with the primary action, and contains no unnecessary words. Every sentence adds value.

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 verification tool with two optional parameters, the description covers the main behavior and return values. It lacks mention of error cases or what happens if both parameters are provided, but overall is fairly complete given no 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?

Input schema already provides 100% coverage with descriptions for both parameters. The description adds only the hint that content_hash is an alternative to JWS, which is useful but minimal. 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 clearly states the tool verifies signed alerts using JWS or content-hash, and mentions delegation to Trust Layer. This distinguishes it from sibling tools like pg_insider_alert_signed (which likely creates alerts) and others focused on media, markets, or entities.

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 context by naming the delegation and JWKS location, but does not explicitly state when to use this tool vs. alternatives or when not to use it. However, the specific function implies usage for alert verification only.

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?

With no annotations, the description does the job by detailing returns (which markets, top 20 cotraders, severity score) and the scoring thresholds. It is read-only in nature but does not explicitly state that. No mention of errors or edge cases, but sufficient for expected behavior.

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: first states the core purpose, second details returns and use case. It is concise, front-loaded, and contains 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 no output schema, the description explains the return structure (markets traded, top 20 cotraders, severity score) and scoring logic. It covers key aspects but lacks precise output formatting and edge case handling. Still sufficient for an agent to understand the tool's function.

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 descriptions. The description reinforces the parameters and adds context (e.g., 'sensitive Polymarket markets' and the 2-10 constraint). It adds value beyond the schema by explaining the use case for the parameters.

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 it finds wallets co-trading across multiple sensitive markets with a target wallet. It specifies the action, subject, and scope, and distinguishes from siblings like pg_wallet_lookup and pg_market_trades by focusing on correlation analysis for detecting coordinated behavior.

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 context and a use case (detect coordinated trading rings) but does not explicitly state when to use this tool over alternatives or when not to use it. Lacks comparative guidance with sibling 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?

Discloses fallback mechanism and output fields. No annotations exist, so description provides behavioral context well. Could mention potential errors or limitations, but current level is good.

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?

Efficiently communicates purpose, mechanism, and output in two sentences. 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 main behavior and output fields. Without output schema, description adequately describes returns. Could add edge case handling, but sufficient for most agents.

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 already describes the address parameter fully (100% coverage). Description does not add extra meaning. Baseline score of 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States specific verb 'Resolve' and resource 'Polygon address to known entity'. Differentiates from sibling tools like pg_wallet_lookup and pg_wallet_risk_profile by focusing on entity identification with AML relevance.

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 usage context or alternatives mentioned. Agent must infer from naming. No guidance on when this tool is preferred over pg_wallet_lookup or pg_wallet_risk_profile.

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?

With no annotations provided, the description carries the full burden. It discloses the backend selection behavior (Ankr or public fallback) and specifies the return fields (MATIC balance, tx count, etc.), implying a read-only operation. However, it lacks details on failure modes, latency, or external dependencies, which is acceptable for a simple lookup.

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, front-loading the core purpose and endpoint behavior. Every word adds value, with 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?

Given the tool's low complexity (single parameter, no output schema), the description is complete. It covers purpose, backend, return fields, and identification of the wallet type.

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% for the single parameter 'address', which is already well-described in the schema. The description adds no additional semantic value beyond the schema, so a baseline score 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 clearly states the tool looks up a Polygon wallet base profile, specifying the data returned (MATIC balance, tx count, contract/EOA detection, risk heuristic) and the backend (Ankr or public fallback). This distinguishes it from sibling tools like pg_wallet_entity_resolve or pg_wallet_risk_profile.

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 tool is for a basic wallet profile lookup, but it does not explicitly provide guidance on when to use this tool versus alternatives (e.g., pg_wallet_risk_profile for risk-specific data). No when-not-to-use or prerequisite conditions are mentioned.

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?

With no annotations provided, the description fully discloses the behavioral traits: it outputs an A–F grade with explanations (flags and points deductions). It describes the data sources and grading logic, which is sufficient for an agent to understand the tool's safety and output nature.

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 at three sentences, each adding value: first defines the output, second explains the composition, third details grading and output. It is well-structured and front-loaded with key 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?

Given the absence of an output schema, the description adequately explains the output (grade, flags, auditability) and the input (address). It covers the tool's operation and dependencies, making it complete for an agent to use 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?

The input schema has 100% coverage for the single parameter 'address', providing a clear description. The tool description does not add extra semantics beyond the schema, so it meets the baseline of 3 without requiring compensation.

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 it provides an aggregated A–F risk profile for a Polygon wallet, specifying the combination of on-chain behavior, entity resolution, and AML screening. It distinguishes itself by being a composite of related tools like pg_wallet_lookup and pg_wallet_entity_resolve, making its purpose distinct from siblings.

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 usage when a risk profile is needed but lacks explicit guidance on when to use this tool versus alternatives. It does not state prerequisites or exclusions, leaving the agent to infer context from mentioned components.

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?

No annotations exist, so description must carry behavioral disclosure. It mentions baseline snapshot but omits side effects (e.g., overwrite behavior, limits). Lacks detail on return value, permissions, or error handling.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three concise sentences, each adding distinct value: purpose, snapshot behavior, and parameter tuning. 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?

Missing output schema info—no indication of what the tool returns. Also doesn't address idempotency or duplicates. Adequate for the parameter details but incomplete for a creation 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 covers 100% of parameters. Description adds minor context (default threshold, free-form tags) but mostly restates 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?

Clearly states it adds a Polygon wallet to a watchlist and ties to subsequent pg_whale_scan. Distinguishes from siblings like pg_whale_remove and pg_whale_list.

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?

Implies use before pg_whale_scan but gives no explicit when-to-use or when-not-to-use guidance. No reference to alternatives or prerequisites.

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?

No annotations provided; the description accurately conveys read-only retrieval behavior and default/filtering details, but lacks depth on rate limits or auth requirements.

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, no wasted words. Efficient and clear.

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 retrieval tool with no output schema, the description covers core functionality and filtering. Missing return format details but acceptable given 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?

With 50% schema coverage, the description adds meaning by explaining default limit and 'since' as ISO timestamp, but address and severity parameters are merely listed without extra context.

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 it retrieves alerts from the watchlist audit log with filtering options, distinguishing it from sibling tools like pg_whale_list and pg_whale_add.

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 clear context on default behavior (50 most recent alerts) and filters, but does not explicitly state when to use alternatives or exclude 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?

Lists returned fields and optional filter, but does not mention pagination or limit behavior beyond schema. No annotations, so description carries full burden.

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, 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?

For a simple listing tool with two optional params and no output schema, the description covers purpose, returned fields, and optional filter completely.

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 baseline 3. Description adds 'optional filter by tag' but does not add new meaning beyond schema descriptions for tag and limit.

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 'List all watched wallets' with specific fields returned, distinguishing it from siblings like pg_whale_add or pg_whale_alerts.

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?

Mentions optional tag filter, but does not explicitly state when to use vs alternatives. However, context from sibling names makes purpose 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?

Discloses default behavior (keeps history) and purge option, but lacks information on permissions, reversibility, or side effects. No annotations to contradict.

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 primary action, 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?

No output schema, but for a removal tool the description is adequate; however, it could mention return state or confirmation for 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?

Schema coverage is 50%; description adds value for keep_history (purge everything) but does not describe the address parameter beyond its existence.

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 action ('Remove a wallet') and the resource ('from the watchlist'), making it distinct from sibling tools like pg_whale_add or pg_whale_list.

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 guidance on when to use keep_history=false vs default, but does not explicitly compare to alternatives, though the context of siblings makes the 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?

Describes the full workflow: comparing balance/nonce, writing a snapshot, and emitting alerts with severity levels. No annotations provided, so the description carries the full burden and does so adequately.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences with no wasted words. The first sentence states the core action, followed by behavior details and usage guidance. Efficient and well-structured.

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 one optional parameter and no output schema, the description covers the main behavior. Missing return format, but the scan-and-alert workflow is sufficiently described for an agent to use 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?

The schema already describes the parameter at 100% coverage. The description adds one nuance: omitting 'address' scans the whole list. Baseline 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 uses a specific verb ('scan') and resource ('watched wallets'), and clearly distinguishes the tool from siblings like pg_whale_add or pg_whale_remove by focusing on scanning and alerting.

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 states when to omit the 'address' parameter (to scan the entire watchlist) and mentions intended periodic usage via scheduler. Lacks explicit when-not-to-use scenarios, but the guidance is clear.

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