Agent Data Tools: Everyday data

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

With readOnlyHint=false, openWorldHint=true, idempotentHint=false already declared, the description adds the crucial missing context: it costs $0.001 USDC on Base per successful call via x402, which explains why a fact-lookup is flagged non-read-only and non-idempotent. Disclosing the World Bank data source and 'latest figure with its year' further clarifies freshness. Only minor gaps (failure/refund behavior) remain.

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

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

Three tight sentences, purpose front-loaded and the field list justified because no output schema exists. The parenthetical examples and source attribution are efficient, though the enumerated return fields make it slightly dense.

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 return fields, and it documents the sole parameter plus the payment model, which resolves the otherwise puzzling non-read-only annotation. Complete enough for a one-parameter lookup, though it omits any error/retry behavior for the paid 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% and the schema already states 'ISO 3166 alpha-2 or alpha-3 code'. The description's examples (SE, SWE, US…) merely illustrate the same accepted formats, adding marginal value 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?

The description opens with a specific verb+resource ('Facts about a country by ISO code') and enumerates exactly what comes back: World Bank name, ISO-2/ISO-3 codes, region, income level, capital coords, and latest population with year. An agent can distinguish this from data siblings like geocode or ip_info immediately.

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 to enrich records with country data' gives an implied use case but no when-not guidance and never points to an alternative sibling (e.g., wikipedia for narrative facts, geocode for coordinates). Usage is inferable but not routed.

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 beyond annotations by disclosing the data source (USGS), the freshness window, and critically the paid-call model ($0.001 USDC on Base via x402 per successful call), which explains why readOnlyHint is false despite this being a data fetch. Rate limits and failure behavior are not covered, keeping it out of 5 territory.

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 resource and scope, then adds filters, use cases, and cost in compact sentences. One long field-list sentence is dense but every clause carries information; 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, listing the returned fields (magnitude, place, time, depth, coordinates, tsunami flag, link) plus the two filters' defaults and the payment requirement gives an agent everything needed to call and interpret results 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% and both parameters are already documented there with their defaults and allowed values. The description restates the same day/week and 2.5/4.5/significant options without adding format or edge-case meaning, 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?

Names a specific verb+resource (recent earthquakes worldwide from USGS) and enumerates exactly what comes back (magnitude, place, time, depth, coordinates, tsunami flag, USGS link). No sibling tool overlaps this domain, so an agent can select it unambiguously.

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 alerts, news and travel checks" gives concrete contexts for when this tool fits. There are no alternative siblings to route against and no when-not conditions, so it falls short of a 5 but is well above implied usage.

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

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

Annotations declare openWorldHint and the safety flags, but the description adds genuinely new behavior: data provenance (Wikidata, CC0) and a precise cost model ($0.001 USDC on Base per successful call, paid via x402), which explains the non-read-only annotation. It stops short of covering failures (no-match, ambiguous names) or result ordering semantics.

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

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

Three tight sentences, front-loaded with purpose, then usage, then cost. Every sentence carries distinct information and none can be dropped without losing value.

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

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

With no output schema, the description compensates by listing exactly what is returned (coordinates, description, country, administrative region, population, elevation where recorded) and includes cost and sequencing guidance, so an agent has everything needed to call and interpret it.

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema, setting the baseline at 3. The description only indirectly touches parameters via 'best match first', adding no format or disambiguation detail (e.g., how to handle partial names) 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 (find) plus resource (places by name in Wikidata), enumerates the returned fields, and specifies ordering ('best match first'). An agent can distinguish this from siblings like weather, sun, or wikipedia 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 ('Use before weather, sun or distance lookups') and a disambiguation use case ('tell two places of the same name apart'). It names downstream tools but does not frame them as alternatives or state any when-not-to-use condition, so it stops short of a 5.

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

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

Annotations declare readOnlyHint=false and idempotentHint=false, and the description explains why: each successful call costs $0.001 in USDC on Base via x402, so it is not a free/idempotent read. The 'per successful call' phrasing also clarifies billing on failure. It does not detail error/retry behavior, keeping it below a 5.

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

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

Front-loaded with purpose, then coverage, use cases, and cost. Every sentence contributes, though the country enumeration and payment sentence make it slightly long. Still efficient and well-ordered.

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

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

