x402 FX, time, weather, HN, holidays, geocoding for agents.
Scored across 15 tools
Each tool targets a distinct domain+action (fx_convert vs fx_latest vs fx_history; geocode vs geocode_reverse vs geocode_search; time_now vs time_convert), so most selections are clear. Minor overlap exists between holiday_check and holidays_next, since both can return upcoming holidays, but the date-anchored vs today-anchored semantics are spelled out in the descriptions.
The dominant pattern is a domain prefix plus action (fx_convert, time_convert, holidays_next), which is readable. However it breaks in places: bare nouns (geocode, hn, weather) sit beside suffixed siblings (geocode_search), and the singular 'holiday_check' clashes with the plural 'holidays' family, so conventions are mixed rather than uniform.
Fifteen tools is well within the ideal range and each one maps to a concrete, useful operation across five coherent domains (FX, geocoding, holidays, time, weather, HN). No tool appears redundant filler at the set level.
Coverage is strong: FX has convert/latest/history, geocoding has forward/reverse/search, holidays has countries/list/check/next/long-weekend, and time/weather have sensible primitives. The only notable gap is HN, which exposes just a story list and explicitly defers full-text search and comment threads to another server.
Use to convert money amounts for quotes, invoices, expense reports or price comparisons: converts an amount from one currency to another at the ECB reference rate of the latest working day or of a given past date (rates since 1999-01-04; weekends/holidays fall back to the previous working day). Returns the converted amount, the rate used and the rate date. Paid tool: x402 USDC on Base, $0.001 per successful call; call without payment to receive the PaymentRequired object.
| Name | Required | Description | Default |
|---|---|---|---|
| to | Yes | Target currency (ISO 4217). | |
| date | No | Historical date YYYY-MM-DD (default latest). | |
| from | Yes | Source currency (ISO 4217). | |
| amount | No | Amount to convert (default 1). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the readOnly/idempotent/openWorld annotations by disclosing the payment model (x402 USDC on Base, $0.001 per successful call), the behavior when unpaid (returns a PaymentRequired object), the weekend/holiday fallback, and the return fields. This is exactly the behavioral context annotations cannot carry.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the action ('Use to convert money amounts...') and densely packed but every clause carries information: rate source, date semantics, fallback, return values, payment terms. Slightly long as a single run-on, but 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 compensates by naming the returned values (converted amount, rate used, rate date) and fully covers the paid-call flow. An agent has everything needed to invoke it correctly and interpret the response.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is already 100%, so the baseline is 3, but the description adds real meaning: the date parameter's ECB-rate semantics, historical range since 1999-01-04, and the previous-working-day fallback. The amount default is left to the schema, so it is not fully additive.
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 (convert) and resource (money amounts between currencies) plus the rate source (ECB reference rate) and scope (rates since 1999-01-04). This clearly separates it from fx_latest and fx_history siblings, which the description implicitly contrasts by defining its own conversion behavior.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives concrete use cases (quotes, invoices, expense reports, price comparisons) and the fallback rule for weekends/holidays, so an agent knows when this applies. It stops short of explicitly naming when to prefer fx_latest or fx_history instead, leaving some routing to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use for trend questions ("how did USD/EUR move this quarter?") and for back-dated conversions: returns daily ECB reference rates for each working day between start and end (max 366 days) for the requested currencies, re-based to any base, with per-currency first, last, min, max and percent change. Paid tool: x402 USDC on Base, $0.002 per successful call; call without payment to receive the PaymentRequired object.
| Name | Required | Description | Default |
|---|---|---|---|
| end | No | End date YYYY-MM-DD (default today). | |
| base | No | Base currency. | EUR |
| start | Yes | Start date YYYY-MM-DD. | |
| symbols | Yes | Comma-separated currencies (max 10). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds substantial behavior beyond the annotations (readOnly/idempotent/openWorld): the 366-day cap, working-day granularity, ECB source, re-basing support, per-currency aggregates, and crucially the x402/USDC pricing model with the PaymentRequired fallback. The payment semantics are non-obvious and fully disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, fully front-loaded: use case first, output shape second, payment requirement last. No filler, and the most decision-relevant detail (paid, $0.002) is stated plainly.
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 explicitly (first, last, min, max, percent change per currency), plus the range cap and payment flow. Nothing an agent needs to call correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description adds constraints the schema omits — the max 366-day window on start/end and the re-basing behavior tied to base. Symbols' 10-item cap is echoed from the schema, so the marginal value is modest but real.
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 between start and end — and front-loads the two use cases (trend questions, back-dated conversions). An agent can distinguish this from fx_latest (current snapshot) and fx_convert (forward conversion) 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 context for when to reach for this tool: trend questions and back-dated conversions. The date-range framing implicitly separates it from fx_latest, but it never names the sibling alternatives or states exclusions explicitly, 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.
Use when you need a current, citable exchange rate: returns the latest European Central Bank reference rates (published once per working day around 16:00 CET) for about 30 major currencies, re-based to any supported currency, optionally filtered to the symbols you need. Includes the rate date so you know how fresh it is. Not for trading; for pricing, reporting, invoicing and conversions. Paid tool: x402 USDC on Base, $0.001 per successful call; call without payment to receive the PaymentRequired object.
| Name | Required | Description | Default |
|---|---|---|---|
| base | No | Base currency (ISO 4217). | EUR |
| symbols | No | Comma-separated target currencies; all ~30 if omitted. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With annotations already covering readOnly/openWorld/idempotent, the description still adds substantial operational context: publication cadence (~16:00 CET on working days), freshness via the included rate date, and the paid x402 USDC-on-Base model with cost and the PaymentRequired response when unpaid. This is exactly the kind of detail 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 'Use when...' and every sentence carries either scope, freshness, or payment information. It is dense but not padded; only the enumeration of use cases is slightly 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?
With no output schema, the description still tells the agent what comes back (rates plus the rate date for freshness) and how payment works. Nothing needed to call it correctly appears 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 both parameters are already documented, establishing a baseline of 3. The description adds mild meaning ('re-based to any supported currency', 'all ~30 if omitted') but no format or syntax detail 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?
States a specific verb and resource: returns latest ECB reference rates, re-based to a chosen base and optionally filtered by symbols. It also implicitly separates itself from fx_history (latest vs historical) and fx_convert (rates vs conversion), so an agent can route 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 when-to-use ('current, citable exchange rate') and when-not ('Not for trading; for pricing, reporting, invoicing'), which is solid context. It does not name a sibling alternative (e.g. fx_history for past dates) explicitly, keeping it 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.
Use when an agent has a city, landmark or postal address and needs lat/lon for maps, weather, distance or logistics: returns the best match with latitude, longitude, display name, country/countryCode, optional admin hierarchy, street/house number, OSM ids and bounding box. Public OpenStreetMap-derived data via Photon (Komoot), with Nominatim fallback. Not found = 404, not charged. Attribute OpenStreetMap when redistributing. Paid tool: x402 USDC on Base, $0.001 per successful call; call without payment to receive the PaymentRequired object.
| Name | Required | Description | Default |
|---|---|---|---|
| q | Yes | Place name or address to resolve (aliases: place, address). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the readOnly/openWorld/idempotent annotations: 404 semantics plus 'not charged', the OSM attribution obligation, the Photon source with Nominatim fallback, and the x402 USDC-on-Base payment model at $0.001 per successful call with a PaymentRequired object when unpaid. That is exactly the behavioral context an agent needs to call a paid, fallback-backed tool safely.
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 payload fields in the first sentence, then layers provider, error, legal and pricing details. Dense but nearly every clause is load-bearing; the pricing/attribution tail slightly crowds a single-sentence tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description enumerates the return shape (lat/lon, display name, country codes, admin hierarchy, street/house number, OSM ids, bounding box), and covers failure mode, cost and licensing. Nothing needed to invoke or interpret a result 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?
Only one parameter (q) and schema description coverage is 100%, so the schema already carries the meaning including the place/address aliases. The description adds no syntax, format, or example guidance for q beyond what the schema states, 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 ('Geocode place or address') and enumerates the returned fields (latitude, longitude, display name, country/countryCode, OSM ids, bounding box). It implicitly covers forward geocoding, but never names the near-identical siblings geocode_search or geocode_reverse, so an agent still has to guess which of the three 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?
'Use when an agent has a city, landmark or postal address and needs lat/lon for maps, weather, distance or logistics' gives a clear triggering condition and downstream use cases. No explicit exclusions or named alternatives are given, so the reverse-geocoding sibling is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use when an agent has coordinates (from GPS, a map click or another API) and needs a human-readable place: returns the nearest OSM feature with display name, country, city, street when available, and lat/lon of the matched feature. Public OpenStreetMap-derived data via Photon, Nominatim fallback. Empty ocean / unknown = 404, not charged. Paid tool: x402 USDC on Base, $0.001 per successful call; call without payment to receive the PaymentRequired object.
| Name | Required | Description | Default |
|---|---|---|---|
| lat | Yes | Latitude -90..90. | |
| lon | Yes | Longitude -180..180. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly, idempotent, openWorld), and the description layers on real operational context: upstream providers (Photon with Nominatim fallback), the 404-on-empty-ocean behavior, and that such failures are not charged. It also discloses the payment model (x402 USDC on Base, $0.001 per successful call) and the paywall handshake (unpaid call returns a PaymentRequired object), which annotations cannot express.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the trigger condition, then the return shape, then data provenance, then error/billing behavior. Three dense sentences with no filler, and the highest-value information (when to use, what you get) leads.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description takes on the return-value burden and does so (display name, country, city, street when available, matched lat/lon). Combined with error semantics, provenance, and payment details, an agent has everything needed to call it and interpret the result.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and both params are documented there with valid ranges, so the schema carries the load. The description adds no syntax, format, or precision guidance beyond what the schema states, 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 gives a specific verb+resource (reverse geocode coordinates into a human-readable place) and enumerates the returned fields. It distinguishes itself implicitly from the forward-geocoding siblings by framing the trigger as 'agent has coordinates', but it never names geocode or geocode_search, so the differentiation is only inferred.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives a concrete when-to-use trigger ('Use when an agent has coordinates (from GPS, a map click or another API) and needs a human-readable place'), which is stronger than most. It omits an explicit when-not / alternative clause (e.g. 'for a text query use geocode_search instead'), so the routing is clear but not fully disambiguated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use for autocomplete-style place pickers or when the query is ambiguous: returns up to limit matches (default 5, max 10), each with lat/lon, display name, type and country. Same OpenStreetMap-derived sources as /v1/geocode. Empty result = 404, not charged. Paid tool: x402 USDC on Base, $0.001 per successful call; call without payment to receive the PaymentRequired object.
| Name | Required | Description | Default |
|---|---|---|---|
| q | Yes | Place name or address to search (aliases: place, address). | |
| limit | No | Max results (1-10). | 5 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the readOnly/openWorld/idempotent annotations: it discloses default and maximum result counts, that an empty result yields a 404 and is not billed, and the full payment model (x402 USDC on Base, $0.001 per successful call, unpaid calls return a PaymentRequired object). Payment and error semantics are exactly the kind of behavior 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?
Three sentences, front-loaded with the usage condition and backed by result shape, error behavior and pricing — no filler. The first sentence is clause-heavy (usage, count, default, max, output fields all in one), 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?
With no output schema, the description still enumerates the returned fields, states the result cap, and covers the failure/billing paths an agent must handle. Nothing material is missing for calling this tool correctly in a paid-API context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with both q and limit already documented including the same 1-10 range and default of 5, so the description's mention of default/max only repeats the schema. The listed return fields (lat/lon, display name, type, country) describe output rather than adding parameter meaning; baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource (geocode search over places/addresses) with an explicit multi-result scope ('returns up to limit matches'), which cleanly separates it from the single-result geocode, geocode_reverse and the fx/time/weather/holiday siblings. An agent can tell what this returns 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 concrete trigger conditions: 'autocomplete-style place pickers' and 'when the query is ambiguous'. It does not name the alternative to pick when the query is unambiguous (i.e. the single-result geocode tool), so the routing rule is one-sided rather than complete.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use to see what the tech/startup community is reading right now or to monitor launches: returns up to 30 stories from one Hacker News list (top = front page, new, best, ask, show, job) via the official HN API, each with title, external URL and domain, score, comment count, posted time and the news.ycombinator.com discussion link. Usernames are omitted (non-personal data). For full-text HN search and complete comment threads use ScrapeMole Social: https://social.scrapemole.workers.dev/v1/hn/search and /v1/hn/thread. Paid tool: x402 USDC on Base, $0.002 per successful call; call without payment to receive the PaymentRequired object.
| Name | Required | Description | Default |
|---|---|---|---|
| list | No | top, new, best, ask, show or job. | top |
| limit | No | Stories to return (1-30). | 10 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark it as a safe read operation, and the description adds substantial context: paid cost model (x402 USDC on Base, $0.002 per successful call, PaymentRequired object on unpaid calls), omitted usernames for privacy, and the exact response fields. This goes well beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with purpose and usage, then details, alternatives, and payment information. It is dense but every clause is informative for correct invocation; the length is justified by the payment and privacy disclosures.
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?
Though there is no output schema, the description enumerates the returned fields, scope (up to 30 stories, one list), payment behavior, and alternative endpoints for related tasks. An agent has enough to call it correctly and understand 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. The description adds meaning beyond the schema by clarifying that 'top' means 'front page' and reinforcing the 1-30 limit, though the list values themselves are largely repeated from 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: 'returns up to 30 stories from one Hacker News list' via the official HN API. It distinguishes the tool from search/thread alternatives and clarifies the exact list types and output fields. The vague tool name 'hn' is rescued by the detailed description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly says when to use it ('to see what the tech/startup community is reading right now or to monitor launches') and when not to use it ('For full-text HN search and complete comment threads use ScrapeMole Social' with specific endpoints). The alternatives and conditions are named directly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use before booking meetings, shipping deadlines or marketplace cut-offs: given a country and a date, returns isHoliday true/false, the matching holiday record(s) if any, and the next public holiday on or after that date in the same country (looks ahead into the following year if needed). Public calendar data only. Paid tool: x402 USDC on Base, $0.001 per successful call; call without payment to receive the PaymentRequired object.
| Name | Required | Description | Default |
|---|---|---|---|
| date | Yes | Date to check (YYYY-MM-DD). | |
| country | Yes | ISO 3166-1 alpha-2 country code. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only cover the safe-read/idempotent profile; the description adds substantial behavior beyond them: it is a paid tool billed via x402 USDC on Base at $0.001 per successful call, and an unpaid call returns a PaymentRequired object rather than failing opaquely. It also discloses the look-ahead behavior (extends into the following year if needed) and that only public calendar data is 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 dense sentence front-loads the decision context, then the outputs, then the payment terms — a sensible priority order with no filler. It is tightly packed but fairly long, and the paid-call mechanics could be one clause shorter, keeping it just below ideal.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description carries the return-value burden and does so fully: isHoliday boolean, matching holiday record(s), and the next holiday with its look-ahead caveat. Combined with the payment/fallback disclosure, an agent has everything needed to invoke it correctly, including how to handle a non-paying call.
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 (date as YYYY-MM-DD, country as ISO 3166-1 alpha-2) are already fully documented in the schema, establishing the baseline of 3. The description adds only marginal semantics by clarifying that the date anchors both the boolean check and the subsequent next-holiday lookup; no format or edge-case detail is added 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 with exact scope: given a country and date, returns isHoliday true/false, matching holiday record(s), and the next holiday on or after that date. This cleanly separates it from siblings like holidays_next and holidays_long_weekend, which perform different calendar computations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Front-loads a concrete usage context ('before booking meetings, shipping deadlines or marketplace cut-offs'), which tells the agent the decision scenario this answers. It stops short of naming alternatives (e.g. holidays_next, holidays_countries) or exclusion conditions, so it is clear on when to use but silent on when not to.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use for scheduling, payroll calendars, travel planning or "is the office closed?": returns every public holiday for a country (e.g. LT, US, DE, JP) in a given year from Nager.Date (~100 countries). Each holiday has date, English name, local name, whether it is nationwide (global) or limited to counties/states, fixed vs movable, and types (Public, Bank, School, Optional, Authority). Public, non-personal data. Paid tool: x402 USDC on Base, $0.001 per successful call; call without payment to receive the PaymentRequired object.
| Name | Required | Description | Default |
|---|---|---|---|
| year | No | Calendar year (default current UTC year). | |
| country | Yes | ISO 3166-1 alpha-2 country code. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnly/openWorld/idempotent annotations, it discloses the data provenance, the returned field set (date, names, global vs county-limited, fixed vs movable, holiday types), and crucially the payment model: x402 USDC on Base at $0.001 per successful call, with an unpaid call returning a PaymentRequired object. This is high-value operational context an agent cannot get 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?
Front-loads the purpose and use cases, then the return shape, then the payment terms. Dense and information-rich with little waste, though the long enumerations make it feel heavier than 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 compensates by enumerating the returned fields, and it covers the paid-call flow end to end. Nothing an agent needs to invoke it correctly or interpret a payment failure 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 country and year are already documented with format and default. The description still adds concrete country-code examples (LT, US, DE, JP) and confirms the year scoping, which marginally enriches the parameter meaning 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 every public holiday for a country in a given year. It distinguishes itself from siblings like holiday_check, holidays_next, and holidays_countries by implying a full-year enumeration, and names the upstream source (Nager.Date, ~100 countries).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives concrete use cases (scheduling, payroll calendars, travel planning, 'is the office closed?'), which clearly frames when to reach for it. However, it never explicitly contrasts with the sibling holiday tools (holiday_check, holidays_next, holidays_long_weekend), leaving the agent to infer the boundary.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use before calling /v1/holidays or /v1/holidays/check to discover supported country codes: returns every country Nager.Date covers (~100), each with countryCode and English name. No personal data. Paid tool: x402 USDC on Base, $0.001 per successful call; call without payment to receive the PaymentRequired object.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the annotations (readOnlyHint/openWorldHint/idempotentHint) by disclosing the pricing model (x402 USDC on Base, $0.001 per successful call), the auth/payment flow, and the exact behavior on non-payment (a PaymentRequired object is returned). Also states 'No personal data', an important privacy trait for an agent.
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 the usage condition, then the return shape, then the payment caveat. Every sentence earns its place 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 compensates by describing the returned fields and count (~100 countries). Payment behavior, data provenance, and prerequisite usage are all covered, so an agent has everything needed to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, so the baseline is 4; the description correctly spends its words on the return payload (countryCode + English name) rather than inventing parameter semantics. Nothing about parameters needs further explanation.
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 (discover/returns) and resource (every country Nager.Date covers, ~100, with countryCode and English name), plus the exact fields returned. Clearly distinguishes it from siblings holidays and holiday_check as the discovery/lookup prerequisite.
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 'Use before calling /v1/holidays or /v1/holidays/check', naming the conditions that select this tool over the sibling holiday tools. Nothing about when to invoke it 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.
Use for travel or leave planning: returns long-weekend windows for a country and year where a public holiday creates 3+ consecutive days off, including whether a bridge day is needed and which dates to take off. From Nager.Date LongWeekend. Paid tool: x402 USDC on Base, $0.001 per successful call; call without payment to receive the PaymentRequired object.
| Name | Required | Description | Default |
|---|---|---|---|
| year | No | Calendar year (default current UTC year). | |
| country | Yes | ISO 3166-1 alpha-2 country code. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations cover the safety profile (readOnly, idempotent, openWorld), but the description adds critical context they cannot: the upstream source (Nager.Date LongWeekend), the paid x402 USDC-on-Base billing model, the $0.001 per-successful-call price, and the failure path — calling without payment returns a PaymentRequired object. That payment/error disclosure is the materially valuable piece.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, both front-loaded: usage/purpose first, behavioral and billing facts second. No filler, and the data source is tucked in without disrupting the flow.
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 conveys the return content (3+ day windows, bridge-day flag, dates to take off), the source, the cost, and the unpaid-call response. Nothing an agent needs to invoke and interpret this correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both params (country as ISO 3166-1 alpha-2, year defaulting to current UTC year) are already fully documented. The description only restates 'for a country and year' and adds no format or defaulting detail beyond the schema, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource ('returns long-weekend windows for a country and year') plus the exact business rule (public holiday creating 3+ consecutive days off) and the payload fields (bridge day needed, dates to take off). This clearly separates it from siblings like holidays, holiday_check, and holidays_next.
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 for travel or leave planning.' That gives a clear triggering context, but it never states when NOT to use it or names the sibling (holiday_check, holidays) to use for adjacent holiday needs, so the routing guidance 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.
Use to answer "when is the next public holiday in Germany?" or to build a short upcoming-holiday list for agents: returns the next public holidays for a country from today via Nager.Date NextPublicHolidays (typically the remainder of the year plus into the next). Optional limit caps the list. Paid tool: x402 USDC on Base, $0.001 per successful call; call without payment to receive the PaymentRequired object.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max holidays to return (1-50). | 10 |
| country | Yes | ISO 3166-1 alpha-2 country code. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnly/openWorld/idempotent annotations, it discloses the upstream source (Nager.Date NextPublicHolidays), the typical coverage window (rest of this year plus into the next), and — critically for an agent — that the tool is paid via x402 USDC on Base at $0.001 per successful call, plus the fallback behavior of an unpaid call returning a PaymentRequired object.
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 every clause carries information (scope, source, coverage window, limit, payment terms). The payment sentence is dense and slightly run-on, which keeps it just short of ideal, 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 covers what comes back (upcoming holidays from today for a country), the typical window, and the payment flow an agent must handle. It stops short of describing the shape of each holiday entry (name, date, local name), which would fully close the gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with 'limit' documented as 1-50 and defaulting to 10 and 'country' as an ISO 3166-1 alpha-2 code. The description only restates that the limit caps the list, adding no new constraint or format detail beyond the schema, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource — 'returns the next public holidays for a country from today' — with an example query that pins the scope to upcoming holidays rather than a full year. That implicitly separates it from holiday_check (is a given date a holiday) and holidays/ holidays_countries, 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?
It gives a concrete use case ('when is the next public holiday in Germany?' or building a short upcoming-holiday list) and notes the optional limit for trimming results. There is no explicit when-not or named alternative among the many sibling holiday tools, 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.
Use for scheduling across time zones: takes a wall-clock time in a source zone (or an ISO instant with offset) and returns the same instant in each target zone with date, weekday, UTC offset and DST flag, plus the UTC instant. Handles daylight-saving transitions correctly (times in a spring-forward gap move to the first valid instant and are flagged). Paid tool: x402 USDC on Base, $0.001 per successful call; call without payment to receive the PaymentRequired object.
| Name | Required | Description | Default |
|---|---|---|---|
| to | Yes | Comma-separated target IANA zones (max 20). | |
| from | No | IANA zone of "time" (ignored if time has an offset). | UTC |
| time | Yes | Local time "YYYY-MM-DD HH:MM[:SS]" in "from", or an ISO instant with Z/offset. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the readOnly/idempotent annotations by disclosing DST edge-case behavior (spring-forward gaps shift to first valid instant and are flagged) and the payment mechanics ($0.001 via x402 USDC on Base, PaymentRequired on unpaid call). These are exactly the behavioral facts an agent must know before invoking.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with the usage trigger, then conversion/DST semantics, then cost. Every sentence earns its place and nothing is repeated.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description compensates by enumerating the returned fields (date, weekday, UTC offset, DST flag, UTC instant) and covers the paid-invocation path. An agent has everything needed to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents time, from, and to (including the offset-overrides-from rule). The description reinforces the wall-clock-vs-instant distinction but adds no new parameter-level detail, warranting the baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific action and resource ('takes a wall-clock time in a source zone ... returns the same instant in each target zone') with the exact return fields enumerated. This clearly separates it from time_now and the fx_* siblings 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?
Opens with an explicit when-to-use trigger ('Use for scheduling across time zones'), which gives clear context. It does not name alternatives (e.g. time_now) or state when-not-to-use, so it stops short of the 5 bar.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use when an agent needs the real current time somewhere (models do not know "now"): returns the authoritative current UTC instant and, for each requested IANA time zone, the local date/time, weekday, UTC offset, abbreviation and whether daylight saving time is in effect. Computed from the IANA tz database, no upstream dependency. Paid tool: x402 USDC on Base, $0.001 per successful call; call without payment to receive the PaymentRequired object.
| Name | Required | Description | Default |
|---|---|---|---|
| tz | No | Comma-separated IANA zones (max 20). | UTC |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnly/idempotent/openWorld annotations, it discloses the data source (IANA tz database, no upstream dependency) and the commercial mechanics: paid via x402 USDC on Base at $0.001 per successful call, with the PaymentRequired object returned on unpaid calls. That is exactly the extra context annotations cannot carry.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the usage trigger, then the return contract, then payment terms — a sensible ordering. The two sentences are dense but every clause carries information; the payment detail could arguably be split for readability.
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 return fields itself (UTC instant, local date/time, weekday, offset, abbreviation, DST flag), and it covers payment behavior and the zero-required-parameter case. Nothing needed to call it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the single tz parameter already documents comma-separated IANA zones with a max of 20 and a UTC default. The description only echoes 'for each requested IANA time zone' without adding format or validation detail, so the schema does the heavy lifting — baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb+resource: returns the authoritative current UTC instant plus per-zone local date/time, weekday, offset, abbreviation and DST status. This is clearly distinct from the sibling time_convert, which converts rather than reports 'now'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives an explicit trigger ('Use when an agent needs the real current time somewhere') and even explains the motivating gap ('models do not know "now"'). It does not name time_convert or state when to prefer it over this tool, so it falls just short of full routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use for trip planning, logistics, event or outdoor decisions: returns the forecast for a location from the Norwegian Meteorological Institute (global coverage): current temperature, wind, humidity, cloud cover, pressure and symbol, an hourly series for the next N hours, and daily summaries (min/max temperature, total precipitation, dominant symbol). Give lat/lon, or a place name resolved via Wikidata. Times are UTC. Licensed CC BY 4.0: credit MET Norway. Paid tool: x402 USDC on Base, $0.002 per successful call; call without payment to receive the PaymentRequired object.
| Name | Required | Description | Default |
|---|---|---|---|
| lat | No | Latitude -90..90. | |
| lon | No | Longitude -180..180. | |
| hours | No | Hourly points to return (1-48). | 24 |
| place | No | Place name (city, landmark), resolved via Wikidata. Give place or lat+lon. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations cover the safety profile (readOnly, idempotent, openWorld), yet the description adds substantial non-annotation behavior: paid tool via x402 USDC on Base at $0.002 per successful call, and the specific failure mode that calling without payment returns a PaymentRequired object. It also discloses the CC BY 4.0 attribution obligation.
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 return shape, then inputs, then payment/legal terms — a sensible order with no filler. It is a dense single paragraph that runs long, but each clause carries distinct information an agent needs.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description fully describes the return payload (current fields, hourly series, daily summaries with min/max, precipitation, dominant symbol). Combined with timezone, licensing, and payment behavior, an agent has everything needed to invoke and interpret the call.
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 genuine meaning beyond the schema: it establishes that lat/lon and place are alternatives ("Give lat/lon, or a place name resolved via Wikidata") and that times are UTC. It doesn't restate bounds or the 1-48 hour range already in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: returns a weather forecast for a location, from a named source (MET Norway) with global coverage. It enumerates the exact payload (current conditions, hourly series, daily summaries), which clearly separates it from siblings like geocode, holidays, and fx_* tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
"Use for trip planning, logistics, event or outdoor decisions" gives clear positive usage context. It does not, however, name a when-not condition or point to a sibling alternative (e.g. geocode for resolving ambiguous names), so it stops short of full routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
geocodegeocode_reversegeocode_searchholiday_checkholidaysholidays_countriesholidays_long_weekendholidays_nextfx_convertfx_historyfx_latesthntime_converttime_nowweatherx402-gated weather and FX exchange rate data endpoints for AI agents.
122 pay-per-call agent tools via x402: task agent, web, speech, crypto safety, company checks
Weather, geocoding, FX rates, holidays, time zones, countries, earthquakes, sun and moon.
Agent-native CRM + get-booked platform. Operate over MCP, or pay per call via x402. No login.
Add one secure layer between your agents and this server.