FreeTier Agent API

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

Annotations already mark this as read-only and open-world, and the description adds meaningful context: free-call limits, paid in-band x402/card behavior, and the two data sources. That is useful operational detail beyond the annotations, though it does not discuss output behavior or rate-limit handling beyond the free-call count.

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

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

The description is compact and mostly front-loads the key constraints: pricing, payment mechanism, search scope, and filters. The purpose appears after the pricing sentence, which is slightly less ideal, but there is little wasted 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?

For a search tool with an output schema and read-only annotations, the description covers scope, sources, filters, and payment mechanics sufficiently to call it correctly. Remaining gaps are mainly sibling differentiation and fuller parameter 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 description coverage is 0%, so the description must carry parameter meaning. It names q, explains type as mcp|x402, and states limit<=100, but it does not describe query syntax, pagination behavior, or why schema lists limit as a string.

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 search action over '~13,000 agent tools,' split into MCP servers and x402 APIs, so the resource and scope are clear. It does not explicitly differentiate itself from close siblings such as dump_agent_tools, mcp_servers, or x402_services.

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 usage as a unified search across both MCP and x402 entries, and names the available filters. However, it gives no explicit when-to-use guidance versus sibling tools like apis_search, mcp_servers, or dump_agent_tools.

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

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

With no annotations, the description carries the full behavioral burden. It discloses that the tool is free and requires no API key, but says nothing about read-only nature, rate limits, response shape, or any other operational trait.

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 with no wasted words. The key selling points (free, live, no key) are front-loaded, though the brevity borders on under-specification.

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 tool with no output schema and no annotations, the description gives only a minimal picture: it says there are five live public APIs and they need no key. It does not describe the return format or what exactly the agent should expect.

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 even though the description adds no parameter information.

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 implies the tool surfaces a sample of five free/public APIs, but it does not state an explicit verb or clarify whether it returns names, endpoints, or metadata. It only weakly differentiates itself from siblings like free_tiers or list_endpoints.

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 mentions that the APIs are free and need no key, which implies a context for use, but it gives no guidance on when to choose this tool over alternatives such as apis_search, free_tiers, or list_endpoints.

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 declare readOnlyHint and openWorldHint; the description adds the crucial behavioral facts an agent cannot see elsewhere: 3 free calls per day across all tools, then $0.001 USDC via x402 or card credits, and the in-band payment mechanism params._meta["x402/payment"]. That is exactly the rate-limit and payment/auth context the annotations do not cover.

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

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

Three dense sentences with no filler; the cost/limit constraint is front-loaded, followed by corpus scope, then filter list. The filter enumeration is telegraphic but functional rather than wasteful.

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?