There is no output schema, but the description specifies the return fields (date, local and English name, observed weekday) and the billing model, covering the essentials. Failure/error semantics are the only notable omission.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning beyond the ISO-code schema: it maps GB to 'England and Wales' and US to 'federal', and confirms the 2024-2100 year range. This usefully disambiguates the country parameter's scope.

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

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

The description names a specific resource (nationwide public holidays), enumerates the covered countries, lists the returned fields (date, local and English name, observed weekday), and states the coverage window (2024-2100). An agent can immediately tell this apart from every sibling.

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

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

It gives concrete use cases ('scheduling, delivery dates and business-day maths'), which sets the context clearly. It does not name alternatives or exclusions, but no sibling overlaps functionally, so the gap is minor.

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 the billing model ($0.001 USDC on Base per successful call via x402) — which explains the otherwise puzzling readOnlyHint=false/idempotentHint=false — and the computation method (local mean synodic month), signaling approximate accuracy.

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

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

Three tight sentences: outputs first, method second, cost last. Every clause carries information an agent needs, with no restatement of the tool name.

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

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

With no output schema, the description compensates by enumerating the returned fields and timezone (UTC), and it flags the payment requirement. 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 date parameter already documents its format and default. The description adds only 'for any date' and the UTC framing, so the schema does the heavy lifting; baseline 3 applies.

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

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

The description names the exact resource (moon phase) and enumerates the concrete outputs: phase name, illuminated percentage, age in days, plus next new and full moon. It is clearly distinguishable from neighboring astronomy/temporal siblings like sun, time, and weather.

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

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

'Use for calendars and night-sky planning' gives an application context but no when-not conditions and names no alternative tool for date/time work (sun, date_info, time). Usage is implied rather than routed.

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

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

Annotations declare readOnlyHint=false and idempotentHint=false, which would otherwise look odd for a stats lookup; the description resolves this by disclosing the x402 payment model ($0.001 USDC on Base, charged per successful call), implicitly explaining why repeat calls are not free. It adds real operational context beyond the structured hints, though it doesn't mention rate limits or failure handling.

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

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

Three sentences, each carrying distinct payload: what is returned, when to use it, and what it costs. The identifying information is front-loaded and there is no filler.

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

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

For a one-parameter, no-output-schema tool, the description covers the return content (day/week/month counts), the data source, and the payment requirement — everything an agent needs to decide to call it and to anticipate being charged.

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

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

Schema description coverage is 100% and the single 'package' parameter is already documented with examples (react, @scope/name). The description adds no further parameter semantics, so the baseline 3 applies.

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

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

States a specific resource (npm package download counts), the exact scope of data returned (last day, week, month), and the source (official npm registry API). This implicitly separates it from siblings like pypi and package, though it never names an alternative 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?

'Use to judge how widely a dependency is used' gives a clear motivating context but no when-not conditions and no comparison against the sibling tools (package, package-audit, pypi) that could plausibly answer related questions.

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 safety/idempotency flags, so the description carries the payment behavior: $0.001 in USDC on Base per successful call via x402. That is non-obvious, operationally critical context an agent must know before invoking. It doesn't cover failure/no-charge behavior or rate limits, so not a 5.

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

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

Three tight sentences: return fields, usage, then cost. The field enumeration occupies the opening sentence but earns its place given there is no output schema. No filler or repetition.

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 listing the returned fields, and it also discloses cost and usage context. For a single-parameter read tool this is nearly complete; only error/not-found and payment-failure behavior are left unspecified.

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

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

There is a single parameter with 100% schema description coverage ('PyPI package name'), so the schema already does the work. The description adds no format, casing, or normalization guidance beyond it, which is the baseline-3 case.

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

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

The description names the resource (a Python package on PyPI) and enumerates exactly what it returns: latest version, summary, licence, required Python version, home page, release date and release count. That is specific enough to distinguish it from siblings like package-audit or npm_downloads. It lacks an explicit verb (e.g. 'fetch/get') and never names the closest sibling it is not, so it stops short of a 5.

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

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

'Use to check a dependency before installing it' gives a clear triggering context for the agent. No alternatives or when-not-to-use conditions are named, so it lands at the 'clear context, no exclusions' level rather than a 5.

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

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

