Citiview Agent Market

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

Annotations cover the safety profile (readOnlyHint, openWorldHint), and the description goes beyond them with a concrete, decision-relevant fact: $0.004 USDC per call via x402, i.e. a paid micropayment operation. It also discloses the granularity of the confidence signal (building/street/city) and that alternatives are returned. It stops short of explaining payment/auth prerequisites or failure modes.

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 that front-loads purpose then lists outputs, ending with the cost caveat. Efficient, though the output enumeration makes it slightly list-heavy at the expense of input guidance.

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

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

With no output schema, the description correctly carries the return-value burden and does so thoroughly (parsed components, confidence levels, verdict, coordinates, timezone, alternatives). The gaps are on the input/usage side, not the output side.

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 50% ('address' has no description), so the description must compensate — but it is written entirely around return values and says nothing about the input. The 'country' restriction behavior is left to the schema alone.

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

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

States a specific verb+resource ('Address verification and standardization') and enumerates the exact outputs it produces, so an agent knows precisely what comes back. However, it never distinguishes itself from the obvious sibling 'address_validate' (nor 'geocode'/'postal'), leaving overlap unaddressed.

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 statement of when to reach for this tool versus address_validate, geocode, postal or zip. The only context offered is the price, not usage 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 already cover readOnlyHint and openWorldHint, so the bar is lower, and the description adds real value beyond them: a per-call price of $0.003 USDC via x402, plus the upstream data source (OpenAQ). It still omits freshness/latency of station data and any rate limits, so it is 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?

Two sentences, front-loaded with the capability and follow-up with the cost. Every clause (pollutants, AOI category, source, price) earns its place; 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?

For a read-only lookup with no output schema, the description adequately signals the response shape (pollutants plus AQI category). It is incomplete on inputs, though: with 0 required parameters and no schema documentation, an agent cannot tell what constitutes a valid call or how the optional location parameters interact.

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 four parameters, so the description carries the full burden. "Near any place" vaguely hints at lat/lon/near, but nothing explains precedence between near and lat/lon, the units or default of radius_m, or what happens when no parameters are supplied (all four are optional).

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?

Concrete verb+resource: retrieves air quality near a place from OpenAQ monitoring stations, and it names the returned payload (PM2.5, PM10, ozone, NO2, US AQI, health category). It does not, however, distinguish itself from the siblings airquality_compare, airquality_history, and airquality_stations, so an agent cannot route between them from this text alone.

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 statement, no when-not-to-use, and no named alternative despite three closely related air-quality siblings. Only an implicit signal ("near any place") hints at the calling context.

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 safety and open-world nature are covered. The description adds genuinely non-obvious operational context: the data comes from the nearest active monitors, results are ranked, and each call costs $0.005 USDC via x402 — the pricing detail is important for an agent that must decide whether to invoke.

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, front-loaded with what is compared and how results are ordered, followed by the cost caveat. Every clause carries information; nothing is redundant padding.

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

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

For a single-parameter, read-only, no-output-schema tool, the description covers scope, metrics returned, ordering, data source, and payment requirement. An agent has everything needed to decide to call it and what to expect back.

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 parameter already documents '2-8 places separated by |'. The description repeats the 2-8 count but adds no separator syntax, format examples, or behavior for out-of-range inputs, so it does not meaningfully extend 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?

Specific verb (compare) plus resource (air quality), with explicit scope (2-8 cities), enumerated metrics (US AQI, category, PM2.5, PM10, ozone, NO2), and output ordering (cleanest to most polluted). It implicitly distinguishes itself from airquality (single place) and airquality_history (past data) via 'compare' and 'current', but never names a sibling to route the agent 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?

Usage is implied by the multi-city framing: use it when you need a side-by-side comparison rather than a single reading. However, there is no explicit when-not guidance and no reference to airquality, airquality_history, or airquality_stations, which are the obvious alternatives for single-location or historical queries.

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

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

Annotations cover the safety profile (readOnlyHint, openWorldHint), so the bar is lower, and the description still adds real behavioral context: the data source ('nearest active monitor'), the 365-day range cap, and the paid-per-call cost ($0.003 USDC via x402), which is critical for an agent deciding whether to invoke it. It does not mention failure modes when no monitor exists nearby.

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-loads the resource and scope, followed by the pricing note. Every clause carries information (metrics returned, pollutants, source, range, cost), with 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?

With no output schema, the description usefully enumerates the returned fields, and it discloses cost and data provenance for a 5-parameter, no-required-param tool. The remaining gap is the unexplained relationship between the 'near' place name and lat/lon coordinates, which matters for correct invocation.

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

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

Schema coverage is 60%; lat/lon carry no schema description. The description adds the pollutant vocabulary (PM2.5, PM10, ozone, NO2, SO2, CO) that maps to the 'parameter' field, but it never clarifies that 'near' and lat/lon are alternative location selectors or how they interact. Baseline 3 given partial schema coverage.

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

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

The description states a specific verb (returns history) and resource (air pollution data) and even enumerates the returned metrics (daily avg/min/max, US AQI, worst day, WHO exceedance days, trend). It distinguishes itself from a current-conditions tool only implicitly via 'history' — it never names siblings like airquality, airquality_compare or airquality_stations.

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: 'history ... up to 365 days' suggests retrospective analysis versus the sibling airquality for current readings, but there is no explicit when-to-use, when-not-to-use, or alternative-routing sentence. An agent must infer the choice from the tool name.

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

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

Annotations already cover the safety profile (readOnlyHint, openWorldHint), but the description adds genuinely non-structured context: the call is metered at $0.002 USDC via x402, and results are limited to stations currently reporting. Missing are rate limits, pagination, and what happens when lat/lon are combined with near/country.

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 front-loaded sentence opening with the verb and resource, then a compact field list and a cost sentence. Nothing is padded, though the nine-item output enumeration is longer than strictly necessary to route a 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?

With no output schema, the description correctly compensates by listing the returned attributes, and it discloses cost. However, for a 6-parameter tool with zero required parameters, it never explains the default behavior when no location or country is supplied, nor limit/pagination semantics — meaningful gaps.

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 50% (lat, lon and limit have no descriptions). The description partially compensates by naming the two location modes (a place vs a country) and by relating the returned fields to the filter intent, but it says nothing about lat/lon pairing, limit/default behavior, or the parameter filter. Baseline 3 for partial compensation.

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

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

Specific verb+resource+scope: 'Find air quality monitoring stations that are reporting now, near a place or across a country.' It also enumerates the returned fields, so an agent knows what it gets. It does not, however, differentiate itself from close siblings like 'airquality', 'airquality_compare' or 'airquality_history', leaving the agent to guess which one to pick.

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?

'Reporting now' and 'near a place or across a country' imply the two usage modes (location-scoped vs country-wide), which is useful. But there is no explicit when-to-use vs when-not, and no mention of when a sibling like airquality_history or airquality would be the better choice; the agent must infer from the field list.

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 genuinely non-obvious traits: the $0.02 USDC per-call x402 payment, the grounding discipline ("writes only from what they say"), and the model used. That is real added context for a paid, open-world tool. It stops short of describing failure/insufficient-sources behavior or latency.

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, front-loaded with the core value (cited answers from live pages) and then the operational facts (grounding, model, cost). Every clause carries information; no filler or 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 no output schema, the description does the work of describing the return shape (concise answer, numbered citations, source list), which is the critical missing piece. It also covers cost and grounding. Minor gaps remain around edge cases (no results, paywall/blocked pages) and how source count affects behavior.

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 q and the 2-6 range/default for sources are already documented structurally. The description adds nothing beyond that about parameter meaning or interaction. Baseline 3 is correct when the schema carries the parameter burden.

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

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

States a concrete verb+resource: it answers a question with a concise, citation-backed response built from live web pages. The mention of live page reading and numbered [n] citations is specific enough that an agent knows exactly what comes back. It does not, however, name or contrast itself with the obvious siblings (answer_cached, ask, docs_ask), so sibling discrimination 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?

Usage is only implied: an agent can infer this is for a sourced answer to a natural-language question. There is no explicit when-to-use, when-not-to-use, or routing to alternatives such as answer_cached (likely the cheaper repeat path) or docs_ask (for document corpora). The per-call cost hint gestures at cost-sensitivity but does not translate it into 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?

Annotations already declare readOnlyHint and openWorldHint, and the description adds genuinely non-obvious behavior: shared cache semantics, a $0.005 USDC x402 charge per call, and no charge when nothing close enough is cached. It does not describe latency or what a hit-vs-miss response looks like, but the cost/charge disclosure 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?

Three short sentences, front-loaded with the identity of the tool, then pricing and cache-miss behavior. The x402 price sentence is slightly redundant with 'a quarter of the price' but still adds concrete cost 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 paid lookup with no output schema, the description covers what is returned (a cited answer), its source, the pricing model, and the miss behavior, which is what an agent needs to call it correctly. Only marginal gaps remain, such as freshness bounds beyond the max_age_days schema field.

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%, with max_age_days and min_similarity documented in the schema itself. The description's 'nothing close enough is cached' implicitly explains the role of the similarity threshold but adds no syntax, range, or default detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb+resource ('shared answer cache' returning 'a recent cited answer') and its provenance ('from /v1/answer'), which clearly separates it from a fresh `answer` call. It stops short of naming the sibling tool directly, so an agent must infer that `answer` is the non-cached counterpart.

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

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

Gives clear selection context: it is the cheap variant of /v1/answer ('a quarter of the price') and is not charged on a cache miss, which tells an agent when the tradeoff is favorable. It lacks an explicit 'use this when X, use answer when Y' exclusion, so the routing is implied rather than stated.

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

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

Annotations already cover the safety profile (readOnlyHint=true, openWorldHint=true), and the description adds genuinely useful non-obvious behavior: answers are grounded in exact quotes, long documents are pre-searched with embeddings, and each call costs $0.02 USDC via x402. The cost disclosure is valuable context an agent cannot get from structured fields, though return format and limits remain unspecified.

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 sentences with the core purpose front-loaded and no wasted filler; inputs, output characteristic, and cost are each covered once. The construction is dense and efficient, with only minor awkwardness in the opening phrase.

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 Q&A tool with no output schema, the description covers the essentials: accepted input formats, the quote-backed nature of the answer, the embedding search step, and the per-call cost. Adding whether url/text are exclusive and what happens on retrieval failure would make it fully complete.

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

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

