ScrapeMole Pulse

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

Annotations already cover read-only/idempotent/open-world, and the description adds substantial context beyond them: the ECB reference-rate source, the weekend/holiday fallback rule, the 1999-01-04 rate floor, the returned fields (amount, rate, rate date), and critically the paid x402 USDC pricing model plus the 'call without payment to receive PaymentRequired' behavior. That last detail is exactly the kind of non-obvious operational trait an agent needs.

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

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

The primary sentence is front-loaded with purpose and use cases, and the payment caveat is separated into its own sentence where it belongs. The first sentence is long and clause-heavy, but nearly every clause carries real information, 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 compensates by naming the three returned values. Combined with rate-source, date-fallback, pricing, and error-path details, an agent has everything needed to invoke it correctly and handle the payment-required case.

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

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

Schema coverage is 100%, so a baseline of 3 is warranted. The description earns above baseline by adding semantics the schema lacks: that 'date' falls back to the previous working day on weekends/holidays and that rates only extend back to 1999-01-04, bounding valid input values.

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

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

The description opens with a specific verb and resource ('convert money amounts') and immediately scopes it to concrete uses (quotes, invoices, expense reports, price comparisons). This clearly separates it from siblings like fx_latest and fx_history, which return rates rather than converted amounts.

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

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

It states the situations the tool serves and clarifies the latest-vs-historical date behavior, which is the main selection decision here. It does not explicitly name fx_latest or fx_history as the alternatives for when you only want a rate, so routing guidance is implicit rather than complete.

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

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

Goes well beyond the readOnly/idempotent/openWorld annotations: discloses the 366-day cap, working-day-only cadence, per-currency return statistics (first, last, min, max, percent change), and full payment behavior ($0.002 via x402 USDC on Base, PaymentRequired on unpaid calls). 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?

Two dense sentences, front-loaded with the use case and return format before the payment details. It is information-rich but each clause earns its place; the pricing sentence is wordy yet operationally necessary.

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

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

With no output schema, the description carries the return burden and does so by naming the per-currency statistics, plus it documents the date range, currency cap, and the full payment flow. Nothing needed to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds constraints not in the schema: the 366-day maximum span and the re-basing behavior of the base parameter. These give the agent calling guidance beyond field labels.

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

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

States a specific verb and resource (returns daily ECB reference rates) and scopes it to trend/history queries, which clearly separates it from the current-rate siblings like fx_latest and fx_convert. An agent can tell the historical nature immediately 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 explicit triggering contexts ('trend questions', 'back-dated conversions'), which implies the siblings fx_latest/fx_convert handle current rates. It does not name those alternatives outright or state exclusions, so it stops short of the 5-level routing guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint. The description adds substantial context beyond that: ECB as the source, publication cadence around 16:00 CET on working days, ~30 currencies, rate-date freshness, and the paid access model with x402 USDC on Base at $0.001 per successful call, including the unpaid-call PaymentRequired behavior.

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

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

The description is front-loaded with the primary use case and then layers on freshness, scope, intended uses, and payment details in a single tight paragraph. Some of the use-case enumeration ('for pricing, reporting, invoicing and conversions') is slightly redundant but still earns its place for routing.

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

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

For a simple, read-only rate retrieval tool with full annotation coverage and 100% schema description coverage, the description supplies everything an agent needs: data source, update frequency, scope, filtering behavior, rate-date freshness, cost, and payment protocol. No output schema exists, but the description adequately conveys the nature of the returned rate information.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description adds only conceptual framing ('re-based to any supported currency', 'optionally filtered to the symbols you need') without new syntax or format details, which matches the baseline 3 for high-coverage schemas.

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

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

States a specific verb ('returns') and resource ('latest European Central Bank reference rates') with scope and freshness. It does not explicitly differentiate itself from sibling tools like fx_convert or fx_history by name, though the word 'latest' and the rate-focused framing provide implicit distinction.

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

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

