Agent Utility Suite (x402)

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, open-world), so the description does not need to restate them. It instead adds genuinely new behavioral context: the billing model is pay-per-returned-result, invalid input (400) and upstream failures (4xx/5xx) are not settled, cost is $0.03 USDC via x402 paid inside MCP, and the flag semantics (RED/AMBER/GREEN) are defined with the specific filing conditions that trigger each.

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

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

Front-loaded with the user questions it answers, then the input contract, then the return payload — a sensible order with no filler sentences. The long enumeration of returned fields is justified because there is no output schema, though the block is dense enough that it reads as a data dump rather than a summary.

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?

There is no output schema, so the description must describe the return, and it does so thoroughly: profile fields, four fiscal years of income/cash-flow/balance-sheet metrics, latest quarter with YoY growth, 8-K and Form 4 detail, latest 10-K/10-Q, flag taxonomy, and the `summary` field. Billing and failure behavior are also covered, leaving nothing an agent needs to invoke it correctly.

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

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

Schema description coverage is 100%, so each of the five parameters is already documented in the schema, and the description mostly restates that any of ticker/company/CIK/domain works rather than adding syntax or precedence rules beyond what the schema says. It does not mention the optional `via` parameter at all. Baseline 3 is appropriate when the schema carries the detail.

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

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

The description opens with concrete example questions ('Give me a quick due-diligence read on NVDA') and then enumerates exactly what one call returns — profile, four years of XBRL financials, latest quarter, 8-K events, insider Form 4 activity, latest filings and color-coded risk flags. It also explicitly distinguishes itself from siblings by naming the five calls it replaces (company_profile, sec_financials, sec_recent_events, sec_insider_trades). An agent can tell this apart from sec_financials or sec_alerts_peek without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It states exactly what input forms are accepted (ticker, company name, CIK or website domain), names the tools it supersedes, and routes follow-up work via next_calls ('what changed in the risk factors and the latest earnings release'). It also states the negative case — unknown, ambiguous or private companies return tickers free and are not charged.

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

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

Goes far beyond the readOnly/idempotent/openWorld annotations: it discloses the ranking order (red before amber), the exact dossier contents, the billing rules (only settled when a result returns; 400/4xx/5xx not charged; unfindable firms go to `failed`; no charge if none found), and the 402 price-quote behavior. This is exactly the behavioral context an agent needs before a paid 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?

Front-loads the use case and output shape before cost, which is good ordering, and every sentence carries information. It is nonetheless long and repeats the price structure twice (the enumerated per-size figures and again as 'Costs $0.03 to $0.15 USDC per call'), which slightly dilutes density.

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, the description fully covers returns: ranking, per-company flags and summary, the dossier contents, and the `failed` bucket. Billing, failure handling, and payment mechanism are all addressed, leaving nothing an agent needs before calling.

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

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

Schema coverage is 100% and the description largely restates the schema ('up to 10 tickers, CIKs or company names'), adding no format or edge-case detail beyond it. The `via` param is already documented in the schema. Baseline 3 is appropriate when the schema carries the full burden.

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

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

States a specific verb and resource (batch company dossiers/portfolio red-flag screen) and immediately differentiates itself from the sibling company_dossier by noting it is 'always less than separate company_dossier calls'. The quoted use-case questions pin down exactly what job it does.

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?

Front-loads two concrete when-to-use scenarios (portfolio problem screening, pre-open red-flag triage) and explicitly compares itself to the single-company alternative on cost. The 'up to 10 tickers' bound plus the price advantage make the routing decision unambiguous.

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

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

Annotations already declare read-only, idempotent, open-world and non-destructive, so the bar is lower; the description nonetheless adds substantial behavioral detail beyond them — how `sources` reports which providers answered, the free 404/name-collision cases, the non-settled 400/4xx/5xx cases, and the $0.005 USDC x402 charge only on returned results.

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

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

Front-loads the user-facing purpose before the dense source inventory, and every sentence carries information (inputs, return composition, error/billing behavior). It is on the long side for a single-paragraph description, but the length is justified by the tool's complexity.

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, the description carries the return-value burden and does so fully: it enumerates the EDGAR, Wikidata, Wikipedia, MX and RDAP fields and explains `sources`. Combined with its billing and error disclosure, an agent has everything needed to call and interpret 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 coverage is 100%, so the baseline is 3, but the description adds meaning: any URL on the domain is acceptable, not just the bare domain, and a `company` name matching several SEC registrants returns candidates (free) rather than failing. That clarifies behavior the schema's 'Use this, `ticker` or `company`' notes do not.

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

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

States a specific verb+resource and even frames it as the literal questions it answers ('Who is behind stripe.com?', 'Is it public, and what is its ticker?'). The input forms (domain/name/ticker/CIK) and the returned content are enumerated, letting an agent distinguish it from sibling tools like domain_enrich or company_dossier.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives clear when-to-use context: works for private companies too, and for public companies 'next_calls lead to their financials, 8-K events and insider trades', which routes the agent onward. It does not, however, explicitly contrast itself against close siblings such as company_dossier, domain_enrich or counterparty_check.

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

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

