draconic21 x402 Data Tools

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

Beyond the annotations (readOnly, idempotent, openWorld, non-destructive), it discloses genuinely useful behavior: US-only coverage, 30-minute per-query caching, the x402/Base payment rail, that the caller's own wallet pays, and that the server never holds a wallet or pays on the agent's behalf. These are non-obvious operational traits an agent must know before invoking.

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 pricing/purpose hook is front-loaded and each sentence is substantive. There is mild redundancy — the price is stated twice and the 'server never pays on your behalf' point is made in both the intro and the payment_header description. Still reasonably tight for the amount of payment detail being conveyed.

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 steps in to describe return values (matched coordinates for forward, containing state/county/tract/block/CBSA for reverse, plus a count/items[] alias). Combined with the fully spelled-out payment handshake, 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 description coverage is 100%, so the schema already documents q-as-alias, lat/lon pairing, address exclusivity, and the payment_header contract. The description largely restates these, though it does add the return-shape note about a count/items[] alias modeled on a comparable's field names. Baseline 3 is appropriate when the schema carries the parameter 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?

The description states a specific verb+resource pair — forward and reverse U.S. geocoding — and names its upstream data source (Census Bureau Geocoder). It clearly enumerates the two modes via the address vs. lat/lon inputs. It does not, however, differentiate itself from the adjacent address_geocode_preview sibling, leaving the paid/preview split to be inferred from the name.

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 explicit procedural guidance: call with no payment_header first to get the challenge, then re-call with the signed header and the SAME business arguments. It also states the mutual exclusivity of the address and lat/lon input modes. It never says when to prefer this paid tool over the _preview alternative, so the when-not half is missing.

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

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

Annotations already declare readOnly, idempotent, non-destructive and openWorld, so the safety profile is covered. The description adds genuinely useful context beyond that: it is free, requires no wallet or payment, takes no arguments, and returns a sample rather than real geocoding output.

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

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

A single tight sentence, front-loaded with [FREE], that conveys pricing, prerequisites, and purpose with no waste.

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

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

For a zero-param preview with no output schema and rich annotations, the description is essentially sufficient, though it promises 'see the shape' without hinting at what fields the sample contains (forward/reverse geocode result), a small gap given the absent output schema.

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

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

With zero parameters the baseline is 4, and the description confirms 'no arguments needed', matching the empty schema with additionalProperties:false. Nothing further is required or missing.

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 precisely what the tool returns (a sample response for address_geocode) and its role (preview before paying), which cleanly distinguishes it from the sibling address_geocode and from the other *_preview tools. An agent can immediately tell this is a static demo rather than a live geocoder.

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 the when: 'so you can see the shape before paying 0.008 USDC', and the 'no wallet, no payment' clause removes preconditions. It stops short of naming address_geocode as the alternative for real lookups, leaving that routing to inference from the name.

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, so the bar is lower. The description adds genuinely new context: the call is free, hits no paid route, and enumerates what comes back (prices, call counts, redeem paths), 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?

One tight sentence, front-loaded with the [FREE] marker and the payoff fields. No waste, though the example id is a small embellishment.

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 annotations covering the safety profile and no output schema, the description does the right work by summarizing the returned fields. What is missing is how this catalog relates to the adjacent list_catalog and per-bundle tools, which an agent choosing between them would want.

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

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

The tool takes zero parameters, so per the rubric the baseline is 4; there is nothing for the description to clarify or omit.

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

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

States a specific resource (every prepaid bundle) plus concrete payload fields (prices, call counts, redeem paths) and an example bundle id. It does not differentiate itself from the sibling list_catalog, which plausibly overlaps.

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 '[FREE] ... without calling any paid route' framing implies when to use it (cheap discovery before redeeming), but no alternative or exclusion is named, and the relationship to list_catalog / bundle_redeem_* 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 already declare readOnly=false, openWorld=true, idempotent=false, destructive=false. The description adds substantial context beyond them: it is a paid x402 operation, it involves a two-phase challenge/response handshake, and it clarifies the caller's own wallet pays ('never this server's'). It stops short of describing token expiry or retry semantics.

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 [PAID] tag and price, then the mechanics. Slight redundancy as the $1.20 USDC on Base is stated twice and the per-call arithmetic is spelled out, but no sentence 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 still explains what each phase returns (payment requirements, then a signed bearer token) and the redemption path via a sibling tool. 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?

Only one parameter and schema description coverage is 100%, so the schema already documents payment_header's structure and the omit-on-first-call guidance. The description largely restates that flow, adding little 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?

States a specific verb and resource ('buy 100x edgar_filings calls') with an explicit prepaid-bundle scope. The contrast with `bundle_redeem_edgar_filings` (redemption) and raw `edgar_filings` (per-call) is clear from the text and title.

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 tells the agent when to use it and how: call with no payment_header first to get the challenge, pay, then call the SAME tool again with payment_header. It also names the follow-up tool (`bundle_redeem_edgar_filings`). Nothing 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 declare openWorldHint=true and idempotentHint=false, but the description adds the key business behavior the annotations cannot express: this call consumes one prepaid credit and involves no x402 payment. That consumption context is exactly what an agent needs before spending a token, though return behavior is not described (no output schema exists).

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 tight sentences with the token-gating front-loaded in brackets. However, the 'no x402 payment on this call' claim is stated twice (in the bracket and again in the body), 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?

For a billing-sensitive redemption tool with no output schema, the description covers the critical unknowns: what it costs (one bundle call), what auth it needs (bundle_token), and where the parameter semantics live. The residual gap is the undocumented business parameters, partially mitigated by the pointer to `edgar_filings`.

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 low (29%), covering only `ticker` and `bundle_token`. The description compensates partially by telling the agent the business arguments are identical to the paid `edgar_filings` tool, which is a genuine shortcut, but it does not name or explain cik/form/limit/since/until itself.

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 action (redeem one call from a prepaid bundle) and immediately separates it from the purchase sibling `bundle_edgar_filings_100` and from the paid `edgar_filings` tool it mirrors. An agent can tell exactly what this does and which sibling it is not.

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 makes the precondition explicit — you must already hold a token from `bundle_edgar_filings_100` — and clarifies this is not an x402-paid call. The alternative (the paid `edgar_filings` tool) is implied as the fallback when no token exists, but that choice is not spelled out.

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 non-read-only, non-idempotent, non-destructive, open-world. The description adds genuinely non-structured behavior: this call consumes one unit from a prepaid bundle token and skips the x402 payment path. It omits failure behavior (invalid/exhausted token), but given annotation coverage this is solid added 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?

Short and front-loaded with the critical token-gated marker. The 'no x402 payment' point is stated twice (in the bracket and again in the second sentence), which is mild redundancy but the whole thing remains 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?

For a token-redemption tool it covers the essentials: the token, the no-payment behavior, and the shared argument contract with the paid sibling. It leaves the token lifecycle (single-use vs reusable, exhaustion/invalid-token outcomes) unexplained, and there is no output schema to lean on for return semantics.

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 only 40%, with `limit`, `crypto_only`, and `entity_type` undocumented in both schema and description. The description partially compensates by pointing to `sanctions_delta` for 'same business arguments', but does not explain the undocumented parameters directly, so it lands at the baseline.

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 (redeem/spend) and resource (one sanctions_delta call from a prepaid bundle token), and names both the purchase sibling (`bundle_sanctions_delta_100`) and the paid equivalent (`sanctions_delta`). An agent can distinguish this from `bundle_redeem_sanctions_screen` and the paid tool 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?

Clearly signals the precondition (you hold a token bought via `bundle_sanctions_delta_100`) and the key exclusion (no x402 payment on this call, unlike the paid `sanctions_delta`). It does not cover what to do when the token is exhausted or how it compares to the other redeem sibling, so it stops just short of full when/when-not 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?

Annotations cover non-readonly and non-idempotent behavior, and the description usefully adds that the call consumes exactly one prepaid token and incurs no x402 payment, which explains why it isn't idempotent. It doesn't describe what happens when the token is exhausted or invalid.

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?

Short and front-loaded with the gating condition first. Slight redundancy — the no-x402-payment point is stated twice — but overall efficient.

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

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

For a no-output-schema redemption tool with annotations covering safety, the description supplies the key context: token-gated, single-credit consumption, same arguments as the paid tool. It could add what is returned or what happens on token failure, but nothing essential for correct invocation 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 all three parameters including the bundle_token bearer token are fully documented in the schema. The description only says the business arguments match the paid sanctions_screen tool, adding no syntax or format detail beyond the schema.

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

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

States a specific verb (redeem/spend) and resource (one call from a prepaid bundle), and names the purchase sibling bundle_sanctions_100 as the source of the token. It does not explicitly distinguish itself from the sibling bundle_redeem_sanctions_delta, which an agent might otherwise confuse it with.

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?