Provides a clear when-to-use condition ('when you need a current, citable exchange rate') and a when-not-to-use exclusion ('Not for trading'). It does not name alternative tools for conversion or historical rates, so sibling routing 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?

Goes well beyond the readOnly/openWorld/idempotent annotations: discloses the upstream data sources (Photon with Nominatim fallback), that a miss returns 404 and is not charged, an attribution obligation, and the full payment model (x402 USDC on Base, $0.001 per successful call, PaymentRequired object on unpaid calls). This is exactly the extra context an agent needs before invoking.

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

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

Front-loads the trigger and the return shape, then layers sourcing, error, licensing and payment details in dense clauses. It is longer than most tool descriptions but nearly every clause carries operational weight for a paid tool; the run-on sentence structure is the only drag.

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

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

With no output schema, the description fully carries the return-shape burden by enumerating the fields returned, and it also covers failure behavior, billing, and licensing. An agent has everything needed to call this correctly.

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

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

Only one parameter (q) and schema description coverage is 100%, so the schema already documents the argument and its aliases. The description adds no syntax or format guidance beyond what the schema states, making the baseline 3 appropriate.

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

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

States a specific verb+resource ('Geocode place or address') and enumerates the return payload (lat/lon, display name, country, OSM ids, bounding box). However, it never distinguishes itself from the closely related siblings geocode_search and geocode_reverse, leaving the agent to guess which geocoding variant 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?

Explicit trigger is given: use when you have a city, landmark, or postal address and need lat/lon for maps, weather, distance or logistics. There is no 'when-not' clause or explicit pointer to geocode_reverse for the coordinate-to-address direction, so routing between siblings 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?

Goes well beyond the readOnly/openWorld/idempotent annotations: discloses the Photon source with Nominatim fallback, that empty ocean or unknown coordinates yield a 404 and are not charged, and the full payment behavior ($0.001 USDC on Base via x402, with an unauthenticated call returning a PaymentRequired object). This is exactly the kind of cost and failure-mode 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-loads the trigger condition, then the return shape, then failure and payment semantics — a sensible priority order. It is dense but every clause carries operational information; only the pricing sentence is slightly heavy for a selection-time read.

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 describe the response, and it does: display name, country, city, street when available, plus the matched feature's coordinates. Combined with the 404 behavior and payment flow, an agent has everything needed to call and interpret results.

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

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

Schema coverage is 100% and both lat/lon bounds are documented in the schema, so the baseline is 3. The description only alludes to the coordinates and the matched feature's lat/lon without adding format or precision guidance.

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: coordinates in, human-readable place out, and enumerates the returned fields (display name, country, city, street, matched lat/lon). The coordinate-input framing cleanly distinguishes it from the name-based siblings geocode and geocode_search.

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

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

Explicitly says when to use it (agent has coordinates from GPS, a map click, or another API) and what condition triggers it. It does not name the forward-geocoding alternative the way the calibration's top example does, so 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?

Goes well beyond the readOnly/openWorld/idempotent annotations: it discloses the empty-result behavior (404, not charged), the payment model (x402 USDC on Base, $0.001 per successful call), and the no-payment response (a PaymentRequired object). This is exactly the kind of auth, cost, and failure-mode context an agent needs before invoking a paid tool.

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

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

Front-loads the usage trigger, then moves through results shape, data source, error behavior, and pricing in three tightly packed sentences with no filler. 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?

With no output schema, the description compensates by naming the returned fields, and it also covers the error case and the payment handshake. Nothing material is missing for an agent deciding whether and how to call this tool.

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

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

Schema description coverage is 100% and both parameters (q, limit) are documented there, including default and range. The description restates the default 5 / max 10 constraint rather than adding new 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?

States a specific verb and resource ('geocode search' returning up to limit matches, each with lat/lon, display name, type, country), which clearly separates it from the single-result sibling geocode via the 'up to limit matches' framing. It references the /v1/geocode endpoint rather than naming the sibling tool, so differentiation is implied rather than explicit.

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

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