Schema coverage is 67% and the schema descriptions are terse ('Document or page URL', 'Raw text instead of url'). The description meaningfully extends this by enumerating accepted document types (web page, PDF, Word, Excel, CSV) and clarifying that raw text substitutes for a URL. It stops short of stating whether url and text are mutually exclusive.

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 ('ask a document') and a concrete result ('get an answer backed by exact quotes'), making the document-Q&A function unambiguous. However, it never differentiates itself from close siblings like docs_ask, answer, or cite, which an agent must choose between.

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 implied by the input shape (provide a URL or raw text plus a question), but there is no explicit when-to-use guidance, no exclusions, and no reference to the sibling tools that also answer questions over content. An agent must infer the selection criteria 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?

Annotations only declare readOnlyHint=true and openWorldHint=true, so the description adds substantial behavioral context: WAV return format, 2000-character limit, no API key, flat pricing, and the x402 $0.005 USDC cost. It goes well beyond the annotations, though it doesn't explain latency or failure modes.

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 covers shape, output, languages, limits, and price. It is front-loaded with the core purpose, though the pricing and x402 details make it slightly crowded.

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

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

Given no output schema, the description covers what is produced (WAV), input constraints (character limit, languages), and operational constraints (price, no key). Remaining gaps like latency or voice selection are minor, since voice is declared ignored.

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 75% and marks model/voice as 'Ignored' and language as an enum-like string. The description clarifies that model and voice only exist for OpenAI request-shape compatibility, and enumerates the languages for 'language', adding value beyond the schema.

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

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

States a specific verb+resource ('text to speech') and explicitly ties itself to the OpenAI /v1/audio/speech request shape, distinguishing it from sibling speech tools like speak, speak_pro, and audio_transcriptions.

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 OpenAI-compatibility and language list imply when it fits, but there is no explicit when-to-use versus speak/speak_pro or guidance on input format. Usage is inferable rather than stated.

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

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

Goes well beyond the readOnlyHint/openWorldHint annotations: it discloses the 20 MB cap, flat pricing, that no API key is needed, the per-call x402 USDC cost, and the length-based price formula. Payment/auth requirements and hard limits are exactly the behavioral context an agent needs before calling.

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

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

Dense and front-loaded: compatibility and formats come first, then constraints and pricing. It is on the long side and the pricing/query-parameter details could be trimmed, but every clause carries information an agent can act on.

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, open-world transcription call with no output schema, the definition covers input methods, formats, size/time limits, and cost, which is nearly everything needed. It stops short of describing error behavior or latency, which would round out the picture.

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, but the description adds real value: it explains the response_format values, that model is ignored, that a public URL is an alternative to file upload, and documents a max_minutes query parameter that does not appear in the schema at all.

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+resource (speech to text transcription) and pins the exact model (Whisper large v3 turbo) plus OpenAI compatibility, so the agent knows what it does and that it is a hosted OpenAI-style endpoint. However, it never distinguishes itself from close siblings like transcribe, transcribe_pro, or audio_speech, so routing still 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?

The description implies usage context (audio under 20 MB, multipart upload or public URL, default 6 / max 30 minutes) but gives no explicit when-to-use or when-not-to-use guidance and names no alternative sibling. An agent can infer a suitable case but has no routing rule against transcribe_pro.

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 genuinely new behavioral context beyond those: the $0.002 USDC x402 payment requirement and the 10-airport batch cap. It omits rate limits and response format, but the cost/payment disclosure is substantive added value.

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 that front-loads purpose and return contents, then closes with the batch limit and pricing. Every clause earns its place with no filler, though the sentence is long enough that a cleaner split could improve scannability.

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

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

With no output schema, the description carries the return-value burden well by enumerating the decoded fields, and it covers cost and batch limits. The one meaningful omission is any explanation of the 'hours' input parameter, leaving the definition slightly incomplete for a 2-parameter tool.

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

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

Schema description coverage is only 50%: 'airport' is documented in the schema (ICAO, comma separated) and the description restates the ICAO/up-to-10 detail, but the 'hours' parameter is explained nowhere. With a full half of the parameters undocumented and the description failing to compensate, this is a clear 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 names a specific resource (aviation weather for airports) and enumerates exactly what it returns: latest METAR decoded plus the TAF forecast. It is clearly distinguished from the generic 'weather' sibling by the METAR/TAF framing, though it never names an alternative tool explicitly, so it falls short of a 5.

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

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

Usage is implied by the content (aviation weather for ICAO codes), and the description notes it accepts up to 10 codes and costs $0.002 USDC per call (x402). However, it gives no explicit when-to-use vs the 'weather' sibling, no when-not conditions, and no prerequisites, leaving usage to inference.

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

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

Annotations already declare readOnlyHint and openWorldHint, so safety is covered. The description adds genuinely useful behavioral context beyond them: the upstream data source (Open Food Facts), the packaged-food scope limit, and the per-call paid cost ($0.002 USDC via x402), which is exactly the kind of thing an agent must budget for.

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 verb and resource, then the return payload, then cost. It is long but every clause carries information; only the enumeration of Nutri-Score/NOVA/eco-score is arguably padded.

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

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

With no output schema, the description correctly enumerates the return contents (name, brand, ingredients, allergens, scores, per-100g nutrition) and discloses cost and source. Missing only failure behavior for unknown or non-food barcodes, which is minor for a one-parameter 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 parameter and schema coverage is 100%, with the schema itself documenting 'EAN or UPC digits'. The description restates the same input form without adding format, checksum, or length guidance, so the baseline of 3 applies.

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

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

States a specific verb+resource ('Product barcode lookup') and names the data source (Open Food Facts) plus the returned fields, so the agent knows exactly what it gets back. It does not differentiate itself from the sibling barcode_read, which is a real ambiguity given the near-identical name.

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

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

Usage is implied rather than stated: the 'packaged food from its EAN/UPC barcode' scoping tells the agent this is for food products with a numeric barcode, but there is no explicit when-to-use, when-not-to-use, or named alternative to barcode_read/nutrition for non-food barcodes.

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 declare readOnlyHint=true, but the description's own action list — click, type, press a key, select, close — describes state-changing interactions (form submits, session teardown) that are not read-only. The description does add real behavioral context (10-step cap, return payload, $0.008 USDC x402 cost), but the direct conflict with the read-only annotation is a serious selection hazard and triggers the rubric's contradiction rule.

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: what it does and its action vocabulary, what it returns, and what it costs. No filler, and the capability statement is front-loaded before the cost so the agent can decide quickly.

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

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

With no output schema, the description carries the return-value burden and handles it well ('what happened, a fresh screenshot, the page text and the clickable controls'), plus the per-call price and step cap. The gap is prerequisites: with 3 of 4 params required, it never states how to obtain `session`/`token` or what happens on failure.

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

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

Schema coverage is 50%: `actions` and `screenshot` are documented in-schema, while `session` and `token` are bare. The description usefully expands on `actions` by listing the supported verbs and the 10-step limit, but adds nothing about what `session` and `token` are (payment/auth credential, session handle) or where they come from. Baseline 3 for partial coverage where the description only partially compensates.

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 concrete verb+resource ('Act in your rented browser session') and enumerates the exact action vocabulary (goto, click, type, press, scroll, select, wait, back, close), so an agent knows precisely what capability this provides. It implies the session must pre-exist, which differentiates it from a session-starting tool, but it never names its closest siblings (browser_start, page_actions) outright.

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: 'your rented browser session' suggests the session comes from elsewhere (browser_start) and the 10-step cap suggests batching actions per call. There is no explicit when-to-use statement, no named alternative, and no guidance on when to prefer a different browsing/scraping 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 annotations only covering readOnlyHint and openWorldHint, the description adds real behavioral context: a 60-minute session ceiling, a 2-minute idle timeout after each action, and per-call billing of $0.03 USDC via x402. It does not explain failure modes (what happens if payment fails or the session expires mid-flow).

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 core offer, the call-to-action pattern, and the cost/expiry terms are all front-loaded at the point where an agent needs them.

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

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

There is no output schema, so the description usefully enumerates the return payload (session id, screenshot, page text, controls), and it covers cost and lifetime. It omits how payment/authorization is performed and what errors look like, which an agent invoking a paid session-creating tool would want.

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

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

Schema coverage is 33% — only 'url' is documented, and the description merely restates it as optional ('optionally at a URL'). width/height get no explanation in either place, though viewport sizing is inferable from the browser-rental context.

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

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

States a specific verb+resource ('Rent a real Chrome browser'), the scope ('up to 60 minutes'), and what it returns (session id, screenshot, page text, clickable controls). It is immediately distinguishable from the sibling browser_act, which it explicitly routes to for follow-up actions.

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

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

Names the companion tool ('/v1/browser/act') and the sequence (start here, then drive step by step), plus the 2-minute keep-alive window that governs when to act next. It stops short of saying when NOT to rent a browser (e.g., vs scrape/screenshot siblings) or stating prerequisites for 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?

Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds a genuinely important behavioral fact the annotations do not: the $0.004 USDC x402 per-call cost, which an agent must weigh before invoking. It still omits response shape and pagination/limit 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?

One dense sentence with the counts front-loaded, followed by the pricing clause. Nothing is wasted, though the single long sentence packs geography, industry, output measures and pricing into one breath rather than structuring them.

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

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

With no output schema, the description correctly carries the return-value burden by naming the metrics returned, and it covers geography, industry filter and cost. It leaves the zero-required-parameter default behavior and the limit parameter's effect unspecified, a minor gap.

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

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

Schema coverage is 80%, so the schema already documents zip, near, level and industry with examples. The description restates the geography levels and the keyword-or-NAICS industry syntax but adds no new syntax or defaults, so the baseline 3 applies.

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

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