Output schema exists so return values need not be explained, and the payment model is fully covered. However, for a 7-parameter tool at 43% schema coverage, the description should clarify category semantics and what alive/kind actually filter on; an agent calling it without those details may build a poorly targeted query.

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 43%, and the description compensates partially: it explains auth=none as "no API key" and limit<=50 (matching the schema's "1-50, default 10"). It adds nothing for category, kind, alive, or https beyond restating the enum key names, leaving the low-coverage gap only half filled.

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

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

The description names a specific verb and resource ("API search") plus the exact corpus scope ("2,230 link-checked public & free-tier APIs, 59 categories"), which separates it from generic siblings like api_directory_sample or list_endpoints. It stops short of explicitly contrasting itself with the closest overlapping siblings (free_tiers, x402_services), so an agent still has to infer boundaries.

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?

Listing the available filters (q, category, auth=none, alive=yes, https=yes, kind, limit) implies how to narrow a search, but there is no stated when-to-use / when-not rule and no named alternative. The agent must infer that this is the discovery step before tools like link_check or free_tiers.

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 and openWorldHint=true, so safety is covered. The description adds meaningful non-obvious behavior: the free-tier limit (3 calls/day), paid access via x402 or card credits, and the in-band payment mechanism (params._meta['x402/payment']). This is useful context beyond structured fields, though it does not describe latency or freshness guarantees.

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

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

The description is compact (three sentences) and contains no fluff. It front-loads pricing/payment behavior before the core purpose, which is slightly unconventional but still readable and purposeful; every sentence contributes.

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

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

For a read-only, zero-parameter tool with an output schema, the description covers purpose, usage, data returned, and payment behavior. It is complete enough to call correctly, with only minor gaps around chain comparison and freshness.

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 does not need to explain inputs, and it correctly implies no user-supplied arguments are required for the core operation.

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

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

The description names a specific resource and scope: 'Live Base mainnet gas price (gwei), latest block, and estimated ETH cost of a USDC transfer (~65k gas) and a plain ETH transfer (21k gas).' This is clear and concrete, though it does not explicitly distinguish itself from the sibling tool 'gas' (which likely covers a broader or different chain scope).

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 includes an explicit 'When to use' clause: 'Use base-gas for current Base gas price and the cost of a transfer.' However, it does not name alternatives (e.g., the sibling 'gas' tool) or state when not to use it, leaving the agent to infer routing between gas-related siblings.

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

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

Goes well beyond the readOnlyHint/openWorldHint annotations: it discloses throughput limits (3 free calls/day shared across tools), cost after that ($0.005 USDC), the payment channel (in-band params._meta["x402/payment"], or card credits), the backing model (Workers AI Llama 3.1 8B), accepted transports (GET query or POST body), and the closed-label output guarantee. These are exactly the operational facts an agent needs that no annotation or schema conveys.

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?

Compact and dense with no filler, but the long pricing/payment sentence is front-loaded ahead of what the tool actually does, delaying purpose recognition for an agent scanning for capability. Every sentence earns its place; only the ordering 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 3-parameter, fully-described-schema tool with an output schema, the description covers capability, limits, cost, transport, and model choice. Nothing needed to call it correctly or predict its cost 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 constraints the schema omits: text capped at 6,000 characters and labels constrained to 2-20 comma-separated values in single or multi-label mode. It does not document the string-typed 'multi' flag's accepted values beyond 'true', which keeps it from a 5.

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

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

States a specific verb and resource ('Text classification: classify text ... into your own labels') plus concrete scope limits (6,000 chars, 2-20 labels, single vs multi-label) and the output guarantee ('output is always one of your labels'). This distinguishes it from near neighbors such as news_sentiment, entity_extract, or summarize, which produce their own taxonomies rather than user-supplied labels.

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' clause names concrete scenarios: routing tickets, emails, or posts into your own labels. However, it never names an alternative tool or states when NOT to use it (e.g., use news_sentiment when you don't have your own labels), so the routing logic relative to siblings remains implicit.

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 declare readOnlyHint and openWorldHint; the description adds substantial context beyond them: the free-tier quota (3 calls/day across all tools), the $0.022 USDC x402 or card-credit pricing with the exact in-band payment location (params._meta["x402/payment"]), and a data-scope constraint ('only each company's own website and DNS; no personal data'). These are exactly the operational facts an agent needs before spending a quota 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?

Two dense sentences with no filler; the output inventory is packed into a parenthetical rather than sprawled. Minor deduction because the billing boilerplate is front-loaded ahead of the actual purpose, pushing the task-relevant content to the second half.

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

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

With an output schema present the description needn't spell out return values, yet it still summarizes the payload; combined with pricing, payment mechanism, data-scope limits, and batch size, an agent has everything required to decide and call correctly.

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

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

The single parameter is fully documented in the schema ('comma-separated domains, max 10') at 100% coverage, so the baseline applies. The description repeats the 10-domain cap but adds no format or validation 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 and resource ('Company enrichment batch') with an explicit scale bound ('up to 10 domains in one call') and enumerates what comes back (profile: name, description, socials, key pages, email provider; tech stack). The batch scope plus the combined profile+techstack payload clearly separates it from the single-domain siblings company_profile and company_techstack.

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 'When to use' line only restates the purpose ('enrich a list of up to 10 domains in one call'), which does imply the batching condition but names no alternative. It never says to use company_profile/company_techstack for single domains or company_contacts when contacts are wanted, and gives no exclusion for the 10-domain limit overflow.

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 adds substantial behavioral context beyond the readOnlyHint and openWorldHint annotations: data comes only from the company's own website, role emails are MX-checked, phones are E.164, personal emails and names are omitted for GDPR, robots.txt is respected, and pricing/payment mechanics are disclosed.

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

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

The description is fairly dense but front-loads pricing, then purpose, then usage. Most sentences carry useful information, though the payment details are prominent enough to slightly dilute the core tool-purpose framing.

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 an output schema, full schema coverage, and annotations, the description provides enough context for correct invocation: it covers the data scope, exclusions, validation behavior, payment requirements, and intended use case.

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 two parameters are already documented in the schema. The description implies domain and country semantics through 'company domain' and 'main phone', but does not add meaningfully more parameter guidance than the schema provides.

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

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

The description clearly states a specific resource and scope: public business contact details from the company's own website, including role emails, main phone, address, company/VAT IDs, and official social profiles. It does not explicitly name or differentiate from the closely related sibling site_contacts, which keeps it from 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?

It gives an explicit use case: 'Use company-contacts for public role emails and main phone of a company domain (no personal data).' It does not say when not to use it or name alternative siblings, so the guidance is clear but not complete.

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 readOnlyHint/openWorldHint annotations, the description discloses the quota (3 free calls/day across all tools), the price and payment channel including the in-band params._meta["x402/payment"] key, and the data-source limits (company's own website and DNS only, robots.txt respected, no personal data). That is substantial operational context; only the failure/empty-result behavior is left implicit.

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 dense paragraph with no filler sentences, and each clause carries information. It is slightly mis-front-loaded, however: the billing/quota sentence leads ahead of the actual capability, which is the more important framing for tool selection.

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

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

An output schema exists, so return values need not be explained, yet the description's field list still frames expectations well. Combined with source restrictions, quota, and payment mechanics, nothing an agent needs in order to call this correctly is missing.

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

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

The single parameter is fully documented in the schema, so the baseline is a 3-4. The description adds real value by documenting a parameter that is NOT in the schema at all: the x402/payment key passed under params._meta for paid calls, which an agent would otherwise not know to supply.

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?

"Company enrichment: domain in, company profile out" states a specific verb and resource, then enumerates the returned fields (name, description, language, logo, founding date, address, social profiles, key pages, MX). It also names the three sibling tools it is not, so an agent can route 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?

The "When to use" clause gives an explicit rule (enrich a domain) and pairs it with the exact alternatives: company-techstack for technologies, company-contacts for business contact details, company-batch for up to 10 domains. Both the selection condition and the exclusions are stated.

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

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

Goes well beyond the readOnlyHint/openWorldHint annotations: it discloses a hard quota (3 free MCP calls per day across all tools), paid pricing ($0.005 USDC or card credits), and the exact in-band payment channel (params._meta["x402/payment"]). It also characterizes the detection methodology (HTML, header or DNS evidence; ~70 signatures), which tells the agent how results are produced and how a metered call should be budgeted.

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?

Compact at three sentences with no filler, but the first thing an agent reads is the billing/quota preamble rather than what the tool does, pushing the purpose behind a long list of priced mechanics. The detection categories are dense but each earns its place by scoping the return.

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

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

With an output schema present, omission of return-shape detail is fine, and the one required param is fully described. What's missing is failure behavior on unknown/unreachable domains and whether low-signature sites return partial evidence, which matters for a metered, open-world lookup.

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 required parameter and schema description coverage is 100%, so the schema already carries the semantics; the description's implicit acceptance of a bare domain ('company website') is consistent with the schema's 'company domain or URL'. It contributes the meta-parameter detail (params._meta payment key) but nothing additional about the domain format.

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 enumerated scope: 'Website tech stack detection: CMS, e-commerce, frameworks, analytics, marketing, support chat, payments, consent, CDN/hosting and email provider'. It also discloses the evidence basis (HTML, header, DNS) and signature breadth (~70), which lets an agent distinguish this from adjacent siblings such as page_meta or dns without opening their schemas.

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

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

The 'When to use' sentence only restates what the tool returns ('see which CMS, analytics, chat and payment tools a website uses'), so it adds a cue but no real routing logic. No when-not conditions and no alternatives named (e.g. page_meta for raw tags, dns for records), even though the sibling list is crowded with overlapping tools.

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

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

Annotations already declare readOnlyHint and openWorldHint, and the description adds genuinely non-obvious behavior: 3 free calls/day followed by $0.0025 USDC via x402 with in-band payment through params._meta, proxy auto-resolution (EIP-1967, ZeppelinOS) to the implementation's own ABI, and bytecode-derived selectors named via OpenChain for unverified contracts. These are the operational facts an agent cannot get from the schema or 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?

It is dense but every sentence carries information an agent needs: pricing constraint, resolution behavior, verified/unverified paths, and sibling routing. Leading with the paywall is slightly unusual but defensible since it gates invocation; a little unpacking of the proxy/fallback chain would improve scan-ability.

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

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

With an output schema present, return shapes need not be restated, and the description covers the parts that matter: cost model, chain scope, proxy dereferencing, unverified-contract degradation, and the reduced-payload option. Nothing needed to call it correctly is missing.

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

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

Schema coverage is 100%, so the enums and defaults are already documented. The description still adds meaning beyond the schema for abi=false ('returns signatures only (smaller)') and explains that proxies yield the implementation's ABI, which changes what address resolution actually returns.

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: a Base or Ethereum contract address resolves to ABI, function selectors/signatures, event topics, and proxy implementation ABIs. It also distinguishes itself from the closest siblings, naming wallet-profile for balances and token-risk for ERC-20 privilege checks.

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

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

There is an explicit 'When to use' clause scoped to agents that need to call or decode an unseen contract, plus two named alternatives with the conditions that select them (balances/account type, ERC-20 dangerous privileges). Nothing is left to inference about routing.

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

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

Goes well beyond the readOnlyHint/openWorldHint annotations by disclosing the commercial model: 3 free calls per day across all tools, then $0.0025 USDC via x402 or card credits, with the exact in-band payment location params._meta["x402/payment"]. Free-tier quota and payment mechanics are exactly the kind of behavior an agent must know 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?

Two dense sentences with no filler; the pricing clause leads and the capability and usage follow. Slight deduction only because the payment mechanics precede the statement of what the tool actually does, delaying the agent's primary identification of the tool.

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?

An output schema exists, so return values needn't be enumerated, and the description still previews the covered fields. For a one-parameter, read-only lookup this is nearly complete; only error handling for unmatched country strings is unaddressed.

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 parameter q is already documented as 'ISO2, ISO3 or country name'. The description restates that same set without adding format examples or failure behavior for invalid codes, so baseline 3 applies.

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

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

States a specific verb and resource — 'Country reference lookup by ISO2/ISO3/name' — and enumerates the exact payload (capital, population, area, continent, currency, phone prefix, TLD, languages, neighbours, time zones). An agent can distinguish it from lookalike siblings such as geocode, currency and holidays 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?

The 'When to use' sentence gives a positive trigger list (ISO codes, capitals, currencies, calling codes, time zones), which is clear context. However it names no alternatives or exclusions, even though currency and geocode sit among the siblings and could plausibly be confused with this 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?

With readOnlyHint and openWorldHint already covering the safety profile, the description adds genuinely non-obvious behavior: the free-tier limit of 3 calls/day across all tools, the $0.002 USDC charge, and the exact in-band payment location params._meta["x402/payment"]. That payment mechanic is information an agent cannot get from annotations, and 'also returns the rate date' adds a return nuance. It stops short of a 5 because nothing is said about failure modes (unsupported currency, rate unavailability).

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 text is compact with no filler sentences, but it is not front-loaded: the pricing boilerplate occupies the opening position and the actual purpose does not appear until the middle. Payment mechanics belong after the purpose statement, not before 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?

An output schema exists, so return-value explanation is not required and the 'rate date' mention is a bonus. However, with zero schema coverage on all three parameters and no format guidance in the description, an agent still lacks what it needs to construct a valid call with confidence — the main remaining hole.

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

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

Schema description coverage is 0%, so the description must carry the parameter burden, and it only lists the names ('Params: from, to, amount'). It never states that from/to are ISO 4217 codes, whether they are case-sensitive, or why amount is typed as a string rather than a number. That is a meaningful gap for a tool whose only inputs are these three fields.

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 operation ('Currency conversion'), the data source ('official ECB euro reference rates'), and the coverage limit ('~30 currencies, daily'). That is enough to separate it from the many price-adjacent siblings such as token_price, gas, and llm_pricing 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?

There is an explicit 'When to use' clause, but it simply restates the purpose ('Use currency for ECB reference exchange rates and conversion'). No alternatives are named and no exclusions are given — an agent gets no signal on when to prefer this over, say, token_price or llm_pricing.

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 declare readOnlyHint and openWorldHint, while the description adds critical behavioral context: the tool requires a $1 USDC payment via x402. It also discloses dataset size and licensing, which helps set expectations. It does not explain the payment flow or whether payment is automatic, but the key cost and access condition are surfaced.

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 that front-load the core action and cost, then add dataset specifics. 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?

The tool is a simple parameterless download with an output schema, so the description need not explain return values. It covers cost, dataset scope, format, and licensing, which is enough to call it correctly. A brief note on how x402 payment is handled would make it complete, but the essential context 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?

The tool has zero parameters, so the schema offers no parameter semantics to document. The baseline for a parameterless tool is 4, and the description appropriately does not invent parameter details.

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

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

The description uses a specific verb ('Buy') and resource ('full Verified API Directory dataset'), and explicitly distinguishes it from a sample by the word 'full'. It adds concrete details (2,230 rows, JSON, licenses), so an agent can immediately tell what it retrieves.

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

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

The description implies when to use it (when you need the complete dataset) but does not explicitly name an alternative like api_directory_sample or state when not to use this tool. Usage is therefore inferred rather than directed.

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 and openWorldHint, yet the description still adds real context: the free-tier quota, the x402/card payment path with the exact in-band parameter, the DoH provider and its fallback, and what the mail-auth check reports (MX hosts, SPF, DMARC policy, warnings). It does not describe failure behavior or rate limiting beyond the daily quota, which keeps it short of a 5.

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 nearly waste-free, with the usage guidance and alternative clearly signposted. Minor deduction: the first sentence is pricing/payment boilerplate rather than the tool's purpose, so the front-loading is inverted relative to what an agent most needs first.

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

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

With an output schema present, return-value explanation is unnecessary, and the description covers capabilities, scope, payment prerequisite, and the sibling alternative. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds two things the schema does not make obvious: only one domain is handled per call, and the full supported record-type vocabulary (SOA, SRV, HTTPS, DS) beyond the schema's default list. It does not explain the semantics of the string-typed mail enum beyond what the schema already says.

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: DNS lookup over DNS-over-HTTPS with an explicit record-type list, plus a mail-auth check (MX, SPF, DMARC) and DNSSEC-validated flag. It also names the sibling it is not (email-verify), so an agent can route without opening either schema.

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

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

Contains an explicit 'When to use' clause covering both capabilities and a contrasting alternative ('Use email-verify to check a single address'). The selection condition between the two tools is stated rather than inferred.

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 and openWorldHint, but the description adds substantial non-schema behavior: a 3-call/day free quota, $0.005 USDC payment via x402 or card credits, and the in-band payment channel params._meta["x402/payment"]. It also identifies the data source (IANA bootstrap RDAP), which explains freshness and coverage. Error/failure modes are not described, so not a 5.

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?

Pricing is front-loaded, which is defensible for a paid tool, but the final 'When to use' sentence largely restates the purpose clause already given ('see who registered a domain, when it was created and when it expires'), wasting space. The field enumeration is dense but 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?

Covers what is needed to invoke correctly: input format caveat, data source, cost and quota, and payment mechanism. Because an output schema exists, return values need not be spelled out. Only gap is absence of any failure semantics (invalid domain, rate-limit exhaustion after payment).

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 there is a single parameter with a worked example, so the schema carries the load. The one semantic detail worth knowing ('subdomains are reduced to the registered domain') is already in the schema text, so the description adds nothing beyond it. 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?

Names a specific verb and resource ('Domain registration lookup via RDAP') and enumerates the returned fields (registrar, IANA id, abuse email, created/updated/expiry, EPP status, nameservers, DNSSEC). This is clearly distinguishable from siblings like dns, ssl_cert, or site_contacts 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?

Explicit when-to-use is given twice ('Use it to vet a domain or check expiry', then the 'When to use' sentence naming registrant, creation, and expiry lookups). No when-not guidance or routing away from adjacent tools such as dns or ssl_cert, which keeps it out of 5 territory.

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 and open-world, but the description adds genuinely non-obvious behavior: it costs $1 USDC via x402 and carries MIT/CC BY 4.0 attribution obligations. It stops short of explaining how the x402 payment is actually settled or whether any free preview 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?

Three compact fragments with zero waste; the cost, which is the biggest gating fact, is front-loaded in the first sentence. Nothing could be cut without losing a decision-relevant fact.

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

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

With an output schema present and no parameters, the description only needs to cover scope, format, cost, and licensing, and it does all four. Only the mechanics of the x402 payment flow are 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?

Zero parameters, so the schema carries no semantics burden and the baseline applies. The description correctly does not invent parameter details and instead spends its words on scope and cost.

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: a full dump of the Agent Tool Directory (~13,000 MCP servers + x402 APIs) in one unified JSON schema. That distinguishes it in spirit from the sample-scoped siblings (mcp_servers_sample, api_directory_sample, dump_llm_pricing), though it never names those siblings explicitly.

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

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

The word "Full" and the stated scale imply this is the complete dataset rather than a sample, which helps against sample siblings, but the description never says when to pick it over dump_mcp_servers, dump_x402_services, or agent_tools. The $1 price is a useful decision input, yet it is not framed as a trade-off against free 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 and openWorldHint, so the description is not burdened with safety disclosure. It adds important behavioral context by stating the cost ($1 USDC via x402), the dataset size, and the JSON format, which an agent needs to know before invoking a paid download.

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 no wasted text. The payment requirement and dataset contents are front-loaded, so the agent gets the key facts 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?

With zero parameters, an output schema, and annotations covering safety/openness, the description supplies the remaining essentials: cost, contents, licensing, and format. It is nearly complete, though it could explicitly position itself against the related pricing and sample 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?

The tool has zero parameters, so there is no parameter semantics to explain. A baseline of 4 is appropriate because the description does not need to compensate for an input schema gap.

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

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

The description clearly states the resource and scope: a full dump of prices for ~3,000 AI models plus verified free tiers, delivered as JSON. The verb 'Dataset download' and the content are specific, but it does not explicitly differentiate this full dump from sibling tools like llm_pricing or llm_pricing_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?

There is no explicit guidance on when to use this tool versus alternatives such as llm_pricing, llm_pricing_sample, or free_tiers. The phrase 'Full dump' implies bulk use, but the agent must infer that from context rather than from stated conditions or exclusions.

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

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

Annotations declare readOnlyHint and openWorldHint, but the description adds something material those annotations do not: this call costs $1 USDC via x402, so the agent knows a payment/authorization step is involved before invoking. It also names the upstream source and MIT license, which is useful provenance for a bulk dataset. It does not explain how the payment negotiation is performed, which is the only 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?

Three short clauses, perfectly front-loaded: price first, then scope, then provenance/license. Every fragment carries distinct information (cost, size, format, source, license) with no repetition of the name or 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?

With an output schema present, the description need not explain return shape, and it correctly covers the two things structured fields cannot convey: the $1 USDC x402 payment requirement and the exact dataset contents (4,259 servers from awesome-mcp-servers, MIT). Only the mechanics of the x402 payment handshake are unstated, a minor gap for a known protocol.

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 and the schema is empty, so there is no parameter semantics to convey; the correct baseline for a 0-param tool applies. The description appropriately spends its words on scope and cost instead of nonexistent 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 a specific resource and scope: 'Full MCP server directory dump (4,259 servers, JSON)', which tells an agent exactly what payload it gets, including the record count and format. It implicitly distinguishes itself from the 'sample' siblings via 'Full', but never names mcp_servers or mcp_servers_sample, so differentiation is left to 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 word 'Full' plus the record count implies this is the bulk/complete option versus the sample siblings, and the $1 USDC price is disclosed up front so an agent can weigh cost. However, there is no explicit 'use this instead of X when Y' routing and no statement of prerequisites beyond the x402 mention.

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

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

Annotations only cover read-only and open-world; the description adds the critical operational fact that access costs $1 USDC via x402, plus data provenance and licensing (GeoNames CC BY 4.0, python-holidays MIT). That payment gate is exactly the kind of behavioral context annotations cannot express. It stops short of explaining the payment flow or what happens before payment succeeds.

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, front-loaded, and every clause earns its place: cost, coverage, provenance, license, format. No filler and no restatement 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?

With an output schema present, return values need not be explained, and the description covers content, cost, and format. It omits any sense of payload size or delivery mechanics for what is explicitly a 'full dump', which matters for an agent deciding to download 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?

Zero parameters, so the baseline is 4. The description adds that the payload is JSON, which is the only relevant detail a parameterless tool can carry.

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

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

States a concrete resource (a full world-reference dump) and enumerates its contents with counts: 252 countries, 418 time zones, ~14,000 holidays. The word 'Full dump' implicitly carves it out from the per-item siblings (country, holidays), though it never names them.

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 'Full dump' framing implies you should take this when you want the complete dataset rather than a single record, and the $1 USDC price is a real selection signal. But there is no explicit when-to-use, no named alternative such as country or holidays, and no guidance on when the cost is worth paying.

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 and openWorldHint. The description adds useful behavioral and operational context beyond that: concrete cost ($1 USDC via x402), approximate volume (~8,900 records), JSON format, data source, and CC BY 4.0 attribution requirement.

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

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

The description is compact and front-loaded with cost and purpose. Each phrase carries distinct information: price, dataset scope, record count, fields, format, source, and license.

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 input parameters and an output schema already present, the description supplies the key non-schema context an agent needs: cost, dataset scope, format, source, and attribution requirement. Nothing essential for selecting or invoking the tool 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, so there are no input semantics to document. The baseline for a parameterless tool is 4, and the description appropriately does not waste space explaining nonexistent 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 a specific operation and resource: a full dataset download of x402 pay-per-call APIs, with approximate record count and fields. It distinguishes itself from sample/query siblings by emphasizing 'Full dump,' though it does not explicitly name the alternatives.

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 when to use this tool by saying it is the paid full dump and that the data is JSON. However, it does not explicitly say when to use x402_services or api_directory_sample instead, nor does it outline prerequisites for x402 payment.

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

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

Beyond the readOnly/openWorld annotations, it discloses that no mail is sent, no SMTP probing occurs, DNS is queried via DNS-over-HTTPS, the mailbox existence cannot be confirmed, and addresses are not stored or logged. It also states the free-call limit and payment mechanism, which are valuable operational details.

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

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

The description is dense but each element—pricing, non-goals, checks, verdicts, data handling, and usage—is relevant to calling or selecting the tool. It is slightly front-loaded with billing information before the tool purpose, but overall it remains compact and information-rich.

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

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

Given one simple required parameter, a present output schema, and annotations covering safety and openness, the description is complete. It still adds the key limitations and data-handling behavior an agent would otherwise lack.

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

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

There is one required parameter and schema coverage is 100%, with the schema itself describing it as 'one email address.' The description reinforces the single-address scope but adds no format, normalization, or validation details beyond the schema.

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

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

The description gives a specific verb and resource ('Email verify: Email address check') and spells out exactly what is checked: syntax, MX/A DNS, disposable domain, role address, and free-mail flags. It also states the verdicts and the single-address scope, though it does not explicitly name sibling tools such as email_verify_quick or email_verify_batch to distinguish 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 includes a clear 'When to use' sentence scoped to one address with DNS-only checking and no mailbox probe. It does not explicitly name alternatives or say when another sibling should be preferred, but the single-address/DNS-only framing gives practical selection 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?

The annotations already declare readOnlyHint and openWorldHint, and the description adds important behavior beyond them: free-call limits, paid x402/card pricing, in-band payment via params._meta, no SMTP probing, and no data storage. These are exactly the operational details an agent needs before invoking a paid, external-call 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?

The description is compact and mostly front-loaded, covering payment terms, capability details, limitations, and usage in only a few sentences. The final 'When to use' sentence is largely redundant, which keeps it from being fully optimal.

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

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

Given one input parameter, an output schema, and readOnly/openWorld annotations, the description is complete enough to call the tool correctly. It also summarizes the returned verdict/flags and summary, though the output schema already owns return-value detail.

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

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

There is one parameter and schema description coverage is 100%, so the schema already explains the comma-separated email list and the max-20 limit. The description repeats the max-20 batch constraint but adds no extra syntax or formatting details beyond the schema 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?

The description gives a specific verb and resource: batch email verification for up to 20 addresses in one call. It also lists the verification checks performed, so an agent can distinguish this from single-email or quick-check 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 includes a 'When to use' sentence, but that sentence mostly restates the tool's batch limit and does not explain when to choose email_verify, email_verify_quick, or this batch tool instead. The max-20 scope implies a list-cleaning use case, but no alternatives or exclusions are 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?

Adds substantial context annotations do not carry: 3 free calls/day across all tools, then $0.0025 USDC via x402 or card credits, with the in-band payment parameter path (params._meta["x402/payment"]) disclosed. It also discloses the no-DNS/fastest trait. Minor tension: openWorldHint=true sits alongside an 'offline, no DNS' claim that is left unexplained, which slightly muddies the external-contact picture.

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 pricing/quota constraint, then the capability, then the when-to-use routing; all sentences earn their place. Slightly dense and repeats the 'quick' framing across the purpose and usage sentences, but no filler.

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

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

Given an output schema exists, the description needn't explain return values, and it covers quota, payment, capability scope, and alternatives. The one loose end is the unexamined relationship between the 'offline' behavior and openWorldHint=true, which leaves the agent guessing about external data sources.

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

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

Schema description coverage is 100% for the single 'email' parameter, so the schema already does the work. The description only implies single-address scope through "for one email", adding no syntax, normalization, or validation details beyond the schema. 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 resource and the exact checks performed: offline syntax check, ~9,900-domain disposable list, role address and free-mail flags, explicitly "no DNS". It names and contrasts the two sibling tools (email_verify adds MX, email_verify_batch for lists), so an agent can pick it without opening a schema.

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

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

Has an explicit "When to use" clause plus a direct alternative: "Use email-verify for MX checks" and "email-verify-batch for lists". The condition that selects each sibling is spelled out rather than inferred.

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 readOnlyHint/openWorldHint annotations by disclosing the pricing model (3 free calls/day, then $0.0025 USDC via x402 or card credits), the in-band payment mechanism (params._meta["x402/payment"]), and the trust model (public RPC, no keys, reverse record checked forward). These are exactly the operational facts an agent needs to plan a 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?

Dense and nearly waste-free, but it leads with pricing before stating what the tool does, which delays the purpose for an agent scanning for capability first. Still, every sentence carries information and the whole thing is short.

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

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

With an output schema covering return values and annotations covering the safety profile, the description fills the remaining gaps: payment handling, supported chains, record selection, and what 'verified' means for reverse lookups. 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?

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: text-record keys are exemplified (avatar, url, com.twitter, com.github), the chain scope (Ethereum and Base) is stated, and the forward-verification semantics of the reverse lookup clarify what `address` + `chain` actually return.

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 pair: bidirectional resolution of ENS/Basenames names to addresses and verified primary names, with optional text records. The examples (vitalik.eth, jesse.base.eth) and the forward-check detail on reverse records make the capability unambiguous and distinct from any sibling tool.

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

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

An explicit 'When to use' clause gives two concrete scenarios: resolve a name before sending funds, or display a verified name for an address. No other sibling tool performs name resolution, so no alternatives need to be excluded; the guidance is clear even without an explicit 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?

Beyond the readOnly/openWorld annotations, the description discloses free-call limits, post-limit payment via x402 or credits, the in-band payment location, the 6,000-character cap, GET/POST input modes, and a literal-occurrence validation rule. These are meaningful operational traits that the annotations alone do not cover.

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

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

The description is dense but mostly efficient, with no filler. Its only structural weakness is that it leads with pricing before stating the core purpose, pushing the most important identification detail into the second 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?

The description covers purpose, usage conditions, sibling alternative, input size limit, supported input methods, payment mechanics, and validation behavior. Since an output schema exists, it does not need to explain return values, and no material gap remains for an agent to invoke the tool correctly.

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

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

The schema already documents the single required text parameter, and the description adds useful constraints: maximum 6,000 characters plus the payment parameter location under params._meta. It adds value beyond the schema, though the schema coverage is already high.

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 gives a specific verb and resource: named entity extraction, and explicitly lists the entity types covered. It also names the sibling tool extract-json and distinguishes this tool from it, so an agent can route correctly without opening the schemas.

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

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

It states exactly when to use entity-extract: people, companies, places, dates, and amounts. It also names the alternative extract-json and the condition that selects it (when you need your own schema), giving both positive and exclusionary 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?

Far beyond the readOnlyHint/openWorldHint annotations: it discloses the pricing model (3 free calls/day, $0.01 USDC via x402 with payment passed in params._meta), the implementation fallback (Llama 3.1 8B JSON mode vs deterministic key:value/regex extractor), post-processing behavior (type-check against schema, missing fields nulled), and an accuracy caveat that the model can misread ambiguous text. Nothing here contradicts the annotations — the tool is a pure read/extract operation.

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

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

Very dense and mostly every sentence earns its place, but the billing/payment preamble is front-loaded ahead of the purpose statement, which is the least useful opening for tool selection. The trailing 'Params: text, schema (JSON string), mode=...' line also partially repeats the schema.

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?

An output schema exists, so return values needn't be explained. The description covers what an agent still needs: size limits (6000 chars, 30 top-level properties, flat objects/arrays of scalars), the transport options (GET query or POST JSON body), cost gating, and accuracy risk. Complete for a 3-parameter extraction tool.

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

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

Schema coverage is 67%, so the structured fields already document text (max 6000 chars) and schema. The description restates those and lists 'mode=auto|heuristic' without explaining what each mode does, leaving the one parameter undocumented in the schema only half-covered. 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 concrete verb and transformation: 'Messy text + JSON Schema in, clean JSON out.' It also names the closest sibling (invoice_json) and the distinguishing scope (short free text, your own schema), so an agent can select it 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?

An explicit 'When to use' clause plus a named alternative with the condition that selects it: 'for invoices and receipts use invoice-json.' This is the when/when-not/alternative pattern done properly.

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 readOnlyHint/openWorldHint annotations: it discloses the quota (3 free calls/day across all tools), the price ($0.0025 USDC), and the exact in-band payment mechanism (params._meta["x402/payment"]). It also documents auto-discovery of feeds from HTML pages and the truncation limit for full content, which the agent cannot learn from 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?

Pricing/limit is front-loaded, then output shape, then usage routing — a sensible order with almost no waste. The middle sentence is long and comma-dense, but each clause conveys distinct API-relevant 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 read-only fetcher with a full output schema, the description covers inputs, filtering, optional full text, return shape, cost, and sibling routing. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is already 100%, so the baseline is 3; the description adds value by explaining filtering with since= and limit= and that include_content=true adds full text. It leaves summary_chars strictly to the schema, which is acceptable given full 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?

States a specific verb+resource: converts RSS/Atom/JSON Feed URLs (or pages that link feeds, auto-discovered) into clean normalised JSON items. It enumerates the returned fields, so the agent knows exactly what it is getting, and it is clearly distinguishable from text-extraction 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?

Has an explicit 'When to use' sentence with concrete scenarios (watch a blog, changelog, podcast, news source) and names the alternative — page-rag for full text of one article page — with the condition that selects it. No inference required.

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 and openWorldHint=true, so safety is covered. The description does add genuinely useful non-schema context — 3 free calls/day across all tools, then $0.001 USDC via x402 or card credits paid in-band via params._meta — which an agent needs before calling. It stops short of describing result shape or how the free-tier quota is tracked, so it is additive but partial.

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?

Compact and free of filler, but badly front-loaded: the opening sentence is about payment/quota rather than what the tool returns, pushing the actual purpose to the second sentence where it is easy to miss.

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?

An output schema exists, so return values need not be explained, and the payment model is covered. However, for a zero-covered two-parameter filter tool the description leaves the category vocabulary and q semantics undefined, which is the main gap an agent would hit.

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

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

Schema description coverage is 0%, so the description must carry the burden, and it only says 'Filter: q, category' without explaining what q matches or what valid category values exist (enums are not present in the schema either). With two undocumented, unenumerated parameters, the agent must guess acceptable values.

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 middle clause names the resource precisely: 'Current free-tier limits for developer services (hosting, DB, auth, email, CI, monitoring) and AI/LLM APIs, with official source URLs.' That is a specific verb+resource, but the description never distinguishes it from overlapping siblings like llm_pricing, llm_pricing_sample, or apis_search, and the first sentence is about billing rather than purpose.

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

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

No statement of when to use this versus the many pricing/directory siblings (llm_pricing, apis_search, api_directory_sample). The only usage-adjacent text is 'Filter: q, category,' which describes mechanics, not selection criteria.

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

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

Beyond readOnlyHint/openWorldHint, it discloses the billing model (3 free calls/day across all tools, then $0.0015 USDC via x402 or card credits, paid in-band through params._meta['x402/payment']) and the data source ('public RPC nodes with failover; no keys'). The no-keys and failover notes tell the agent there is no auth step and that failures are handled upstream.

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 carry purpose, scope, return contents, and the alternative, with no filler. The only structural weakness is that the pricing/payment preamble precedes the purpose statement, so the core capability is not fully front-loaded.

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

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

For a read-only, zero-required-param tool with an output schema already present, the description supplies everything an agent needs: what it returns, which chains, the routing alternative, auth requirements, and cost implications of calling it.

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

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

Schema coverage is 100% on the single 'chains' parameter, so the schema already defines the accepted values. The description names the five chains but adds no syntax or default guidance beyond what the schema states. 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: live gas prices across 5 named EVM chains, with the exact per-chain payload (gwei, latest block, transfer/swap cost in native and USD, cheapest-chain ranking). It explicitly distinguishes itself from the sibling base_gas (Base only).

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?

Contains an explicit 'When to use' clause covering both jobs (pick the cheapest chain, price a transfer/swap) and names the alternative with its exclusion: 'Use base-gas for Base only.' 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?

Adds substantial context beyond the readOnly/openWorld annotations: free-tier quota (3 calls/day across all tools), price and payment mechanism ($0.0015 USDC via x402 or card, paid in-band through params._meta['x402/payment']), caching, and ODbL attribution requirements. These are behavioral facts 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?

Dense but front-loaded and largely waste-free: pricing/quota, then capability, then usage. The pricing clause arriving first slightly buries the actual capability, but every sentence carries information.

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

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

With an output schema present, return values needn't be explained, and the description still names the key returned fields (structured address, country code, bbox, OSM id). Minor gaps: no guidance on error/no-match behavior or whether q and lat/lon are mutually exclusive.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reinforces a few semantics — country as an optional filter, limit as 'up to 5 matches', and lat+lon pairing for reverse mode — but adds little that the schema does not already state.

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

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

States a specific verb and resource ('Geocoding with OpenStreetMap Nominatim') and covers both directions: address/place -> coordinates and lat+lon -> structured address. An agent can tell what it does, though it never mentions the sibling geocode_batch, so the batch-vs-single distinction is left implicit.

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 'When to use' line restates the purpose rather than giving real selection criteria — it names no alternatives (e.g., geocode_batch for multiple addresses) and no exclusions. Usage is implied by the forward/reverse mode split but not genuinely guided.

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 readOnlyHint and openWorldHint, but the description adds substantial behavioral context: free-call quota, per-call price, in-band x402 payment parameter, caching, provider, and ODbL attribution. This goes well beyond the structured annotations.

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

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

The description is compact and mostly front-loaded, but it leads with service-wide pricing before stating the tool's purpose and repeats the 'up to 5' limit in both the purpose and usage sentences. Minor redundancy keeps it below top marks.

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 batch geocoding tool with full schema coverage and an output schema, the description covers the essential calling context: quota, pricing, payment mechanism, batch limit, provider, cache, and attribution. It stops short of explaining partial-failure behavior or error cases.

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 the separator, max count, and optional ISO-2 country filter. The description adds that place names are accepted in addition to addresses, but otherwise mostly restates schema semantics; this is the baseline for high-coverage schemas.

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 ('Geocode batch'), the batch size ('up to 5'), the outputs ('coordinates and a structured address'), and the optional country filter. The batch scope clearly distinguishes it from the single-address sibling 'geocode'.

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

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

The description explicitly says when to use it: 'Use geocode-batch for up to 5 addresses at once.' However, it does not explicitly name the sibling 'geocode' as the alternative for single-address requests or state when not to use this batch tool.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety and external-data behavior are covered. The description adds important non-schema context: free-tier limits, paid fallback via x402/card credits, in-band payment location, and the fact that date converts the result into an is_holiday answer. It does not explain error or pagination behavior, but the added pricing/payment context is substantive.

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

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

The description is reasonably short, but it leads with billing and free-tier details before stating the tool's core purpose. The key 'what it does' sentence comes after payment mechanics, which is less front-loaded than ideal for tool selection.

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

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

Given the presence of an output schema, the description need not explain return values. It covers the core scope, date behavior, pricing/payment, and country coverage, which is most of what an agent needs for this 3-parameter, read-only lookup tool. Remaining gaps are minor: year default behavior and country code format are left to the schema.

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

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

Schema description coverage is only 33%: country is described as 'ISO2', year is an enum, and date has no schema description. The description compensates for date by explaining 'date=YYYY-MM-DD answers is_holiday' and implies the year scope, but leaves year default/behavior and country format underexplained in the prose. This is a partial, not full, compensation for the low 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 resource and scope: 'Public holidays for ~490 countries/territories for 2026 and 2027', and explains the optional date=YYYY-MM-DD behavior. It is clear what the tool returns, though it does not explicitly differentiate itself from any similar sibling tool.

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

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

The 'When to use' sentence says to use holidays to list public holidays or test one date for a country, which gives basic usage context. However, it restates the obvious rather than explaining when not to use it or naming an alternative 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?

Well beyond the readOnlyHint/openWorldHint annotations, it discloses pricing and free-tier limits, the in-band x402 payment parameter, a card-licence alternative, the 10-page/8 MB/22 s caps, that documents are not stored, that failures are not charged, and that it runs on Cloudflare Workers AI. These are exactly the operational traits an agent must know before invoking a paid call.

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

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

The critical call-shape constraint (exactly one of url/text/file_base64) is front-loaded, and the use-case routing is placed where it can be scanned. The cost is some redundancy: pricing is stated three times and the free tier twice ("3 free MCP calls per day" vs "1 free call per caller"), which could briefly confuse a reader.

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?

An output schema exists, yet the description still summarizes the returned fields and the value/quote/confidence triple plus arithmetic checks, so an agent knows what it will get. Combined with transport options (POST JSON, raw upload, GET query) and payment paths, nothing needed to call it correctly is missing.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds a constraint the schema does not express: the inputs are mutually exclusive and exactly one must be supplied (schema has no required fields). It also restates the url/text/file_base64+mime_type grouping, which clarifies how mime_type pairs with file_base64. It does not add 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 and resource: an invoice/receipt (PDF, image, or text) is converted into structured JSON with a fixed accounting schema, and the schema's fields are enumerated. It explicitly distinguishes itself from extract_json (any text, custom schema) and page_rag (web page to Markdown), so an agent can pick it without opening sibling schemas.

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

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

Contains an explicit "When to use" block naming two alternatives and the condition that selects each: invoices/receipts here, arbitrary text with a custom schema to extract_json, web pages to page_rag. It also gives concrete fallback guidance for scanned PDFs without a text layer (send page images).

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 declare readOnly/openWorld, so the description carries real weight and delivers: 3 free calls/day shared across all tools, $0.0025 USDC via x402 or card credits, and the in-band payment field path. That quota/payment disclosure is exactly the kind of context annotations cannot express, though timeout, redirect-following policy, and failure semantics remain unstated.

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

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

The description opens with billing mechanics before saying what the tool does, which is poor front-loading for tool selection. The 'in one call' phrase and the 20-URL limit are each stated twice, so it is not wasteful but it is redundant and mis-ordered.

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?

An output schema exists, so return fields needn't be explained, and cost, quota, and batch size are all covered. What is missing is operational behavior an agent would want before spending a paid call: per-request timeouts, whether redirect chains are followed by default, and how partial failures are reported.

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

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

Schema coverage is 100% and the single param already documents 'comma-separated absolute URLs, max 20', which the description merely repeats. Baseline 3 is appropriate since the schema does all the work and the description adds no syntax or edge-case detail.

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

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

Specific verb+resource with an enumerated output set: 'HTTP status, final URL after redirects, redirect count, latency, content-type, ok flag' tells the agent exactly what it gets back. It does not distinguish itself from nearby siblings like page_check or robots_check, which also touch URLs, so an agent still has to infer 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?

The 'When to use' clause gives a use case (broken-link testing, up to 20 URLs in one call), but it only restates the capability line rather than adding a decision rule. There is no when-not guidance and no mention of page_check/robots_check as alternatives for single-page or crawler-rule checks.

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

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

With no annotations, the description carries the full burden and does real work: it discloses cost ($0.00 to call), the per-route free-call throttle, ordering (core products first), and the fields returned. It stops short of stating rate limits beyond the free-call note or whether the listing is ever cached/stale.

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 lead ('Free. List every endpoint ... example query') is well front-loaded, but the following 14-item price enumeration is a dense inline dump that could be collapsed to a range or deferred to the response. It is informative yet heavy for a description field.

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 and no annotations, so the description must describe the return shape, and it does: price, description, and example query per endpoint, with core products ordered first. Only a note on response size/pagination 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, so the baseline is 4; nothing about parameter meaning needs explaining, and the description correctly spends no words on 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 a clear verb and resource ('List every endpoint') plus what each entry contains: price in USDC, description, example query. It implicitly separates itself from the per-endpoint siblings (tx_explain, ens, geocode) as the catalog view, but never names a sibling or the discovery role explicitly.

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?

'Free' and '1 free call per route per caller' hint at when it is cheap to call, but there is no explicit guidance on when to use this versus discovery siblings like apis_search, api_directory_sample, or free_tiers. Usage is implied rather than directed.

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 readOnlyHint/openWorldHint by disclosing a concrete commercial constraint (3 free calls per day across all tools, then $0.005 USDC), the exact in-band payment mechanism (params._meta["x402/payment"]), and data provenance (LiteLLM price table, MIT). Rate limit, auth/payment path, and price source are exactly the behavioral facts 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?

Dense but zero-waste: cost/free-tier framing first, then what it computes, then params, then when-to-use. Four sentences each carrying distinct information, with the commercial constraint front-loaded where it matters most for a paying agent.

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

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

For a 5-param, 0%-coverage tool with an output schema, the description covers payment, source of truth, model selection syntax, and the two input modes (estimate vs supplied token counts). It omits only what "calls" means semantically and that numeric inputs arrive as strings, so an agent could mis-specify that one parameter.

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 0% schema description coverage, the description carries the full parameter burden and mostly succeeds: models is given format, examples, search-word fallback, and a hard cap of 15; text vs input_tokens is framed as an either/or. The gap is "calls," which is listed but never explained, and the fact that all five params are typed as strings is not flagged.

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

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

States a concrete verb+resource: "Token & cost calculator: estimate tokens for a text ... and price it across several models using provider list prices." That is specific enough to act on. It does not, however, distinguish itself from near-neighbors like token_compare, llm_pricing, or dump_llm_pricing, which an agent could easily 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?

Explicit positive routing exists: "When to use: Use llm-cost to compare what a workload costs across models." It also implies the token-estimation path via the text/input_tokens params. It gives no when-not guidance and never names the sibling tool that would be the 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 only declare readOnlyHint and openWorldHint; the description adds substantial context the annotations cannot convey: a metered quota (3 free MCP calls/day across all tools), a $0.005 USDC charge via x402 or card credits, and that payment is supplied in-band at params._meta["x402/payment"]. This is exactly the kind of billing/authorization behavior an agent must know 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?

Two dense sentences with no filler; the billing terms lead (arguably the most decision-critical fact) followed by the data scope and filter list. Slightly crowded but every clause carries information, and nothing is repeated from structured fields needlessly.

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

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

For a read-only filterable data tool with an output schema already defining return shape, the description covers cost model, dataset breadth, provider coverage, all filter dimensions and the result cap. An agent has everything needed to decide and 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 0% across 9 parameters, so the description carries the full burden and does: it names every parameter (q, provider, free, max_input_per_m, min_context, vision, tools, sort, limit), gives the enum values for the flag/sort params, and adds the constraint limit<=100 that the schema does not express.

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

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

The description names a specific resource (AI model list prices: input/output/cached token pricing, context window, capability flags, plus free tiers/rate limits) and its scale (~3,000 models, named providers). It does not explicitly distinguish itself from close siblings such as llm_pricing_sample, dump_llm_pricing or llm_cost, which is the only thing keeping it from 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?

It enumerates the available filtering modes (free=yes, vision=yes, tools=yes, sort, limit) which implies how to narrow results, but never states when to choose this tool over llm_cost, llm_pricing_sample or dump_llm_pricing, nor any prerequisites beyond the payment note.

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

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

No annotations exist, so the description must carry behavioral context; it usefully discloses cost (free), data provenance (LiteLLM table), license (MIT), and price unit. It does not state freshness, caching, or rate behavior, so it is helpful but incomplete for a tool with zero annotation coverage.

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 dense sentence, front-loaded with the free/cost qualifier and otherwise carrying only essential scope, unit, and provenance. 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, read-only list tool with no output schema, the description supplies enough (model count, price unit, source) to call it correctly. Slightly more detail on return fields would make it airtight, 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 per the rubric the baseline is 4; the description adds that prices are in USD per 1M tokens, which is useful framing but not a parameter concern.

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 ("List prices") plus scope ("five popular LLMs") and unit (USD per 1M tokens), which separates it from the likely full sibling llm_pricing and the llm_cost sibling. An agent can identify it as a lightweight pricing lookup 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?

"Free" and "sample" of only five models imply a cheap/quick first stop versus llm_pricing or llm_cost, but no alternative is named and no explicit when/when-not condition is given. Usage is inferable but not 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 already establish readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description goes beyond that with genuinely non-obvious operational context: a 3-call-per-day free quota shared across all tools, then $0.001 USDC via x402 or card credits, paid in-band through params._meta["x402/payment"]. That payment mechanism is exactly the kind of thing an agent cannot learn 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?

Two sentences, no filler, and the return-shape clause is a useful close. The main structural flaw is that the long pricing/payment sentence is front-loaded ahead of the actual purpose statement, delaying the agent's answer to "what does this do?" until sentence two.

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

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

With an output schema present, the description needn't document return fields, and its one-line return summary is sufficient. Six optional parameters with zero schema descriptions leave gaps (no default or max for limit, no pagination behavior), but for a read-only search tool with clear filter names the coverage is largely adequate.

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

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

Schema description coverage is 0%, so the description carries the full burden. It glosses keyword, category, language, scope, and official flag, but never mentions the limit parameter at all, nor explains that limit is typed as a string or that official only accepts "yes" — quirks an agent would otherwise get wrong.

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 gives a specific verb and resource ("Search 4,259 MCP (Model Context Protocol) servers") and enumerates the filterable dimensions, so the agent knows exactly what the tool returns. It does not, however, distinguish itself from the closely related siblings mcp_servers_sample and dump_mcp_servers, which is the only thing keeping it from 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?

Implicit guidance comes from the enumerated filters and the note that results include repo URL and description, which signals "use this to find a server." There is no explicit when-to-use/when-not statement and no routing to mcp_servers_sample or dump_mcp_servers, so the agent must infer which of the three MCP tools to pick.

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

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

With no annotations, the description carries the full behavioral burden. It does disclose two useful traits: cost ("Free") and licensing ("MIT source"). However, it says nothing about how the five are selected (first five, random, curated), the return format, or any pagination/rate behavior.

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

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

A single tight sentence with no filler, and the distinguishing constraint ("Five sample") appears early. It is arguably too terse rather than bloated, which is a completeness issue, not a conciseness one.

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 annotations, no output schema, and no parameters, the description is the only documentation the agent gets. It omits the return shape, how the sample is chosen, and any relation to the full-directory siblings, leaving meaningful gaps for a tool whose entire value is its curated content.

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 the baseline is 4. The description adds nothing parameter-related, but nothing is needed — there are no inputs to disambiguate and schema coverage is 100%.

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 identifies the resource (MCP servers) and the scope (five samples drawn from a 4,259-server directory), so an agent can guess what comes back. But it is a noun phrase with no action verb, and it never distinguishes itself from siblings mcp_servers or dump_mcp_servers. Purpose is inferable rather than stated.

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

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

There is no when-to-use guidance. The word "sample" faintly implies a preview, but the description never says to use this instead of mcp_servers when you only need a few examples, nor names any alternative. An agent must infer the tradeoff on its own.

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

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

With readOnlyHint and openWorldHint already declaring the safety and open-world profile, the description still adds meaningful context: the free-call quota (3/day across all tools), the paid continuation path with price and payment mechanism, and the in-band x402 payment parameter location. Still missing are failure behavior for unmatched entities and whether the Wikipedia check can fail independently of the news half.

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

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

Dense and short overall, with no filler sentences. The one structural weakness is ordering: the billing/quota paragraph is front-loaded ahead of what the tool actually does, so the purpose statement arrives second when it should lead.

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 two-parameter read-only tool with an output schema and annotations already covering safety and open-world behavior, this covers the remaining essentials: what it returns, which sources back it, and the cost model. Only entity-miss behavior and the independence of the two sub-results (news vs Wikipedia) are left unstated.

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

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

Schema coverage is 100% and both parameters are documented in the schema, so the baseline is 3. The description reinforces the split by describing 'a Wikipedia identity check of the entity', which quietly explains why a language parameter exists, but it adds no format or syntax guidance (entity disambiguation, lang values) 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 and resource — a 24h entity news snapshot — and enumerates the outputs (article count, top sources, top countries, headlines) plus a Wikipedia identity check, naming the data sources (GDELT DOC 2.0, Wikipedia). This is far more specific than the name alone and implicitly distinguishes it from news_monitor/news_sentiment by scoping to one entity over 24h, but it never names those siblings to rule them out.

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?

An explicit 'When to use' sentence gives the selection condition: a 24h media snapshot of one company, person or project. That is clear positive guidance, but there are no exclusions or pointers to the obvious alternatives (news_sentiment for tone, news_monitor for ongoing tracking, wiki_fact for identity alone).

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

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

Goes well beyond the readOnlyHint/openWorldHint annotations: discloses the exact pricing model (3 free calls/day across all tools, then $0.005 USDC via x402 or card credits), how payment is transmitted in-band via params._meta["x402/payment"], and the upstream data source (GDELT DOC 2.0). Those are operational facts 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?

Two dense sentences, no filler, with pricing and the payment mechanism front-loaded. The capability block is somewhat packed (language count, field list, data provider crammed into one clause), but every element is load-bearing for an agent deciding whether to call.

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 an output schema exists, return values needn't be explained, yet the description still summarizes them (title, URL, source domain, language, country, time). Combined with cost, data provenance, and sibling routing, nothing an agent needs before invoking it is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema lacks: the timespan accepts a bounded range from 1h to 2 weeks, results favor recency (newest first), and the corpus spans 65+ languages. It doesn't explain the q syntax beyond what the schema says, so it stops short of a 5.

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

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

States a specific verb+resource ('News search and monitor') with concrete scope: worldwide articles in 65+ languages, keyword match, time window, newest first. It explicitly separates itself from news_entity and news_sentiment by naming what each of those does instead.

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?

Contains an explicit 'When to use' clause that routes the agent: news-monitor for latest articles by keyword, news-entity for a 24h who-writes-about-X digest, news-sentiment for tone. Both alternatives are named with the condition that selects them.

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 and openWorldHint=true, and the description adds meaningful behavioral context beyond that: free-call limits, per-call pricing after the limit, in-band payment location, default timespan, data source, and the shape of the sentiment result. It does not discuss failure modes or data-quality limitations, which keeps it from a 5.

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

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

The description is compact and front-loads the commercial/payment constraints before explaining the sentiment output and use case. Every sentence contributes, though leading with pricing rather than the tool's core analysis slightly delays the primary purpose.

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

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

Given the simple three-parameter schema, existing output schema, and annotations, the description covers purpose, data source, default window, result fields, cost, and use case. It is complete enough to invoke correctly, with the main missing piece being explicit sibling differentiation.

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, lang, and timespan. The description adds the default window of 7 days for timespan and clarifies that q can be a topic, company, or person, but it does not add substantial semantics beyond the schema.

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

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

The description states a specific analyzed resource: average tone of worldwide news coverage about a topic/company/person over a window, with label, trend, and timeline, sourced from GDELT DOC 2.0. This is clear enough to distinguish it from generic search or entity-extraction siblings, though it does not explicitly contrast itself with news_monitor or news_entity.

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

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

It gives an explicit use case: judging whether coverage of a topic is negative or positive and whether the trend is improving or worsening. It does not state when not to use it or name alternative sibling tools for overlapping news workflows, so it is clear but not fully routing-oriented.

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 behavioral context beyond the annotations: a hard rate limit of 3 free calls/day shared across all tools, a $0.012 USDC price, and the exact in-band payment mechanism via params._meta["x402/payment"]. That payment detail is critical and appears nowhere in the annotations or schema. It's consistent with readOnlyHint=true and openWorldHint=true.

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

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

Three tight sentences with no filler; the pricing/rate-limit preamble is front-loaded so cost is known before committing. Slight awkwardness in leading with billing before stating what the tool does, but 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?

Because an output schema exists, return values needn't be explained, and the description covers cost, quota, payment flow, and scope plus a docs link. The only meaningful gap is sibling routing guidance for an agent choosing among the many discovery 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?

The single 'q' parameter is fully documented in the schema with examples, so baseline is 3 per the coverage rule. The description adds only the unschema'd payment meta-parameter, which is behavioral rather than semantic detail about the search input 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?

States a specific verb and resource set: 'Discover AI-agent tooling in one call: matching MCP servers, x402 pay-per-call services and agent tools for any query.' The tri-resource scope distinguishes it from single-resource siblings like mcp_servers or x402_services, though the sibling names are never mentioned.

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?

'Built for agents that need to find and chain new capabilities at runtime' implies the use case but gives no explicit when-to-use/when-not, and never names the obvious alternatives (mcp_servers, x402_services, agent_tools) that this pack aggregates. An agent has to infer that this is the broad-search option versus the targeted siblings.

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

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

Annotations only declare readOnlyHint and openWorldHint, so the cost/limit model is genuinely additive: 3 free calls per day shared across all tools, then $0.022 USDC via x402 or card credits, paid in-band via params._meta["x402/payment"]. That is exactly the kind of operational context structured fields do not carry. Minor gaps remain around what happens on failure or which inputs are guaranteed to yield 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 dense sentences with no filler, and the deliverable list is well enumerated. The one structural weakness is front-loading the billing quota and payment mechanics ahead of the statement of purpose, which delays the agent's answer to 'what does this do.'

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?

An output schema exists, so return values need no prose, and the annotations cover safety. The description covers pricing, bundling, and output readiness. The gap is that both parameters are optional, and the description never says what happens when neither url nor domain is supplied.

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 url and domain, including that domain is derived from url when omitted. The description adds only a loose mapping of url to contacts/people and domain to profile/tech stack, without new syntax or format detail. Baseline 3 applies.

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

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

The description names a specific verb and resource ('Find B2B leads on any company website') and enumerates the concrete deliverables: contact emails, people, company profile, tech stack, and up to 3 email verifications. The phrase 'in one call' implies aggregation vs. the individual sibling tools (company_contacts, company_profile, company_techstack), but it never names them, so the differentiation requires 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?

Usage is only implied through 'in one call' — the agent can gather this is the bundled alternative to the individual company_* tools. There is no explicit statement of when to prefer this pack over those siblings, nor any prerequisites or exclusions beyond the daily quota.

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 readOnlyHint and openWorldHint annotations, the description discloses free-tier limits, paid pricing, and in-band payment mechanics. It also enumerates exactly which checks are performed. It does not describe failure behavior or partial-result semantics, but the output schema likely covers return structure.

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

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

The description is compact and includes only relevant information: pricing, purpose, coverage, and a use case. The cost sentence is somewhat dense and placed before the purpose, but it remains clear and front-loaded.

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

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

Given the output schema, annotations, and full schema coverage, the description provides enough information to understand what the tool returns and when it is useful. The main minor gap is lack of explicit differentiation from sibling single-purpose 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 description coverage is 100%, so both the domain and url parameters are already documented in the schema. The description adds little parameter-specific meaning beyond the schema, making a baseline 3 appropriate.

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

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

The description names a specific resource (a domain) and specifies an aggregate health check covering WHOIS, DNS, SSL, robots.txt, and sitemap. It clearly distinguishes this tool as a one-call pack rather than a single-purpose check.

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

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

It provides a use case: vetting a site before outreach, purchases, or integrations. However, it does not explain when to use this pack versus the many sibling single-purpose tools such as domain_whois, dns, ssl_cert, robots_check, or sitemap.

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

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

Annotations already cover the safety profile (readOnlyHint, openWorldHint), and the description adds genuinely non-obvious behavior: the free-tier quota (3 calls/day across all tools), the $0.008 USDC x402 / card-credit cost, and that payment is passed in-band via params._meta["x402/payment"]. It does not explain supported chains or behavior on unknown hashes, but the monetization mechanics are a meaningful disclosure.

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

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

The pricing line is front-loaded and the core capability follows immediately, with the info URL last. Minor waste: 'FreeTier Payment Verification pack' restates the tool title, and the pricing boilerplate is longer than the tool-specific content.

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

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

An output schema exists, so return values need not be explained, and annotations cover read-only semantics. For a blockchain verification tool, though, the description omits chain coverage and failure behavior for unknown or unmined hashes, which are the details an agent most needs before calling.

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

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

There is a single parameter, fully described in the schema at 100% coverage ('Transaction hash to verify'), so the schema already does this job. The description does not add format details (chain scoping, hash length, multichain handling), leaving it at the baseline for full-coverage schemas.

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 (verify a blockchain transaction) and enumerates the outputs: live status plus a plain-language explanation of what the transaction did. That clearly differentiates it in substance from single-purpose siblings like tx_status and tx_explain, but it never names those siblings, so an agent must infer that this is the combined 'both in one call' option.

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?

'Verify a blockchain transaction before you trust it' and 'One call for agents that handle payments' imply the use case, so usage is inferable. However, given that tx_status and tx_explain exist as overlapping siblings, the description never says when to pick this pack over them, nor does it state exclusions or prerequisites.

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

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

Annotations only cover readOnlyHint and openWorldHint; the description adds the critical non-schema behavior: a 3-call/day free quota shared across all tools, then $0.024 USDC via x402 or card credits, and the exact in-band payment mechanism (params._meta["x402/payment"]). That payment/quota disclosure is exactly what an agent needs before invoking a metered tool and is unavailable anywhere else.

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 preamble occupies roughly the first third of the text and precedes the actual purpose, so the definition is not front-loaded on what the tool does. The trailing URL plus "built for AI agents on x402" partially restates the payment sentence, adding redundancy.

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