P0: FX, rates, news and weather

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

Annotations only cover safety (readOnly, idempotent, openWorld), while the description adds substantive behavior: pricing at $0.001 per call, the exact endpoint GET /eu/fx, the requirement for an x402 or MPP client, the alternative authenticated path with an Authorization: Bearer key, and the important guarantee that bad input is refused before any charge. That is far beyond what the annotations convey.

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 in the first clause, with payment mechanics after it, and every sentence carries distinct information. The payment/access-key sentence is long and comma-heavy, mildly reducing readability, but it is not padding.

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

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

With no output schema and no parameters, the description compensates by sketching the return contents (EUR base, roughly 30 currencies, publication date) and by explaining the two-step payment flow and the schema link. An agent knows what it gets, what it costs, and what to do with 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?

The schema has zero parameters, so the baseline is 4 and there is no parameter meaning to add. The description never implies hidden or optional inputs, which keeps the empty schema unambiguous.

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

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

The description names a concrete resource and scope: 'the latest ECB euro foreign exchange reference rates (EUR base, ~30 currencies such as USD, GBP, JPY)' plus the publication date. The word 'latest' implicitly separates it from the sibling eu_fx_history, but the sibling is never named, so differentiation is inferential rather than explicit.

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

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

'Use for euro exchange rates' gives a clear use context, and the description explains the two invocation paths (fetch the returned x402 request, or supply a P0 key to have the tool make the call). It stops short of stating when NOT to use it, e.g. that historical series belong to eu_fx_history, so there is no explicit exclusion.

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/idempotent annotations, it discloses the two operating modes (return the exact paid x402 request vs. with a P0 key actually execute the call), the $0.002 price, the deduction behavior, and that bad input is refused before any charge. That is exactly the payment/auth context an agent cannot get from annotations.

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

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

The purpose is front-loaded, but the text is a dense three-sentence block carrying a purchase URL and a truncated fragment ('with min.') that reads as a generation artifact. The pricing/key details earn their place; the garbled clause does not.

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

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

For a paid, open-world read tool with no output schema, it covers cost, auth header format, key acquisition, pre-charge validation, and points to a full schema for the response. The actual return shape of the history series is only referenced via link, not described.

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 ccy and days are already fully documented with defaults, pattern, and min/max. The description restates 'ccy=USD, days=1..30' without adding format or interpretation beyond the schema, so the baseline of 3 applies.

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

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

The description states a concrete resource and scope: daily ECB euro foreign exchange reference rates for one currency against EUR over at most the last 30 days. The word 'history' plus the 30-day bound implicitly separates it from the sibling eu_fx (presumably the current rate), though that sibling is never named.

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 a short euro exchange rate history' plus the hard 'up to the last 30 days' cap gives a clear when-to-use and an implicit when-not-to-use (longer histories need something else). It stops short of explicitly routing to eu_fx or another sibling for spot/long-range data.

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 (readOnly/openWorld/idempotent), the description discloses the non-obvious two-mode behavior: by default it returns a priced x402 request object rather than data, the exact cost ($0.005/call), that invalid input is rejected before charging, and that a P0 bearer key switches it to executing the call and deducting the price. That payment-deduction side effect sits in mild tension with readOnlyHint=true, but the description surfaces it explicitly rather than hiding it.

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

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

The description is front-loaded with the trigger and data sources, then the payment mechanics, then the key option — a sensible order with no filler sentences. The long embedded key-purchase URL and parenthetical pricing make it dense, but each element carries actionable 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 paid, dual-mode aggregation tool it covers cost, auth requirements, input validation, and geographic coverage limits. The main gap is that there is no output schema and the shape of the returned hazard data is deferred to an external schema link the agent cannot follow from the description alone.

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 bounds and the km (1..500, default 100) and days (1..30, default 7) ranges are already fully documented in the schema. The description adds no parameter-level meaning beyond restating that lat/lon identify the site, which is the correct baseline-3 outcome.

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 verb and resource — natural-hazard context for a point — and enumerates the three data sources it aggregates (NWS alerts, USGS earthquakes, NASA EONET events). That clearly separates it from `weather` and `news_latest`, but it never distinguishes it from `hazards_near_batch`, so sibling differentiation is incomplete.

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

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