'Use for autocomplete-style place pickers or when the query is ambiguous' gives a clear positive selection criterion, which implicitly steers unambiguous lookups to the single-result geocode tool. No explicit exclusion or named alternative is stated, so it stops short of the 5 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?

Annotations already declare readOnly, openWorld and idempotent, so the safety profile is covered. The description adds real value beyond them: usernames are omitted (privacy posture), the 30-story cap, and critically the paid-access model (x402 USDC on Base at $0.002/call, with a PaymentRequired object returned on unpaid calls). Only the exact return payload shape is left implicit, and that is described in the purpose sentence.

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 plus a payment caveat, front-loaded with the purpose before the routing and pricing details. Every clause carries information, though the run-on length slightly hurts 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?

No output schema exists, so the description compensates by enumerating returned fields (title, external URL and domain, score, comment count, posted time, discussion link). Purpose, filtering, pricing and privacy behavior are all covered for a two-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%, so the baseline is 3. The description adds meaning the schema does not: 'top = front page' glosses the enum value, and it reaffirms the 1-30 limit range. Marginal but genuine added value.

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

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

States a specific verb and resource — returns up to 30 stories from one Hacker News list — and enumerates the list variants (top, new, best, ask, show, job). Siblings are all unrelated services (fx, geocode, weather, holidays), so the tool is trivially distinguishable.

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

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

Explicitly frames when to use it ("see what the tech/startup community is reading right now or to monitor launches") and where to go instead for full-text search and complete comment threads, naming the alternative endpoints. Nothing is left to inference.

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

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses that this is a paid x402/USDC-on-Base tool at $0.001 per successful call and that an unpaid call returns a PaymentRequired object — critical cost and failure-mode context. It also scopes the data source ('public calendar data only') and explains the automatic year lookahead.

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

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

It front-loads the use case and wastes no words, with payment terms last. The first sentence, however, crams both the usage trigger and the full return specification into one long clause, which slightly hurts 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?

There is no output schema, so the description must describe returns — and it does so fully (boolean, matching record(s), next holiday). Combined with annotations covering safety and the description covering cost and data scope, an agent has everything needed to call this correctly.

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

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

With 2 parameters at 100% schema description coverage (date format YYYY-MM-DD, ISO 3166-1 alpha-2 for country), the schema already carries the parameter semantics. The description adds no extra constraints such as supported country coverage or behavior for invalid codes, so baseline 3 applies.

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

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

The description gives a precise verb+resource (check whether a given country/date is a public holiday) and spells out the return payload: isHoliday true/false, matching holiday records, and the next holiday on or after that date. That combination of output shape cleanly separates it from siblings like holidays_list, holidays_next, and holidays_long_weekend without needing to name 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?

It states concrete usage contexts (before booking meetings, shipping deadlines, marketplace cut-offs) and the lookahead behavior when no holiday is near. However, it never says when NOT to use it or points to the sibling that lists holidays in bulk, so routing between holiday_check and holidays_next is left to inference.

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

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

Annotations cover the safety profile (readOnly, idempotent, openWorld), but the description goes further by disclosing the data source, the holiday attribute set (date, names, nationwide vs county-limited, fixed vs movable, types), that the data is public and non-personal, and the paid x402 USDC model with per-call price and the PaymentRequired-on-unpaid-call behavior. That payment semantics is information annotations cannot carry. It stops short of noting rate limits or any caching/retry 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?

Front-loaded with the use case and the core outcome before details, and every clause carries information (source, attributes, payment). The 'Public, non-personal data' clause is slightly expendable, but nothing is padded verbosely.

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 per-holiday fields and coverage, so an agent knows what it gets back. The main gap is sibling disambiguation among the holiday tools, which is not addressed.

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 (country as ISO 3166-1 alpha-2, year defaulting to current UTC year). The description only adds illustrative country codes (LT, US, DE, JP), which is a marginal gain over the schema. Baseline 3 is appropriate.

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

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