Annotations cover the read-only/idempotent/non-destructive profile, but the description adds substantially more: cost ($0.02 USDC via x402), the settlement rule (only charged when a result is returned; 400 and upstream 4xx/5xx are not settled), graceful degradation (a source that can't be reached is reported as failed rather than failing the call), and the 'screening aid, not legal advice' caveat. This is unusually rich behavioral disclosure.

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

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

Front-loaded with the three guiding questions, then what the call runs, then return shape, then alternatives and pricing. It is long and dense, but nearly every clause carries distinct information (sources screened, cost, settlement, failure semantics). Minor compression possible in the source enumeration.

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 exists, and the description fully covers return values (verdict block/review/clear, one-line summary, per-reason provenance, underlying facts). Combined with the failure-handling and billing notes, an agent has everything needed to call and interpret 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 coverage is 100%, so the baseline is 3, but the description adds real meaning: it clarifies that name is both OFAC-screened and used for a company lookup, that domain accepts a URL or email, and that wallet is the pay/receive address (e.g. an x402 payTo). The combination logic ('and/or') for otherwise-optional parameters is genuinely useful 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?

Opens with three concrete user questions ("Is it safe to pay this vendor?", onboarding, payTo attribution) and states exactly what one call runs: OFAC screening, company profile, domain/email checks, and on-chain wallet risk. It explicitly names the four siblings it replaces (sanctions_screen, company_profile, domain_enrich, wallet_risk_check), so an agent can distinguish it without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit when-to-use scenarios (vendor onboarding, KYB, payee vetting before x402 or USDC payment, fraud screening) and names the exact alternative tools it consolidates. The 'and/or' combination of name/domain/wallet is described, so the agent knows how to compose inputs.

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

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

Annotations already declare readOnly/idempotent/non-destructive/openWorld, and the description adds substantial extra context: cost ($0.02 USDC per call via x402), the billing rule that invalid input (400) and 4xx/5xx failures are not settled, the full row shape returned, and the disclaimer that gains need cost basis. This is well beyond what the annotations convey.

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

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

Front-loads the user questions and then the required inputs and return contents, so an agent gets the gist immediately. It is dense and slightly long, with some repetition around the tax-advice caveat and CSV output, but nearly every sentence carries usable 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?

There is no output schema, so the description must describe return values, and it does so thoroughly: per-transfer labels, CPA treatment categories, counterparty, tx link, stablecoin USD value, per-asset totals, counts, and optional CSV. Combined with schema-complete parameters, an agent has everything needed to call and interpret 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 description coverage is 100%, so the schema already documents wallet, chain, year, from, to, include_csv, and via. The description reinforces the base default and the year-vs-from/to alternation but adds no format, constraint, or edge-case meaning beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource (crypto transactions for a wallet in a tax year) and frames it around three concrete user questions. An agent can distinguish it from siblings like wallet_risk_check or token_risk_check because it is clearly the tax/ledger reporting tool, not a risk assessment.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The opening example questions make the intended use cases explicit (period activity, accountant export, taxable transfer identification), and the 'record for preparing taxes, not tax advice' caveat sets a scope boundary. It never explicitly names an alternative sibling or says when not to use it, so it stops short of a 5.

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

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

Annotations already declare read-only/open-world, but the description adds substantial behavior: ordering ('most serious first'), inclusion thresholds ('$100K+ insider purchases'), exclusions ('SPACs left out'), and a full billing model ('charged only when a result is returned: invalid input (400) and upstream failures (4xx/5xx) are not settled', $0.025 USDC via x402). The per-call charge is consistent with idempotentHint=false.

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?

Dense and front-loaded with the user-intent phrasings before the mechanics. Slightly long for a single paragraph, and the x402/price sentence partially duplicates server-level instructions, but nearly every clause carries operative 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?

With no output schema, the description compensates by describing the return ('Starts with a few plain-sentence `summary` lines') and the four sections with their content. Combined with defaults and the subscription pointer, an agent has everything needed to call and interpret 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 description coverage is 100% and the schema already documents each parameter, its defaults, and its effects. The description's parameter sentences ('narrow alerts and earnings to a watchlist', 'pick sections') largely restate that, so the baseline 3 applies rather than true added value.

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

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

States a specific aggregated resource ('One call combines') and enumerates exactly what it pulls together: recent SEC alerts, latest earnings, weekly IPOs, and macro indicators. An agent can distinguish it from siblings like sec_earnings_today, sec_ipo_filings, or economic_indicators without inspecting schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Opens with the concrete questions it answers ('What happened in the markets...', 'Give me a morning briefing'), explains how to narrow via tickers/include, and explicitly names the alternative for recurring use: 'For one every morning on your webhook, use daily_briefing_subscription.' Timing and payment conditions are also 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?

Goes well beyond the annotations (readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false) by disclosing the billing model ($3 USDC/30 days), that invalid input and 4xx/5xx are not settled, retry behavior on failed deliveries, the HMAC-SHA256 signing scheme, the test-ping/2xx precondition for charging, and the near-immediate first delivery. The only gap is what happens if the webhook later goes permanently dead or whether the secret can be rotated.

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

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

Front-loaded with the user-facing use case and then dense with operational detail, so nearly every sentence earns its place. It is on the long side and repeats the test-ping/2xx condition that already appears in the webhook_url schema description.

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 paid, mutating, zero-required-parameter subscription tool with no output schema, it covers delivery cadence, payload shape ({type: 'briefing', briefing: {...}}), signing, retries, charging semantics, extension, and cancellation. Nothing an agent needs to invoke or explain this call correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds semantic framing the schema does not: that delivery_hour_utc=11 is '7am New York, before the US open', that tickers acts as a watchlist narrowing SEC alerts and earnings, and that renew_subscription_id preserves the existing webhook and settings. It stops short of explaining the returned signing_secret's use beyond a pointer to `verify`.

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

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

States a specific verb+resource: subscribe a webhook to receive the daily market briefing for 30 days. It explicitly names the sibling it mirrors ('the same briefing daily_briefing returns') and the free management tool, so an agent can distinguish it from daily_briefing and sec_alert_subscription without opening schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Opens with the exact user intent it serves ('Send me a market briefing every morning') and names alternatives for each related need: daily_briefing for one-off reads, sec_alert_subscription_status to check or cancel, renew_subscription_id to extend. Both when-to-use and when-not are covered.

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

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

Annotations already declare readOnly/openWorld/non-destructive, but the description adds genuinely new behavioral context beyond them: live-lookup semantics, the billing model ('charged only when a result is returned'), the non-settlement of 400/4xx/5xx failures, and the exact cost ($0.004 USDC via x402). That payment/failure transparency is high-value information an agent needs before calling.

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

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

Front-loads what the tool does, then moves through outputs, use cases, billing, and cost with no filler. The two quoted framing questions are slightly verbose but earn their place by making the use cases concrete.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only profiling tool with full schema coverage and no output schema, the description covers what is profiled, why to use it, and payment behavior. It stops short of describing return structure/pagination, but with no output schema declared this is a minor gap rather than a blocking one.

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 both parameters (domain and via) are fully documented in the schema, including that a full URL is accepted and only its hostname is used. The description adds no further parameter detail, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Profiles a domain from live DNS and its website') and then enumerates exactly what is extracted: MX records, inferred email provider, SPF/DMARC, verified services from TXT, HTTPS reachability, and stack/security headers. An agent can distinguish this domain-level DNS/web profiling from siblings like company_profile or email_verify without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly lists when to use it: 'lead enrichment, email deliverability checks, vendor due diligence or security reviews.' This is clear usage context, but no alternative siblings are named or excluded, and there is no guidance on when a different tool would be preferable.

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

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

Beyond the annotations (readOnly, openWorld, non-idempotent, non-destructive), the description discloses rich behavior: per-source cache TTLs (1h for yields/fed funds, 12h for BLS), an `unavailable` field for non-responding sources, and precise billing semantics including that invalid input (400) and upstream failures are not settled. This is exactly the extra operational context annotations cannot carry.

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?

Dense and front-loaded: it leads with the questions answered and the returned series before moving to caching and billing. The question list is slightly verbose but earns its place as use-case framing, and nothing reads as filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a paid, multi-source data tool with no output schema, the description is complete: it describes the return contents, the optional history, unavailability handling, caching, and the x402 cost/settlement rules. An agent has everything needed to call it and anticipate the response.

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 parameters (via, indicators, history_months) are already fully documented in the schema. The description restates the indicators and the optional 24-month history without adding format or usage detail beyond what the schema provides, so the baseline 3 applies.

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

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

The description names a specific resource (key US macro indicators) and enumerates exactly what is returned: the Treasury par yield curve, BLS CPI/core CPI, unemployment and nonfarm payrolls, and the NY Fed fed funds rate. It even frames the tool as answering concrete questions, so an agent can instantly tell it apart from the SEC/filing siblings that dominate the namespace.

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?

Usage context is clear: the tool exists to answer macro-data questions, and 'Choose indicators to keep the answer short' tells the agent how to scope calls. However, it never states when NOT to use it or names a sibling alternative for related financial data, so it stops short of full routing 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?

Beyond the readOnly/idempotent annotations, it discloses key behavioral traits: no SMTP probing, catch-all domains accept any name, an invalid address is still a valid answer, only DNS failures error out, billing semantics (charged only on a returned result; 400/4xx/5xx are not settled), and the $0.001 x402 cost. This is substantially more than the annotations provide.

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

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

The purpose is front-loaded as three crisp questions followed by a scannable list of checks. It is dense and mostly earns its length, though the billing rule is stated twice ("not charged" vs. the explicit 400/4xx/5xx carve-out), a minor redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description carries the return contract itself: a verdict (deliverable/risky/undeliverable), a 0-100 score, and reasons. Combined with the check list, billing and cost disclosure, an agent has everything needed to invoke and interpret 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 description coverage is 100%, so both `email` and `via` are fully documented in the schema itself, including the accepted 'Jane Doe <jane@acme.com>' form. The description adds no parameter-level detail beyond the schema, so the baseline 3 applies.

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

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

The description opens with the concrete questions it answers ("Is this email address valid?", "Will mail to it bounce?", "Is it a throwaway...?") and then enumerates the exact checks performed. An agent immediately knows this is email-address validation, distinct from any sibling 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?

It states the triggering context clearly — "before an agent sends mail or saves a lead" — which tells the agent when to call it. It does not name alternative tools or exclusions, but no sibling covers the same ground, so the guidance is sufficient though not exhaustive.

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

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

Goes well beyond the annotations by disclosing sample freshness (refreshed every 5 minutes to 6 hours depending on the tool), a per-client rate limit, that pricing and payment routing are included, and that it also answers GET. These are exactly the operational traits annotations cannot convey, and they do not conflict with readOnly/idempotent hints.

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

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

Front-loaded with the essential behavior, then the alternate listing mode, then usage. The GET URL example is the only arguably extraneous element, though it is useful for integration testing. Overall tight for the amount of behavior it must convey.

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, the description carries the full burden and does so: it enumerates what comes back (the sample answer, the price of a call with your input, where to send it, or a list of tools with sample URLs). Combined with refresh cadence and rate limits, an agent has everything needed to call and interpret 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 coverage is 100%, so the baseline is 3, but the description adds real meaning: omitting `tool` switches the tool into a full listing mode with sample URLs, which the schema only implies via optionality. `via` is left to the schema, which already explains it is auto-filled.

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

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

States a specific verb and resource: it returns a paid tool's live sample answer to its documented example input, plus pricing and payment destination. It also declares the alternate no-argument behavior (list every paid tool with its sample URL), which cleanly separates it from every paid sibling it samples.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit when-to-use cases: checking output format and quality before paying, or testing an integration. It also explains the no-`tool` listing mode. It stops short of stating when not to use it (e.g. for production/real work, where you should pay), so it is clear context without exclusions.

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

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

Annotations already establish readOnly/idempotent/non-destructive, and the description adds substantial extra behavior: it flags impossible supersaturated results, returns `steps` with equations, applies ASHRAE psychrometrics at site elevation, and details the x402 billing semantics including when charges do and do not apply.

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?

Informative and front-loaded with example questions, but the billing/elevation/units detail in the back half is dense and somewhat overlong for a description intended for tool selection.

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 complex 13-param tool with nested state objects and no output schema, the description covers inputs, outputs (loads, tons, SHR, condensate, state points, steps), error behavior, units and billing—everything an agent needs to call it correctly.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds value by explaining the two-property state rule, the mixed-air back-calculation of outdoor air %, and the cooling/heating mode behavior beyond what field descriptions state.

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

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

The description states a specific verb+resource (cooling coil load / air mixing) and opens with three concrete example questions that map directly to the tool's function, making its scope unambiguous and distinguishing it from hvac_psychrometrics and hvac_duct_size.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It clearly states the required inputs ('Give the airflow and either the entering and leaving air...') and gives context for AHU/RTU selection, coil schedules and design checks. It doesn't explicitly say when to prefer hvac_psychrometrics alone, but the usage context is strong.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), but the description adds the billing model ($0.002 USDC per call via x402), the settlement edge cases (400 and 4xx/5xx not charged), the physics assumptions (Darcy-Weisbach/Colebrook-White, galvanized steel, standard air), and per-result 'steps' output. This is rich context well beyond the 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?