Clear routing context: use this when you hold a token from bundle_sanctions_100 and want no x402 payment, versus the paid sanctions_screen. Missing an explicit comparison against bundle_redeem_sanctions_delta, but the trigger condition is 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 only tell the agent it is a non-read-only, non-idempotent, open-world call. The description goes well beyond that: it discloses the exact price (0.4 USDC on Base), the x402 settlement mechanism, that the caller's own wallet pays, that the server never holds a wallet or pays on the caller's behalf, and that the response carries the redeemable token.

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 essential facts — PAID, exact price, and what the payment unlocks — before the redemption and wallet details. It is somewhat dense and repeats the price, but every sentence carries load-bearing information about cost, flow, or custody.

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, but the description compensates by telling the agent what the response contains (the token and how to redeem it) and naming the redemption tool. For a paid, two-step purchase flow this covers the cost, mechanics, custody, and next step an agent needs.

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 payment_header's shape and the two-step challenge flow, which sets a baseline of 3. The description reinforces how the parameter is used in context ('omit on your first call', 'call again with the SAME business arguments plus this field'), adding operational meaning beyond the raw field definitions.

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 ('unlocks a signed bearer token good for 100 further POST /v1/sanctions_screen calls') and explicitly differentiates from the per-call alternative by naming the price comparison. It also names the sibling needed to use the result (bundle_redeem_sanctions_screen), so the agent can distinguish it from sibling bundle tools 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 sequencing ('Call with no payment_header first to receive the payment requirements' then call again with the header) and a clear when-to-use rationale (cheaper than per-call, one settlement instead of 100). It also routes the agent to the redeem tool for the follow-up step, 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 declare non-readonly, open-world, non-idempotent, non-destructive; the description adds richer context: the 0.5 USDC/Base x402 payment, that the calling agent's own wallet pays, and that the server never holds a wallet or pays on the agent's behalf. This goes 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?

Front-loads the paid nature, price and what you get, then the flow. Dense but every sentence carries needed information; slight repetition of the wallet/payment framing costs a point.

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 single-optional-param payment tool with no output schema, the description covers the price, what the token grants, the redemption path, and the full two-call interaction, leaving no operational gap.

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 single payment_header parameter is fully documented in the schema, including how to obtain and format it. The description reinforces the flow but adds little parameter meaning the schema does not already carry, so the baseline 3 applies.

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

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

States a specific action (buy a prepaid bundle of 100 sanctions_delta calls) with price and mechanism up front. Clearly distinguishes this purchase tool from the redemption sibling it names.

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: redeem with bundle_redeem_sanctions_delta, and call with no payment_header first to receive the x402 challenge, then repeat with the signed header. When-to-use and the two-step flow are spelled out.

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/idempotent/openWorld, so the safety profile is covered — and the description goes well beyond it by disclosing the paid tier, the 0.01 USDC-on-Base price via x402, that the caller's own wallet pays, and that the server never holds a wallet or pays on the caller's behalf. That is exactly the kind of behavioral context 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 core purpose and price tag, then the merge/scope claim, then the input rule, then payment mechanics. Dense but each sentence carries required information. Slightly long, with the competitor-comparison clause being the only near-disposable 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?

For a paid, nested-payment-header, no-output-schema lookup tool, the description covers everything an agent needs: accepted identifier types, ambiguity handling, the full x402 payment handshake, and the shape of the returned record. No output schema exists, yet the return fields are summarized.

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 each parameter already documents its own mutual exclusivity, so the schema does the heavy lifting. The description's restatement of the 'exactly one of' rule and the q-as-name-alias note add only marginal value beyond the structured fields. 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 a specific verb+resource — a normalized company-identity record — and enumerates the returned fields (legal name, LEI, CIK, tickers/exchanges, jurisdiction, status, parent). It also scopes the data sources (SEC EDGAR + GLEIF LEI) and contrasts scope against a narrower alternative, so an agent can tell it apart from the edgar_* and company_lookup_preview siblings 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 states the input constraint ('Exactly one of name/q/ticker/lei/cik required'), the fallback behavior for ambiguity ('ambiguous name queries return top_matches instead of guessing'), and the exact payment call sequence (call with no payment_header to get the challenge, then re-call with the same business args plus the signed header). Nothing about when/how to invoke 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 already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered without description help. The description adds that no wallet or payment is needed, which is useful context beyond annotations. However, it doesn't disclose what the sample response contains or any rate limits on the free preview, leaving moderate gaps.

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

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

A single sentence with the 'FREE' tag at the front, immediately followed by the purpose and constraints. Every clause earns its place: free status, sample nature, payment context, and no-argument/no-wallet qualifiers. No redundancy.

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

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

For a zero-parameter, read-only preview tool with no output schema, the description is adequately complete: it explains the free sample purpose and confirms no wallet or arguments are required. It could say more about what the sample response actually contains (e.g., which fields), but the core needs for correct invocation are met.

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

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