Annotations already cover the safety profile (destructiveHint=false, openWorldHint=true), yet the description adds real behavioral context: the $0.001 USDC-on-Base x402 payment requirement, that it is a self-contained computation ('No outside service'), that results are UTC, and that polar day/night is handled. It omits failure/refund behavior and whether the payment must be pre-authorized. The 'No outside service' claim sits slightly in tension with openWorldHint=true, but reads as 'no third-party data API' rather than a direct 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?

Three compact sentences, front-loaded with the returned quantities, then scope/method, then practical use, then cost. Every clause carries information — no filler and no repetition of the tool name.

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

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

With no output schema, the description usefully enumerates the returned fields and the polar edge case, and it discloses the per-call cost — enough to call correctly and anticipate billing. It would be stronger with a hint about the response shape (units, timestamp format) or payment-failure handling.

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% — lat/lon ranges and the date default are already documented. The description reinforces the 'any place and date' scope but adds no syntax, format, or timezone detail beyond what the schema provides, so the baseline 3 applies.

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

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

The description enumerates exactly what is computed — sunrise, sunset, solar noon, civil dawn/dusk, and day length — for 'any place and date', with the computational basis (standard solar equations) and edge-case handling (polar day/night) stated. An agent can distinguish this immediately from siblings like moon, weather, or time without opening the schema.

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

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

It gives clear use context ('Use for photography, events and outdoor planning') and scope ('any place and date', defaults handled by the schema). It does not, however, name when NOT to use it or point to adjacent siblings such as moon, weather, or time, which an agent might otherwise confuse for this capability.

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 the output fields, that DST is handled, the 10-zone conversion limit, and crucially the pricing/auth model ($0.002 USDC on Base via x402). The cost and payment mechanism are material behavior an agent must know before invoking, and the description covers them.

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

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

Four sentences, front-loaded with the core capability before usage and pricing. Dense but every sentence earns its place; the pricing detail is the only element that could be perceived as slightly tacked-on, but it is 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 listing the returned fields, and the annotations plus the explicit cost disclosure round out the picture. Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100%, so every parameter (zone, at, to) is already documented in the schema, including the ISO 8601 format and the max-10 constraint. The description restates 'any IANA time zone' and 'up to 10 other time zones' without adding format or edge-case detail, so it is 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 verb (get current date/time, or convert a moment) and resource (time in an IANA zone), and enumerates the returned fields (UTC offset, weekday, abbreviation, Unix timestamp). It is trivially distinguishable from siblings like weather or fx, so an agent knows exactly what 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?

Explicitly names three triggering scenarios: needing to know the time, scheduling across time zones, and converting a timestamp to local time. That is strong context, but it offers no exclusions or alternative tools for the closest cases, so it stops short of a 5.

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

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

Annotations cover safety metadata (readOnlyHint=false, openWorldHint=true, idempotentHint=false), and the description adds material context beyond them: the data provenance (Norwegian Meteorological Institute) and, critically, the x402 payment model at $0.002 USDC on Base per successful call — a cost/auth detail an agent must know before invoking. It still omits failure behavior, rate limits, and whether the forecast horizon changes cost.

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

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

Front-loaded with the resource and retrieval method, and the field enumeration is informative rather than filler since there is no output schema. The trailing list of use domains and pricing sentence are slightly padded but each carries real decision value, so only minor trimming is possible.

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

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

With no output schema, the description takes on the burden of describing returns and does so thoroughly (every returned field plus forecast length). Parameters are fully documented by the schema and payment is disclosed; only error/edge behavior and output units for wind are missing, which is a small residual gap.

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

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

Schema coverage is 100% and every parameter carries a description with range and default ('lat -90 to 90', 'lon -180 to 180', 'hours 1-48, default 12'), so the schema carries the semantics. The description only restates the 48-hour forecast ceiling and otherwise adds no parameter nuance, making the baseline of 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 resource and access path ('Weather for any point on Earth by latitude and longitude') and then enumerates exactly what is returned — temperature in Celsius, conditions, precipitation, wind, humidity, cloud cover, pressure, plus an hourly forecast up to 48 hours. Nothing about the tool's function is left ambiguous, and it is unmistakably distinct from every sibling (base-gas, fx, time, etc.).

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 use contexts ('travel and event planning, logistics, agriculture') and a catch-all for any agent needing weather, which is clear guidance for when to reach for it. It offers no exclusions or named alternatives, but none exist among the siblings, so the only real gap is minor.

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