Agent Data Tools: Everyday data

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

Annotations already declare readOnly/openWorld/non-idempotent/non-destructive, and the description adds substantive context beyond them: the data source and snapshot freshness (OurAirports, committed snapshot), latency ('answers in milliseconds'), and the cost model ($0.01/call, first 25 free, failed calls free). Crucially it explains the consequence of idempotentHint=false — 'each call is charged, so repeats are not free' — which the annotation alone would leave ambiguous.

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 lookup modes, then return fields, then data provenance, then pricing — a sensible information order with no filler sentences. It is a single dense run-on sentence chain, and the pricing clause is lengthy, but each element carries decision-relevant information.

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

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

With no output schema, the description compensates by enumerating the returned fields (codes, name, city, country, region, coordinates, elevation, size, scheduled service, Wikipedia link) and noting distances in nearest-airport mode. Combined with full schema coverage and explicit cost/read-only behavior, 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 coverage is 100%, so the baseline is 3, but the description adds real meaning the schema does not: the two mutually exclusive query modes (q versus lat+lon) and that the coordinate mode returns nearest airports 'with distances'. That mode distinction matters more than any single field definition, though it does not explain interplay between q and country/scheduled.

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

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

States a concrete verb and resource ('Look up airports by IATA or ICAO code, name or city') and covers both operating modes: identifier/name search and lat+lon nearest-airport lookup. The listed return fields and dataset scope (~9,500 airports) make it clearly distinguishable from neighbors like airport_status (live status) and geocode (addresses).

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 cases ('travel tools, flight data enrichment and geocoding airport codes') plus a worked example ('q=Stockholm'), which tells an agent when this tool fits. It stops short of naming alternatives or exclusions — e.g. it never says to use airport_status for live flight status rather than this tool — so it is clear context without routing.

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

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

Beyond the annotations it discloses refresh cadence (~every minute), cost ($0.01/call via x402 USDC or card key, first 25 free, failed calls free), and that repeats are not free — which directly explains the idempotentHint=false annotation. It also clarifies the empty-result behavior ('normal when nothing is reported'), so the agent knows an empty response is not an error.

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 capability and the field list before the calling convention, cost, and safety note. It is dense but every sentence carries information; the payment sentence is a bit long, which keeps it just short of the top score.

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

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

With no output schema and a single optional parameter, the description fairly complete: it names the returned field groups and their reasons, the freshness, the empty state, and the cost. It does not describe the response envelope (single object vs list of events), which is the one loose end for an agent parsing 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%, so the baseline is 3, but the description adds an example (airport=LGA) and the semantic that omitting the parameter covers the whole country and that no events means normal operations. That last point is genuinely new relative to the schema's 'default: all US airports with events'.

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: live FAA National Airspace System status for US airports, enumerating ground stops, ground delay programs, arrival/departure delays with min/max/trend, and closures. No sibling tool in the list covers aviation status, so there is no ambiguity to resolve, and an agent can tell exactly what this returns.

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

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

It gives a clear use context ('before travel planning, logistics or customer notices') and explains the two calling modes: an IATA code for one airport, or nothing for the country. What is missing is any exclusion or named alternative, though no sibling tool overlaps this domain, so that 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 upstream source and license (Open Library, CC0), that the check digit is verified before any lookup, that invalid or unknown ISBNs are refused uncharged, and the exact cost model ($0.01/call, first 25 free, failed calls free, repeats not free). Its 'changes nothing' claim is consistent with readOnlyHint=true and destructiveHint=false, and the repeat-charge note matches idempotentHint=false.

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 lookup action and the field list, and the example is placed usefully. It runs long in a single block and the closing 'Reads or computes only and changes nothing' slightly restates what readOnlyHint already declares, but no sentence is 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 input format, expected output fields, validation behavior, and cost/failure semantics. An agent has everything needed to decide whether to call it and how to interpret a refusal.

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

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