"Use when you need natural-hazard context for a site by latitude/longitude" gives a clear triggering condition, and the parenthetical "(US only)" on NWS alerts tells the agent when part of the result will be empty. It stops short of naming alternatives such as `hazards_near_batch` or `weather` or stating when-not to use it.

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

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

Goes well beyond the readOnly/idempotent annotations: it discloses the $0.05 per-call price, the x402/MPP payment flow, that the tool returns a ready-to-POST request body rather than data by default, that invalid input is rejected before any charge, and that a P0 bearer key changes the behavior to an in-tool paid call with deduction. That is exactly the operational context annotations cannot carry.

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

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

Front-loads the trigger and scope, then the payment mechanics, then the key-based shortcut — a sensible order. It is dense and the final sentence is long, but every clause carries operational information rather than filler.

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

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

For a paid, two-mode tool with no output schema, the description covers the return shape (a paid request body plus schema link, or the data itself with a key), the auth requirement, the cost, and the failure behavior. An agent has everything needed to decide and invoke 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 km, days, and sites are already documented with ranges and the 1–10 item limit. The description adds only the 'lat,lon' string format for sites and the fact that km/days apply uniformly to every site, which is marginal 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 ('screen several sites for natural hazards at once') plus the concrete scope (up to 10 'lat,lon' points in one POST) and explicitly ties results to the sibling endpoint /hazards/near, so an agent can distinguish it from hazards_near 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?

Opens with an explicit trigger ('Use when you must screen several sites at once') and clarifies that each site is answered exactly like /hazards/near, which implicitly routes single-site work to that sibling. It stops short of naming hazards_near as the alternative for one site, so the exclusion is 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?

Annotations only declare read-only/idempotent/open-world; the description adds substantial behavior the annotations cannot convey: pricing ($0.001 per call), the two execution modes (returns an x402 request URL vs. executes with a P0 bearer key and deducts price), and that invalid input is rejected before charging. This is exactly the payment and charge context an agent needs before invoking.

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

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

Purpose is front-loaded in the first clause and each sentence carries new information (return shape, payment path, key path). It is dense and somewhat run-on, with a long embedded purchase URL, but no sentence is pure 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 paid, dual-mode tool with no output schema, the description covers the return contents, the price, the exact endpoint, the key-authenticated alternative, and the no-charge-on-bad-input guarantee. An agent has everything needed to decide and correctly invoke 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 q, lang, and limit are already documented with bounds and enum. The description only echoes the q= notion of a query and adds no constraint or format guidance beyond the schema, which is the baseline 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?

States a concrete verb and resource (top Wikipedia articles for a query) plus the returned fields (title, short description, lead-section extract). The subject matter (topic, person, place, company, coin, concept) makes it trivially distinguishable from siblings like weather, eu_fx, or news_latest.

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

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

The opening 'Use when you need knowledge search for facts about...' gives clear situational triggers. It does not name a sibling alternative or state when NOT to use it (e.g., for current events, news_latest is better), 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?

Because the annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, the safety profile is fully covered. The description still adds substantial behavior beyond this: the $0.002 per-call price, the distinction that without a key the tool returns the exact x402/MPP request rather than data, the guarantee that "Bad input is refused before any charge", and the alternative that with a P0 bearer key the tool executes the paid call itself. These are exactly the kind of behavioral traits an agent needs to know before planning, and none are in the annotations.

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

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

The description is front-loaded with the use case and data sources, then the mechanics, pricing, and key option. Each sentence carries information relevant to invocation. The key-purchase URL is verbose, and the long parenthetical about topics is slightly dense, which keeps it from a 5. There is no filler, though.

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, four-parameter tool with no output schema, the description covers the necessary things: the data returned (headlines with links and dates), the cost, the validation behavior, and the two execution modes with or without a key. It does not describe the shape of the returned JSON, paging, or whether the "link to the full schema" is always returned. These are minor gaps, but they matter for a 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 documents q, hours, limit, and topic, including array bounds and default values. The description adds only marginal meaning: it restates that q replaces the topic list and that topic count is fixed ("11 topics or your own q="). It does not mention hours or limit at all, so the baseline 3 is appropriate when the schema does the work.

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

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