The tool has zero parameters, so per the rules the baseline is 4. The description directly states 'no arguments needed', which reinforces the schema and removes any doubt for the agent. No further parameter detail is possible or needed.

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 this is a free sample response for company_lookup that shows the shape before paying, which is a specific verb (lookup) and resource (company) with a clear preview purpose. It distinguishes from the paid sibling by explaining the free preview role. It does not restate the full SEC EDGAR + GLEIF LEI merge detail from the title, but the preview nature is clear.

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 'No wallet, no payment, no arguments needed' and frames it as a preview 'before paying 0.01 USDC'. This tells an agent exactly when to call it: to inspect the response shape without payment. It clearly contrasts with the paid company_lookup tool, making the when-to-use condition obvious.

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 the readOnly/idempotent/openWorld annotations, it discloses the cost (0.001 USDC on Base), that payment is made by the calling agent's own wallet and never by the server, the data provenance (own GDELT news_search client plus Hacker News), and an honesty guarantee that whyItMatters/match are null rather than fabricated sentiment.

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 price and paid-feed identity are front-loaded, which is good, but the body is an overstuffed run-on full of parenthetical asides (the 'matching its $0.001 price exactly'/'field-for-field' compatibility claims add bulk without decision 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?

There is no output schema, so the description carries the return-shape burden and does so: it names headlines[] with title/url/source/publishedAt and the {status, data, meta} nesting, plus the optional limit and the full payment round-trip. 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 description coverage is 100%, so both parameters (limit, payment_header) are already fully documented in the schema, including the base64 payload shape. The description largely restates the schema ('Optional limit (1-30, default 20)'), so with the schema carrying the load a baseline 3 is correct.

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

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

The description states a specific resource — a fixed, no-required-params crypto headline feed returning headlines with title/url/source/publishedAt — so an agent can tell what it returns. It does not name the obviously adjacent sibling crypto_news_preview (the sibling list pairs every paid tool with a *_preview variant), so the differentiation burden falls on the 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?

It gives explicit invocation flow: call first with no payment_header to get the x402 challenge for free, then re-call with the same business arguments plus the signed PAYMENT-SIGNATURE header. It does not say when to prefer this over crypto_news_preview or news_search, but the payment mechanics are unusually well specified.

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. The description usefully adds that no wallet, payment, or arguments are required, which is real auth/cost context beyond the annotations. It does not describe the sample's contents, but the free/no-auth detail is valuable.

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

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

A single front-loaded sentence beginning with the [FREE] marker, so the key distinction is immediately visible. Efficient and appropriately sized for a zero-param preview.

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 zero-param preview with no output schema, the description covers what the agent needs: it returns a sample of crypto_news, is free, and needs no auth. Minor gap is not describing the sample's content, but the preview concept is complete.

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

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

Zero parameters, so the baseline is 4. The description reinforces this with 'no arguments needed', consistent with the empty schema. Nothing further is required.

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 purpose: it is a free sample response for the crypto_news tool, letting the agent see the response shape. This cleanly distinguishes it from the paid sibling crypto_news without needing to open 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?

The description communicates when to use it (before paying 0.001 USDC) and names the parent tool it previews, which routes the agent between preview and paid version. It stops short of an explicit 'use crypto_news for real data' statement, so it is clear but not fully spelled out.

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 (readOnly/openWorld/idempotent/non-destructive): the exact data sources (IANA RDAP bootstrap, TLD registry RDAP, own resolver, no third-party DoH relay), a 30-minute cache, that raw is honestly null, and the full payment model where the calling wallet pays and the server never holds a wallet. These are non-obvious traits an agent needs to call it correctly.

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 but well front-loaded: the paid marker and one-call value proposition come first, followed by data sources and payment mechanics. Some redundancy — the $0.012 USDC / x402 payment terms appear both at the start and the end — but nearly every sentence 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?

Despite there being no output schema, the description explains return contents (RDAP fields, email-auth records, posture summary, additive aliases, null raw), sources, caching, and the payment precondition. 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 description coverage is 100%, so both parameters (domain and the nested payment_header) are already fully documented in the schema, including the two-step payment handshake. The description's parameter-relevant content merely restates the payment flow, so the baseline 3 is appropriate when 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 and resource ('Domain identity & trust posture in one call') and enumerates exactly what is returned: RDAP registration data, live DNS email-auth (MX/SPF/DMARC/NS), and a heuristic posture summary. An agent can clearly separate this from siblings like domain_intel_preview or email_validate 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?

The description gives a concrete paid-workflow instruction ('Call with no payment_header first to receive the payment requirements... call this same tool again with the SAME business arguments'), which is useful usage guidance. However, it never says when to prefer this over the sibling preview tool or email_validate, so alternative-selection guidance is absent.

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?

The annotations already cover read-only, idempotent, non-destructive, open-world behavior, so the bar is lower. The description still adds real value beyond them: no wallet, no payment, and a sample (not full) response, which is exactly the behavioral context an agent needs before spending USDC.

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

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

A single sentence with the [FREE] marker and pricing context front-loaded; every clause earns its place and nothing is repeated from structured fields.

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

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

For a zero-parameter inspection tool with no output schema, the description covers cost, payment, and argument expectations. The one meaningful gap is whether the sample payload is static or live data, which would affect how an agent interprets the preview.

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

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

With zero parameters the baseline is 4. The statement 'no arguments needed' is consistent with the empty schema and additionalProperties:false, giving the agent positive confirmation rather than leaving it to infer from an empty properties object.

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 plainly that this is a free preview returning a sample response for the domain_intel tool, which distinguishes it from its paid sibling. The actual domain-specific subject matter (RDAP/DNS email-auth) lives only in the title, but for a preview tool the 'what' is adequately conveyed.

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?

'See the shape before paying 0.012 USDC' gives a clear condition for choosing this over the paid domain_intel, and 'no arguments needed' clarifies invocation. It stops short of explicitly naming domain_intel as the alternative to call once satisfied, but the routing intent is unmistakable.

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 behavior: the agent's own wallet pays, this server never holds a wallet or pays on the user's behalf, and the first call is free to retrieve the payment challenge. This is exactly the kind of payment-flow disclosure 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 price and purpose, and the payment steps follow logically. Slightly redundant in restating the $0.03/USDC/x402 payment detail in two places, which costs it a point.

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, but the description makes clear the return is the union of filings + company facts for one company, so an agent knows what to expect. With annotations covering safety and the schema covering inputs, the only residual gap is explicit return-shape detail, which is minor given the explicitly named constituent tools.

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 schema already documents all 8 parameters including the nested payment_header. The description adds the nuance that business arguments must be reused identically across the two calls, but no format or constraint detail beyond the schema. Baseline 3 is appropriate.

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

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

States a specific verb+resource: it bundles edgar_filings + edgar_company_facts for one company in a single paid call, and even quantifies the cost advantage over buying both ($0.04 vs $0.03). An agent can identify the constituents and the combined resource 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 clear operational context: call with no payment_header first to get the x402 challenge, then re-call with the same business arguments plus the signed header. It implies use-when-you-need-both via the 'cheaper than buying both separately' framing, but never explicitly routes to edgar_filings or edgar_company_facts for single-need 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 non-destructive behavior. The description adds valuable context beyond annotations: it is free, requires no wallet or payment, and takes no arguments. No contradictions with 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?

Two tightly written sentences, front-loaded with [FREE] and the core purpose. Every phrase adds useful selection information: sample nature, target sibling, cost model, and lack of required arguments. No waste.

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

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

For a zero-parameter preview with no output schema, the description is adequate: it identifies the source tool, clarifies the sample nature, and notes no payment or arguments are needed. It could mention whether the sample is static or truncated, but nothing critical for correct invocation is missing.

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

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

The tool has zero parameters and 100% schema coverage, so parameter semantics are inherently minimal. The description reinforces this by stating 'no arguments needed', which matches the empty schema. Baseline for zero-param tools is 4.

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 the tool returns a sample response for edgar_bundle and explicitly frames it as a free preview before paying. It clearly distinguishes itself from the paid sibling edgar_bundle, but relies on the title or external knowledge of edgar_bundle to know what data is actually sampled.

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 condition and alternative: use this to see the shape before paying 0.03 USDC for edgar_bundle. It also clarifies no wallet, payment, or arguments are needed. No explicit when-not guidance, but 'sample' implicitly limits use to preview rather than production data.

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

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

Annotations already declare it a read-only, idempotent, open-world operation, so the safety profile is covered; the description adds genuinely non-redundant behavior: paid ($0.02 USDC on Base via x402), live-fetched from data.sec.gov, wallet never custodied by the server, and the two-step challenge/retry handshake.

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 paid tag and the core resource description, then covers the payment flow in one compact sentence. Slightly redundant in restating the price and 'your own wallet pays' twice, but no sentence 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?

For a 4-param, 0-required tool with nested payment object and no output schema, the description discloses what is returned (concept value, period end, form, filed date), the data source, and the full payment handshake. Only the sibling/alternative routing is left implicit.

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 every field (cik, ticker, concepts, payment_header) is already documented in the schema, so the baseline is 3. The description echoes the payment_header mechanics but adds no syntax or format detail beyond the schema.

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

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

States a specific verb/resource combo: fetch key XBRL facts (Assets, Revenues, NetIncomeLoss, EPS) for a US-listed company by ticker or CIK, with the source (data.sec.gov). It is clearly distinct from filings/fulltext siblings, though it never names the paid-vs-preview sibling (edgar_company_facts_preview) that an agent would most need to disambiguate.

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 operational workflow: call with no payment_header first to receive the x402 challenge, then re-call with the same business arguments plus the signed header. It does not, however, advise when to prefer this over the preview or the bundle/filings 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, openWorld, non-destructive. The description adds genuinely new context: no wallet, no payment, no arguments — auth and cost behavior not captured by annotations. What it does not clarify is the fidelity of the sample (truncated vs. representative), which is the main behavioral unknown for a preview.

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, both earning their place, with the [FREE] marker and no-payment constraint front-loaded. No redundancy.

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

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

For a zero-param preview tool with no output schema, the critical missing piece is what the sample actually contains and how faithful it is to the paid response. The description gestures at 'the shape' but gives no detail, leaving the agent to call blind on whether the data is usable.

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?

Zero parameters, so baseline is 4. The description reinforces this with 'no arguments needed', confirming the agent should call it bare.

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 clearly that it returns a sample response of edgar_company_facts, tying it directly to the sibling paid tool. The resource is identified by the title (SEC EDGAR XBRL company facts); the description itself is about the preview mechanism rather than the data content, so it falls just short of a self-contained 5.

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

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

Explicitly frames the use case: 'see the shape before paying 0.02 USDC'. This tells the agent when to reach for the preview rather than the paid call. It does not spell out the inverse (use edgar_company_facts when you need actual data), but that is strongly 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 cover read-only/idempotent/open-world, and the description adds substantial non-obvious behavior: a paid endpoint at a stated price, live fetch from data.sec.gov, the two-call x402 handshake, and the critical assurance that the calling agent's own wallet pays and the server never holds funds. That is exactly the kind of operational context 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 key facts (paid, resource, forms, output) but the price and payment mechanism are repeated three times across the bracket prefix and body, which costs space without adding 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?

For a seven-parameter paid tool with a nested object and no output schema, the description covers return contents (URLs, timestamps), data source, and the full payment lifecycle. Only the routing versus sibling EDGAR tools 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 all seven parameters are already documented in the schema. The description restates the payment_header workflow but adds no syntax or precedence detail beyond it (e.g. that cik overrides ticker is in the schema, not here). 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 (retrieve recent SEC filings) with scope: by ticker or CIK, enumerated form types (10-K, 10-Q, 8-K), plus what's returned (document URLs, acceptance timestamps). It does not explicitly distinguish itself from siblings like edgar_fulltext_search or edgar_company_facts, so it stops short of a 5.

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

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

Gives clear procedural guidance for the payment flow ('call with no payment_header first'), but never says when to choose this tool over edgar_fulltext_search, edgar_company_facts, or edgar_bundle. Usage is implied by the resource description rather than contrasted with 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 cover safety (readOnly, idempotent, non-destructive, openWorld), so the description's job is to add context. It does so by disclosing the pricing model (free vs 0.02 USDC), the absence of any wallet/payment requirement, and that no arguments are needed — none of which is 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?

A single tight sentence, front-loaded with the '[FREE]' marker and the preview purpose. Every clause earns its place.

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

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

With no output schema, the description correctly tells the agent this returns a sample response so the shape can be inspected before paying. That covers the essential need for a zero-param preview tool, though it could note the sample is illustrative rather than live data.

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

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

The tool takes zero parameters, which is the baseline-4 case. The description confirms 'no arguments needed', matching the empty schema, though there is nothing further to disambiguate.

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 exactly what the tool is: a free sample response for edgar_filings, so the agent can inspect the response shape without paying. The resource and the distinguishing trait versus sibling edgar_filings are both explicit.

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 when to use it — before spending 0.02 USDC on the paid edgar_filings call — and notes no arguments are required. It does not explicitly state that this is not a substitute for real data, but the 'preview/sample' framing implies 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 the safety profile (readOnly, idempotent, non-destructive, openWorld), yet the description goes further and discloses the cost ($0.02 USDC on Base), the x402 payment handshake, the free first call with no payment_header, and that the server never holds or spends a wallet. That is exactly the extra context 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?

The cost is front-loaded in a bracket tag and the routing rule comes before the payment mechanics. It is dense with no filler, though the closing payment sentences are slightly repetitive of both the schema and the opening tag.

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 read-only search with no output schema, the description supplies the complete picture an agent needs: what is searched, how to narrow it, when to prefer the sibling, and the full two-step payment procedure.

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%, including a fully spelled-out payment_header object, so the schema carries the parameter semantics. The description's payment-flow narrative (call with no header first, then resend with the signed header) largely restates what the schema already documents, so it adds little beyond the baseline.

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 actual TEXT of SEC filings) plus scope (since 2001, any company, by phrase) and even names the upstream index it uses. It explicitly contrasts itself with sibling edgar_filings, so an agent can disambiguate 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 explicit routing rule: use this when you don't know which company filed, use edgar_filings once you do. That is a clear when-to-use / when-to-use-something-else statement naming the concrete alternative.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds genuinely new context beyond the annotations: it is free, requires no wallet and no payment, and takes no arguments. That auth/cost disclosure is exactly the kind of extra context worth crediting.

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

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

A single sentence, front-loaded with the [FREE] tag and the preview purpose, then the cost rationale and the no-argument/n0-payment guarantee. No sentence is wasted and nothing is buried.

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 zero-arg, annotation-rich preview tool with no output schema, the description tells the agent everything needed to invoke it: it is free, requires nothing, and returns a sample of the paid tool's shape. It could be slightly stronger by stating that no real data is returned or how the sample relates to live results, but it is complete 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?