States a specific verb+resource (count businesses) with the exact scope (US county, state or ZIP) and enumerates the returned measures (establishments, employees, payroll, average pay, per-capita business density). An agent can distinguish this from siblings like demographics, economy, or company 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 phrase 'for market sizing and competition checks' gives explicit usage context, which is more than implied. However, it names no alternative tool and states no when-not condition, so it stops short of the top score.

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

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

Annotations already cover the safety profile (readOnlyHint=true, openWorldHint=true), so the description earns credit for adding the paid-call detail ($0.002 USDC via x402), which is genuine cost context. However, it does not disclose that the tool is multi-mode and that the mode is selected implicitly by which parameters are supplied, which is important behavior for a zero-required-param 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?

A single dense sentence, front-loaded with the tool's identity and capability groups, with the cost caveat at the end. The parenthetical lists are long but each element carries information; nothing is redundant.

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

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

For a 10-parameter, three-mode tool with zero required parameters and no output schema, the description omits the most critical thing: how to select a mode and which parameters each mode consumes. The agent cannot reliably construct a valid call from this description plus the sparse 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 40% across 10 parameters, so the description must compensate, and it largely does not. It adds useful category detail (which unit families and date operations are supported) but never explains the core mapping of expr/value/from/to/date/date_op/days/months/years to a given mode, leaving mode selection ambiguous.

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 ('Exact calculator') and enumerates three concrete capability families: math expressions, unit conversion, and date arithmetic. It does not, however, name or differentiate against obvious siblings such as unit_convert, convert, or dates_business_days, so the agent must infer overlap 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?

Usage is only implied by listing capabilities; there is no explicit when-to-use, when-not, or alternative routing despite several siblings covering unit conversion and business-day date math. An agent gets a rough sense of scope but no guidance on choosing this over unit_convert or dates_business_days.

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 safety profile is covered. The description adds genuine non-structured context: a per-call price of $0.004 USDC via x402, which is essential for an agent deciding whether to invoke a paid tool. It still does not disclose image dimensions defaults or synchronous/asynchronous behavior, but the pricing disclosure is a meaningful addition.

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 sentences, front-loaded with the core capability, then the output formats, then pricing. 'Ready to drop into a report or message' is mildly promotional but does convey the intended downstream use, so little is wasted.

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

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

With no output schema, the description carries the burden of stating the return artifact, and it does so (PNG or SVG image). Cost and output format are covered. What is missing for an 8-parameter rendering tool is any guidance on required inputs (0 params are required, which is unusual and unexplained) and size defaults.

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 63%, with width, height, and title undocumented in both places. The description partially compensates by naming chart types, formats, labels, series and legend, and implying 'several series' support, but it gives no syntax or range guidance for the undocumented dimensions and does not explain the pipe-separated value conventions 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+resource (produce chart images) and enumerates the supported chart types (bar, line, pie, scatter) plus output formats (PNG/SVG). An agent can tell immediately this renders charts from supplied numeric data, distinct from generation siblings like image_generate or token_chart, which produce different artifacts.

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 'Ready to drop into a report or message,' which suggests a presentation context but never states when to choose this over alternatives such as token_chart or image_generate. No exclusions or prerequisites are given, so the agent must infer selection.

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

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

With only readOnlyHint/openWorldHint annotations, the description carries the behavioral load and does so richly: it discloses the payment mechanism (x402, no API key), per-token pricing, the $0.002–$0.0053 per-call range, how the 402 quote interacts with 'upto' payers, streaming support, and the 2048 output-token ceiling. None of this is derivable from annotations or schema.

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

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

Well front-loaded with purpose before cost mechanics, and most sentences earn their place because pricing is decision-relevant for a paid endpoint. The closing 'Costs $0.0053 USDC per call (x402)' is redundant with and slightly muddles the earlier 'minimum $0.002 a call, at most $0.0053' statement.

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

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

For a paid, no-output-schema tool, the description covers the request/response contract ('same shape as OpenAI'), auth/payment setup, cost bounds, streaming, and model selection. An agent has enough to invoke it correctly; only edge specifics like rate limits or error-shaped responses are absent.

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 20% (model is the sole described parameter), so the description must compensate, and it does: it explains the model override behavior and the /v1/models list, the upstream output-token cap for max_tokens, streaming support for stream, and that messages follows the OpenAI shape. Only temperature is left to the caller's prior knowledge.

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 ('OpenAI-compatible chat completions on Meta Llama 3.1 8B') plus a use-case qualifier ('fast general chat'). It partially distinguishes itself from the many sibling *_chat_completions tools by noting the model parameter can reach 'any model listed at /v1/models', but it never explicitly says when to choose it over e.g. deepseek_chat_completions or gpt_oss_20b_chat_completions.

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 supplies integration context (set the OpenAI SDK base URL, pay with x402 instead of an API key) and implies usage via 'fast general chat', but gives no explicit when-to-use or when-not-to-use guidance relative to the dozens of sibling chat tools. The model-override note is the only routing hint.

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

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

Goes well beyond the readOnly/openWorld annotations by disclosing the cost model (0.015 USDC per call via x402), the hard cap of 300 chunks, and the exact embedding model and dimensionality. These are real operational facts an agent needs. It stops short of describing failure modes or latency.

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 outcome ('Ready-to-search chunks') and packs model, limits, and pricing into tight sentences with no filler. Slightly dense, but every clause 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 no output schema, the description carries the burden of explaining returns and does so (chunks with offsets + embeddings). Combined with the disclosed chunk cap and cost, an agent has enough to invoke and budget. Edge-case behavior (invalid URL, oversized input) is not covered.

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 60%: embed, overlap, and chunk_size carry descriptions, while url and text do not. The description compensates partially by noting URL accepts pages, PDFs, and Office files and that chunks overlap, but gives no acceptable ranges or defaults beyond what the schema already states.

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 (turns a URL or text into chunks) and details the full pipeline output: overlapping chunks, character offsets, and bge-m3 1024-dim embeddings. It is highly specific about what is produced, but does not explicitly distinguish itself from embedding siblings like embed/embeddings/vectors.

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

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

Implies usage via 'ready for any vector store' and 'in one call,' suggesting it is the combined extract+chunk+embed step. However, it names no alternatives and gives no explicit when-to-use vs when-to-use-something-else guidance despite many closely related siblings (embed, embeddings, scrape, crawl).

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

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

Annotations cover the safety profile (readOnlyHint=true, openWorldHint=true), so the bar is lower. The description adds genuinely useful non-annotation context: the call costs $0.002 USDC under the x402 payment scheme, which an agent must know before invoking. It stops short of describing failure behavior for unresolvable DOIs/URLs or how the external fetch affects latency.

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, front-loaded with the capability and the input/output surface, with pricing immediately after. Slightly promotional phrasing ('a ready reference') costs a little density, 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?

With no output schema, the description should clarify what comes back (a formatted citation string, and whether internal links/DOIs are included), and it should resolve the mutual-exclusivity of the three identifier inputs. For a paid tool with four loosely-specified parameters, those omissions leave real gaps.

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 25% (just the 'style' parameter), which the description partially compensates for by listing the styles and naming the three identifier types. But with zero required parameters, the critical semantics — that doi/url/isbn are alternatives and presumably exactly one must be supplied — are never stated in either place.

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 (format/generate) and resource (citation) and enumerates the output styles (APA, MLA, Chicago, Harvard, IEEE, Vancouver, BibTeX) plus the accepted inputs (DOI, ISBN, URL). However, it never distinguishes itself from the close sibling 'citecheck', leaving the agent to guess which one handles citation formatting vs. citation validation.

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: if you have a DOI, ISBN or URL and want a formatted reference, use this. There is no explicit when-to-use statement, no mention of the 'citecheck' alternative, and no guidance on what to do when an identifier is invalid or unresolvable.

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 genuinely useful non-schema behavior: the verdict taxonomy, the fact that it returns a deciding quote, the 6-citation cap, and the exact cost model ($0.005 + $0.006/citation, $0.041 per x402 call). Remaining gaps are minor (fetch failures, timeouts, paywall handling).

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

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

Front-loaded with the core action and its four verdicts, then cost. One dense sentence plus a pricing sentence, with no filler. The pricing detail is somewhat dense but earns its place because cost is not available in any structured 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?

With no output schema, the description must convey return shape, and it does: per-citation verdict plus deciding quote. Cost, cap, and read-only nature are all covered. The main omission is the unresolved url/claim vs citations invocation model for a 3-param, 0-required 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 only 33% (only 'citations' is documented), so the description has to compensate. It partly does: it explains that claim and url form a cited pair and that 'citations' is JSON [{claim,url}] capped at 6. It never clarifies the ambiguity of three parameters with zero required — whether url+claim are a single-pair alternative to the batch 'citations' array, or must accompany it.

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

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

States a specific verb and resource — reads a cited source and judges whether it supports a claim — and enumerates the exact output verdicts (supported, partial, not supported, contradicted) plus the deciding quote. That is far more specific than the sibling 'cite' or 'links_check', and an agent can tell instantly what this returns.

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 task context is implied ('for each claim and the URL cited for it'), so an agent can infer this is for post-hoc citation verification, but the description never states when to prefer this over the sibling 'cite' or 'links_check', nor any preconditions (e.g. source must be publicly fetchable). Usage is inferable, not 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=true and openWorldHint=true, so safety is covered. The description adds genuinely useful behavioral facts beyond that: the 500-text cap and the $0.01 USDC per-call x402 cost, which an agent must know before invoking. It omits what happens above 500 texts or any latency/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?

Two dense sentences: purpose, scope, output shape, cost and cap, all front-loaded with no filler. Every clause carries information an agent needs.

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

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

With read-only/open-world annotations, no output schema, and full schema coverage, the description supplies what is missing: output fields, the 500-text limit, accepted input format, and pricing. Only edge behavior (over-limit handling, default k) is left implicit.

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

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