The description uses specific verbs and resources, such as "recent headlines with links and dates", and names the concrete data sources (the "GDELT index", "US agency press releases"). An agent can immediately tell this tool apart from siblings like sec_filings or domain_report, which serve different content. The word "latest" and the topic parameter also set a clear recency or topical scope.

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

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

The phrase "Use when an agent needs recent headlines with links and dates" gives a clear condition for use, and the parenthetical note that "us-agencies and federal-register are US government sources" signals when to pick those variants. However, it names no sibling tool and gives no explicit exclusions, so the agent must infer that sec_filings and similar tools are alternatives. The guidance is good but not a full when-to-use versus alternatives statement.

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?

Against annotations that only declare readOnly/idempotent/openWorld, the description carries genuinely additive behavior: a per-call price ($0.002), the fact that bad input is rejected before any charge, the exact auth header format (Bearer p0k_…), a key-purchase URL, and how the paid-vs-unpaid path differs. This is exactly the cost and billing context annotations cannot express.

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

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

The use case is front-loaded and the pricing/validation/auth facts each earn their place, but the single dense paragraph packs a long purchase URL and two distinct execution modes into one block, which makes it harder to parse. A short split between 'what it does' and 'how billing works' would improve scanability without adding words.

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

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

Given no output schema, the description still tells the agent what comes back (rate, date, source), that a full schema link is available, and how to complete the fetch with an x402 or MPP client. The one gap is that it does not say what the returned document looks like in the paid-key path or whether the series/date echo back, but for a three-parameter read tool this is close to sufficient.

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 date, tenor, and series, including the default tenor of 10y and the enum meanings. The description only echoes the 10y default ('US Treasury par yield curve (default 10y)') and adds no format or edge-case guidance beyond what the schema states, which is the expected baseline 3 when the schema does the work.

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

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

The description names a specific resource set (SOFR from NY Fed, euro short-term rate from ECB, US Treasury par yield curve) and what is returned with it (date and source), which is far more concrete than the bare title 'Rates reference'. It is slightly blurred by the dual delivery modes ('returns the exact paid x402 request' vs. 'makes the paid call itself and returns the data'), so an agent must read the whole paragraph to know what it actually receives.

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

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

The opening 'Use when an agent needs an official reference rate with its date and source' gives a clear selection condition, and the P0 access key clause explains the alternative execution path. No sibling tools among eu_fx, hazards_near, weather, or news_latest overlap in domain, so no cross-tool routing is needed, but the description never explicitly says so or contrasts with eu_fx for FX-adjacent needs.

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 (readOnly/openWorld/idempotent), the description discloses the payment model ($0.001 per call), the x402/MPP protocol, that a URL to the full schema is returned, that invalid input is rejected before any charge, and the exact auth header format plus where to buy a key. It also explains the dual behavior: without a key it returns a request specification, with a key it executes the call and deducts the price.

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?

Content is front-loaded with the use case first, then mechanics. However, the final sentence is a long run-on stacking the key header, purchase URL, and deduction behavior, which makes the paid-call mode harder to parse than the first mode.

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 names the returned forecast fields, and it covers pricing, auth, and failure behavior for a tool with real monetary cost. It leaves minor gaps such as response shape/units and pagination or horizon limits relative to the 240-hour cap, but nothing that would block a correct call.

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

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

Schema description coverage is 100%, covering lat/lon ranges and the hours horizon default and limits, so the schema already does the explanatory work. The description adds no per-parameter meaning (e.g., how the horizon affects returned step granularity) beyond echoing the data fields, so the baseline of 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 ('weather forecast') with explicit scope ('latitude/longitude anywhere in the world') and enumerates the returned fields (temperature, wind, humidity, pressure, cloud cover). An agent can distinguish this from eu_fx, hazards_near, or news_latest without opening any schema.

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

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

The opening 'Use when you need a weather forecast for a latitude/longitude' gives an explicit triggering condition, and the two operating modes (no key vs. P0 key) are clearly delineated. It stops short of naming when to prefer a sibling tool or when this tool is inappropriate, so it is not a full 5.

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