Zero parameters, so the schema carries no semantics to explain. The description correctly states 'no arguments needed', reinforcing what the empty schema shows. Baseline 4 applies for a parameterless tool with 100% coverage.

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

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

The description names the specific resource it previews (edgar_fulltext_search) and states its exact role: return a sample response so the agent can see the response shape. It implicitly distinguishes itself from the paid sibling by referencing the 0.02 USDC cost, so an agent can route correctly. It does not describe what the underlying EDGAR full-text search actually returns, but that is the paid tool's job.

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: use this before paying to inspect the response shape. The paid alternative is identified by name and cost, giving the agent a decision basis. There is no explicit 'do not use if' or mention of the many other *_preview siblings, so it falls short of a full when/when-not 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?

Adds substantial context beyond the annotations: a paid x402 flow with an explicit price, the wallet-ownership model ('your own wallet pays, never this server's'), the DNS sourcing method (own resolver, protocol-level), the static self-maintained disposable list heuristic, and the concrete limitation of no SMTP/inbox verification.

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

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

Front-loads the key 'PAID + price' fact, which is good, but it is one dense paragraph that repeats the 0.006 USDC/Base price and the no-vendor/wallet assertions more than once, adding 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 implies return content by listing the checks and 'flags', and it fully explains the payment prerequisite. It stops short of describing the actual response shape, which would help close the gap left by the missing output schema.

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

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

Schema description coverage is 100%, so both the email and payment_header parameters are fully documented in the schema. The description restates the two-step payment flow but adds no syntax or format detail beyond what the schema already provides, 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+resource and enumerates exactly what is validated (syntax, MX/A-fallback deliverability, disposable/role/free-webmail flags, SPF/DMARC), plus explicitly what it does NOT do (no SMTP connection, no inbox confirmation). It also distinguishes itself from a sibling by noting 'same sourcing as domain_intel'.

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 call flow ('Call with no payment_header first to receive the payment requirements') and clarifies the boundary that it never confirms a specific inbox. However, it never names the obvious free alternative email_validate_preview or states when to prefer one over the other.

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). The description adds genuinely useful context beyond them: no wallet or payment required, no arguments needed, and — critically — that the payload is a sample rather than live validation output, which prevents the agent from treating the data as real.

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

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

One sentence, front-loaded with the [FREE] marker and immediately explaining the sample-response purpose. Every clause carries information; nothing 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?

For a zero-argument preview with no output schema, the description supplies the essentials: it is free, needs no wallet or parameters, and returns a shape-demonstrating sample. It does not detail the fields present in the sample, but 'see the shape' adequately signals the caller should inspect the response itself.

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

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

The schema has zero properties and 100% coverage, so the baseline is 4. The description reinforces this by stating 'no arguments needed', which is accurate and prevents an agent from hunting for missing inputs.

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 exactly what the tool returns: a sample response for email_validate, provided free so the caller can inspect the response shape before paying. It names the sibling (email_validate) it previews, so an agent can distinguish it from the paid tool and from other *_preview siblings.

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

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

It clearly frames the use case: call this first to see the shape, before spending 0.006 USDC on the real email_validate. There is no explicit 'do not use for real validation' exclusion, but the 'sample response' wording and the reference to the paid tool make the boundary 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?

Beyond the read-only/idempotent/ open-world annotations, the description discloses that results are cached 30 seconds across all callers, the exact cost (0.002 USDC via x402), and the critical trust boundary that 'your own wallet pays, never this server's.' These are precisely the behavioral facts 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 [PAID] tag and price are front-loaded, and the sentences are information-dense with little padding. The payment/wallet point is stated twice ('paid via x402 by the calling agent's own wallet' and 'your own wallet pays, never this server's'), a minor redundancy in an otherwise tight 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?

With no output schema, the description compensates by enumerating the returned values, the units (gwei), the chain scope, the caching behavior, and the full payment handshake. An agent has everything it needs to invoke this tool correctly on the first attempt.

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 sequencing meaning the schema cannot: that payment_header should be omitted on the first call and supplied on the retry with the same business arguments. It also pins the chain to base mainnet, reinforcing the enum.

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

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