Schema description coverage is 100%, so both parameters (k, texts) are already documented in the schema, establishing a baseline of 3. The description adds only the 500-item ceiling for 'texts' and does not explain the '|' delimiter or the auto behavior of k beyond what the schema states.

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 ('Cluster and label') with scope ('up to 500 texts') and a concrete preview of the output ('topics with an AI-written label, size, share and examples'). It is distinguishable from near-siblings like classify or chunk by describing grouping into topics, though it never names those alternatives 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?

Usage context is implied only through example inputs (reviews, tickets, survey answers, search results). There is no statement of when to choose this over classify, dedupe, or chunk, and no prerequisites beyond the implicit cost 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?

Annotations only declare readOnlyHint and openWorldHint, but the description goes well beyond them: streaming support, a hard 2048 output-token cap, per-token pricing with a minimum and maximum per call, the 402-quote semantics, and the fact that 'upto' payers are billed only for tokens actually used. For a metered external call, these cost and limit disclosures are exactly the behavioral context an agent needs before invoking it.

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

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

The purpose and endpoint are front-loaded, which is good, but the pricing is stated twice ('$1.98 per million input and $3 per million output' and again 'Costs $0.0173 USDC per call'), and the 402/'upto' explanation is dense. Some sentences are load-bearing, others repeat.

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

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

With no output schema, the description carries the return-value burden and does so by stating the response shape matches OpenAI and that streaming is supported. Combined with cost, token cap, and payment semantics, an agent has enough to call and interpret the tool, though error/permission behavior beyond the 402 flow 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 only 20% (just the ignored 'model' field), but the description compensates by asserting OpenAI-identical request/response shape and noting the model field is ignored. It still says nothing about max_tokens (though the 2048 cap hints at it), temperature, or the messages structure, so it only partly closes the coverage gap; 3 is the fair baseline here.

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

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

The description names the specific model (Qwen 2.5 Coder 32B) and the intended workload (code generation, review and fixes), which is a concrete verb+resource+scope statement. It distinguishes itself from the many generic chat_completions siblings by being code-focused, but never explicitly names the nearest alternatives such as kimi_code_chat_completions or qwen_chat_completions, so differentiation is inferred 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?

It gives concrete setup guidance (point the OpenAI SDK base URL at the /v1/coder endpoint) and the payment scheme, which implies when to use it. However, there is no explicit when-not guidance and no routing to sibling models, even though the sibling list contains at least one other code-oriented chat 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?

Goes well beyond the readOnlyHint/openWorldHint annotations: it discloses sandbox isolation ('fresh isolated container'), a hard capability limit ('no Internet access'), the return channels (stdout, stderr, exit code), and the cost/payment model (timeout-tiered pricing plus an x402 USDC charge). These are exactly the operational facts an agent needs before invoking a code-execution primitive.

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 purpose, then use cases, then pricing in three tight sentences with little waste. The pricing tail is slightly muddled, however: '$0.02 up to 60 s' and 'Costs $0.02 USDC per call' can be read as two different charges, which invites confusion rather than clarity.

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

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

With no output schema, the description correctly enumerates the returns (stdout, stderr, exit code), and all four parameters are documented in the schema. Minor gaps remain, such as whether any filesystem state persists between calls or concurrency limits, but nothing critical for correct invocation is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: runtime versions and bundled libraries for language, and cost-per-tier for timeout_s that the schema's '1-60, default 10' does not convey. stdin is not elaborated on, so it is not a full 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?

Names a concrete verb (Run) and resource (Python 3.13/JavaScript Node 24/bash in a fresh isolated container) with unusual specificity about runtimes and libraries, so an agent knows exactly what executes. It does not explicitly differentiate itself from near-neighbors like data_run, calc, or devtools, which keeps it short of a 5.

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

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

States the intended use cases ('calculations, data wrangling, parsing and testing snippets'), giving clear context for when this tool fits. There are no explicit exclusions or pointers to sibling alternatives for adjacent tasks (e.g., simple math via calc), so it stops short of a 5.

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

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

Annotations already declare readOnlyHint and openWorldHint, so the read-only nature is covered. The description adds genuinely new behavioral context the annotations lack: the exact per-call cost ($0.005 USDC) and the x402 payment mechanism, which an agent must know before invoking. It still omits how matching works or what a failure/empty result looks like.

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 efficient sentence that front-loads the resource and source before listing fields, with the cost appended as a second clause. No filler, though the field enumeration is dense and the pricing could be its own sentence.

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

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

With no output schema, the description usefully enumerates the returned metrics, which does real work. However, for a 3-parameter tool with 33% schema coverage, the critical omission is parameter meaning — an agent cannot tell whether 'name' is required-and-exact or fuzzy, nor what 'limit' defaults to.

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% — 'name' and 'limit' have no schema descriptions at all, only 'state' does. The description never compensates, discussing only returned data fields rather than what name must contain, what limit controls, or how state filters results.

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 (US college facts) and its authoritative source (Department of Education College Scorecard), then enumerates the exact data fields returned — admission rate, tuition, net price, graduation/retention, earnings, debt. It is unmistakable against the sibling list, which contains no other college-data tool, though it never states an explicit retrieval verb.

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 guidance on when to use this tool versus alternatives, no note that 'name' is a college/institution name, and no indication of how the state and limit parameters interact with results. The only contextual instruction is the per-call price, which addresses payment rather than usage.

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 safety profile is covered. The description adds genuinely non-obvious behavior: it reads a live website (open-world implication), enumerates the return fields, and discloses the $0.01 USDC x402 cost, which is critical pre-invocation context not found in annotations.

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

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

Front-loaded with purpose and mechanism, then a tight enumerated field list, then cost. The field enumeration is long but each item is informative; nothing reads as filler.

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

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

With no output schema, the description correctly compensates by listing the returned fields, and it discloses cost and access mode. It stops short of covering failure behavior (invalid/unreachable domain), which is a minor gap for a single-parameter read tool.

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

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

Schema coverage is 100% with an inline example ('cloudflare.com'), so the schema already documents the sole parameter. The description's 'from a domain' reinforces but adds no new syntax or format detail beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific resource ('Company profile from a domain') plus the mechanism ('reads the website') and enumerates the returned fields, so an agent knows exactly what it gets. It does not explicitly contrast itself with near-neighbors like company_registry or report_company, so full sibling 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?

Usage is implied by the 'from a domain' framing, but there is no explicit when-to-use, when-not-to-use, or named alternative despite many overlapping siblings (company_registry, report_company, uk_company, profile). Adequate but the agent must infer 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?

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds genuinely useful behavioral context beyond the annotations: the data provenance (GLEIF), jurisdiction coverage, and a per-call cost of $0.003 USDC via x402, which an agent needs before invoking a paid endpoint.

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

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

A single front-loaded paragraph that opens with the core purpose, then enumerates outputs, input modes, use cases, and cost. Dense but efficient; the field list is long yet each item earns its place for a registry lookup.

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

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

With no output schema and 4 parameters, the description carries the full burden and discharges it: it names the returned fields, both input paths, the coverage scope, the cost, and the intended use cases. Nothing essential for correct invocation is missing.

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

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

Schema description coverage is 75%, so most parameters are documented. The description adds value by framing the search modes — name (optionally with country) versus LEI — clarifying the two mutually alternative lookups. The 'limit' parameter is left unexplained in both schema and description, a minor 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?

States a specific verb and resource — an official legal-entity registry lookup backed by GLEIF Global LEI Index across 200+ jurisdictions — and enumerates exactly what it returns. An agent can distinguish this from sibling registry tools (uk_company, company, package_registry) without opening the schema.

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

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

Gives clear usage context ('For KYB, compliance and due diligence') and states the two invocation modes (by name with optional country, or by LEI). It does not explicitly say when to prefer this over overlapping siblings such as uk_company or uk_kyb, so routing is left partly to inference.

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

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

Annotations already declare readOnlyHint and openWorldHint, so safety is covered. The description adds genuinely non-obvious operational context: the $0.005 USDC per-call x402 cost and the fact that the two modes hit different upstream services (GovInfo vs Congress.gov). It stops short of covering rate limits, pagination, or behavior when both parameters are supplied.

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 with the resource front-loaded, followed by the two modes and then cost. Every clause carries information; the cost disclosure is last, which is acceptable but slightly less scannable than leading with capability.

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

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

With no output schema, the description enumerates the fields returned in bill-lookup mode, which is the key detail an agent needs. It does not characterize the search-result shape or the meaning of limit, a modest but real gap for a two-mode 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%, and the description compensates for the weakest parts: it explains that q drives full-text search against GovInfo and that bill takes an id like hr1-119, including the format exemplar's meaning. The limit parameter remains undocumented in both schema and description, which keeps this below 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 resource (US Congress bills) and two distinct operations: keyword search of bill text via GovInfo, and bill-id lookup returning named fields. The named output fields (title, sponsor, cosponsors, policy area, latest action) make the retrieval mode concrete and unmistakable.

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 effectively routes between the two modes by naming the parameter that selects each (q for keyword search, bill for detail) and attributing each to its backing source. It does not add explicit when-not-to-use guidance, but no sibling tool overlaps this domain, so exclusions are largely unnecessary.

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 the safety profile is covered. The description adds genuinely non-schema information: a per-call cost of $0.005 USDC settled via x402, which matters for an agent deciding whether to call it. It does not disclose limits such as max source size or how many calls the budget implies.

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: the mechanism and inputs first, the value proposition second, the cost last. No filler and nothing repeated from the schema verbatim.

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

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

With no output schema, the description should carry more of the return-shape burden; 'with source markers' is a hint but not a description of the packed output. Inputs and pricing are covered adequately, but an agent cannot tell how passages are delimited or how the budget is enforced. Adequate but with clear gaps.

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 75%, so the schema already documents the pipe-separated url/text conventions and the default token_budget of 2000. The description restates the same concepts ('long texts or URLs', 'your question', 'token budget') without adding format or constraint detail. Baseline 3 is appropriate.

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

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