States a precise verb and resource ('returns every public holiday for a country in a given year') plus the data source (Nager.Date) and country coverage (~100 countries). The scope is unambiguous, but it never distinguishes itself from the four sibling holiday tools (holiday_check, holidays_next, holidays_countries, holidays_long_weekend), which an agent will see side by side.

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

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

Gives concrete usage contexts — scheduling, payroll calendars, travel planning, 'is the office closed?' — which is a clear statement of when to reach for it. However, it offers no exclusions or alternative routing despite four closely related holiday siblings, so the agent must infer which one to pick.

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

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

Annotations cover the safety profile (readOnly, idempotent, openWorld), and the description adds behavior they cannot express: no personal data, paid access via x402 USDC on Base at $0.001 per successful call, and the failure mode (calling without payment yields a PaymentRequired object). Cost and auth semantics are exactly the kind of context an agent needs before invoking.

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

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

Three short sentences, front-loaded with the usage directive, then what is returned, then the payment model — no filler. It is slightly dense and packs a lot of unrelated commercial detail into one sentence, but nothing is redundant.

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

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

For a zero-parameter, no-output-schema enumeration tool, the description supplies everything needed: what it returns, approximately how many items, the field names, and the payment prerequisite. Nothing an agent must know to call it correctly is missing.

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

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

There are zero parameters, so the baseline is 4 and there is nothing for the description to disambiguate. It does describe the shape of the returned records (countryCode plus English name), which is mildly useful but strictly about output, not 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?

States a specific verb and resource ('discover supported country codes... returns every country Nager.Date covers (~100), each with countryCode and English name'), and the enumeration is concrete enough to separate it from its sibling 'holidays'. An agent can tell instantly that this is the lookup/enumeration tool rather than a query tool.

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

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

Opens with an explicit precondition: 'Use before calling /v1/holidays or /v1/holidays/check', which names the exact endpoints (matching the holidays and holiday_check siblings) whose country codes this tool supplies. This is a clear when-to-use statement rather than inferred guidance.

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

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

Annotations cover readOnly/openWorld/idempotent, and the description adds substantial context beyond them: the upstream source (Nager.Date LongWeekend), the paid model (x402 USDC on Base, $0.001 per successful call), and crucially the failure protocol — call without payment and you get a PaymentRequired object. That payment/auth behavior is exactly what annotations cannot express.

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

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

Two dense sentences, front-loaded with the use case and the returned payload, followed by the source and payment terms. No filler and nothing redundant 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 still characterizes the return content (long-weekend windows, bridge-day flag, dates to take off), names the data source, and discloses the payment flow. An agent has everything needed to call it and interpret the result correctly.

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

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

Schema description coverage is 100%, so both parameters (year, country with ISO 3166-1 alpha-2 and a current-UTC-year default) are already fully documented in the schema. The description adds no parameter syntax or format detail beyond that, 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?

Specific verb and resource: returns long-weekend windows for a country/year where a public holiday creates 3+ consecutive days off, plus bridge-day requirement and dates to take off. This is clearly differentiated from siblings like holiday_check, holidays, holidays_next, and holidays_countries, so an agent can select it without opening another 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?

"Use for travel or leave planning" gives an explicit usage context, which is more than most siblings likely offer. However, it names no alternative tool and gives no when-not condition (e.g., use holidays_next for the next single holiday vs. this for multi-day windows), leaving sibling routing 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 cover only the safety profile (readOnly, idempotent, openWorld), and the description adds the operational facts an agent actually needs: it is a paid tool, priced at $0.001 per successful call via x402 USDC on Base, and an unpaid call returns a PaymentRequired object. It also discloses the typical result window (remainder of the year into the next), which is behavior no annotation conveys.

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

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