The description names a specific verb and resource ('Current Base gas market read live from Base's own public JSON-RPC') and enumerates the returned values (legacy gas price, EIP-1559 base fee, priority/max fee, transfer cost estimate), clearly distinguishing it from a hosted gas-oracle vendor. It does not explicitly differentiate itself from the sibling gas_price_preview, so it falls just short of a 5.

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

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

The two-step x402 invocation pattern is spelled out concretely: 'Call with no payment_header first to receive the payment requirements' then call again with the signed header. It also scopes the tool to 'Base mainnet only (eip155:8453).' It offers no explicit comparison to the free gas_price_preview alternative, 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 establish readOnlyHint, idempotentHint and destructiveHint=false. The description adds genuinely non-annotated context: no wallet, no payment required, and zero arguments. Return format is not described, but as a shape-preview tool that gap is minor.

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

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

A single front-loaded sentence. The cost/benefit framing ('[FREE]' ... 'before paying') leads, and every clause earns its place.

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

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

For a no-argument preview tool with no output schema, the description supplies what an agent needs: cost, prerequisites (none), and intent. It does not hint at what fields the sample response contains, but that is what the call itself reveals.

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?

Zero parameters, so the baseline is 4. The description reinforces this by explicitly stating 'no arguments needed', which matches the empty schema.

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

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

States a specific verb+resource: it returns a sample response for gas_price. The '[FREE]' marker and 'before paying' clause distinguish it cleanly from the paid gas_price sibling without needing to open 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 clear context for use: run this to see the response shape before spending 0.002 USDC. It stops short of explicitly naming gas_price as the follow-up alternative, but the implied workflow is 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 cover the safety profile (readOnly, idempotent, openWorld), and the description adds substantial behavior beyond them: a two-call x402 payment handshake, per-section parallelism with independent timeout guards, graceful degradation (a failing section returns status "unavailable" rather than failing the whole call), and per-section status/sources output. It also clarifies the server never holds a wallet, which is important for 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?

It is long but dense and front-loads the paid/pricing signal, then the section list, then failure behavior, then the payment handshake. Minor redundancy: the $0.05 price and "paid via x402" are stated three times, and the wallet-ownership point is repeated.

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 composite tool with no output schema, the description covers the essentials: what runs and when, partial-failure semantics, the two-step payment protocol including the exact header shape to echo back, and cost. 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 description coverage is 100%, so the schema already documents mutual exclusivity of name/ticker/lei/cik and the optionality of email/domain/wallet; baseline would be 3. The description adds routing semantics the schema cannot express — that any combination of identity/domain/wallet/email is allowed and that only sections backed by supplied arguments execute — which is genuine 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 composite resource (a merged KYB report) and enumerates exactly which sub-reports it runs (company_lookup, sanctions_screen, domain_intel, wallet_profile, email_validate), each corresponding to a sibling tool. An agent can immediately distinguish this aggregator from the individual section tools 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 the use case (compliance/onboarding) and the triggering condition clearly: supply at least one of name/ticker/lei/cik/domain/wallet/email, and only the implied sections run. It also frames the alternative economically (bought separately up to $0.064 vs flat $0.05), but never explicitly names a sibling like company_lookup or wallet_profile as the thing to use when you only need one section.

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 readOnly/idempotent/non-destructive, and the description adds real value beyond them: it is free, requires no wallet or payment, and takes no arguments. The one gap is whether the returned sample is canned data or a live lookup, which matters for downstream trust in the output.

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

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

A single sentence, front-loaded with the [FREE] tag and the reason it exists, followed by the payment and argument constraints. Every clause earns its place with no redundancy.

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

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

For a no-input preview tool with annotations carrying the safety profile, the description is nearly complete: it explains the cost model and the purpose. It does not describe the returned sample's structure, but given the tool exists specifically to let callers observe that shape, a modest gap remains.

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

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

With zero parameters the schema is fully self-documenting, and the description reinforces this with 'no arguments needed', confirming the caller cannot and should not supply input. Baseline is 4 for a 0-param tool.

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 sample response for kyb_pack so the caller can see the shape before paying. It distinguishes itself from the paid kyb_pack sibling by naming it directly. Slight ambiguity remains about whether the sample is static or live, but the free-preview role is clear.

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 explicit when-to-use context: run this before paying 0.05 USDC for kyb_pack. It also states the preconditions (no wallet, no payment, no arguments), which is exactly the guidance an agent needs to avoid misfiring on the paid tool. No explicit 'what will not work' beyond cost/free terms, so not 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 establish read-only, idempotent, non-destructive behavior. The description adds material context not in annotations: the operation is free and avoids paid routes, which matters on a paid API server. It does not detail auth or rate limits, but that is not critical for a read-only catalog.

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

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

Single sentence, front-loaded with the [FREE] marker and core purpose. Every phrase contributes: catalog scope, included price/description metadata, and the no-paid-route constraint.

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 zero-parameter, read-only catalog endpoint with no output schema, the description supplies the catalog scope, included metadata, and free/no-paid-route behavior. Annotations cover safety traits, so no necessary context 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?

Zero-parameter schema with 100% description coverage; baseline is 4. No parameter meaning needs to be conveyed, and the description does not need to compensate for schema gaps.

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 ('Returns'), specific resource ('full tool catalog'), included metadata ('prices and descriptions'), and a clear differentiator ('without calling any paid route'). This cleanly separates it from paid endpoint siblings and preview variants.

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?

Signals when to use it via '[FREE]' and 'without calling any paid route', implying it is the discovery step before invoking paid routes. It does not explicitly name alternative discovery tools, but the routing condition 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 already declare read-only/idempotent/open-world/non-destructive, yet the description adds substantial context beyond them: the paid x402 model and price, the fact that the first call returns a payment challenge for free, that the calling agent's own wallet pays and the server never holds one, and that it returns headlines/URLs/metadata only and never relays article body text.

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 price tag and core capability, and each sentence is largely functional. The payment mechanics are stated twice within the description ('Call with no payment_header first...' and '$0.009 USDC on Base, paid via x402...'), which is mild redundancy in an otherwise dense, well-ordered block.

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 11-parameter paid tool with a nested payment_header object and no output schema, the description covers the critical unknowns: the payment handshake, what the return contains, and the timeline-vs-articles behavior. 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. The description still adds meaning beyond the schema by explaining what mode:'timeline' actually returns (volume+avg-tone series) and by consolidating the timespan range, sort options, and max_records bounds, though most individual parameter meaning is already in the schema.

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

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

States a specific verb+resource ('Multi-language, multi-country news headline search plus an optional volume/tone timeline') and grounds it in a named data source (GDELT DOC 2.0). An agent can distinguish it from siblings like crypto_news or social_trends_pulse 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?

Gives clear usage context: pass mode:'timeline' for a per-period volume+tone series instead of an article list, and explains the required first-call-without-payment flow. It does not name a sibling alternative (e.g. news_search_preview, crypto_news) or state exclusions, so it stops short of the 5 bar.

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, idempotent and non-destructive. The description adds meaningful context beyond them: no wallet, no payment required, and no arguments — key facts for an agent deciding whether to invoke it in a paid pipeline.

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

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

A single sentence front-loaded with [FREE] and the purpose, with zero filler. Every clause earns its place.

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

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

For a zero-argument preview whose entire purpose is to show response shape, the description is largely sufficient. It could hint at what the sample contains, but with no output schema and no parameters, little more is required.

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?

Zero parameters, so the baseline is 4. The description reinforces this with 'no arguments needed,' leaving no ambiguity about how to call 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?

States clearly it returns a sample response for news_search so the agent can preview the response shape — a distinct role next to the paid sibling news_search. The verb is implicit (it returns a static sample rather than performing a search), but the intent is unambiguous once you read it.

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

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

Tells the agent exactly when to use it: before paying 0.009 USDC, implying the paid news_search is the alternative. It does not spell out the paid tool by name, but the condition that selects this tool is explicit and 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?

Goes well beyond the readOnly/idempotent/openWorld annotations by disclosing hard limits (10 MiB, 40 pages/call), the SSRF-hardened fetch, and the critical failure mode that scanned/image-only PDFs return empty text with a warning rather than a fabricated OCR guess. The payment flow (server never holds a wallet, caller's wallet pays) is also spelled out, which 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 price and purpose, then capabilities, then constraints, then payment mechanics. Dense but nearly every clause carries information; the repeated '$0.04 USDC on Base' statement is the one mildly redundant element.

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 covers the return shape (per-page plain text + metadata), the degenerate case (empty text + warning for image-only PDFs), and the full payment lifecycle, so an agent has everything needed to call it correctly on the first attempt.

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

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

Schema coverage is already 100%, so the baseline is 3; the description adds real value on top by restating the url/pdf_base64 mutual exclusivity, the 10 MiB decoded cap, and the semantics of the payment_header two-step handshake that the schema documents only partially.

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 ('PDF -> per-page plain text + metadata') plus the exact mechanism (pdfjs-dist) and explicit negations (no OCR, no tables, no vendor), which separates it from generic extraction tools and from the pdf_extract_preview sibling implied by the catalog.

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 operational guidance: pass exactly one of `url` or `pdf_base64`, and make a first call with no payment_header to receive the x402 challenge before paying. It does not, however, explicitly name a sibling alternative (e.g. pdf_extract_preview) or state 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?

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is fully carried by structured data. The description adds two non-obvious facts not in annotations: no wallet/payment is required and no arguments are needed. That is real added value, but it stops there.

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

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

One tight sentence, front-loaded with [FREE] and the payment/error-proofing facts. 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?

For a zero-param preview tool this is adequate: it tells you it costs nothing and takes no inputs. But it never states what the real pdf_extract actually extracts, so an agent cannot fully judge whether this sample is worth invoking.

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?

Zero parameters, so baseline is 4. The description explicitly states 'no arguments needed,' which correctly and usefully reinforces the empty schema.

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

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

The description states this is a free sample/preview of pdf_extract, so the resource is clear and the sibling relationship is explicit. But it never says what the tool actually does (PDF text extraction), only that it mirrors pdf_extract. A reader who did not recognize the name would not know the purpose from this sentence.

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 implies the usage condition (free preview before paying for pdf_extract), but gives no explicit when-to-use vs. when-to-use-pdf_extract guidance beyond 'sample response.'

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, but the description adds substantial context beyond them: this is a paid x402 tool, the calling agent's own wallet pays, the server never holds a wallet or pays on its behalf, and the change data comes from OFAC's own feed rather than a self-diff of snapshots. That is exactly the kind of behavior an agent needs before invoking.

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 price, then purpose, then the differentiation, then the payment mechanics, so the important routing signal comes first. Slightly redundant in stating the 0.008 USDC/Base price twice, but every sentence otherwise earns its place.

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

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

The payment mechanics, data provenance, and required parameters are covered thoroughly enough for a nested-object, 5-param tool. With no output schema, it does not describe the return shape (e.g., the list of publications and fields), which is the main remaining gap.

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 five parameters (limit, since, crypto_only, entity_type, payment_header) are already documented in the schema. The description reinforces the crypto/change semantics and the payment_header flow but adds no syntax or format detail beyond what the schema provides; 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+resource: which OFAC SDN entries and crypto wallet addresses were added, removed, or modified since a date, sourced from OFAC's official change-tracking feed. It explicitly contrasts its scope with a point-in-time screening check, so an agent can distinguish it from sanctions_screen 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?

Gives clear usage context ('what changed since I last screened' vs 'is this on the list right now') and the payment invocation flow (call with no payment_header first, then re-call with the signed header and the SAME business args). It does not name the alternative sibling (sanctions_screen) directly, so routing is implied rather than spelled out.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so safety and idempotency are covered. The description adds that it is free and needs no wallet/payment/arguments, which is useful context beyond annotations, but it does not describe what the sample response actually contains.

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

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

Single compact sentence that front-loads the free preview nature and the no-payment/no-argument conditions. No wasted words.

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

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

For a zero-parameter preview tool with no output schema, the description covers what it is and what it costs (free). It could mention that the returned data is a sample/stale rather than live OFAC deltas, but the preview label and 'sample response' phrasing largely convey this.

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?

Zero parameters, so baseline is 4. The description correctly states no arguments are needed, matching the empty 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 it is a free preview of the OFAC sanctions change-tracking tool and that it returns a sample of the paid response shape. This distinguishes it from the paid sanctions_delta, though the phrasing 'sanctions_delta' could be clearer as 'the paid sanctions_delta 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?

Implies use when you want to see the response shape before paying. Does not explicitly say 'use the paid version for real data' or list alternatives, but the preview-vs-paid distinction is clear from the description and sibling naming.

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, non-destructive, openWorld), so the bar is lower, yet the description still adds useful behavior: live fetch rather than a stale snapshot, and an explicit custody statement that the server never holds a wallet or pays on the caller's behalf. This is material context beyond the structured 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?

The pricing is front-loaded, which is appropriate, but the same fact is repeated three times ('0.006 USDC on Base via x402', '$0.006 here vs its $0.01', '$0.006 USDC on Base, paid via x402'). The wallet-custody sentence is also echoed in the payment_header schema description, so the prose is longer than the payload warrants.

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 should ideally indicate what a screen returns (match/no-match, score, matched alias), but it never describes the response shape. The payment and screening mechanics are complete, yet an agent still cannot predict the result format 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 description coverage is 100%, so every parameter (name, type, lists, wallet, threshold, payment_header) is already documented in the schema, including the fuzzy-vs-exact match semantics and the notes that 'pep' is not screened. The description mostly restates the type/threshold/lists fields as compatibility knobs without adding new syntax, 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: 'Screen a name and/or crypto wallet address against the U.S. Treasury OFAC SDN list'. It scopes what is matched (primary names, aliases, digital-currency addresses) and notes it comes live from the official export service. It does not distinguish itself by name from nearby siblings like sanctions_screen_preview, sanctions_delta, or bundle_sanctions_100, so differentiation relies on inference.

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 payment flow is spelled out precisely: call with no payment_header first to get the challenge, then retry with the signed header using the same business arguments. However, there is no guidance on when to choose this tool over sanctions_screen_preview or sanctions_delta, so the sibling-selection question is left unanswered.

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), and the description adds information they cannot express: no wallet or payment is required, no arguments are needed, and — critically — the output is a sample rather than live screening data, which prevents an agent from mistaking it for real OFAC 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?

Two short sentences, zero filler, with the cost/purpose signal ('[FREE]', 'before paying') front-loaded so the agent grasps the value proposition immediately.

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 zero-parameter, read-only preview with no output schema and full annotation coverage, the description supplies everything needed to invoke it correctly and interpret the result as illustrative data. It could be marginally stronger by stating what the real screening response contains, but nothing required for correct invocation is missing.

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

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