States a specific verb and resource: it picks the passages most relevant to a question from long texts or URLs and packs them into a token budget with source markers. That is far more informative than the bare name 'context'. It does not, however, distinguish itself from adjacent siblings like chunk, summarize, rerank, or extract, so an agent must 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?

'Fit more useful context into a prompt for less' implies the use case (preparing prompt context from long sources), which is useful but indirect. There is no explicit when-not guidance and no named alternative among the many compression/retrieval siblings. Usage is implied rather than stated.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds genuinely useful non-structured context: the data source (FPDS) and the paid-access model ($0.005 USDC per call via x402), which an agent must know before invoking. It does not cover pagination or how limit behaves.

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

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

Two sentences, front-loaded with what the tool returns and the data source, followed by the cost caveat. Every clause carries information; nothing is redundant padding.

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

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

With no output schema, the description does the work of describing return fields (amounts, agency, NAICS, dates, descriptions) and discloses the payment requirement. The remaining gap is that limit/pagination behavior is never explained, which matters for a list-style endpoint.

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

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

Schema coverage is 50%: 'q' is documented in the schema and the description restates its scope (keyword, vendor or agency). The 'limit' parameter is undocumented in both schema and description, so the description does not compensate for the coverage gap. Baseline 3 is appropriate.

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

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

States a specific verb+resource: 'US federal contract awards (FPDS)' with 'who won government contracts for a keyword, vendor or agency'. It also enumerates the returned fields (amounts, agency, NAICS code, dates, descriptions), which lets an agent separate it from near-neighbors like grants or company_registry 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?

Usage is implied by the subject matter (query contract award data for a keyword/vendor/agency), but there is no explicit when-to-use, when-not-to-use, or alternative named among the many siblings (grants, contract_inspect, report_contract_audit). The agent must infer the boundary itself.

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

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

Annotations cover the safety profile (readOnlyHint=true, openWorldHint=true), and the description goes beyond them with two operationally important facts an agent must know before calling: the 1 MB payload ceiling and the $0.002 USDC x402 charge per call. It also promises 'a list of every error' on validation failure, which sets expectations for failure output. It stops short of describing what a successful result looks like.

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

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

A single front-loaded sentence carrying formats, optional validation behavior, size limit, and price, with essentially no filler. The clause stacking makes it slightly dense to parse, but every clause contributes information an agent needs.

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

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

For a 4-parameter, no-output-schema tool with 50% schema coverage, the description supplies the missing format vocabulary, the size cap, the pricing/auth signal (x402), and the validation-error behavior. The main remaining gap is the shape of the returned converted payload, which no structured field covers.

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 50% (only 'from' and 'schema' are documented), so the description must compensate. It does: enumerating the five supported formats clarifies the undocumented 'to' parameter, and 'typed CSV values' plus 'Optional JSON Schema' add nuance about the schema parameter's role. The 'data' parameter's expected encoding (inline string, since the 1 MB limit is inline) is still left implicit.

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 (convert) plus the exact resource domain (CSV, TSV, JSON, XML, YAML) and adds a secondary function (JSON Schema validation), which cleanly separates it from unit_convert, doc_convert, and media_convert in the sibling list. It does not, however, explicitly name any sibling or state the boundary against them, so the differentiation is implicit 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?

Usage is only implied: an agent can infer 'use this when you need to move structured data between text formats,' and the phrase 'optionally validate ... against a JSON Schema' hints at when the schema parameter applies. There is no explicit when-to-use, when-not-to-use, or alternative-tool routing, so it stays at the minimum-viable level.

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 100-page cap, robots.txt compliance, the exact return fields (URL, title, text), cost structure, and the behavioral difference store=true causes (7-day share link instead of inline data). This is exactly the kind of operational context annotations cannot carry.

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

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

Front-loaded with purpose and scope, then options and cost. Dense and mostly waste-free, though the two pricing statements ('$0.005 + $0.001 per page' and 'Costs $0.025 USDC per call') read as partially redundant and slightly muddled rather than crisply separated.

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

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

With no output schema, the description steps in to name the returned fields, and it covers the limit, compliance behavior, and the store toggle plus pricing. An agent has everything needed to call it correctly and anticipate the response shape.

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: store=true changes the return channel rather than just 'return a link', and it frames path_prefix and the page cap in behavioral terms. The added value over the schema is genuine though modest.

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 (crawl) and resource (a website) with the output form (clean Markdown) and scope rules (same-site links, up to 100 pages, robots.txt). Very clear what the tool does, but it never names a sibling like scrape or sitemap to draw the boundary between single-page and site-wide extraction.

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 scope rules ('follows same-site links from a start page', 'up to 100 pages') imply when this multi-page tool fits versus one-shot extraction, and the store=true line explains an option's purpose. However, there is no explicit when-to-use/when-not statement or named alternative, so the agent must infer the routing decision.

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 safety profile is covered. The description adds genuinely non-obvious context: the paid x402 model at $0.003 USDC per call, plus hard ceilings of 50 coins and 10 currencies. It stops short of return/pagination details, but the cost disclosure is the important behavioral fact here.

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 tightly packed sentences, front-loaded with what the tool returns, then how to call it, then the cost. No filler and no redundancy with 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?

With no output schema, the description compensates by naming the returned fields and the billing model. It is essentially complete for a two-parameter read tool, with only minor gaps around failure modes and whether symbol ids are case-sensitive.

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

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

Schema coverage is 100%, so baseline is 3, but the description goes beyond the schema by supplying accepted symbol formats (btc, eth, sol), alternative CoinGecko ids, example currencies (usd, cad, eur) and per-call limits — none of which appear in the schema's terse property descriptions.

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

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

States a specific verb+resource ('Live crypto prices') and enumerates the returned fields (24h change, market cap), which is more than a restatement of the name. It does not, however, distinguish itself from close siblings such as token_price, crypto_movers, or crypto_candles, so an agent must infer the boundary 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?

The description explains how to invoke it ('Pass symbols (btc,eth,sol) or CoinGecko ids') but gives no when-to-use/when-not guidance and never names an alternative such as crypto_candles for historical data or crypto_movers for rankings. Usage is implied by the resource, not by any routing rule.

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 announces write operations – 'create tables, insert, update' – and state that 'persists between calls', while annotations declare readOnlyHint=true. Those are directly in conflict, which is the rubric's condition for a 1. The rich quota/cost/batch-limit detail it does add (200 MB, 20 statements, $0.003 USDC) cannot offset the contradiction.

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 front-loaded sentence that opens with 'Your own private SQLite database that persists between calls', then colons into capability, limits and price. Dense with no filler, though the pricing clause could have been separated rather than strung into the same sentence.

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

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

With no output schema and a 3-parameter surface, the description covers what an agent most needs: persistence semantics, wallet keying, batch cap, storage quota and per-call cost. It omits return/result shape and multi-statement transaction/atomicity behavior, which are the remaining gaps.

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% (`sql` and `params` carry no descriptions), so the description must compensate. It does partially: 'up to 20 SQL statements per call (parameters supported)' explains the batch limit and parameter binding that the schema leaves implicit. It still never clarifies how the single `sql` field relates to the `statements` array, so it is adequate but incomplete.

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 set and resource: 'Your own private SQLite database that persists between calls... create tables, insert, update and query'. The persistence model and wallet-keying are clear. It does not differentiate itself from the sibling `sql` (or `sql_generate`/`storage`), so it stops short of a 5.

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

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

Gives operational constraints (up to 20 statements per call, 200 MB per wallet, $0.003 USDC per call) that shape usage, so usage is implied. But it never states when to choose this over the sibling `sql` tool or when not to use it, and no preconditions (schema creation order, wallet funding) are spelled out.

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

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

Adds real behavioral context beyond the readOnlyHint/openWorldHint annotations: the x402 payment mechanism, the 402 max-quote semantics, upto-payer billing, a minimum/maximum per-call cost, and the 8192 output-token cap. This is genuinely useful for an agent, marred only by pricing stated twice and slightly inconsistently ('at most $0.0740' vs 'Costs $0.0740 USDC per call').

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

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

Front-loaded with the core identity and capability, then payment details, which is the right ordering. It runs long and repeats the per-call cost, so one sentence could be trimmed, but nothing is deeply wasted.

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

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

For a chat-completions tool with no output schema, the description covers identity, compatibility, capability set (tool calling, reasoning, streaming), token limits, and the full payment flow. What it omits—per-parameter semantics—is mostly recoverable from the stated OpenAI compatibility, so it is close to complete.

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

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

Schema coverage is low at 33% and the description never explains messages, temperature, max_tokens, stream, or tools directly. It does partially compensate by asserting 'Same request/response shape as OpenAI', which lets an agent map the parameters to known OpenAI semantics, but that is the only semantic contribution.

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 (chat completions) on a named, distinct model (DeepSeek V4 Flash) and immediately contrasts it with its siblings by calling out its speed/price profile and 1M-token context. An agent can distinguish it from deepseek_pro_chat_completions and the other *_chat_completions tools without opening the schema.

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

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

The description implies when to reach for this tool (fast, inexpensive, OpenAI-compatible) and how to wire it up (set the SDK base URL, pay via x402), but never explicitly says when to choose it over deepseek_pro_chat_completions or the generic chat_completions. Usage context is present but left to inference.

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

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

Annotations (readOnlyHint, openWorldHint) only say it's a read-only networked call; the description goes well beyond by disclosing the auth model (x402 payment instead of an API key), rate/cost behavior ($2.64/M input, $7.92/M output, min $0.002, cap $0.2178), how the 402 quote is computed, and the 8192-output-token ceiling. Minor deduction: the closing sentence 'Costs $0.2178 USDC per call' contradicts the earlier metered-with-minimum pricing, which could mislead an agent about cost.

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 opening sentence is well front-loaded, but the cost model is restated three times (per-token rates, the 'at most $0.2178' cap, and then a flat '$0.2178 USDC per call'), which is redundant and, in the last case, inconsistent. Trimming the repeated pricing would make it noticeably tighter.

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 chat-completions endpoint with no output schema, the description covers the essentials an agent needs: model identity, OpenAI response shape, token ceiling, streaming/tool-calling support, and payment mechanics. Only the payment/activation flow (how x402 settlement actually happens client-side) and the sibling-selection question are left 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?

