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

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

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?

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.