Schema coverage is 100% and the single parameter already documents 'ISBN-10 or ISBN-13, with or without hyphens', so the baseline is 3. The description adds modest value by noting spaces are tolerated and by giving a worked example (isbn=9780140328721), but no format normalization or edge-case rules beyond that.

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 ('Look up a book by its ISBN-10 or ISBN-13') and enumerates exactly what comes back (title, authors, publishers, date, pages, subjects, language, cover, Open Library link), which cleanly separates it from book_search and validate_isbn. It does not explicitly name a sibling it is not, so it stops short of a top score.

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 a reading list, a product listing or a citation' gives concrete when-to-use contexts, and the ISBN-only input implicitly scopes it away from title/author searching. There is no explicit when-not clause or named alternative, so it is clear context rather than full 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, destructiveHint=false and openWorldHint, and the description adds genuinely new operational facts: pricing ($0.01/call via x402 USDC or card key, first 25 free, failed calls free) and that repeated calls are charged, which explains the idempotentHint=false. The sentence "Reads or computes only and changes nothing" largely restates readOnlyHint rather than adding nuance, and there is no mention of result pagination or total-hit behaviour.

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

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

Front-loading is good — purpose and routing come before pricing — but the opening is a long run-on sentence that packs the field list, source, licence and filtering note together. The clause "Reads or computes only and changes nothing" duplicates the readOnlyHint annotation and could be cut without loss.

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 appropriately enumerates the returned fields, and the cost model is fully spelled out so the agent knows calls are metered. Minor gaps remain: no statement of what happens when no works match, and no hint on total availability versus the 20-item cap.

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 defines all four parameters and their bounds; the description's "up to 20 works" and "ISBNs (up to 5)" confirm the outputs rather than the inputs. It does add value beyond the schema by showing what q actually accepts (free-text words over title/author) through the worked example, which disambiguates q from the dedicated title/author params.

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 ("Search books by title, author or any words") and enumerates the returned fields plus the data source (Open Library catalogue, CC0). It separates itself from the neighbouring book_isbn/validate_isbn tools with "Use to find a book's ISBN, an author's works or editions before an ISBN lookup."

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 guidance (find an ISBN, enumerate an author's works or editions prior to an ISBN lookup) and clarifies a choice point with "Filter by author or title alone if you like." It also supplies a worked example, q=dune frank herbert, so the agent knows the expected query shape.

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

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

Adds substantial behavior beyond annotations: pricing ($0.01/call), access methods (x402 USDC or card key /credits), the first 25 calls free, and failed calls free. It also reinforces that the call reads/computes only and that repeated calls are billed, which is useful operational context not captured by 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?

Front-loads the resource and returned fields, then adds useful pricing context. It is somewhat dense, and the phrase 'Reads or computes only and changes nothing' partly repeats the readOnly/destructive annotations, but overall there is little waste.

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

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

For a simple one-parameter lookup with no output schema, the description fully covers the returned data fields, data source (World Bank open data), and billing behavior. 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 coverage is 100% and the parameter is already documented as ISO 3166 alpha-2 or alpha-3. The description nonetheless adds examples (SE, SWE, US, country=SE) that make the accepted format immediately clear, providing modest value beyond the schema.

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

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

States a specific verb and resource: returns facts about a country by ISO code, then enumerates the exact fields returned (name, ISO-2/ISO-3, region, income level, capital coordinates, population). It is clearly distinguishable from sibling geocoding and economic-indicator 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?

Gives a clear usage context ('Use to enrich records with country data') and a concrete example ('country=SE'). It does not explicitly compare against alternatives such as geocode or econ_population, so it stops short of full when/when-not 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, openWorld, non-destructive and non-idempotent. The description reinforces the read-only nature and explains the billing model (first 25 free, failed calls free, each call charged), which usefully justifies the idempotentHint=false, but it omits rate limits, result caps, or ordering of returned events.

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 what the tool returns and how to filter, followed by use cases and pricing. Dense but each sentence carries information; the pricing clause is long but material to an agent deciding whether to repeat a call.

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

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

For a two-optional-parameter read tool with no output schema, the description covers source, returned fields, filters, cost and side-effect profile. Only the full set of valid periods and any result-count limits are left uncovered.

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. The description adds example magnitude tiers (2.5, 4.5, significant), but it also narrows the period to 'day or week' while the schema allows hour and month, which adds little and slightly muddies the picture.

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

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

States a specific verb and resource (list recent earthquakes worldwide from USGS) and enumerates the returned fields (magnitude, place, time, depth, coordinates, tsunami flag, USGS link), so an agent knows exactly what it gets. No sibling tool covers seismic data, so differentiation is implicit but unambiguous.

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 contexts (alerts, news, travel checks) and a worked call example (period=day). It lacks any when-not-to-use note or mention of alternatives such as filtering by location, which is the main remaining gap.

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: discloses that data comes from a committed snapshot (so calls answer instantly), that the snapshot date is included in the answer, and that pricing is $0.01/call with 25 free and failed calls free — which also explains why idempotentHint is false ('repeats are not free'). This is exactly the kind of 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 resource and payload, then freshness, then pricing. Dense but mostly earned; the pricing/auth sentence is longer than needed but conveys genuinely useful invocation constraints.

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

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

With no output schema, the description carries the return-shape burden and does so: three metrics, units, ordering, and the snapshot date in the answer. Source/licensing (World Bank, CC BY 4.0) and cost model round out everything an agent needs 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 baseline is 3; the description adds meaning the schema lacks by stating results are ordered newest-year-first and that country accepts either ISO code form (SE, SWE) or English name, with a worked example (country=SE).

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

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

States the resource (GDP) plus the exact three metrics returned (current US$, real growth %, per capita) and the 1-10 year window, so the agent knows precisely what data comes back. The resource is naturally distinct from siblings like econ_inflation and econ_population, though no sibling is named explicitly to sharpen the boundary.

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

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

'Use for country comparisons, market sizing and macro context' gives concrete usage contexts. It stops short of naming alternatives or exclusions (e.g., when to prefer econ_inflation for price levels), so it's clear but not fully routing.

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

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

Goes well past the annotations: discloses that reads come from a committed snapshot (so latency is low), that the snapshot date is included in the answer, and that failed calls are free while repeats are charged. This is consistent with idempotentHint=false and readOnlyHint=true rather than contradicting 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?

Front-loads what the tool returns and the country identifier before moving to sourcing and billing. Dense but almost every clause carries information; the pricing detail is slightly over-weighted relative to the core semantics.

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, yet the description explains the shape of the return (1-10 annual values, newest first, snapshot date included). Combined with the source, licensing, and cost model, an agent has everything needed to call it correctly 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%, so both parameters are already documented with ranges and formats. The description repeats the country format (ISO code or English name) and adds the newest-year-first ordering, but that ordering concerns output, not 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 the exact metric (annual % change in CPI), source (World Bank), and the distinguishing sibling set (econ_gdp, econ_unemployment, econ_population) is implicitly excluded by naming CPI specifically. An agent knows precisely 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 use cases ('real-return, pricing and macro questions') and a worked example (country=SE), which is more than most tools offer. It does not explicitly say when to pick econ_gdp or econ_unemployment instead, so routing between the econ_* siblings is still inferred 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?

Beyond the supplied annotations (readOnlyHint=true, destructiveHint=false, idempotentHint=false), the description adds crucial billing context: $0.01/call via x402 USDC or card key, first 25 free, failed calls free. It also explains that repeats are not free, aligning with idempotentHint=false. It does not describe rate limits or full response shape, so a 4 is appropriate.

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 definition is front-loaded with the core resource and data elements, then usage, then pricing. It is dense but every sentence contributes: dataset identity, fields, use cases, example, pricing, and safety note. Slight redundancy in repeating the date range and default, but overall efficient.

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

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

For a read-only single-parameter tool with full schema coverage and clear annotations, the description is complete: it states what is returned, when to use it, the cost model, and that the snapshot’s record date appears in the answer. No output schema exists, yet the description adequately explains the return contents.

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 documents `days` as 1-365 with default 30. The description repeats the range and adds an example (`days=30`), but does not add meaningful semantics beyond what the schema provides. Baseline 3 is correct when the schema does the heavy lifting.

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 dataset (Treasury Debt to the Penny) and specifies the returned quantities: total public debt outstanding, debt held by the public, intragovernmental holdings, changes over 1/30/365 days, and a daily history. It clearly distinguishes this from siblings like econ_gdp, econ_inflation, and econ_treasury_rates by focusing exclusively on national debt figures.

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 states when to use it: 'when an agent needs the current US federal debt figure, its trend, or a daily series for a chart or brief.' The example `days=30` reinforces the typical call. However, it does not name an alternative or state when not to use this tool, which keeps it from 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?

Beyond the readOnly/destructive annotations it discloses latency ('every call answers at once'), data provenance and vintage (committed World Bank snapshot, CC BY 4.0, snapshot date in the answer), pricing per call, that failed calls are free, and that repeats are not free — which explains the idempotentHint=false flag. That is substantial 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 purpose, fields and country input before secondary detail; every sentence communicates something. The billing point is stated twice ('Price $0.01/call... failed calls free' and 'each call is charged, so repeats are not free'), which is mild redundancy.

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

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

With no output schema, the description still names the returned measures, their units, the year ordering and count, and notes the snapshot date is included in the answer. Combined with the disclosed cost model, 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 coverage is 100%, so the baseline is 3; the description still adds ordering information not present in the schema ('last 1-10 years with the newest year first') and restates accepted country identifiers with an example. It does not clarify what happens for out-of-range or unknown-country inputs.

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

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

The description opens with a specific verb and resource ('Population of any country from World Bank data') and enumerates the three returned measures. It is clearly distinguishable from siblings such as econ_gdp, econ_inflation and econ_unemployment by resource, so an agent can pick it without inspecting schemas.

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

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

It gives concrete usage context ('Use for market sizing, per-capita figures and demographics') and an example call (country=SE). It never names an alternative tool or states when not to use this one, so guidance is clear but not exclusionary.

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

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

Annotations already declare readOnlyHint and destructiveHint=false, so the 'reads or computes only and changes nothing' clause is largely redundant. What the description adds beyond annotations is valuable: per-call pricing via x402 USDC or card key, failed calls free, first 25 free, and a 'dated snapshot' rather than live data — all reinforcing the idempotentHint=false that repeat calls cost money.

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?

Coverage and scope are front-loaded, followed by use guidance and then the example. It is a dense single block with a slightly redundant safety clause, but no sentence is 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?

No output schema exists, yet the description specifies what the response contains (per-security averages plus marketable, non-marketable and all interest-bearing totals) and the time horizon. That is sufficient for correct invocation of 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% and the schema already states months is 1-24 with default 12, so the 'up to 24 months' text and months=12 example mostly restate it. The description does add a little on the security filter by naming values the schema truncates ('non-marketable series', 'floating rate notes', 'all interest-bearing debt'), but no matching syntax is given.

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?

Uses a specific verb-plus-resource framing: 'Average interest rates on US Treasury securities by month', then enumerates the security classes covered (bills, notes, bonds, TIPS, FRNs, non-marketable) and the aggregates. This clearly differentiates it from siblings like econ_national_debt or econ_inflation without the agent needing to open a schema.

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

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

'Use for the US government's borrowing cost, a rate trend or macro context; not a live yield curve' gives both a positive use case and an explicit exclusion. It stops short of naming a specific alternative tool for current yield-curve data, so routing to a sibling is still 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 annotations: discloses that reads come from a committed snapshot so latency is immediate, that the snapshot date is embedded in the answer, and the full billing model ($0.01/call, 25 free, failed calls free, repeats not free). This also explains the idempotentHint=false annotation rather than contradicting it.

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

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

Front-loads what the tool returns and the country identifier format, then covers provenance and pricing. Slightly heavy on payment mechanics for a tool description, but every sentence is informative and none are tautological.

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 carries the return contract itself: both series, units as % of labour force, 1-10 years newest-first, and the snapshot date included in the answer. An agent can call this without further discovery.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema lacks: accepted ISO forms (SE, SWE) alongside English names, and that years are returned newest-first. It does not describe edge cases such as unknown country names or out-of-range years.

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 (unemployment rate, total plus youth 15-24, as % of labour force) plus the data source and coverage window. It is clearly distinguishable from siblings econ_gdp, econ_inflation and econ_population, which cover different indicators.

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 a clear usage context ("Use for labour-market and macro questions") and a concrete invocation example (country=SE). It does not explicitly name an alternative tool or state when not to use it, 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.

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

Beyond the read-only annotations, it discloses source (Wikidata CC0), pricing, the free quota, that failed calls are free, and that repeated calls are charged. It also reiterates that the tool changes nothing, which is consistent with the readOnlyHint annotation.

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 return fields, then follows with usage, example, pricing, and safety notes. It is generally efficient, though the read-only restatement is partly redundant with annotations and the pricing sentence is 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?

For a simple two-parameter geocoding tool with no output schema, the description is complete enough: it names the source, lists returned fields, explains result ordering, gives an example, and covers billing and read-only behavior.

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

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

Schema coverage is 100%, so both the name and count parameters are already documented in the schema. The description adds an example and the fact that results are best match first, but it does not add syntax or matching nuance beyond that.

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: find places by name in Wikidata and return their coordinates and related place metadata. It clearly scopes this as forward geocoding by name, which distinguishes it from siblings such as geocode_reverse and geo_distance.

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 usage context: use before weather, sun, or distance lookups, and use it to disambiguate places with the same name. It does not explicitly route users to geocode_reverse for coordinate-to-place lookups, but the by-name scope makes the distinction reasonably clear.

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 readOnly/destructive/openWorld, yet the description adds substantial new context: the upstream data source and license (Wikidata, CC0), result ordering ('best match first'), which fields may come back (country, region, population, elevation), and the billing model ($0.002/call, first 25 free, failed calls free). The note that repeats are not free operationalizes idempotentHint=false in concrete terms.

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

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

Front-loaded with the core action and inputs, then use cases, then cost and safety notes. It is slightly overstuffed: the opening clause largely restates the title, and the billing point is made twice ('charged per call' and 'repeats are not free').

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 helpfully names the returned fields, and pricing plus the read-only guarantee cover the operational concerns. It does not specify the coordinate representation (lat/lon order, decimal precision) or failure behavior beyond 'failed calls free', which leaves a small gap for a tool returning coordinates.

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 by the schema, and the description adds little parameter-level detail. The example (name=Uppsala) and 'best match first' give mild ordering context for count, but no format guidance such as coordinate ordering or precision.

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 a place or address to latitude and longitude') and enumerates accepted inputs (city, town, landmark, address name). The forward direction is clear enough to distinguish it from the sibling geocode_reverse without opening either schema.

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

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

Explicitly names downstream uses ('for maps, distance, weather or routing') and provides a worked example (name=Uppsala), which gives an agent clear context for selecting it. It stops short of an explicit exclusion like 'use geocode_reverse to go from coordinates back to a place', so the alternative is only implied by the sibling name.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=true, and idempotentHint=false. The description adds important behavioral context beyond annotations: pricing, failed-call policy, auth options, and the fact that repeated calls are charged.

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

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

The purpose is front-loaded and most sentences carry useful information. The first sentence is dense with output-field details, but the overall structure remains efficient and readable.

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 needs to explain return values, and it does: nearest populated place, largest place within radius, country/ISO code, administrative region, population, distance, Wikidata id, and nearby places. It also covers pricing and auth, making the definition complete enough for an agent to call correctly.

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

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

Schema description coverage is 100%, so lat, lon, and radius are already documented in the schema. The description provides an example coordinate pair and mentions radius indirectly, but adds little parameter semantics beyond the schema.

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

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

The description states a specific verb and resource: turning latitude/longitude into place names. It distinguishes itself from the sibling geocode by explicitly saying to use geocode for place name to coordinates, and it names the key returned geographic fields.

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 such as labeling GPS points, photos, deliveries, or IP-derived coordinates. It also explicitly routes the opposite operation to the sibling tool geocode.

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

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

Annotations already cover read-only, open-world, non-destructive and non-idempotent; the description adds real context on top: the source (NLM API), a returned-field inventory, a non-medical-advice disclaimer, and cost behaviour ('first 25 free; failed calls free... repeats are not free') that concretely explains why idempotentHint is false. It does not contradict any annotation, though it omits rate limits or result-cap behaviour for a broad query.

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

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

Purpose and scope are front-loaded in the first clause, with the returned-field list and the pricing/disclaimer tail after. Almost every sentence carries information an agent needs, though the payment and 'repeats are not free' lines are somewhat verbose for what they convey.

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, and the description compensates by enumerating the returned fields (NCT id, title, status, phase, conditions, interventions, sponsor, enrollment, dates, location/country counts, link). With the safety profile in annotations and full parameter docs in the schema, 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?

Schema description coverage is 100%, so the schema already documents all five parameters including defaults and ranges. The description only lightly echoes them ('by condition, intervention or any words', 'optionally only recruiting ones') and adds no format or syntax guidance beyond the schema. Baseline 3 applies.

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

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

States a specific verb and resource ('Search ClinicalTrials.gov studies') plus the three axes it searches by (condition, intervention, any words) and a default filter ('optionally only recruiting ones'). No sibling tool overlaps this domain, so disambiguation is trivially satisfied and the scope is unmistakable.

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

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

Explicitly says 'Use to find trials for a condition or drug' and gives a concrete invocation example ('condition=type 1 diabetes'), which tells the agent the intended call shape. No when-not-to-use or alternative is named, but there is no sibling to route to, 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?

Annotations already declare read-only, non-destructive and open-world; the description adds genuinely new context: data provenance (own statutory rules for 8 countries vs Nager.Date elsewhere), the 2024-2100 validity window, and per-call pricing with 25 free calls and free failures. It also explains why repeat calls aren't free, which reconciles with idempotentHint=false, but does not discuss error behavior or coverage limits outside the 8 statutory countries.

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 what the tool returns and who it is for, then data sources, then pricing. Dense but nearly every clause carries information; the pricing/key sentence is long but justified for a paid endpoint.

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 lists the returned fields and their meaning (observed-day shifting, nationwide flag), which is what an agent needs. Remaining gaps are the year-range applicability for non-statutory countries and result format (array vs object), neither of which blocks correct invocation.

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

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

Schema coverage is 100%, with both parameters fully documented (ISO code or English name, year 2024-2100 defaulting to this year). The description only adds exemplar codes (SE, JP, CA) and a sample call, so it does not materially deepen semantics beyond the schema.

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

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

States a specific verb+resource ('Public holidays for a year in over 100 countries') and enumerates the returned fields (date, local and English name, nationwide flag, observed day), so it is unmistakable against siblings like weather, time or country.

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 a clear use context ('scheduling, delivery dates and business-day maths') plus a concrete call example (country=SE), but offers no explicit when-not guidance or named alternative — acceptable here since no sibling covers holidays.

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, the description discloses the computation method (mean synodic month), pricing and free-call structure, failed-call behavior, and the fact that repeats are charged. It also clarifies that the tool only reads or computes and changes nothing, which reinforces the safety 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 what the tool returns and stays reasonably concise. The final sentence partially repeats the pricing and read-only points, keeping it from being maximally tight.

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 one-parameter computation tool, the description covers return values, method, usage context, cost, failure behavior, and side-effect profile. No output schema exists, but the description adequately enumerates what comes back.

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

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

Schema coverage is 100% and the schema already documents the single date parameter, including its default-now behavior. The description only adds an example value, without extra constraints or format details, so 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 clearly identifies the resource and return fields: moon phase name, illumination percentage, age in days, and next new/full moon dates. It is unmistakably about lunar data, though it does not explicitly differentiate itself from nearby siblings such as sun or date_info.

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 usage contexts (calendars and night-sky planning) and a concrete example date. It does not state when not to use it or name alternatives, so it falls short of full when/when-not guidance.

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

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

Annotations already cover read-only, open-world and non-destructive behavior; the description adds genuinely new context: the cost model ($0.01/call, first 25 free, failed calls free) and the reason repeats are not free, which explains the non-idempotent hint. It does not describe the shape of the returned counts, but no output schema exists to cover that either.

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

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

Front-loaded with purpose and source, then use case, then cost. Dense but no wasted sentence; the 'reads or computes only and changes nothing' clause is partly redundant with readOnlyHint but short.

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

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

For a one-parameter read-only lookup, the definition covers purpose, source, cost and usage. The main missing piece is a hint about the return structure (per-period counts), which matters since there is no output schema.

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

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

Schema description coverage is 100% and the single 'package' parameter already documents scoped names ('@scope/name'). The description's 'package=hono' example duplicates rather than extends that, so 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 — download counts of an npm package over day/week/month from the official npm registry API — and the sibling set (pypi for Python) makes the npm scope meaningful. An agent can tell exactly what it retrieves 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 a clear use case ('judge how widely a dependency is used') and names the data source, but does not state when not to use it or point at alternatives like pypi for Python packages. Clear context with no explicit exclusions.

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

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

Annotations declare read-only and open-world, and the description adds genuinely new context: price ($0.01/call via x402 USDC or card key), first 25 free, failed calls free, and repeats are not free — consistent with idempotentHint=false. The 'reads or computes only and changes nothing' line plus data-source licensing goes beyond the annotation surface.

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 payload contents, then use cases, then a concrete example, then pricing. Dense but every clause carries information; the billing sentence is the longest but is 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 adequately enumerates the return bundle across four data domains. It leaves minor gaps: how 'short' the hourly forecast window is, response shape, and behavior on ambiguous or unknown place names.

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 required parameter with 100% schema coverage ('Place name, such as Stockholm or Lyon, France'). The description only adds a minimal example (place=Stockholm) and doesn't address ambiguity handling or whether a country qualifier improves resolution, so it adds little 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 composite resource — coordinates, country/region/population/elevation, current weather plus hourly forecast, sunrise/sunset/day length, and country facts — with named data sources (Wikidata, MET Norway). An agent can tell exactly what it gets back without opening a schema.

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

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

It gives concrete use cases (travel planning, event/delivery context, enriching a city name in a record) and frames itself as a cheaper bundle than 'the tools bought one by one'. It stops short of naming the specific siblings to skip (weather, sun, country, geocode), so the routing is implied rather than explicit.

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, the description discloses important behavioral details: pricing per call, first 25 free, failed calls free, and that repeated calls are charged. It also explicitly confirms the tool only reads or computes and changes nothing, consistent with readOnlyHint=true.

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

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

The description is front-loaded with what the tool returns, followed by usage, example, and billing details. It is reasonably concise, though the pricing and repeat-charge information is somewhat verbose and partially restates the cost point.

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

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

For a simple, one-parameter read-only lookup with no output schema, the description lists the returned fields, gives usage context, an example, and billing/side-effect behavior. Nothing essential for correct invocation 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?

The single parameter is fully described in the schema as the PyPI package name. The description adds a concrete example (package=requests), which helps clarify the expected value format beyond the schema's terse description.

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

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

The description clearly states the resource (a Python package on PyPI) and enumerates the returned information: latest version, summary, licence, required Python version, home page, release date and release count. The example and 'Use to check a dependency before installing it' make the tool's purpose unambiguous and distinguish it from sibling data 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?

It gives a clear usage context: check a dependency before installing it, with an example call. It does not mention alternatives or when not to use it, but there is no obvious overlapping sibling for PyPI package metadata.

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 computation is local ("No outside service"), that results are in UTC, that polar edge cases are handled, and the full billing model ($0.01/call, first 25 free, failed calls free, repeats charged). The billing note usefully explains why idempotentHint is false, and "reads or computes only and changes nothing" is consistent with readOnlyHint=true.

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

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

Outputs and scope are front-loaded and every sentence carries information, including the pricing clause. The semicolon-chained phrasing packs several topics (outputs, edge cases, billing, safety) into one dense block, which slightly hurts scanability.

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 enumerates the returned fields and their time basis (UTC), plus day-length and polar handling, which is sufficient for an agent to use the results. Pricing and safety are also covered, so nothing material is missing for a three-parameter read tool.

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

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

Schema coverage is 100%, with lat/lon ranges and the date default already documented in the schema, so the baseline is 3. The description adds only an example coordinate pair and the UTC output convention; it does not clarify date formats or invalid-coordinate behavior.

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

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

The first sentence names the concrete outputs (sunrise, sunset, solar noon, civil dawn/dusk, day length) and the inputs (any place and date), so the verb-plus-resource is unambiguous. It is clearly separable from siblings such as moon, time, weather and holidays, and even notes the polar day/night edge case.

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 supplies concrete usage context ("photography, events and outdoor planning") and a worked coordinate example, which tells an agent when the tool is appropriate. It stops short of naming alternatives or exclusions (e.g. use moon for lunar data, time for timezone conversion), so there is no explicit when-not-to-use 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?

Beyond the annotations it discloses DST handling, the 10-zone conversion cap, per-call pricing ($0.01 via x402 USDC or card key), the 25 free calls, and that failed calls are free. It also explains why repeats cost money, which is exactly the context an agent needs to interpret idempotentHint=false on an otherwise read-only 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?

Core capability, usage triggers, example and pricing are front-loaded in a logical order. The x402/MPP client-test sentence and the /credits parenthetical lean promotional and dilute focus, though they do carry payment-relevant information.

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

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

For a 3-optional-parameter read tool with no output schema, the definition covers defaults, limits, DST behavior, billing, and failure cost. An agent has everything needed to call it correctly and to anticipate the cost of repeating a 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 zone, at and to are already fully documented, and the description mostly restates them (UTC default, max 10 zones). It adds only a concrete example (zone=Europe/Stockholm) and the framing that 'to' converts the same moment. That is marginal added meaning over 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 first sentence names a specific resource and verb: exact current date and time in any IANA time zone, plus UTC offset, weekday, abbreviation and Unix timestamp, with optional multi-zone conversion. This is unmistakably distinct from siblings like sun, moon, or holidays, which share the temporal domain but not the function.

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 explicit when-to-use triggers: knowing the current time, scheduling across time zones, and turning a timestamp into local time. It also flags a secondary use case (paid end-to-end client test). No when-not guidance or named alternative is offered, but no sibling actually overlaps enough to require 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?

Annotations already declare readOnly, openWorld, non-idempotent and non-destructive, and the description adds real value on top: data provenance (Norwegian Meteorological Institute), city resolution via Wikidata, and explicit pricing ($0.002/call via x402 USDC or card key, first 25 free, failed calls free). The line 'each call is charged, so repeats are not free' usefully explains the practical consequence of idempotentHint=false. It does not cover error behavior for unresolvable city names or caching/latency.

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

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

Front-loaded with the core capability and return fields, then provenance, then cost — a sensible order. The description is dense but nearly every sentence carries information; only the 'Example: city=London' fragment and the 'any agent that needs the weather' clause are low-yield.

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 does so by enumerating the weather fields, their units, and the hourly horizon. Combined with 100% schema coverage on inputs, provenance, and pricing, an agent has what it needs to call it correctly; only the exact response shape/ordering is 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?

Schema description coverage is 100%, so the schema already documents lat, lon, city, and hours including ranges and defaults, making 3 the baseline. The description adds only modest semantics beyond that: the Wikidata-based resolution of city names and an example (city=London), while the '48 hours' and Celsius/mm units largely restate schema or return-value detail.

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

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

States a specific verb+resource (current weather plus 48-hour hourly forecast) and enumerates the returned fields: temperature in Celsius, conditions, precipitation in mm, wind, humidity, cloud cover, pressure. It also names the two input modes (city name or lat/lon), which cleanly separates it from siblings like air_quality, sun, or time.

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?

Offers broad use contexts (travel and event planning, logistics, agriculture, 'any agent that needs the weather') but never names an alternative tool or a when-not-to-use condition. The 'any agent that needs the weather' phrasing is close to tautological, so an agent still has to infer that air_quality/sun are different tools for different 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 already declare readOnlyHint, openWorldHint, destructiveHint=false, so the safety profile is covered; the description adds genuinely new context: MET Norway as the data source, a per-call price of $0.002 via x402 USDC or a card key, 25 free calls, and free failed calls. The repeated-charge warning ('repeats are not free') is useful cost behavior beyond the annotations, consistent with idempotentHint=false. Units (metric vs imperial) are never specified, which is a real behavioral gap for a weather payload.

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 returned fields, then usage, then pricing. Slight redundancy in stating the price twice ('Price $0.002/call...' and 'each call is charged'), 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 enumerating the returned fields, and it covers input forms, time horizon, and cost. Missing pieces are output units and differentiation from the `weather` sibling; otherwise an agent could call this correctly from the definition.

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` ranges and the 1-48 hour bound are documented there. The description only reinforces the city-vs-coordinates choice and supplies one example (city=London), adding little beyond the schema; baseline 3 applies.

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

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

States a concrete verb and resource plus returned fields (temperature, conditions, precipitation, wind, humidity, cloud cover, pressure) and the 48-hour horizon, with the accepted input forms (city name or lat/lon) named explicitly. It is not differentiated from the sibling tool `weather`, which appears to cover overlapping ground, so an agent cannot fully resolve which one to pick from this text alone.

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

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

Gives a clear use context: today's weather or tomorrow's forecast for travel, events, logistics, or a daily brief. It does not state when NOT to use it or point to the `weather` sibling as an alternative, so exclusion guidance is missing.

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