With only 33% schema description coverage, the description compensates by anchoring the whole request to OpenAI's well-known shape ('Same request/response shape as OpenAI'), which defines messages, temperature, tools and stream semantics, and it explicitly states the 8192 output cap and the x402 pricing tie-in. It adds little on `model` (already documented as ignored in the schema) but overall it covers most of the six parameters adequately.

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?

It names a specific verb and resource (OpenAI-compatible chat completions) and pins the exact model plus its capabilities (reasoning, tool calling, 1M-token context). However, it never distinguishes itself from the very close sibling `deepseek_chat_completions` (or the other `*_chat_completions` siblings), so the agent must infer which DeepSeek endpoint to pick.

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

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

The description gives operational setup (point the OpenAI SDK at the given base URL, pay per token via x402 instead of an API key), which implies how to call it. It stops short of explicit when-to-use guidance: there is no statement about which tasks warrant this model over `deepseek_chat_completions`, `coder_chat_completions`, or the cheaper variants.

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 safety is covered. The description goes beyond them by disclosing the per-call cost and payment mechanism ($0.002 USDC via x402) plus the fact that a chain rank is returned, which is genuinely non-obvious operational context. It stops short of stating behavior for a zero-argument 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 tight sentences with the core capability front-loaded and the cost disclosure trailing. Nothing is wasted, though cramming resource, rank, and pricing into one sentence slightly muddies the 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?

With no output schema, the description carries the return burden and does mention TVL plus chain rank, which is adequate for a two-optional-parameter lookup. It omits what an all-empty call returns and whether both inputs can be combined, a minor gap for this complexity level.

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 100% schema description coverage, the schema already documents both parameters, including the DefiLlama slug format. The description restates example values rather than adding constraints (e.g. slug casing, that both are optional and how they combine), so the baseline 3 applies.

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

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

It states a concrete resource (total value locked), enumerates examples for both entity types (aave, uniswap / Base, Ethereum), and notes the returned chain rank. However, it never distinguishes itself from the many neighboring DeFi tools (defi_protocols, defi_chains, defi_yields), leaving an agent to infer why TVL specifically belongs here rather than there.

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 or when-not-to-use guidance and no named alternative; 'and/or' merely hints that either input is acceptable. An agent gets no routing signal versus defi_chains or defi_protocols, which likely cover overlapping 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 establish readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds genuinely useful behavior beyond that: the returned fields (base + reward APY, 30-day mean APY, TVL, IL risk, link) and a per-call cost of $0.0028 USDC via x402, which is important for an agent budgeting calls. It omits freshness/latency and pagination 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?

Three compact clauses: scope, capabilities, return/cost. It is front-loaded on the resource and maximum density with no filler sentences.

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

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

With no output schema, the description correctly compensates by listing return fields, and it discloses the x402 cost. For a 7-parameter, all-optional read tool this is nearly sufficient; only freshness/rate-limit context and a note on the limit parameter are missing.

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

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

Schema description coverage is already 86%, and the description still adds meaning by enumerating the filterable dimensions (chain, protocol, token symbol, stablecoin-only, minimum TVL) and both sort modes. Only 'limit' is left unaddressed, but the baseline for high coverage is 3 and this description clearly exceeds it.

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

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

The description names a specific resource (DeFi yield pools, 16,000+ of them) and its differentiators (APY base+reward, 30-day mean, IL risk), which conceptually separates it from defi_tvl, defi_fees and defi_dexs. However, it never explicitly names or contrasts with those siblings, which share overlapping filter dimensions like chain and protocol.

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: the filter list and 'sort by APY or TVL' suggest this is for finding top-yielding pools, but there is no explicit when-to-use, no when-not-to-use, and no pointer to alternatives such as defi_tvl or staking_rates. The cost note is helpful but is not usage guidance.

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

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

Annotations already cover the safety profile (readOnlyHint, openWorldHint), but the description adds genuinely useful behavior: the authoritative data source (Census ACS 5-year) and a paid access model ($0.003 USDC per call via x402), which an agent must know before invoking. It stops short of noting failure behavior for invalid or non-US ZIPs.

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, zero filler. Resource and scope come first, followed by the metric enumeration and pricing; the metric list earns its place because there is no output 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?

For a one-parameter read lookup with no output schema, the description covers the resource, source, returned fields, and payment requirement. Remaining gaps are minor: response shape/units and error behavior on invalid ZIPs.

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 'zip' parameter is already documented as a 5-digit ZIP, so the baseline is 3. The description restates the ZIP keying but adds no format edge cases (non-US, leading zeros) beyond the schema.

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

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

States a specific verb-resource pair ('US demographics by ZIP code') plus the underlying source (Census ACS 5-year) and an enumerated payload. The ZIP scoping implicitly separates it from demographics_area, but the sibling is never named, 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?

Usage is only implied: the ZIP-keyed input and metric list tell an agent this is the tool for ZIP-level US demographic lookups. There is no explicit when-to-use, when-not-to-use, or pointer to demographics_area for non-ZIP granularity.

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 the safety profile is covered. The description adds genuinely non-schema information: the call costs $0.005 USDC via x402, which is material to an agent deciding whether to invoke it, plus the US-only coverage constraint. It stops short of describing latency or failure behaviour.

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

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

Front-loads the core purpose, then the metric list, then the price. The long metric enumeration is justified because there is no output schema, so it is the only signal of what is returned. Only minor redundancy in restating geographic levels twice.

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

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

With no output schema, enumerating the metrics is the right call and makes the return value reasonably predictable. However, with four parameters, zero required, and only 50% schema coverage, the description leaves input semantics (address vs lat/lon, defaults, how level interacts with the request) 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?

Schema coverage is 50%: 'level' and 'address' are documented, but 'lat' and 'lon' have no descriptions anywhere. The description echoes the level enumeration (tract, city, county, state, national) and states that an address or place is accepted, but never clarifies lat/lon usage or that all four parameters are optional with 'level' defaulting to all.

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

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

States the resource (demographics), the geographic scope (any US address or place at tract/city/county/state/national level) and enumerates the returned metrics, so the agent knows exactly what comes back. It does not, however, distinguish itself from the sibling tool 'demographics', which an agent must still disambiguate on its own.

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 phrase 'in one call' hints that a single invocation covers all levels, but there is no explicit when-to-use guidance, no statement of when another tool (e.g. the sibling 'demographics') is preferable, and no guidance on choosing address versus lat/lon. An agent gets only implied usage.

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 the safety profile is covered. The description adds a genuinely important behavioral fact beyond the structured fields: each call costs $0.002 USDC via x402, which is decision-relevant metering information. It does not, however, say anything about per-op failure behavior or that individual operations are deterministic and side-effect free.

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 with no filler: the capability list is front-loaded and the pricing note trails it. The enumeration is long but each item is a distinct operation, so the length is justified rather than padded.

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 19-operation, 7-parameter tool with no output schema, the description does not say what any operation returns — e.g. whether json_validate yields a boolean or a diagnostics object, what format the hash or password takes, or how regex_test reports matches. The operation list tells the agent what it can ask for but not what it gets back, which is the main completeness gap.

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

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

Schema description coverage is 57%: op has a full enum-like description, and count/length/pattern are annotated, but min, max and input are bare. The description restates the operation list (reinforcing op semantics) and mentions 'secure random numbers', hinting at min/max as a range, but never explains those parameters or what input means per op. It therefore only partially compensates for the uncovered parameters.

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

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

The description enumerates the concrete operations clearly (hashing, encode/decode, JWT decode, JSON validate, UUID, random, regex, slugify, word count, timestamp) and the schema's op parameter names each one, so the agent knows exactly what resource family this covers. However, it never distinguishes itself from single-purpose siblings that already exist (jwt_decode, json_validate, regex, text_slugify, text_stats, timestamp, random, random_password, encode), leaving the agent unable to tell why it should pick this bundle over 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?

There is no when-to-use guidance, no exclusions, and no mention of the many overlapping siblings. Given that jwt_decode, json_validate, regex, timestamp, text_slugify, random and random_password all exist as separate tools, the absence of any routing rule is a real gap rather than a minor omission.

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 behavior beyond the readOnly/openWorld annotations: crawl cap of 50 pages, a 7-day index lifetime, index reuse for repeat questions, and citation of source pages. It does not state failure modes (e.g., unreachable site) or latency, but the operational traits disclosed are substantial.

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 opening sentence is well front-loaded and dense, but the pricing is stated three times with inconsistent framing ('$0.03, or $0.05 above 25 pages. Costs $0.05 USDC per call (x402)'), which is redundant and slightly confusing. Redundancy costs it clarity.

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

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

For a crawl-and-answer tool with no output schema, the description covers cost, scope, indexing, reuse, and citation, which is enough to invoke it correctly. Minor gaps remain around error handling and what 'cites the pages' looks like structurally.

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 75% and the schema already documents site, refresh, and max_pages (including the 1-50/default 25 range). The description adds the 50-page ceiling context and the 7-day reuse window, but 'question' remains undocumented in both places. Baseline 3 is appropriate given the schema does most of the work.

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 (ask a question) and resource (any website or documentation), and describes the mechanism (crawl, index, search, cite). It does not explicitly differentiate itself from close siblings like 'ask', 'answer', 'video_ask', or 'vision_ask', leaving the agent to infer this is the docs/site-specific variant.

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 have a question about a website or docs site) and notes that later questions reuse the index, which helps multi-turn usage. But it never states when NOT to use it or names alternatives despite many overlapping siblings (ask, answer, crawl, scrape), so routing between them is left to inference.

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

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