The tool takes zero parameters (schema coverage 100%, empty object), so the baseline is 4. The description reinforces this with 'no arguments needed', aligning with the empty schema rather than contradicting 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?

States exactly what the tool returns (a sample response for sanctions_screen) and frames it as a preview of the paid counterpart, which cleanly separates it from the many *_preview siblings. An agent can tell from the description alone that this is a free shape-inspection call, not real screening 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?

Gives a clear use condition: run it to see the response shape before paying 0.006 USDC for sanctions_screen. The paid alternative is named, so the when-to-use decision is easy to infer, though it never explicitly states 'use sanctions_screen instead when you need actual screening results'.

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), and the description adds substantial behavior they don't capture: the tool is paid (0.07 USDC on Base via x402), the calling agent's own wallet pays, the server never holds a wallet, and the payment challenge is free on the first call. This is exactly the extra non-annotation context an agent needs before invoking a paid endpoint.

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 core purpose is front-loaded in the first clause, which is good, but the pricing is stated twice ('0.07 USDC on Base via x402' and again '$0.07 USDC on Base, paid via x402') and the long parenthetical plus payment paragraph make it denser than necessary. Sentences are individually clear but the redundancy costs it.

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 archive-analysis tool with no output schema, the description conveys what the output classifies (signal ids/topics by trend status), the time window, and the full payment handshake. It does not describe the return payload shape or pagination, but the coverage of purpose and payment is largely sufficient to invoke correctly.

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

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

Schema description coverage is 100%, with both 'days' (1-90) and 'payment_header' fully documented in the schema itself. The description restates the days range and the payment_header flow but adds no semantics beyond what the schema already provides, so the baseline 3 for high coverage applies.

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

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

The description states a precise analytical output: which signal ids/topics are 'stable, rising, new, or fading' across the last N archived days, and explicitly frames it as an 'archive compound' rather than a brief dump. It names one sibling (signal_history) as the alternative, but leaves the overlapping signal_delta and signal_topic_trace siblings unaddressed, so differentiation is only partial.

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 names the alternative and the condition that selects it ('not a full brief dump — buy signal_history for that'), and gives a concrete two-step invocation flow for payment. It stops short of stating when this tool should NOT be used relative to signal_delta/signal_latest/topic_trace, so it 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 declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds genuinely new behavioral context: it costs nothing, requires no wallet or payment, and takes no inputs — the key operational facts 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?

A single tight sentence with the '[FREE]' marker and the sibling it previews front-loaded, followed by the zero-friction facts. No filler, no repetition of the title.

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, but the description explicitly frames the return as a sample response whose purpose is to reveal the shape, which is the relevant expectation-setting an agent needs. It is complete for a zero-argument, zero-cost preview tool.

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

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

The tool takes zero parameters, which is the baseline-4 case, and the description reinforces this by stating 'no arguments needed' so the agent knows not to supply any. Nothing further is required.

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

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

States a specific resource (a sample response for signal_continuity) and explicitly distinguishes it from the paid sibling, with the free/preview nature front-loaded. An agent can tell immediately this is the no-cost sample path rather than the production signal_continuity call.

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

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