Dense and front-loaded with the example questions that anchor the tool's purpose, then inputs, outputs, units and pricing in order. It is long, and the units enumeration partly repeats the schema, but nearly every sentence carries information an agent needs.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite eight optional parameters and no output schema, the description fully specifies the return payload (exact diameter, rectangular equivalent, nearest standard sizes, friction loss, velocity pressure, Reynolds number, design checks, and 'steps') plus unit systems. Nothing needed to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description encodes cross-parameter constraints the schema cannot express: 'any two of a duct size, airflow, velocity and friction rate', and the fixed-side behavior for a single width/height. These combination rules materially affect a correct call.

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?

Names a specific computation (duct sizing and friction loss) and leads with three concrete example questions that define the resource precisely. It is trivially distinguishable from siblings hvac_coil_load and hvac_psychrometrics, which cover different HVAC domains.

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 'for duct design and checking' and, more usefully, explains the input-combination rule: give any two of size/airflow/velocity/friction rate, and that a lone width or height is held as a fixed side. It stops short of explicit when-not guidance or naming which sibling to use for related HVAC questions.

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

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

Beyond the read-only/idempotent annotations, it discloses the billing model ($0.002 USDC via x402), exactly when a charge occurs versus when it does not (400 and 4xx/5xx are unsettled), the validation behavior (impossible states are errors), and the returned `steps` audit trail. This is unusually rich 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 opens with the core question framing, then moves through inputs, outputs, equations, validation and billing in a logical order. It is dense and long, but nearly every sentence provides distinct, useful information rather than padding.

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, the description carries the return-value burden and discharges it fully: it enumerates all seven state properties plus specific volume, density, vapor pressure, and the embedded `steps` object. Combined with units, elevation, error and billing coverage, an agent has everything needed to call and interpret 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 coverage is 100%, so the baseline is 3, but the description adds the crucial combinatorial semantics that the schema cannot express: any two of seven thermodynamic properties are sufficient to define the state, and units/elevation govern both inputs and results. It does not mention the `via` tracking parameter, minor against its added value.

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

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

The description names a specific computation (psychrometric state-point solving) and grounds it in two concrete example questions about dew point, enthalpy and RH. It clearly distinguishes itself from the HVAC siblings hvac_coil_load and hvac_duct_size by resource and operation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It states the operative input rule ('from any two of dry bulb, wet bulb, dew point, relative humidity, humidity ratio, enthalpy or grains') and names the domains it serves (HVAC design, commissioning, energy, comfort), plus the failure condition (impossible states). It never explicitly routes away from a sibling or states when-not-to-use, so it falls short of a 5.

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

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

Goes well past the annotations (readOnly, openWorld, non-idempotent, non-destructive) by disclosing that it reads live from chain, runs risk checks, is built for polling via latest_block, costs $0.01 USDC per call via x402, and — critically — that invalid input (400) and upstream failures (4xx/5xx) are not settled. This charging/settlement detail is not derivable from any structured field.

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?

Purpose, scope, and polling pattern are front-loaded, and the dense enumeration of returned fields is informative rather than filler. It is long and slightly repetitive (the 6-hour limit appears twice), but nearly every sentence carries actionable 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?

With no output schema, the description carries the full burden of describing returns, and it does so in detail: name/symbol, new-contract flag, owner/renouncement, code powers, upgradeability, liquidity in USD, OFAC screening, and a verdict enum with reasons, plus latest_block for polling. An agent has everything needed to call and interpret 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 description coverage is 100%, so the schema already documents every parameter. The description restates the window limits (60 min default, up to 6 hours), the newest-first cap (up to 20), and the liquidity/high-risk filters, but adds no format or syntax detail beyond what the schema provides. 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?

States specific verbs and resources: it 'finds every pool created against WETH, ETH or USDC on Uniswap v2/v3/v4 and Aerodrome,' groups them, and runs the newest through token_risk_check. An agent can distinguish this (a launch-discovery + verdict tool) from siblings like token_launches_peek or token_risk_check without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Clearly frames the use case (trading/research agents asking what launched and which look safe) and gives the polling workflow with since_block. It also notes the default 60-minute window up to 6 hours. However, it never explicitly contrasts with the sibling token_launches_peek, leaving the agent to infer the distinction between a full verdict run and a cheap peek.

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

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

Annotations only cover the safety profile (readOnly/idempotent/non-destructive); the description goes well beyond by disclosing the 12-hour list refresh, exact pricing ($0.005 USDC via x402), the billing rule that 400 and 4xx/5xx are not settled, and the fuzzy-vs-exact matching behavior. That is exactly the extra context annotations cannot carry.

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

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