Annotations already establish readOnlyHint and openWorldHint, so the safety profile is covered. The description adds real behavioral context beyond them: a hard 25 MB input cap, the accepted output format (Markdown), the two mutually exclusive input modes, and an explicit per-call cost of $0.01 USDC via x402 — the last being important for agent budgeting and rarely surfaced elsewhere.

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, front-loaded with the core verb and supported formats, followed by the input contract and cost. The format enumeration is information-dense rather than padding, and no sentence restates the title or wastes tokens.

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 readOnly/openWorld annotations present and no output schema, the description carries only part of the burden, and it does so well: it states the output format, input modes, size cap, and cost. It stops short of noting failure modes (bad URL, unsupported format, page limits) or routing to sibling converters, which keeps it just under complete.

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

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

Schema description coverage is 100% and each of the three parameters is documented in-schema, so the baseline is 3. The description reinforces the url-vs-base64 alternation and the filename pairing rule and adds the 25 MB limit, but it introduces no syntax, format, or edge-case detail the schema does not already 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?

Strong specific verb+resource: converts an enumerated set of document formats (PDF, docx, xlsx, ODS/ODT, CSV, HTML, XML, images) into clean Markdown. An agent immediately knows what the tool produces. However, it never distinguishes itself from close siblings in the same namespace (doc_convert, office_convert, convert, pdf_tools, ocr), so it falls short of a 5.

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

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

It gives concrete invocation mechanics — 'Send a public file URL or base64 file plus filename (max 25 MB)' — which is genuinely useful. But it offers no when-to-use/when-not guidance and never names an alternative sibling (doc_convert, office_convert, ocr), so selection between similar tools is left entirely to inference.

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

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

The annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered, and the description adds genuinely useful disclosure the annotations do not carry: a per-call price of $0.003 USDC via x402, plus the underlying data sources (RDAP/WHOIS, DNS, HTTPS probe). It omits what happens on a non-existent/unregistered domain and any rate or failure behavior, 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?

A single sentence, front-loaded with the purpose then the return inventory, closing with the cost. No filler or restatement of the tool name.

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

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

There is no output schema, so the enumeration of returned fields is doing necessary work and is reasonably thorough; the cost is also disclosed. It stops short of describing the response shape or behavior for unavailable domains, so an agent still lacks a little 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?

One parameter with 100% schema description coverage ('e.g. example.com'), so the schema carries the burden. The description adds nothing about the domain argument — e.g. whether a subdomain, IDN, or bare name is accepted — so the baseline 3 applies.

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

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

States the verb and resource ('Domain lookup') and then enumerates the specific data returned: availability, registrar, created/expiry dates, nameservers, A/AAAA/MX/NS/TXT records, and HTTPS reachability. This makes it distinguishable from the narrower 'dns' sibling in practice. It falls short of a 5 because no sibling (dns, domain_audit) is named or explicitly ruled 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?

No when-to-use condition, no prerequisites, and no alternatives are offered ('use dns for records only, domain_audit for a full audit' would be the natural routing). The only practical guidance is the cost line, which is cost transparency rather than usage guidance.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds material context the annotations do not: this is a paid call at $0.005 USDC via x402, and the response includes a grade and remediation steps. It stops short of noting rate limits or what happens on an unresolvable domain.

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, zero filler, and the scope is front-loaded before the cost constraint. The long check list is dense but every item conveys distinct scope 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, single-parameter tool with no output schema, the description covers purpose, deliverable, and the payment requirement, so an agent can call it correctly. Only the accepted domain format and edge-case behavior (invalid/unreachable domains) remain 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?

There is one parameter, 'domain', with 0% schema description coverage and no clarification in the description about expected format (bare domain vs URL vs subdomain). The parameter is largely self-evident from the tool name, which mitigates but does not fully compensate for the 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?

States a specific verb+resource ('Domain and email security audit') and then enumerates the exact checks performed (SPF, DMARC, DKIM, MX, DNSSEC, CAA, HTTPS, HSTS, headers, redirect) plus the deliverable (a grade and fixes). That enumeration clearly separates it from generic siblings like domain, dns, certs, or report_domain.

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, no exclusions, and no named alternative for overlapping tools such as dns, http_inspect, or report_domain. The only selection-relevant hint is the cost note, which tells the agent it is not a free call but not when it is the right call.

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), so the bar is lower, and the description adds genuinely non-structured behavior: a per-call charge of $0.005 USDC via x402. It also discloses what data categories come back. It does not say what happens for an unknown drug name or whether multiple brand/generic matches are returned.

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 tightly packed sentence: purpose and source first, then the returned content, then the cost caveat. No filler, no redundancy, and the paid-call detail is placed last where it does not obstruct 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?

With no output schema, the description carries the burden of describing returns, and it does so by listing label sections, side effects and recalls. The x402 payment cost is also disclosed. Only edge-case behavior (no match, partial data, rate limits) is 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?

There is one parameter with 100% schema description coverage, and the schema already documents it as 'Brand or generic name'. The description repeats essentially the same phrase, adding no new syntax, format, or matching semantics, so the baseline of 3 applies.

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

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

The description names a specific resource and source ('Drug information from openFDA') and enumerates the exact payload (label sections, side effects, recalls), so the agent knows precisely what it gets. It does not, however, differentiate itself from the sibling 'recalls' tool, which overlaps on the recalls portion, so it falls short of the top band.

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: the enumeration of label fields, side effects and recalls signals when an agent would want it, and 'for a brand or generic drug name' hints at the accepted input. There is no explicit 'use this instead of X' or when-not guidance, and the overlap with the 'recalls' sibling is left unresolved.

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 adds genuinely new behavioral context: an explicit per-call cost ($0.005 USDC via x402) and per-indicator data provenance (IMF vs World Bank vs ECB), which materially affects whether an agent should call this or a free sibling.

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 that front-loads the resource and indicator coverage, then appends provenance and cost. Every clause carries information; it is long but not padded, and the cost detail is placed last where it is easy to find.

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 data-retrieval tool with no output schema, the description lists available indicators but says nothing about the return shape, units, or how results are keyed by year. The cost note and source attribution are helpful, but the missing explanation of from/to and output format leaves a real gap.

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

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

At 50% schema coverage, the schema documents 'country' (ISO code) and 'indicators' (comma list) while the description adds useful provenance mapping (e.g., interest rates/exports/FDI from World Bank, policy rate from ECB). However, the 'from'/'to' parameters are undocumented in both schema and description, and the description never says they are years or how the range behaves.

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 (macroeconomic indicators), enumerates the core indicators, and names the data sources (IMF WEO with forecasts, World Bank, ECB), so an agent knows exactly what domain this tool covers. The phrase 'for any country' implicitly contrasts it with the US-scoped sibling macro_us, though it never names that sibling.

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: 'for any country' suggests this is the general-purpose macro tool versus country-specific siblings like macro_us or labor, and the mention of forecasts hints at forward-looking use. There is no explicit when-to-use/when-not-to-use statement or named alternative, so the agent must infer 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?

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered by structured data. The description adds genuinely new operational context: the per-call price ($0.0035 USDC) and the x402 payment requirement, which an agent must know before invoking. It does not disclose rate limits or failure behavior, 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?

Three short sentences, front-loaded with what is checked, then when to use it, then cost. Every sentence earns its place with zero padding.

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

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

For a single-input tool with no output schema, the description covers the checks performed, the use case, and the payment model. It would be slightly more complete if it hinted at the result shape (booleans vs. score) or deliverability semantics of the flags returned.

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

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

Only one parameter exists and its schema description coverage is 0%, so the description must carry the burden. "Verify an email address" implies the input is an email string, but there is no guidance on accepted formats or edge cases. Baseline 3 for a single-parameter tool with the implicit naming.

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

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

States a specific verb+resource and enumerates exactly what the verification covers (syntax, MX lookup, disposable/role flags), so the agent knows the deliverable. It does not differentiate from the sibling email_analyze, which is the only thing keeping this below 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?

"Use before sending or storing an address" gives a clear triggering context for the tool. It stops short of naming exclusions or pointing at alternatives such as email_analyze, so it is clear context without 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?

Annotations already establish readOnlyHint=true and openWorldHint=true, which the description does not contradict. Beyond that, it adds genuinely useful behavioral facts: a 100-text batch cap, fixed/flat pricing, and an explicit per-call cost under x402. It stops short of rate limits or truncation behavior for oversized inputs.

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, front-loaded with capability, model, and dimensions, followed by limits and cost. The pricing sentence is somewhat redundant in restating price twice ('one flat price' then explicit token math and per-call USDC), which is the only slack.

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

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

With no output schema, the description usefully discloses the output dimensionality (1024) and model, covering the main return-value question. The remaining gap is parameter selection between 'text' and 'texts' and any note on input size limits beyond count.

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

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

Schema description coverage is 50%: 'texts' is documented ('Up to 100 texts') but 'text' is bare, and the description does not explain the relationship between the single-text and batch parameters. With zero required parameters, the description should clarify which one to pass and how they interact; the 100-text limit is the only added meaning, so the baseline 3 fits.

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: text embeddings for semantic search and RAG, with model identity (BGE-M3), dimensionality (1024), and multilingual support. However, it never differentiates itself from the near-identical sibling tool 'embeddings' (nor from 'vectors'/'rerank'), which is a real ambiguity given the catalog.

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

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

Use cases ('semantic search and RAG') are implied, but there is no explicit when-to-use guidance and no mention of the sibling 'embeddings' tool that appears to do the same thing. An agent has no basis for choosing between embed, embeddings, vectors, or rerank.

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, and the description goes well beyond them: it discloses the auth model (no API key, paid per request via x402), the batch ceiling (up to 100 inputs per call), the concrete cost ($0.143 USDC per call), and the response shape (matches OpenAI /v1/embeddings). Cost, auth and batch limits are exactly the 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?

Purpose is front-loaded in the first sentence and the paragraph is dense with usable facts. There is mild redundancy in the pricing sentences ('flat price' followed by 'priced by size and model'), which slightly muddies the cost model, but overall little 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?

There is no output schema, but the description compensates by stating the response shape is identical to OpenAI /v1/embeddings, and it covers auth, batch size, and cost. For a single-purpose, 100%-documented 3-parameter tool this is nearly complete, with only the 'flat price' vs 'priced by size' tension left unresolved.

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

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

