utilpeek: macro snapshot (US Treasury yield curve, ECB FX rates, dollar-index proxy)

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

Annotations already cover readOnly/idempotent/openWorld, and the description adds substantial context beyond them: explicit non-coverage (VIX, equity indices, gold land in `not_included`), null commodities with `not_configured` when no EIA key, failure handling (`sources_failed` with null section, 503 when all fail and not charged), latency (under 0.2s cached, up to ~30s on the slow Treasury feed), price and free-tier limits.

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 sentence, followed by inclusion/exclusion, failure semantics, and operational facts. It is dense and mostly earns its length, though the licence/source attributions and docs/pricing sentence add bulk that could be trimmed for a fast-selecting agent.

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 an output schema present, the description need not explain return shapes, and it instead covers everything else an agent needs: scope, exclusions, degraded-source behavior, latency, cost, and free-tier limits. Nothing material for correct invocation is missing.

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

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

The tool takes zero parameters, so the baseline is 4; there is no parameter syntax for the description to clarify. The description correctly implies a no-argument call, and there is no gap to compensate for.

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 ('get/return one macro snapshot') and enumerates exactly what the snapshot contains: US Treasury par yield curve with spreads, ECB euro rates, a dollar-index proxy, EFFR/SOFR, WTI/Brent/Henry Hub. It also explicitly distinguishes itself from the sibling treasury_yield_curve, so an agent can route without opening another schema.

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

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

Gives a clear when-to-use ('needs the rates backdrop before a market decision') and names one alternative for a specific case ('For the Treasury curve on a past date use treasury_yield_curve'). It does not, however, address the FX-focused siblings (get_fx_rates, get_live_fx_rates) or other market-data tools, so when-not coverage is partial.

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