Front-loaded with the two core questions, then matching behavior, then return shape, then cost — a sensible ordering with no filler. It is dense and long, but nearly every clause carries distinct information an agent needs.

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, the description carries return-value burden and does: score, matched name (primary vs a.k.a.), listing fields, and the `clear` flag on no match. Combined with cost, refresh cadence and matching rules, nothing material is missing for correct invocation.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds semantics the schema lacks: name matching is tolerant of word order, accents, punctuation, honorifics, suffixes and typos, while crypto_address is exact match only, and it explains that the score is a 0-100 name-match value used with the threshold and that type/country act as filters.

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?

Opens with the two exact questions the tool answers and names the resource precisely (OFAC SDN and Consolidated lists, plus listed crypto addresses). An agent can distinguish it from wallet_risk_check or counterparty_check without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly names the situations it serves: KYC, vendor onboarding, payments and compliance checks, with the 'screening aid, not legal advice' boundary. It stops short of naming sibling alternatives (e.g. when to prefer wallet_risk_check or counterparty_check), so it is clear context without exclusions.

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

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

Annotations already cover the safety profile (readOnly, idempotent, openWorld, non-destructive), and the description adds substantial context beyond them: one payment round trip via x402, per-page ok:true/ok:false isolation so one bad URL does not spoil the batch, error codes (bot check, unreachable, unsupported content), JS not executed, no account/API key, and no charge if nothing can be read.

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 primary use case and batching benefit are front-loaded, and nearly every sentence carries information. It is a single dense block rather than a scannable structure, and the pricing clause ($0.008 vs $0.002 per page) takes some parsing, but there is little outright waste.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description carries the return-value burden and does so fully: Markdown main content or full mode, tables, code blocks, meta/JSON-LD metadata, PDF and RSS handling, per-URL success/error shape and ordering. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is 3; the description still adds value by explaining the 2-5 URL constraint, request-order result mapping, the mode main/full distinction, and how max_chars_per_page truncation is resumed via scrape_markdown next_offset. It goes modestly beyond the schema without re-documenting every field.

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

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