Schema description coverage is 100%, so all three parameters are already documented in the schema (including that `model` is ignored and `encoding_format` accepts base64). The description largely restates these facts rather than adding new syntax or format meaning, so the baseline of 3 applies.

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

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

The first clause states a specific verb+resource: an 'OpenAI-compatible embeddings endpoint', with the backed model (bge-m3), dimensionality (1024) and language coverage (100+). It is clear what the tool does, but it never distinguishes itself from the sibling `embed` (or `vectors`/`rerank`), leaving the agent to guess which embedding tool to pick.

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 implied through the integration mechanics ('point any OpenAI SDK at https://agents.citiviewgroup.com/v1') and the pricing model, so an agent understands how to call it. However, there is no explicit when-to-use guidance, no when-NOT-to-use exclusions, and no comparison against the clearly related `embed` sibling.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safe-read profile is covered. The description adds a genuinely useful non-structural fact – a $0.004 USDC per-call x402 cost – but says nothing about pagination, units, or how far back data goes, which matters for a series tool with no output schema.

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

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

Two sentences, front-loaded with the data scope and ending with the cost, with no filler. The indicator listing is dense but each item earns its place; only minor tightening is possible.

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, no-output-schema data tool the safety and cost picture is adequate, and the covered series are named. Gaps remain: the 'points' parameter is unexplained, and there is no differentiation from the electricity/gas/mix siblings an agent is likely weighing.

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%, near the baseline threshold. The description maps 'indicator' values to the covered series and ties 'state' to residential electricity, but 'points' (presumably history depth) is undocumented in both the description and the schema, leaving one parameter opaque.

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 (retrieves) and resource (US energy prices from the EIA) and enumerates the covered series: gasoline, diesel, WTI, Henry Hub gas, crude inventories, and state electricity prices. It is clear what the tool returns, but it does not distinguish itself from overlapping siblings like energy_electricity_prices, energy_gas_prices, energy_mix, or energy_forecast.

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 never states when to use this tool versus its numerous siblings, several of which cover the exact same series (electricity prices, gas prices). No prerequisites, exclusions, or alternatives are given; the agent must infer routing 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?

Annotations only cover read-only and open-world characteristics, but the description adds a genuinely important behavior not in structured data: a $0.002 USDC per-call charge under x402. It also describes the return arrangement (ranked cheapest first, 12-month change, US average), which no output schema supplies. Rate limits and failure modes remain undisclosed.

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 that front-loads the resource and coverage, with cost last. Nothing is wasted, though the parenthetical sector list and the cost clause make it slightly congested for one sentence.

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

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

For a two-parameter read-only tool with no output schema, the description covers coverage, units, sorting, comparative fields and the billing requirement. It is near-complete; only tiered/error behavior and how the free vs paid boundary works are 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%, so both parameters are already documented in the schema; the description only echoes the sector vocabulary and the 'every US state' scope. It adds no syntax, default or filtering nuance beyond the schema, so the baseline of 3 applies.

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

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

States a specific resource (electricity prices), scope (every US state, latest month), granularity options (residential/commercial/industrial/all), unit (cents per kWh) and ordering (cheapest first). It is easily distinguished from the adjacent energy_gas_prices and energy_mix siblings, which cover different resources.

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 the tool is useful (state-level retail electricity rate comparison for the latest month) but names no alternatives or exclusions, so an agent must infer whether to pick this over energy_gas_prices, energy_mix or energy_forecast from names 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?

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds genuinely non-obvious operational context: a $0.003 USDC per-call x402 charge, which affects whether an agent should call it speculatively. It stops short of return format or rate limits, but the cost disclosure is real added value.

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

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

One sentence, front-loaded with the source and coverage, then the horizon, then the cost. No filler; every clause (source, commodities, horizon, latest actual, 12-month change, price) carries information an agent needs.

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

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

With no output schema, the description carries the return-shape burden and does so: monthly series plus latest actual and 12-month change. Read-only safety comes from annotations and cost is stated, so the only thin spot is history_months, which is a minor gap for a 0-required-param 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 50%: the indicators parameter is documented in-schema, and the description enumerates the same commodity list, adding little. history_months has no description anywhere, and the '12-24 months' horizon only loosely hints at its meaning. Baseline 3 is appropriate given the split 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 with scope: an EIA Short-Term Energy Outlook price forecast covering gasoline, diesel, WTI, Brent, Henry Hub gas and residential electricity over a 12-24 month horizon. The 'forecast' framing cleanly separates it from the sibling price tools (energy_electricity_prices, energy_gas_prices, energy), which read actuals rather than projections.

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 makes the use case (forward-looking price outlook) obvious by implication, but never states when to prefer it over the spot-price siblings or any exclusions. An agent must infer the routing decision from the word 'forecast' 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?

Annotations already establish this is a safe read (readOnlyHint) on an open-world data source. The description adds genuinely non-derivable behavior: the $0.002 USDC per-call x402 payment requirement, which materially affects whether an agent should invoke it. It still omits return shape, freshness guarantees and any rate limits, so it is not a full 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?

A single front-loaded sentence that states resource, scope and price up front, with the city list illustrating coverage rather than padding. Slightly long enumeration, but every element earns its place as scope definition.

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 one-optional-parameter, no-output-schema tool, the description covers what is returned conceptually (national/regional/state/metro values with weekly change) and the cost of calling it. Freshness cadence and coverage caveats are the only real gaps.

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 'grade' parameter with its default and allowed values, so the schema carries the semantics. The description's 'gasoline or diesel' only loosely gestures at the grade dimension and adds no format or default 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 resource and scope: this week's gasoline/diesel prices with national, PADD, state and metro breakdowns, plus weekly change ranking. That is far more precise than a generic 'energy prices' tool, and 'gasoline or diesel' implicitly separates it from energy_electricity_prices. However, it never names a sibling (e.g. gas, energy_electricity_prices, energy_mix) to route the agent 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?

Usage is only implied: the weekly framing signals this is the tool for current pump prices, but there is no statement of when to prefer it over the sibling 'gas' or 'energy_electricity_prices' tools, and no exclusions or prerequisites beyond the cost note. Minimum-viable guidance.

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

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

Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds meaningful behavioral context beyond that: the $0.003 USDC per-call cost via x402, the geographic scope, and the exact content and comparison basis of the response. It does not mention rate limits or response shape beyond the field list.

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, front-loaded sentence covering resource, scope, output fields, and cost; nothing is wasted. The parenthetical fuel list is slightly verbose but useful for scoping expectations.

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

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

With no output schema, the description carries the return-value burden and does so by enumerating the metrics returned (GWh, share by fuel, renewable/carbon-free share, five-year delta). Combined with the cost note and scope, an agent has enough to call it correctly; only pagination/format details are absent.

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 parameter is self-documenting ('State name or code; omit for the US'). The description reinforces the default behavior by stating 'any US state or the whole US', adding a small amount of clarity 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 resource and scope: 'Electricity generation mix for any US state or the whole US', plus the exact units (gigawatt-hours) and breakdown dimensions (share by fuel, renewable and carbon-free share, five-year comparison). An agent can tell this apart from energy_electricity_prices or energy_forecast by content, though no sibling is named 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?

Usage is implied rather than stated: an agent can infer this answers generation-mix questions, and the cost line hints at a paid call. There is no explicit when-to-use/when-not guidance or routing to alternatives such as energy, energy_electricity_prices, or energy_forecast.

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 behavior, so the bar is lower. The description adds genuinely non-structured context: the payable cost ($0.002 USDC per call, x402) and that returned record types include avatar, url, twitter and description. It does not mention rate limits or failure behavior for unregistered names.

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

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

A single front-loaded sentence that packs purpose, both directions, sample inputs, and price with no filler. Slightly dense, but every clause earns its place.

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

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

No output schema exists, and the description compensates by naming the record fields returned and the payment mechanism. The one real gap is sibling disambiguation against ens_profile, which the description should arguably own given the near-identical naming.

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 there is only one parameter, so the baseline is already 3+. The description reinforces the two acceptable value forms by giving real examples on both sides (vitalik.eth, jesse.base.eth, 0x address), which is useful even though the schema says the same thing.

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 pair (resolve / reverse-resolve), the resource (ENS and Basenames names), and the concrete input/output shapes (vitalik.eth → address, 0x address → primary name). It is clear on its own, but it never distinguishes itself from the sibling tool ens_profile, which an agent could easily mistake for the same capability.

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 two usage modes (forward lookup vs reverse lookup) by showing both input forms, but gives no explicit when-to-use guidance and no routing away from ens_profile. Nothing states prerequisites or when the paid lookup is warranted.

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 meaningful behavior beyond annotations: it discloses the research method (live sources: Stack Overflow, GitHub issues, docs), the return format (cause + fix with code, with citations), and the cost model ($0.02 USDC per call via x402). Annotations only say readOnlyHint=true and openWorldHint=true; the cost and sourcing details are valuable additions not derivable 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?

Single sentence, front-loaded with purpose, then input form, then output, then sourcing, then pricing. Dense and every clause earns its place.

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

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

For a tool with no output schema and 40% param coverage, the description tells the agent what it takes in (error + optional code) and what it returns (cause, fix, citations) plus the price, which is enough to call it. Minor gap: no mention of the async job-id mode or the language/framework hints that would help disambiguate input prep.

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 40%, and the description only implies the 'error' and 'optional code' parameters. It does not explain language, framework, or the async flag (which returns a job id) - that behavior is only in the schema's async description. Baseline is 3 for the partial coverage where the schema carries some detail but the description fails to compensate for the low-coverage params like language/framework.

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 (fix), resource (an error/stack trace), and the exact output (likely cause + concrete fix with code). Distinguishes from generic research/debug siblings by naming it 'error fixer for coding agents' and describing the specific input form (paste error + optional code).

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

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

Clearly signals when to use it: when you have an error message or stack trace and want a cause plus a fix. It does not name explicit alternatives (e.g., docs_ask, search, github_issues, ask), so usage is clear but not fully routed relative to siblings.

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