The use case is front-loaded and the payment caveat is appended compactly in one sentence. The sentence is long and packs example query, source, limit, and billing together, but 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 no output schema, the description carries the burden of describing returns, and it does so at a high level (upcoming holidays from today, typically through the next year). The billing/payment flow is fully covered; only the concrete shape of the returned holiday records 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%, with both country (ISO 3166-1 alpha-2) and limit (1-50) documented in the schema itself, so the baseline is 3. The description only restates that limit 'caps the list' and adds no format or edge-case detail beyond the schema.

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

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

States a specific verb and resource (returns the next public holidays for a country) and pins the temporal scope to 'from today', which separates it from the year-scoped siblings holidays and holiday_check. The upstream source (Nager.Date NextPublicHolidays) is named, so the agent knows exactly what data it gets.

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

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

Opens with an explicit use case ('Use to answer "when is the next public holiday in Germany?"'), giving clear context for when to reach for it. It does not name alternatives such as holidays or holiday_check or state exclusions, so it stops short of full when/when-not 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 only cover read-only/idempotent/open-world traits; the description goes well beyond by disclosing DST-gap handling (spring-forward times shift to the first valid instant and are flagged) and the paid access model (x402 USDC on Base, $0.001 per successful call, PaymentRequired object returned when unpaid). These are exactly the behavioral facts an agent needs and that no structured field supplies.

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 usage trigger, and the output-field enumeration is dense but informative. Slightly heavy on listing return fields, though with no output schema that detail is justified.

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

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

There is no output schema, so the description carries the return-value burden itself and does so (date, weekday, UTC offset, DST flag, UTC instant). It also covers the payment prerequisite and DST edge case, leaving nothing an agent needs to call it correctly unstated.

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

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

Schema coverage is 100%, so the schema already documents time, from and to with formats and defaults. The description adds only marginal parameter-level detail, restating that the source may be a wall-clock time or an ISO instant; 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 (convert a wall-clock or ISO instant into target zones) and enumerates the returned fields. It is clearly distinguishable from time_now, which reports the current time rather than converting a supplied instant.

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 for scheduling across time zones" gives a clear triggering context, and the mention of accepting either a wall-clock time or an ISO instant clarifies input scenarios. However, it never names an alternative tool or states when not to use this one.

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

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

Beyond the annotations, it discloses that results come from the IANA tz database with no upstream dependency, and it explains the paid x402/USDC payment model including the exact price and what happens if payment is omitted. These are important operational traits not present in the structured annotations.

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

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

The description is front-loaded with the primary use case and return shape, then proceeds to source and payment details. It is dense but every sentence adds relevant information, though the single long colon construction could be split for easier scanning.

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 that there is no output schema, the description adequately explains the return payload fields, the data source, and the payment behavior. An agent has enough information to invoke the tool correctly and understand the possible PaymentRequired response.

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

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

Schema description coverage is 100%, so the schema already documents the tz parameter, including comma-separated IANA zones and a max of 20. The description only refers generally to 'each requested IANA time zone' and adds no syntax or constraint details beyond the schema.

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

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

The description states a specific verb and resource: it returns the authoritative current UTC instant and local time details for requested IANA time zones. It also distinguishes itself from the sibling time_convert by framing the use case as needing the real current time, not converting between zones.

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

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

It explicitly says when to use the tool: when an agent needs the real current time somewhere, noting that models do not know 'now'. It does not name alternatives or when-not-to-use cases, so it falls short of a full 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 cover only readOnly/openWorld/idempotent, yet the description adds the commercial and payment model (x402 USDC on Base, $0.001 per successful call, calling without payment yields a PaymentRequired object), the empty-result behavior (no alerts = 200 with count 0), and data provenance (official public-domain NWS, US only). These are material traits an agent cannot infer from the annotations.

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

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

A single dense paragraph, but it is front-loaded with the use case and return shape before dropping into filters, edge-case behavior, and pricing. Every sentence carries information; only the breadth makes it feel long rather than filler.

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

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