Communicates when to use it ('see the shape before paying') and what it requires (no wallet, no payment, no arguments). It does not explicitly state the inverse condition — that paid signal_continuity should be used for real data — but that is strongly implied and the sibling name is given.

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 by disclosing the full x402 payment lifecycle: price (0.04 USDC on Base), who pays (the calling agent's own wallet), the two-call handshake, and the explicit guarantee that the server never holds a wallet or pays on the agent's behalf. This is exactly the behavioral 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 payment tag and the core purpose, and every sentence is actionable. Minor redundancy: the price and the 'your own wallet pays, never this server's' guarantee are each stated twice.

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, no-output-schema tool the description covers the payment handshake fully, which is the hardest part for an agent to get right. It is thin on what a 'Signal brief' actually contains and on failure modes (e.g., date outside the archive), so an agent still lacks some result-shape context.

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

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

Schema description coverage is 100%, so the schema already documents both date and payment_header in detail. The description's 'Body { date: YYYY-MM-DD }' merely restates the schema without adding format edge cases or fallback behavior for unavailable dates. 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 a specific verb and resource — point-in-time purchase of ONE archive date's full Signal brief — and immediately distinguishes the scope from 'buying full history,' which maps to signal_history. An agent can tell this apart from sibling tools 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?

Gives a clear use case (backtesting or auditing a single curated day) and the key procedural rule: call first with no payment_header to get the challenge, then re-call with the same arguments plus the signed header. It does not, however, route the agent to signal_day_preview for a free look or name signal_history / signal_latest explicitly as 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 readOnlyHint, idempotentHint, etc., so safety is covered. The description adds that no payment or authentication is needed, which is valuable context beyond the annotations. It doesn't describe the return format, but as a preview that's less critical.

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

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

Two concise sentences, front-loaded with [FREE] and the key differentiator. Every word earns its place.

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

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

Given zero params and rich annotations, the description adequately covers the tool's purpose and usage. It could briefly mention what the signal represents, but for a free preview the current level of detail is sufficient.

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?

Zero parameters, so baseline is 4. The description confirms no arguments are needed, which aligns perfectly with the empty schema.

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

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

The description states it's a sample response for signal_day, showing the shape before paying. It clearly identifies the premium counterpart, though the actual content of the daily signal isn't described beyond being a sample.

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 'No wallet, no payment, no arguments needed,' clearly indicating when to use this free preview versus the paid signal_day. The sibling context makes the preview/paid pattern evident.

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 goes well beyond them: it discloses price (0.05 USDC on Base via x402), that the caller's own wallet pays, that the server never holds a wallet, and the two-step payment-challenge handshake. This is exactly the mutation/payment context an agent needs.

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

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

Dense but front-loaded with the payment-gating context before the mechanical details. Every sentence serves a purpose (cost, availability check, no-payment first call), though the payment description is repeated between the prose and the schema-adjacent text.

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, but the description names what comes back (new, changed, removed headlines) and fully covers the payment/auth prerequisite and the availability pre-check. Sufficient for an agent to invoke correctly, though the exact response shape is left implicit.

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%, including the nested payment_header object and its name/value fields, so the schema carries the parameter burden. The description reinforces the payment_header lifecycle but adds little syntax beyond what the schema already documents; 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 (return new/changed/removed headlines) and resource (Signal headlines since since_date), and explicitly distinguishes itself from signal_latest by framing itself as a cheap delta check rather than a fresh re-scrape.

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

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

Explicit when-to-use: intended repeat purchase for an agent holding an earlier dated brief. Gives the exact precondition workflow — call the free availability endpoint first, pay only when has_newer_day is true, and omit payment_header on the first call. Nothing 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?

The annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the safety profile is covered. The description adds genuinely useful context beyond that: no wallet, no payment, no arguments required, which tells the agent this call is cost-free and credentialless — a real behavioral trait not encoded 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?

A single sentence, front-loaded with the '[FREE]' tag, that states the artifact, its purpose, and the cost/credential profile with no filler. Every clause earns its place.

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

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

For a no-argument, read-only preview with no output schema, the definition covers cost, credentials, and intent adequately. The one gap is that it never hints at what the previewed payload contains, which is nominally the tool's whole point, though the title largely compensates.

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

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

There are zero parameters and schema coverage is 100%, so the baseline is 4. The description confirms 'no arguments needed,' aligning with the empty schema rather than contradicting it, and adds nothing misleading.

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 artifact — a free sample response for the signal_delta tool — and distinguishes it from its paid sibling by price and by the absence of a wallet requirement. It stops short of explaining what the underlying signal content actually is (the title's 'what changed since your last pull' carries that weight), so it is clear but not fully self-contained.

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

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

It gives an explicit condition for use — 'before paying 0.05 USDC' — which routes the agent to this preview over the paid signal_delta when it only wants to inspect the response shape. It does not state when the paid tool is the better choice, but the free-vs-paid split makes the alternative obvious.

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

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds the critical behaviors annotations cannot: it is a paid tool (0.10 USDC on Base via x402), the two-step challenge/sign flow, that the calling agent's own wallet pays, and that the server never holds or uses a wallet. That is exactly the kind of auth and cost context an agent needs.

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

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

Front-loaded with the [PAID] tag and price, then the resource, then the payment procedure. Four sentences that mostly earn their place, though the price is stated twice ('0.1 USDC' and '$0.10 USDC on Base'), which is 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 and a paid, two-step interaction, the description covers the payment lifecycle, wallet ownership, and day-range semantics completely. The main omission is any hint of what a 'brief' contains, but for a paid archive fetch the invocation-critical information is present.

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 genuine meaning beyond the schema: cost is flat regardless of day count (so days is not a pricing lever) and payment_header is optional on the first call, defining the same-arguments-replay contract. This enriches the parameter behavior rather than repeating 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?

The description states a specific verb and resource: returns the last N days (1-30) of Daily Agent Signal briefs from a proprietary archive. An agent can infer this is the multi-day counterpart to signal_day/signal_latest, though no sibling is named explicitly. Purpose is clear but not differentiated by name.

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 explicit operational guidance for the paid flow ('Call with no payment_header first to receive the payment requirements') and signals the multi-day use case via the 1-30 day range and flat pricing. It stops short of naming signal_day/signal_latest as the single-day alternatives, so routing is inferred rather than stated.

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

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

Annotations cover read-only/idempotent/non-destructive, and the description adds real context beyond them: it is free, requires no wallet, no payment, and no arguments. Auth/payment prerequisites are exactly the kind of behavior an agent needs and the annotations do not supply.

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

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

One compact sentence, front-loaded with the [FREE] marker and the key precondition (no wallet/payment). Minor redundancy between '[FREE]' and 'before paying', but nothing bloats it.

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 zero-argument preview tool with no output schema, the description covers the essential facts: free, no auth, no params, sample of signal_history. It stops short of hinting at what the sample data looks like, but nothing needed 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?

Zero parameters, so the baseline is 4. The description confirms 'no arguments needed', which matches the empty schema and prevents an agent from hunting for required inputs.

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 the verb+resource clearly (a sample/free variant of signal_history) and distinguishes itself from its paid sibling signal_history by explicitly framing itself as a preview of the response shape. It does not explain what the archive content actually is, but the preview-vs-paid distinction is unambiguous.

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

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

Gives clear context: use it to see the shape before paying 0.1 USDC, with no wallet or payment required. It does not explicitly name signal_history as the alternative to call after previewing, but the 'before paying' framing implies the when-to-use condition well enough.

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: it discloses the exact price and network (0.03 USDC on Base), the x402 mechanism, that the calling agent's own wallet pays and this server never holds a wallet, and the two-step challenge-then-retry flow. None of this is derivable from readOnlyHint/idempotentHint/destructiveHint/openWorldHint.

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 paid status and leads with the payload contents before the payment mechanics. Slightly redundant: the price '0.03 USDC on Base via x402' is stated twice, once in the bracket and again mid-paragraph, which costs space without new 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?

For an open-world, no-output-schema tool the description covers the essentials: what the payload contains, that continuity is derived from a stored archive, and exactly how to satisfy payment. Minor gaps remain around freshness/latency or whether prior archive data is bundled, which an agent budgeting a paid call might want.

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 already 100%, so the baseline is 3. The prose adds the meaningful operational nuance that the parameter is omitted on the first call and supplied on retry with the same business arguments, and reinforces that the header comes from the caller's own x402 client.

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

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

States a specific resource and enumerates what it returns (curator judgment, buyer_value, action_hint, sources) plus the continuity aspect versus a multi-day archive. The word 'Today's' does imply recency, but with siblings like signal_day, signal_history, signal_continuity and signal_delta, the description never names which sibling it is not, so the agent must guess at the boundary.

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 procedural guidance for the payment handshake ('call with no payment_header first'), which is genuinely useful. It does not, however, explain when to pick this over signal_day or signal_history, leaving alternative selection implied by the word 'Today's' and by nothing else.

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/idempotent/non-destructive, so the bar is lower. The description adds meaningful behavior beyond that: it is free, costs no wallet or payment, and requires no arguments – exactly the traits that distinguish a preview from the 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?

A single sentence with the [FREE] marker front-loaded, immediately conveying the cost benefit. Zero wasted words.

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

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

For a zero-arg preview tool with no output schema, the description explains what it returns (a sample signal_latest response) and the cost model, which is enough to call it correctly. A hint at what the sample contains would make it fully complete.

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

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

The tool takes zero parameters, which sets the baseline at 4, and the description reinforces this with 'no arguments needed.' There is nothing further to document.

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 purpose: a free sample response for signal_latest to inspect the output shape before paying. The verb+resource (preview of the signal_latest payload) is clear, and it explicitly distinguishes itself from the paid sibling signal_latest.

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 ('see the shape before paying 0.03 USDC') and names the paid alternative by implication. It does not spell out when-not to use it (e.g. when real data matters), so it stops short of a fully explicit routing 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?

Annotations cover the safety profile (readOnly, idempotent, non-destructive), and the description goes well beyond by disclosing the full x402 payment flow: call without payment_header first to get the challenge, sign with your own wallet, retry with the same business args, and that the server never holds a wallet. That is non-obvious operational context an agent cannot get 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-loads the PAID tag and core purpose well, but the price ('$0.06 USDC on Base') is stated twice and the payment mechanics are repeated in both the description and the payment_header schema field, adding 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 names the returned fields (dates, headlines, judgments, vs_prior, ranks), and it fully documents the payment handshake. Nothing an agent needs to invoke this paid tool 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 the mutual-exclusivity rule for topic vs id that an agent must honor. It does not add format examples beyond the schema, keeping it at 4 rather than 5.

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

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

States a specific verb ('trace') and resource ('ONE topic or ONE signal id across every dated archive brief'), and explicitly distinguishes itself from buying full history, which separates it from sibling signal_history. An agent can tell it apart 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?

Gives a clear selection condition ('when you only care about one thread') and the constraint 'Provide exactly one of topic or id'. It implies the full-history alternative but never names signal_history explicitly, so an agent must infer the sibling to route against.

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, open-world and non-destructive behavior, so the bar is lower. The description adds genuinely useful context beyond them: it is free, requires no wallet/payment, and takes no arguments.

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 compact sentences with the [FREE] tag and the pay-to-preview rationale front-loaded. Every clause earns its place; nothing 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?

For a zero-parameter, read-only, free preview with no output schema, the description covers what an agent needs: what it returns (a sample response), its cost (free), and its purpose (inspect shape before paying). Only the content of the sample itself is unspecified, which is acceptable for a preview.

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

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

There are zero parameters, so the baseline is 4. The description reinforces this with 'no arguments needed,' correctly signaling that the call takes none.

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 action (return a sample/free preview response) and explicitly ties it to the sibling signal_topic_trace, so the agent can tell it apart from the paid tool. It does not explain what a 'topic/id trace' actually contains, so the resource is only partially clarified.

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 use condition: call this to inspect the response shape before paying 0.06 USDC for signal_topic_trace. It does not state exclusions (e.g., that the data is canned/sample rather than live), but the when-to-use is explicit enough.

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?

The description goes well beyond the annotations (which only cover read-only, open-world, idempotent, non-destructive). It discloses the payment model (0.015 USDC on Base via x402), that the calling agent's own wallet pays and the server never holds a wallet, that each source is independently optional so a failing upstream degrades gracefully, and the dedup/ranking behavior (cross_source flag, rank-based combined_score). This is rich operational context an agent needs to invoke it correctly.

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 key facts: paid cost, merged feed, and source list come first. It is somewhat dense and repeats the payment amount twice ('0.015 USDC on Base' and '$0.015 USDC on Base'), which is minor redundancy, but every sentence otherwise earns its place.

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

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

Given a 3-parameter tool with no output schema and annotations that only cover safety, the description supplies the missing context: payment flow, degradation behavior, dedup semantics, and the trade-off vs. wiki_trends_pulse. Nothing an agent needs to call it correctly appears to be 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 limit, sources, and payment_header in detail. The description adds only marginal parameter meaning beyond the schema (e.g., reiterating that payment_header is omitted on the first call), so the baseline of 3 is appropriate.

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

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

States a specific verb+resource ('merged trending-topics feed') and enumerates the exact four sources (Hacker News, Lobsters, Mastodon, Wikipedia). It also explicitly differentiates from the sibling wiki_trends_pulse, noting it is 'cheaper and broader.' An agent can distinguish this from wiki_trends_pulse and social_trends_pulse_preview 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?

Provides a specific call pattern: 'Call with no payment_header first to receive the payment requirements,' then call again with the same business arguments plus the signed header. It also names wiki_trends_pulse as the narrower alternative. It lacks explicit when-not-to-use guidance (e.g., when to prefer a paid, non-preview tool vs. the preview 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?

Annotations already establish readOnly, idempotent, non-destructive and open-world behavior, but the description adds genuinely useful context the annotations cannot convey: that it is free, requires no wallet or payment, and takes no arguments. This is a real value-add beyond the structured safety 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?

A single sentence, front-loaded with the [FREE] tag, that carries the cost, the payment prerequisite, and the parameter expectation without any 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 and no parameters, the description's job is largely to explain that the return value is a sample. It does that ('see the shape'), though it gives no hint about the fields or volume of that sample, leaving a small gap for an agent deciding whether the preview is representative enough.

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

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

The tool takes zero parameters, so per the rubric the baseline is 4. The description reinforces this with 'no arguments needed', which is consistent with the empty schema.

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

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

The description states this is a free sample response for social_trends_pulse, letting the caller see the output shape before paying. That is a specific verb+resource for a preview tool, though the underlying subject matter (social/trending topics) is only carried by the title rather than the description text itself.

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 frames when to use it: before paying 0.015 USDC for the paid sibling, and it confirms no arguments are needed. It stops short of an explicit 'use this instead of social_trends_pulse when you only need the shape' instruction, but the routing intent is 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 cover readOnly/idempotent/openWorld/non-destructive, but the description adds substantial context beyond them: 5-minute caching, a low-liquidity flag, a defined 'unsupported-token error — never a fabricated price' behavior, and the full x402 payment flow where the caller's wallet pays and the server never does. This is exactly the behavioral disclosure 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?

The key facts are front-loaded ([PAID] tag, price source) and most sentences are load-bearing. There is mild redundancy — the '$0.003 USDC on Base via x402' cost and the 'your own wallet pays, never this server's' rule appear more than once — which costs it a point.

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 shape (leader-compatible prices[]/asOf/count/unresolved). It also covers caching, error behavior, and the payment handshake, so nothing an agent needs to invoke this 5-param, nested-object tool 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 schema documents every parameter including the payment_header nested shape. The description reinforces the batch nature of `coins` and its leader-compatible semantics, but adds little syntax or format detail beyond what the schema already states — the baseline 3 for full schema coverage.

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

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

The description states a specific verb and resource ('Base token price read live from on-chain state') and names the exact pricing sources (Chainlink Data Feed aggregators on Base, deepest Uniswap V3 USDC pool). An agent can tell this apart from gas_price, crypto_news, and the other siblings 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?

It gives a clear calling workflow ('call with no payment_header first to receive the payment requirements' then retry with the signed header) and states the pricing path selected per input type. It does not explicitly name the free sibling token_price_preview as the alternative for no-payment use, which keeps this from 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 readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds genuinely useful context beyond that: it is free, requires no wallet or payment, needs no arguments, and returns a sample rather than live data.

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

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

A single tight sentence front-loaded with the [FREE] tag and the key takeaway (sample before paying). Every phrase earns its place with no redundancy.

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

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

For a zero-argument preview tool with no output schema, the description adequately conveys the free, sample-only nature and the cost of the real call. It could note the preview is illustrative/possibly stale, but nothing critical 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?

Zero parameters, so there is nothing for the description to disambiguate. The statement that no arguments are needed is a reasonable confirmation, and the 4 baseline for a parameterless tool 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 it is a free sample response for the sibling tool token_price, so an agent can tell it apart from the paid token_price and the other *_preview siblings. The title carries the actual subject matter (Base token price via Chainlink + Uniswap V3) rather than the description, leaving the description slightly thin on what data it previews.

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 when: use it to see the response shape before paying 0.003 USDC for token_price. It implies token_price is the paid alternative without naming an explicit exclusion or when-not-to-use condition.

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 (readOnlyHint, idempotentHint, openWorldHint, destructiveHint=false), the description discloses the cost (0.005 USDC on Base), the payment protocol (x402), and crucially that the calling agent's own wallet pays and the server never holds a wallet or pays on its behalf. Payment-quoting behavior is fully surfaced, which 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 paid marker and the data payload, then the payment mechanics. Efficient overall, but the 0.005 USDC cost and 'x402/paid via' framing are repeated across sentences, which is minor redundancy in an otherwise tight 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?

With no output schema, the description carries return-value explanation and does so by enumerating the three bundled datasets. Combined with annotations covering the safety profile and the description covering the payment flow, an agent has enough to invoke it correctly. Return format particulars (fields, units, cadence) are not detailed, which keeps it just short of fully complete.

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

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

The single payment_header parameter already has 100% schema description coverage, and the description reinforces its two-phase role (omit first to get the challenge, include the signed payload second). It adds the payment-flow meaning on top of the schema rather than repeating it, though it adds little on the header's internal name/value structure.

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

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

States a specific resource and scope: U.S. public debt outstanding, Treasury operating cash balance, and current-quarter exchange rates, bundled from api.fiscaldata.treasury.gov in one call. An agent knows exactly what data it returns. It does not, however, explicitly name or differentiate itself from the sibling treasury_fiscal_snapshot_preview, which is the natural alternative.

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 operational guidance: call once with no payment_header to receive the x402 challenge, then call again with the SAME business arguments plus the signed header. This is explicit and actionable. It misses only the when-to-use-vs-preview routing that would fully separate it from the free sibling tool.

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

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

Annotations already establish readOnly/idempotent/non-destructive, and the description adds the genuinely useful behavioral facts: free, no wallet, no payment, no arguments. It does not describe what the preview actually contains or whether the sample values are real or synthetic, which is the one remaining behavioral gap.

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

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

A single front-loaded sentence that leads with the free-preview nature and packs cost, payment, and argument requirements without waste. Nothing to trim.

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

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

For a simple zero-param preview with full annotation coverage and no output schema, the description covers selection and invocation fully. It is only slightly thin on what data the snapshot preview actually demonstrates (Treasury fiscal content), which an agent might want before choosing this over another preview.

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

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

The tool takes zero parameters, so there is nothing to disambiguate; the description correctly confirms 'no arguments needed,' matching the empty schema with additionalProperties=false. Baseline 4 for a 0-parameter tool.

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

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

The description names the exact resource it mirrors (treasury_fiscal_snapshot) and states the tool's distinct role: a free sample response that shows the shape before payment. That cleanly separates it from the paid sibling and from other *_preview tools in the catalog.

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 it (to see the response shape before paying 0.005 USDC) and when not to (no wallet, no payment, no arguments needed), implicitly routing real data consumers to treasury_fiscal_snapshot. Nothing 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 already cover safety (readOnly, idempotent, openWorld, non-destructive), but the description goes far beyond: it discloses the 0.03 USDC payment requirement, the x402 two-step challenge/sign flow, the 10-minute cache, the live data sources (Base RPC + Blockscout + OFAC index), and that the server never holds a wallet. These are exactly the traits an agent needs and none are duplicated 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 purpose, then capabilities, then payment mechanics — logically ordered. It loses a point for repetition: pricing ('$0.03 USDC on Base') and the x402/self-pay point appear two to three times, which is redundant even if partly clarifying.

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 by enumerating the returned fields plus the additive alias names. Combined with the payment flow and caching details, 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 both address and payment_header are already documented in the schema, including the nested {name, value} shape. The description reinforces the payment_header pattern but adds little syntax or format detail beyond what the schema provides; a 3 baseline is appropriate.

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

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

States a specific verb ('Profiles') and resource ('Base wallet/contract address') and enumerates exactly what is returned: is-contract, activity timestamps, tx counts, balances, counterparties, label hits, OFAC check, risk summary. An agent can distinguish it from wallet_profile_preview and the many signal_/bundle_ siblings 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?

Clearly explains the invocation pattern: 'Call with no payment_header first to receive the payment requirements; your own wallet pays, never this server's.' This is strong operational context. It stops short of explicitly contrasting with the free wallet_profile_preview sibling or stating when the paid version is warranted over it, so not 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 readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds useful context beyond these: it is free, requires no payment, no wallet, and no arguments, which is exactly what an agent needs to know before invoking a preview 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?

One tightly written sentence front-loads [FREE] and the core purpose, then adds the practical benefit. Every clause earns its place.

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

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

For a zero-argument preview tool with no output schema, the description supplies the key missing context: it is free, self-contained, and requires no inputs. The title supplies the sample content details (activity, balances, OFAC check, risk summary), so nothing critical is left unexplained.

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

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

There are zero parameters, so the baseline is 4 per the rubric. The description confirms 'no arguments needed,' which aligns with the empty schema but does not add further parameter meaning.

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 exactly what the tool returns ('A sample response for wallet_profile') and explicitly distinguishes it from the paid sibling by calling it a free preview. An agent can tell it apart from wallet_profile 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?

It clearly indicates when to use it: to see the shape before paying 0.03 USDC for wallet_profile. It does not explicitly state 'use wallet_profile for real data' or list exclusions, but the alternative is strongly 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 are present (readOnly, openWorld, idempotent, non-destructive), but the description adds substantial context beyond them: cost, the x402 paywall handshake, 10-minute caching per query, required attribution string, licensing, and which provider returns alerts. This is exactly the extra behavioral detail the annotations cannot express, and nothing contradicts them.

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 one-line purpose before elaborating on sources and payment. It is dense but nearly every clause carries information; the main redundancy is the price/payment restated at both start and end, which slightly pads an otherwise information-rich paragraph.

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 tool with no output schema, the description covers what an agent needs: the payment flow, geographic routing logic, return fields (provider, attribution), caching, and provider-specific limitations. Nothing material for correct invocation 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 aliases, ranges, and the U.S.-only caveat. The description restates much of this (lat/lon vs location, forecast_days, alerts U.S./NWS-only) rather than adding syntax or format detail. Baseline 3 is appropriate since the structured 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 and scope: "Current conditions + short forecast, worldwide." It is immediately distinguishable from weather_preview via the explicit paid marker ("[PAID — 0.004 USDC on Base via x402]") and names its data sources (NWS + MET Norway). An agent can tell what it does and that it differs from the free preview sibling 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?

Provides strong routing guidance: U.S. coordinates go to NWS with alerts, everything else to MET Norway without alerts, and it explains that address resolution is U.S.-only ("non-U.S. place names are never resolved this way"). It also explains the unpaid-first workflow. It stops short of explicitly naming weather_preview as the free alternative, so it lacks a true when-not clause.

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, idempotent, and non-destructive behavior. The description adds useful non-schema context: the response is a sample, no authentication or payment is needed, and it takes zero arguments. It does not clarify whether the sample is static or live, which is a minor remaining gap.

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

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

A single front-loaded sentence: the [FREE] tag, the purpose, the cost avoided, and the zero-setup nature. Nothing is wasted and the most decision-relevant fact leads.

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 zero-parameter preview with no output schema, the description gives enough to call it correctly and explains why one would (see the shape before paying). The only omission is a hint at what the sample payload contains.

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

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

With zero parameters, the baseline is 4. The description reinforces this by stating 'no arguments needed', which correctly matches the empty schema.

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

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

The description clearly frames this as a free sample/preview of the weather tool, distinguishing it from the paid sibling by mentioning the 0.004 USDC cost it avoids. It does not, however, say what the weather data actually contains (current conditions, forecast, coverage) beyond the word 'weather'.

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 use case explicitly — inspect the response shape before paying — and clarifies that no wallet, payment, or arguments are required. It implies but never names the paid 'weather' sibling as the alternative, so a small inference is left to the agent.

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, yet the description adds substantial behavior the schema cannot express: it is a paid call ($0.025 USDC on Base via x402), the first call must omit payment_header to receive the challenge, the calling agent's own wallet pays, and the server never holds a wallet. That is exactly the kind of auth/payment flow context this dimension rewards.