States a specific verb and resource ('read several web pages at once', 'Reads 2-5 public URLs in one paid call') and explicitly positions itself against scrape_markdown ('each exactly like scrape_markdown') and site_map (as a URL source). An agent can tell it apart from the single-page sibling without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives concrete when-to-use triggers (compare competitors' pricing pages, read top search results, pages a site_map call found) and names scrape_markdown as the alternative for continuing a truncated long page. It stops short of an explicit 'use the single-page tool instead when you have only one URL' exclusion, so it is clear context rather than a full when/when-not/alternatives statement.

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?

Far exceeds the annotations: it discloses that JS is not executed, that bot-check/empty pages return 422 and are not charged, that invalid input (400) and upstream failures are not settled, the exact cost ($0.002 USDC via x402), PDF limits (100 pages, 15 MB, no OCR), and JSON-LD/Next.js fallback behavior. This is exactly the value-add the annotations cannot carry.

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 single

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 exists, so the description must describe returns, and it does thoroughly: Markdown body, extracted metadata fields, HTTP status, word/token counts, optional links, and pagination parts. Nothing an agent needs in order to call it and interpret results is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description goes further by explaining the cross-parameter pagination flow (pass next_offset back as offset) and the token-saving intent of strip_link_urls, which adds workflow meaning beyond the per-field schema text.

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

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

States a precise verb+resource ('read a web page...') and enumerates the input types (article, documentation, PDF, RSS feed) plus the exact output (clean Markdown). Very clear. It does not, however, name or contrast any sibling such as web_search_read or scrape_batch, so the agent gets no explicit differentiation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The opening sentence gives a clear when-to-use trigger ('when an agent needs to read a web page...'). It does not state when NOT to use it or point to alternatives, so routing to siblings is left to inference.

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

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

Annotations cover the safety profile (readOnly, non-destructive, open-world), and the description adds context they cannot: the free/no-payment model, per-client rate limiting, the fact that it returns no company/filing/excerpt content, and that a ready-to-send paid call is bundled when something is new. That is unusually rich behavioral disclosure.

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

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

Front-loads the free/counts-only distinction, then the polling rationale. Every sentence carries a distinct fact (cost, scope, output limits, cursor chaining, rate limit) with no padding.

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?

There is no output schema, so the description carries the burden of describing the return shape – counts by level and type plus a new cursor – and it does so. Combined with annotations and full schema coverage, an agent has everything needed to call it correctly and interpret the result.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema by tying the filters to sec_market_alerts' identical semantics and explaining that the returned cursor is the value to pass back into `since` for incremental polling. It does not restate per-parameter syntax, which the schema already handles.

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

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

States a specific verb and resource – it 'counts the alerts sec_market_alerts would return' – and immediately scopes the result to counts by level and type with a cursor. The sibling relationship to sec_market_alerts is explicit, so an agent can distinguish the two without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an unambiguous when-to-use: poll for free every few minutes and only call the paid sec_market_alerts when new_alerts > 0. It names the alternative and the exact condition that selects it, leaving nothing to inference.

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

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

Well beyond annotations, it discloses HMAC-SHA256 signing with a signing_secret issued once at signup, ~2-minute delivery latency, 2-minute retry cadence, restart survival, the test-ping requirement, and precise billing semantics (charged only on returned result; 400 and 4xx/5xx not settled). Annotations only give the generic readOnly/openWorld/idempotent profile, so this extra operational detail is genuinely additive.

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

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

Front-loaded with the use case and pricing, and nearly every sentence carries distinct operational information. It is a single dense run-on paragraph, however, and re-lists filter values already present in the schema, so it is not maximally tight.

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 exists, yet the description explains the delivered payload shape (same as sec_market_alerts), the transport, signature scheme, retries, error treatment, cost, and lifecycle. An agent has everything needed to invoke it correctly.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds meaning the schema does not: the levels default of red/amber/green, the whole-market default for tickers, the extend-by-30-days behavior of renew_subscription_id, and the relationship between signing_secret and webhook_url. It only partially elaborates the type enums it re-lists.

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

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

States a specific verb and resource: it creates a paid 30-day subscription that POSTs SEC alerts matching supplied filters to an HTTPS webhook. It distinguishes itself from siblings by naming sec_market_alerts as the shape source and sec_alert_subscription_status as the free status/cancel path.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Opens with the exact user intent it serves ('tell me the moment any of my holdings files something bad, without polling'), then gives when-to-use-this variants: create new vs. extend via renew_subscription_id vs. cancel/check with sec_alert_subscription_status. Alternatives and preconditions (2xx test ping) are explicit.

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

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

Annotations declare non-readOnly, non-destructive, non-idempotent, which is a somewhat odd mix for a status/cancel tool. The description adds real value beyond that: it states the operation is free, that cancel takes effect immediately with no refund, and it enumerates the returned status fields (active state, expiry, delivered count, last delivery error). That is meaningful behavioral disclosure, though it doesn't address auth failure or idempotency of repeated cancels.

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 key qualifier ('Free, no payment needed') before the mechanics. Dense but every clause carries information; only the long enumeration of return fields makes it slightly heavy.

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, the description compensates by listing what the status call returns (active, expiry, delivered count, last delivery error) and by clarifying the destructive-looking cancel path is refund-free. Nothing an agent needs to invoke this correctly is missing.

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

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

Schema description coverage is 100%, so both required parameters and the cancel flag are already documented in the schema. The description corroborates the credential source and the cancel semantics but adds no format or edge-case detail beyond the structured fields, so the baseline 3 applies.

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

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

The description names a specific verb (check) and resource (SEC alert subscription), plus the secondary action (cancel), and contrasts with the sibling sec_alert_subscription by naming it as the source of the credentials. An agent can distinguish this from sec_alerts_peek and sec_alert_subscription without opening schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It states the prerequisites (subscription_id and signing_secret from sec_alert_subscription) and the trigger for the cancel path (set cancel: true). It doesn't explicitly say when not to use it or route to a different sibling for related tasks, but the context is clear.

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

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

Annotations cover safety (readOnly, non-destructive, openWorld, non-idempotent), but the description adds substantial economic and behavioral context beyond them: a free 404 when no releases exist, billing only on returned results, non-settlement on 400/4xx/5xx, and the $0.01 USDC x402 cost. It also describes the full return payload shape, which matters since there is no output schema.

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

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

Dense and front-loaded — the purpose, use cases, and return fields come first, with billing details last. It is longer than strictly necessary and some billing sentences could be tightened, but almost every clause carries operational 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?

With no output schema, the description fully enumerates what each result contains (company, ticker, EDGAR acceptance time, headline, revenue/EPS/margin/guidance highlights, opening paragraph, EX-99.1 and filing links), so an agent can consume the response without guessing. Nothing needed to call or interpret it is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantics: the cursor-chaining pattern ('pass the previous answer's cursor' into `since`) and the watchlist framing for `tickers`. It also explains the default day and the weekend/`latest` intent, though the schema largely carries the field documentation.

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

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

States a specific verb and resource (lists SEC 8-K item 2.02 earnings releases) with clear scope (a day, across all companies, newest first) and immediately distinguishes itself from siblings like sec_list_filings and sec_recent_events. The opening example questions anchor the intent precisely.

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?

Names concrete use cases ('Who reported earnings this morning?'), the watchlist filter, the cursor-polling pattern, and an explicit cheaper alternative (free sec_alerts_peek with types ["earnings"] counts them first). When-to-use and when-to-use-something-else are both covered.

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

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

Annotations already cover safety (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint), and the description layers on substantial extra behavior: TOC/page numbers/XBRL/HTML are stripped while tables are kept as rows, output carries filing date, fiscal period, accession number and sec.gov link, a 200,000-character cap, the 404 SECTION_INCORPORATED_BY_REFERENCE edge case with its free pointer, and the billing rule that only settled results are charged ($0.01 USDC via x402, 400/4xx/5xx not settled).

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

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

Front-loaded with example questions and the core one-section guarantee, then routing, edge cases, and pricing in descending priority. Every sentence carries information, but the opening question examples and the citation/pricing detail make it longer than strictly necessary for an expert agent.

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 exists, so the description must describe returns and it does: clean text with citation metadata, a character cap, and explicit error semantics for by-reference sections and invalid input. Combined with 100%-covered parameters and rich annotations, nothing an agent needs to invoke this correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds genuine semantics beyond the schema: lookup defaults to the latest filing, fiscal_year (2001+) selects an earlier report with 10-Q mapping to the latest quarter ending in that year, and a company-name ambiguity resolves to a free list of tickers. It stops short of restating enum syntax, which the schema already handles.

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

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

States a precise verb and resource: returns exactly one section (risk_factors, mda, business, etc.) of a US public company's 10-K/10-Q from SEC EDGAR as clean text. It explicitly distinguishes itself from siblings sec_filing_sections (several sections of one filing) and sec_section_changes (year-over-year deltas), so an agent can route without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Names the alternatives and the exact condition that selects each: sec_filing_sections for several sections, sec_section_changes for what changed, sec_list_filings to discover accession numbers. It also gives positive use cases (investment research, due diligence, competitor analysis) and states the tool's scope as a single-section extractor.

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

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

Goes well beyond the readOnly/idempotent annotations: it discloses the exact billing model ($0.015 per call, cheaper than per-section), that 404 on no-readable-sections is free, and that 400/upstream 4xx-5xx are not settled. It also documents the `not_found` behavior for sections absent from the filing and the x402 payment requirement — all operationally material context the annotations do not carry.

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

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

Front-loaded with purpose and an example, then inputs, then pricing/error semantics — a sensible order. It is dense and mostly earns its length, but the payment mechanism is stated twice ('Costs $0.015 USDC per call via x402' and 'Paid per call with x402 inside MCP'), which is redundant.

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?

There is no output schema, so the description carries the return burden — it specifies clean text, 2-3 sections, the `not_found` list, and the 404 case. Combined with the cost/error behavior and the per-section equivalence to sec_filing_section, an agent has everything needed to call and interpret this tool.

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

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

Schema description coverage is 100%, so the baseline is 3. The description largely restates schema semantics (latest filing default, `fiscal_year` since 2001, exact `accession_number`, ticker/CIK/company) and its 'Business and cybersecurity exist only in 10-Ks' note duplicates the schema's enum description rather than adding new syntax or format detail.

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

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

States a specific verb+resource+scope: returns 2-3 named sections of the same 10-K/10-Q, with the exact section list enumerated. It explicitly distinguishes itself from the sibling sec_filing_section ('Same inputs and output per section as sec_filing_section... at $0.015 for up to three sections instead of $0.01 each'), so an agent can route between the two without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Opens with the selecting condition — answering several questions about one report at once, with a worked example — and names the alternative (sec_filing_section) plus the economic reason to pick this one. Implicit exclusions are also clear: it is per-filing, so multi-company or multi-filing needs go to the batch/single sibling.

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

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

Beyond the annotations (which already declare readOnly/idempotent/non-destructive), the description discloses derived fourth quarters and cash flows with a `derived` flag, restatement behavior ('latest filing that reports it, so restated figures replace original ones'), period limits, filing coverage back to 2009, currency/filer scope, and the billing model (charged only on returned results; 400/4xx not settled). That is unusually rich 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?

It is front-loaded with representative questions then a dense but information-rich block, with almost every clause carrying load (fields, derivation rules, limits, pricing). The example questions are somewhat bulky and the single-paragraph wall of text could be better segmented, keeping it from a 5.

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, the description carries the full burden of describing return values, and it does: enumerated statement line items, derived margins and YoY growth, the `derived` flag, period counts, restatement semantics, and billing. An agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3 and the schema does the heavy lifting. The description still adds meaning beyond the schema: period selection maps to filing types (annual from 10-Ks vs single quarters), fiscal_year reaches earlier years, and identifiers are accepted by ticker/CIK/company 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 states a specific verb+resource: it returns a US public company's key financial-statement figures (income statement, balance sheet, cash flow) from SEC XBRL data. The example questions and enumerated field lists make it immediately distinguishable from siblings like sec_filing_section or sec_fund_holdings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives concrete usage cues ('What were Apple's revenue over the last five years?', 'Is Tesla's FCF positive?') and states constraints like annual/quarterly period selection, 20-period cap, back to ~2009, and 'US-GAAP filers only (not IFRS 20-F filers)'. It does not explicitly name sibling alternatives or when not to use it, so it stops short of a 5.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive, openWorld), but the description adds substantially more: $0.01 USDC per call via x402, the billing rule that a 404 no-match is free and 400/4xx/5xx are not settled, charging only when a result is returned, 50-result cap, and cross-page aggregation of top companies/forms. These are exactly the operational facts an agent cannot get from the 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?

Front-loaded with the example questions, then search mechanics, then the return payload, then pricing — a sensible priority order. It is longer than average, and the enumeration of hit fields is exhaustive, but that length is largely justified because no output schema exists. Minor trimming is possible but little is genuinely wasted.

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, the description carries the full return-value burden and does so: it lists every hit field (company, ticker, CIK, form, document type, date, period, accession number, links, 8-K items, location, next_call), the total hit count, the top-companies/forms aggregation, and next_offset paging. Payment, error, and pagination behavior are all stated, so nothing an agent needs to call and interpret this correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents every parameter including quoting syntax, form arrays, date formats, and offset paging. The description restates the quote syntax and filter dimensions ('filter by form, by company (ticker, CIK or name) and by filing date') without adding new semantics — this is baseline territory where the schema does the heavy lifting.

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

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

States a specific verb+resource ('Searches the full text of SEC EDGAR filings and their exhibits since 2001') and anchors it with four concrete example questions that no sibling like sec_list_filings or sec_filing_section could answer. An agent can immediately tell this is a keyword/text retrieval tool rather than a structured filing or section reader.

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 four example questions function as explicit use-case triggers, and the `next_call` field description ('the paid call that reads it — a 10-K/10-Q section, the 8-K event, or the document as Markdown') routes the agent onward to the deeper-read siblings once a hit is found. It stops short of naming those siblings directly or stating when NOT to use this tool (e.g. vs web_search or free_sample), so it is clear context without explicit 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?

Annotations already declare readOnly/idempotent/non-destructive, and the description adds material behavior the annotations cannot: the x402 payment model ($0.01 USDC per call), the settlement rule (charged only when a result is returned; 400 and 4xx/5xx not settled), and the aggregation behavior (positions merged across sub-managers, options marked put/call). These are exactly the operational facts an agent needs before invoking a paid 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?

Front-loaded with the user questions the tool answers, then inputs, then output shape, then cost — a sensible ordering. The long parenthetical manager roster is somewhat bloated and partially redundant with the `fund` schema example, but every remaining sentence (return fields, pricing, settlement) carries real 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?

With no output schema, the description fully carries the return contract: total value, position count, per-position fields (issuer, CUSIP, value, shares, % of portfolio, put/call), cross-sub-manager merge, quarter-over-quarter new/exited/adds/cuts, and a plain-English summary. An agent can predict the response and cost without any further source.

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 baseline is 3; the description still adds some meaning by tying `period` to 'latest or any period', explaining that returned changes compare against the prior quarter, and noting that `limit` affects listing while totals/changes cover the whole portfolio. The manager-name examples largely duplicate the schema, which keeps this from a 5.

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

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

The title and description state a precise verb+resource: 13F-HR fund holdings for a named manager or CIK, with concrete example questions ('What does Warren Buffett own?', 'Did Bridgewater sell Nvidia?'). This is clearly separable from siblings like sec_insider_trades or sec_financials, which cover different filer types and data.

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?

Usage context is clear: give a fund/investor name or CIK, with an enumerated set of common managers and a fallback ('any other 13F filer'). It also sets the eligibility boundary (managers over $100M in US equities file within 45 days), which implicitly tells the agent when this tool applies. It does not, however, name a sibling to use instead for adjacent questions (e.g., individual insider trades), so no explicit 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?

Goes well beyond annotations (which only cover read-only/idempotent safety) to disclose the 404-free behavior, that 400 and 4xx/5xx are not settled, the $0.005 USDC x402 cost, the 40-filing cap, and analytically important semantics like 10b5-1 plan and tax-withholding sales being separated.

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

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

Front-loaded with the motivating questions and the return shape before filters and billing, so the most important information comes first. It is dense and long, but nearly every clause carries distinct information rather than repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description fully specifies the return payload (trader identity, transaction date/code/meaning, shares, price, value, holdings, ownership type, footnotes, and an aggregate summary). For an 8-param paid read tool this is complete enough to call correctly.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning: transaction_codes examples (["P"] for open-market purchases), what include_derivative actually pulls in (option/RSU grants, exercises, expirations), and the 40-filing ceiling on limit. The ticker/CIK/company alternatives are also clarified.

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?

Opens with concrete questions the tool answers, then names the specific resource (Form 4 filings from SEC EDGAR) and its scope (officers, directors, 10% owners). The verb+resource is unambiguous and clearly distinct from siblings like sec_list_filings or sec_filing_section.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives clear triggering questions and describes the filter conditions (filing date, transaction code, include_derivative) that select this tool's behavior. It doesn't explicitly contrast against sibling filing tools, but the scope and examples leave little ambiguity about when to reach for it.

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

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

Goes well beyond the annotations (readOnly/destructive/openWorld/idempotent) by disclosing the billing model ($0.005 USDC per call via x402, settled only when a result is returned, 400/4xx/5xx not charged) and the incremental-polling contract via cursor. It also discloses data recency (~last week) and default filtering behavior, which annotations cannot express.

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

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

Front-loaded with the questions it answers, then scope, output, filtering, polling, and pricing — a logical order with no filler. It is dense and a little long, but each clause carries distinct operational information, so nothing is wasted.

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, the description compensates by describing the returned fields (stage, filing link, SPAC flag), ordering (newest first), recency window, and pagination via cursor. Together with the cost/settlement details, an agent has everything needed to call and iterate correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it defines each stage in terms of actual filing forms, clarifies that `since` takes the previous response's cursor, and explains the include_public_companies exclusion rule. This is more than the schema restates, though it does not cover the `via` or `limit` semantics.

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

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

States a specific verb+resource (lists IPO registrations from EDGAR's live feed) and pins the scope precisely: new IPO/SPAC registrations, newest first, with stage labels. It distinguishes itself from the broader sec_list_filings sibling by restricting to IPO/SPAC events and naming the filing types it captures (S-1, F-1, S-11, S-1/A, S-1MEF, 424B4).

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?

Usage is well-signaled through concrete triggering questions ('Who filed for an IPO this week?', 'Any new SPACs?') and operational guidance (poll with `since` = previous cursor; filter by stage or SPACs). It clearly states what is excluded (resale/follow-ons unless include_public_companies) but never names a sibling tool as the alternative, so it stops short of an explicit when-not/alternative routing.

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

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

Beyond the readOnly/idempotent/openWorld annotations, it discloses pricing ('free, no payment needed'), a per-client rate limit, a 50-filings-per-call cap, mode-dependent freshness (back to 2001 vs. the last few business days), and that every filing carries a next_call with the exact paid call, arguments and price. These are material behavioral facts an agent needs and none are in the 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?

Front-loaded with the two usage modes and dense throughout; the field inventory sentence (company, ticker, form, date, link, sections, items, next_call) is efficient. The three sample questions in the live-feed mode are somewhat redundant with the prose but they illustrate the use case usefully, so nothing is wasted outright.

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 an 8-parameter, no-output-schema tool this covers the essentials: both modes, all filters, defaults and caps, freshness windows, returned fields, rate limiting, and the monetization hook. An agent can call it correctly without inferring anything significant.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: items accepts words like 'earnings' and implies forms ["8-K"], a multi-company name match returns tickers for free, and since behaves differently per mode (2001 for one company, days for the market feed). It adds value over the schema text rather than repeating it.

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

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

The description states a concrete verb and resource (list a company's or the market's SEC filings) and explicitly separates the two operating modes with worked example questions. It also names sec_filing_section as the tool that extracts section text, so an agent can distinguish this index/feed tool from its extraction sibling without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It clearly says when each mode applies (ticker/CIK/company = historical company filings; no company = live market-wide feed) and routes section extraction to sec_filing_section. What is missing is an explicit when-not-to-use statement or a direct comparison against siblings like sec_recent_events or sec_earnings_today, which overlap with the 'latest feed' use case.

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=true, idempotentHint=false). The description adds genuinely useful non-annotation behavior: pricing ($0.005 USDC via x402), the billing policy (only settled when a result returns; 400/4xx/5xx not charged), store retention (~last day), and ordering (most serious first, then newest). That said, the standard for credit is lower when annotations carry safety, and return format is largely enumerated rather than deeply explained, so a 3 is fitting.

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

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

Front-loaded with representative user questions, then the alert taxonomy, then filters, then the polling/pricing mechanics. It is dense but every sentence carries information; the nested severity enumeration is long but is the tool's core value proposition.

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 exists, and the description compensates by listing the return fields (company, ticker, EDGAR acceptance time, items, text excerpt, filing link, paid read call) plus the cursor-based paging contract and cost model. An agent has everything needed to call and interpret 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 coverage is 100%, so the baseline is 3. The description still adds value beyond the schema by mapping `levels` to their constituent item codes, explaining that `since` takes the prior `cursor`, and clarifying that `tickers` acts as a watchlist over the whole market by default.

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

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

States a concrete verb and resource (surfacing red-flag alerts from new SEC filings across the whole market) and specifies the scope, severity taxonomy, and the exact filing events covered. An agent can distinguish it from sec_recent_events or sec_insider_trades without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit polling workflow (pass the previous answer's `cursor` as `since`, check the free sec_alerts_peek before paying) and states the cost-gating condition. When-to-use and the cheap alternative are both spelled out rather than implied.

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

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

Annotations already cover the read-only, idempotent, non-destructive, open-world profile, and the description adds substantial extra context: the four-business-day reporting window, item-code meanings, the 10-event cap per call, and detailed x402 billing behavior (charged only when a result returns, 404 and 400/5xx not settled). This is exactly the kind of behavior an agent cannot infer from structured fields.

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

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

Front-loaded with a plain-language framing question and then a structured inventory of return contents, so an agent can skim effectively. It is on the long side, with mild redundancy between the opening example questions and the later item-code list, plus a slightly repetitive x402 pricing sentence.

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 9 parameters, no output schema and no required fields, the description carries the burden well: it explains lookup keys (ticker/CIK/company), filtering, the accession-number mode, what is returned, and the billing/error model. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes further by decoding item codes (5.02 = executive/director changes, 2.02 = earnings, 1.01/2.01 = deals, 1.05 = cyber) and explaining the accession_number lookup path and per-call limit. It adds real interpretation beyond the schema text.

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

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

States a specific verb and resource: returns a US public company's most recent 8-K filings from SEC EDGAR, newest first, with item codes, prose text and EX-99 exhibits. It also distinguishes itself from siblings by naming sec_list_filings as the free accession-number lister and contrasting with a generic filing lookup.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives concrete use cases (event monitoring, news/earnings agents, due diligence, trading research) and names an alternative tool, sec_list_filings, for obtaining accession numbers. However, it never states when NOT to use it (e.g. versus sec_earnings_today or sec_alerts_peek), so routing guidance is strong but not exhaustive.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), yet the description adds substantial behavioral context beyond them: the billing model (charged only when a result returns, 404 free, 400/5xx not settled), $0.04 USDC via x402, the 'moved but identical counts as unchanged' rule, and the exact diff notation. This is unusually rich disclosure.

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

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

Front-loaded with concrete question examples, then mechanics, then billing. Dense and information-rich, but a few parentheticals and clauses could be trimmed; nothing is truly wasted, though it is longer than strictly necessary.

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 exists, so the description carries the return-shape burden and does so: it enumerates added/removed/edited paragraphs, word-level diff markers, and the summary counts plus unchanged-text share. Combined with billing and error behavior, an agent needs nothing else to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description nonetheless adds semantics the schema cannot: the default pairing of latest vs. previous 10-K, the newer/older role of fiscal_year vs. compare_to_fiscal_year, the 2001 floor, and the late-2023 filing boundary for cybersecurity. It adds meaning beyond the structured fields without restating syntax.

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?

Specific verb+resource: compares one 10-K section between two filings paragraph-by-paragraph. The three example questions and the explicit enumeration of outputs (added/removed/edited with diff markers) make it unmistakable against siblings like sec_filing_section, which merely returns a section.

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?

States intended use cases (risk monitoring, due diligence, investment research) and the default comparison behavior plus the fiscal_year/accession_number/compare_to_fiscal_year selection rules. It does not, however, explicitly name sibling tools (sec_filing_section, sec_filing_sections, sec_full_text_search) as alternatives for narrower 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?

Annotations already declare readOnly/idempotent/openWorld/non-destructive, so the bar is met, yet the description adds substantial operational detail: sitemap discovery order via robots.txt, index following with concrete caps (10 child sitemaps, 20,000 URLs), gzip support, home-page link fallback, no-charge on 502/404, and x402 pricing with no account/API key.

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

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

Front-loads the use case and result, then details discovery, filtering, follow-up calls, and cost. Dense but largely earns its length; some clauses (sitemap internals, pricing) run long and could be tightened.

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, the description supplies the return shape (page URLs with last-modified dates), failure semantics (502/404 uncharged), cost model, and the downstream scrape_batch workflow — everything an agent needs to invoke and then act on the result.

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

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

Schema coverage is 100%, so baseline is 3. The description goes slightly beyond by giving worked filter examples ('pricing', 'blog 2026', '/docs/') and restating the limit default of 200, but most parameter meaning is already in the schema, so it does not add deep new semantics.

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

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

States a specific verb+resource (map a site's pages/URLs) and immediately gives concrete motivations (find pricing, docs, blog, careers pages). It is clearly distinguishable from siblings like scrape_batch or web_search by framing itself as a pre-read inventory step.

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 when to use it ('before reading them'), what to give it (any URL on the site), and connects it to the next step ('next_calls read the first matches with scrape_batch'). It even names the behavior it mirrors (Firecrawl's /map), leaving nothing to inference.

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

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

Annotations already declare readOnlyHint, openWorldHint, and destructiveHint=false, but the description adds substantial behavioral context: free/no payment, rate-limited per client, counts-only return, ready-to-send paid call when new_tokens > 0, and polling-bot orientation. It does not contradict any annotation.

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

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

The description is front-loaded with the free/no-payment point, then explains counts, limits, paid alternative, and polling use. It is dense but efficient. Minor redundancy exists between 'Free, no payment needed' and 'peek for free,' but nothing is wasted overall.

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 what is returned (counts, distinct tokens, by DEX, latest block) and what is not returned (addresses, names, risk verdicts). It also covers payment model, rate limits, and the paid sibling alternative, leaving no critical gap for correct invocation.

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

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

Schema description coverage is 100%, so the schema already fully documents via, minutes, and since_block. The description mentions since_block/minute semantics and polling with latest_block, but adds little beyond the schema, matching the baseline of 3 when structured fields do the heavy lifting.

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

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

The description states a specific verb (counts), resource (pools created against WETH/ETH/USDC), scope (Uniswap v2/v3/v4 and Aerodrome on Base), and time basis (since_block or minutes). It clearly distinguishes itself from the paid new_token_launches sibling by explaining that this tool returns only counts.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly says when to use this tool (free polling: 'peek for free, pay only when new_tokens > 0') and when to use the alternative (paid new_token_launches for token addresses, names, and risk verdicts). The when-not condition is implied by the paid alternative and rate limit.

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

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

Annotations already say read-only and open-world, and the description adds substantial context beyond them: cost ($0.005 USDC per call via x402), the exact billing rule (charged only when a result is returned; 400 and 4xx/5xx are not settled), the upstream data sources read, and the limitation that this is heuristic, not a simulation or audit.

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

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

Front-loaded with the three questions it answers and what it reads, then pricing and error handling at the end, so the important detail comes first. It is a single long block, and the middle section that lists contract features is dense enough that it would read better as a list.

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 exists, so the description must explain return values, which it does: a verdict (high_risk, caution, no_flags), a risk score, and the reasons. It also covers failure modes (wallet address error, 400/5xx not charged), which is everything needed to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning the schema does not: the `address` must be a contract with code (a wallet address is an error), and the chain scope (Base or Ethereum) determines which DEX liquidity sources are used (Aerodrome only on Base).

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?

Names the exact resource (an ERC-20 contract on Base or Ethereum), the exact action (reads code, owner, proxy, privileged powers, DEX liquidity, OFAC screening, returns a verdict) and the question it answers. It also separates itself from adjacent siblings by declaring that a wallet address with no code is an error, which distinguishes it from wallet_risk_check.

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?

States the decision point clearly: use it before an agent buys, accepts or lists a token. It also states what it is not ("Heuristics, not a sell simulation or audit") and that wallet addresses are invalid input. It stops short of naming a specific alternative sibling to use instead for other cases.

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

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

Annotations already cover read-only/idempotent/open-world, and the description adds substantial non-obvious context: the sell test is a simulation with nothing sent on-chain, billing is settled only on success while 400/4xx/5xx are not charged, cost is $0.009 USDC via x402, and it is not financial advice. This goes well beyond what the annotations declare.

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

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

Front-loads the user-facing questions and the verdict scale, then the evidence sources, then the output shape and commercial terms in a logical order. The on-chain evidence list is long but each item is load-bearing; the only slack is mild redundancy between the grade and risk-score descriptions.

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, the description carries the full burden and delivers: it enumerates the returned artifacts (letter grade with meanings, sub-70-char one-liner, two-sentence take, red flags, good signs, USD liquidity, 0-100 risk score, honeypot sell test). An agent knows exactly what it gets back and what it costs.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds framing value by characterizing 'address' as a token contract with the Base-default/Ethereum choice spelled out in prose. The 'via' parameter is not discussed, which keeps it from a 5.

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

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

Opens with the exact questions it answers (scam? safe to ape? rug risk? accept as payment?) and states the resource (a token contract on Base/Ethereum) and the output (A-F grade). It also names the sibling token_risk_check as the destination for full evidence, so an agent can distinguish the two without opening schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly frames when to use it (quick verdict questions) and when to go elsewhere ('For every detail, token_risk_check returns the full evidence'). It also discloses the payment model and that only settled results are charged, which is directly relevant to deciding whether to invoke it.

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

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

Annotations already cover read-only/open-world/destructive flags, and the description still adds substantial non-obvious behavior: $0.005 USDC x402 cost per call, billing only on returned results, 12-hour OFAC refresh cadence, live on-chain reads, and an explicit 'screening aid, not legal advice' caveat. This is exactly the kind of billing and freshness context annotations cannot convey.

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

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

Front-loaded with the core question and the trigger scenario, and each sentence carries real information (what is checked, what is returned, pricing). It is a dense run-on paragraph with stacked clauses, but little is genuinely wasted.

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 exists, so the description carries the return contract and it does: verdict values (high_risk, caution, no_flags), a 0-100 risk score with reasons, and an explorer link. Combined with the stated inputs, cost, and freshness, an agent has everything needed to decide and call correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds mild context by tying the address to a payTo target and by naming the two chains it can query, but the parameter semantics (0x-address pattern, enum values, default) are already fully carried by the schema.

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

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

States a specific question it answers ('Is it safe to send money to this address?') plus the resource checked (an address) and the chains covered. It clearly distinguishes itself from siblings like token_risk_check and sanctions_screen by scoping to a wallet/contract address and enumerating exactly what it inspects (OFAC SDN/Consolidated, ownership, multisig, delegate, proxy, tx count, balances).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives a concrete trigger: use it before an agent pays an x402 payTo, a vendor, a user or another agent. It also discloses the pricing/settlement model (charged only when a result is returned; 400/4xx/5xx not settled). It stops short of naming alternatives (e.g. when to prefer token_risk_check or counterparty_check) or 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?

Goes well beyond the annotations by disclosing the return payload (ranked title/URL/snippet/date, direct answer or knowledge panel, related searches), the billing model ($0.006 USDC per call via x402), and precisely which outcomes are and are not charged (empty results are an error and free; 400/4xx/5xx not settled). That cost/settlement detail is exactly the behavioral context an agent needs before calling a paid tool.

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

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

Front-loaded with purpose, then return shape, then sibling routing, then billing — a sensible ordering where each sentence carries information. The three-sentence payment passage is slightly verbose relative to the rest, but it is decision-relevant for a paid call rather than 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?

With no output schema, the description compensates by describing the result structure (title, URL, snippet, date, optional direct answer/knowledge panel, related searches) and the cost/error contract. Nothing an agent needs to select or invoke this correctly is missing.

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

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

Schema description coverage is 100%, so num, query, country, language and time_range are already documented in the schema with defaults, patterns and enums. The description mentions filtering by country, language and recency but adds no syntax or semantics beyond what the schema states, so baseline 3 applies.

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

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

Opens with a specific verb+resource ("Answers any question that needs the live web") and immediately scopes the domain with concrete example queries. It also distinguishes itself from the retrieval siblings by naming web_search_read and scrape_markdown, so an agent can tell the three apart without opening schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly routes the agent: use web_search_read when you also need page contents, or scrape_markdown on an individual result, and notes the country/language/recency filtering available for narrowing. It does not state when *not* to reach for general web search (e.g., preferring sec_full_text_search for filings), so the guidance is strong but not exhaustive.

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

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

Adds substantial context beyond the annotations: unreadable pages (bot checks, errors) are skipped into `skipped`, results/all-results/direct-answer/related-searches are returned, and the cost model is spelled out ($0.012 USDC via x402, charged only when a result returns, 400 and 4xx/5xx not settled). None of this is derivable from the readOnly/openWorld/idempotent hints.

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

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

Front-loads the core behavior (search + read as Markdown) before secondary details, and every clause earns its place. It is dense and long, but the density is warranted by the billing and skip semantics.

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 paid, complex tool with no output schema, it discloses the salient return fields (`skipped`, all results, direct answer, related searches) and the charging conditions. It stops short of describing the full response shape, but an agent has enough to call it correctly.

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

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

Schema coverage is 100% so the baseline is 3; the description still adds routing value by grouping the filter parameters (country, language, recency) and the adjustable characters-per-page, reinforcing intent beyond the per-field schema text.

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

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

States a specific compound verb+resource ('searches the web, then reads the top results up to 3 as clean Markdown') and explicitly ties the reading behavior to scrape_markdown, so an agent can distinguish it from web_search and the raw scrape 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?

Frames the use case clearly ('answers a research question in one call' and 'gets sources' text instead of just links'), which implies when to pick it over a link-only search. It names scrape_markdown as sharing the reader, but never gives an explicit when-not or direct routing rule against web_search or scrape_batch.

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

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

Annotations only supply readOnly/openWorld/idempotent hints, but the description goes far beyond them: it discloses the request mechanics (GET then POST, unpaid), the checks performed (402 challenge parsing, OFAC screen, contract-vs-wallet detection on Base/Ethereum, Bazaar usage figures), the verdict vocabulary, and notably the billing semantics (only charged when a result returns; 400 and 4xx/5xx are not settled, $0.003 USDC per call). That is exactly the extra context an agent needs before invoking a paid tool.

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

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

Front-loaded with the decision question and trigger, then moves through checks, verdicts, billing, and cost in a tight sequence. It is long, but nearly every sentence carries distinct operational information; only the title restatement at the top is mildly redundant.

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 no-output-schema tool with an open-world, paid side effect, the description supplies everything needed: the request method, the checks, the return verdicts (ok_to_pay/caution/do_not_pay with reasons), the unreachable-endpoint case, and the settlement rules. Nothing material is left for the agent to infer.

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 all four parameters are already documented, including max_price_usd's effect on the verdict and method's auto GET-then-POST behavior. The description largely restates these ('Set max_price_usd to enforce a budget'; GET, then POST) without adding format or edge-case detail, so the baseline 3 applies.

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

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

The description opens with a specific verb and resource framed as a decision question: it answers whether an x402 endpoint is safe to pay before an agent pays an unknown seller. This is a distinct capability no sibling (token_risk_check, wallet_risk_check, counterparty_check, sanctions_screen) covers, so an agent can route to it confidently.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives a clear triggering context: run it 'before an agent pays a seller it has not used before', and instructs the agent to use max_price_usd to enforce a budget. It does not name an alternative or state when to skip it (e.g., already-verified sellers), so it stops short of explicit when-not guidance.

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