With no output schema, the description still lists the returned fields, the filter selectors (state/point/place/zone), severity and event refinement, empty-result semantics, geographic scope, and payment/error behavior. An agent has everything needed to select and call the tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds the framing that the filter modes are alternatives ('filter by state... by point... or by NWS zone') with concrete zone examples (TXZ211, NYC061) and notes that state codes also cover territories and marine areas. It also explains full=true vs trimmed text, which is not spelled out in the schema.

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

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

Starts with a specific verb+resource ('returns the currently active National Weather Service alerts') and enumerates exactly what comes back (event, severity, certainty, urgency, affected areas, onset/expiry, issuing office). It is clearly distinguished from the sibling us_weather_forecast, which covers forecasts rather than active alerts.

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

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

Gives concrete when-to-use contexts ('before travel, logistics, field work, events or outdoor plans in the US, or to monitor severe weather') and a clear scope boundary ('US only'). It does not explicitly route the agent to the forecast sibling for forecast data, so it stops short of full alternative-aware 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 readOnly/idempotent/open-world, and the description adds material behavior beyond them: the paid x402 USDC-on-Base pricing model, the exact $0.002 cost, that failed/out-of-US calls are not charged, and that a payment-less call returns a PaymentRequired object. That is context an agent cannot get from the 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?

Front-loaded with the use case, then output shape, then constraints and pricing — a sensible order with no filler sentences. It is a single dense paragraph, though, and the return-value inventory could be tightened.

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

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

There is no output schema, yet the description enumerates the returned fields (name, °F/°C temperature, wind, precipitation chance, short/detailed forecast, nearest city/state, time zone, forecast zone, alerts summary), covers error behavior, cost, and the hourly alternative. Nothing an agent needs to call or interpret this tool is missing.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds real semantics: the hourly=true branch caps at 48 periods (matching the 'hours' param), alerts=false suppresses the alert lookup, and lat/lon versus place are presented as alternatives. It stops short of detailing units or precedence between lat/lon and 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-and-resource pair (resolves lat/lon or US place to an NWS grid and returns a 7-day forecast) and explicitly scopes itself as the US/official-NWS option, distinguishing it from the global 'weather' sibling. An agent can identify both what it does and what it does not cover 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?

Names concrete use cases (trip, event, delivery, field-work planning) and the selecting condition ('when an official forecast matters'), then names the alternative for out-of-scope calls: points outside the US return 404 and should use /v1/weather (MET Norway). Both when-to-use and when-not-to-use are covered.

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

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

Goes well beyond the annotations by disclosing the data source, UTC time convention, CC BY 4.0 licensing/attribution requirement, and critically the paid x402 USDC payment flow with cost and the PaymentRequired object behavior for unpaid calls. These are operationally essential details the annotations do not convey, with no 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?

A single dense but front-loaded paragraph: use case first, then return shape, then input guidance, then legal/payment constraints. Every sentence carries useful information, though it is somewhat packed and could be broken into clearer sections.

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 a solid job enumerating return fields (current conditions, hourly series, daily summaries) and covers the unusual payment model and licensing. Minor gaps remain around units and exact response structure, but an agent has enough to call it correctly.

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

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

Schema coverage is 100%, so the schema already documents lat, lon, hours, and place. The description adds only a light restatement of the lat/lon vs place alternative and notes Wikidata resolution, which the schema already mentions. 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 ('returns the forecast for a location') and names the data source (MET Norway) plus global coverage, which implicitly contrasts with the US-specific siblings. However, it never names us_weather_forecast or us_weather_alerts, so the agent must infer the boundary from 'global coverage' 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?

Provides clear usage contexts ('trip planning, logistics, event or outdoor decisions'), which is better than nothing. But it gives no when-not guidance and never mentions the closely related US NWS siblings that an agent should consider for official US forecasts and alerts.

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