GridHub Electricity Market Data

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

Annotations already establish readOnlyHint, idempotentHint, and non-destructive behavior, so the description correctly focuses on what they cannot convey: oldest-first row ordering, the counterintuitive 'limit truncates from the OLDEST end' behavior, default and maximum window sizes, pagination via start/end, and the credential modes (Bearer key at 500 req/day, x402 pay-per-call, or truncated free sample mode). This is rich behavioral disclosure beyond annotations. The only remaining gap is that it doesn't state the response row shape or timestamp resolution, though an output schema exists.

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 most consequential gotcha (limit truncates from the oldest end) is front-loaded, and the dense paragraphs are each load-bearing. It is long, but the length is driven by genuine complexity (six metrics, two window regimes, three auth modes) rather than padding. Minor tightening of the auth paragraph is possible but would risk losing 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?

Given six parameters, two enums, an output schema, and open-world annotations, the description covers everything an agent needs to call this correctly: metric semantics, window defaults and limits, ordering/limit behavior, pagination, and the full authentication and sample-mode story. Because an output schema exists, it correctly does not spend space on return values.

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 already 100%, so the baseline is 3, but the description adds substantial meaning beyond the schema: metric units and semantics (wholesale price in local currency per MWh, demand in MW, generation per fuel with zone restrictions like GB/US-CAISO, carbon-intensity in gCO2/kWh GB-only, capacity European-only), the ~400-day annual default window for capacity, and the direction in which limit truncates.

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 opening sentence gives a precise verb+resource+scope: 'Time series for one metric in one zone over a start/end window (Unix seconds).' It enumerates exactly which metrics are available (price, demand, generation, carbon-intensity, interchange, capacity) with units, so the agent knows what this tool retrieves versus its siblings like get_latest and get_zone_brief, which the description explicitly positions as the alternative for current values.

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?

Explicit routing: for 'the latest N points' set start close to now, or use get_latest / get_zone_brief instead. It also gives window defaults, max window per call, pagination guidance, and sample-mode behavior, so an agent knows when this tool is and isn't the right choice without opening the schema.

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 safety (readOnly, idempotent, non-destructive), yet the description adds auth mechanics (Bearer ghk_key header vs x402/X-PAYMENT pay-per-call), rate limits (free key, 500 req/day), and degraded no-credential behavior (sample mode, 50-row history cap, results clearly marked). These are behavior traits not present 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?

Front-loaded with purpose and payload, then caveat, then auth. Every sentence is useful, though the auth/credential block is dense and could be trimmed for a tool whose primary job is data retrieval.

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?

An output schema exists so return values need not be explained; the description still covers the timestamp semantics caveat, alternatives, and authentication/sample-mode limits. Nothing an agent needs to invoke this correctly is missing.

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

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

Schema coverage is 100%, so the enum values and the api_key header preference are already documented. The description still reinforces the zone scope (per-region metric availability) and why api_key matters (free sample truncation), adding modest meaning beyond the schema's baseline.

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 ('most recent value of every metric one zone publishes') and enumerates the exact payload per region (price/demand, generation by fuel for GB and US-CAISO, carbon intensity for GB, interchange where available). It also names the sibling it is not (get_zone_brief), so an agent can differentiate without opening 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?

Explicitly states the triggering question ('what is the price/demand/carbon intensity in X right now') and gives a when-not/alternative rule: 'use get_zone_brief for a strictly at-or-before-now value with historical context', with the reason (day-ahead prices up to ~36h ahead).

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 by disclosing refresh cadence ('Rebuilt every 5 minutes'), full auth options (Bearer ghk_ key, x402 payment), the free-tier rate limit (500 requests/day), and the exact consequence of no credentials (sample mode, history capped at 50 rows). These are operationally decisive details an agent cannot get from structured fields.

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 purpose and usage examples before the auth/billing detail, and every sentence carries real information. The auth paragraph is dense but earn its place given the free-sample and pay-per-call behavior; only slight verbosity keeps it from a 5.

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, return values need no explanation, and the description still covers freshness, auth paths, rate limits, and degraded-mode behavior. Nothing an agent needs to invoke this correctly is missing.

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

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

Schema description coverage is 100% and the single api_key parameter is fully documented in the schema, including the header-vs-argument preference and sample-mode consequence. The description largely repeats that auth context rather than adding new parameter semantics, so baseline 3 applies.

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

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

States a specific verb and resource ('Current headline values for all 25 zones in one call') and immediately contrasts with the per-zone siblings via 'cheapest way to compare zones' and examples like ranking US ISOs. An agent can distinguish this bulk-snapshot tool from get_latest/get_zone_brief 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?

Provides concrete usage scenarios ('which European zone has the lowest price right now', 'rank US ISOs by demand') that clearly convey when this tool is the right pick. It does not, however, explicitly name alternatives (get_latest, get_history) or state exclusions, so routing is implied rather than spelled out.

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 the safety profile (readOnly, idempotent, non-destructive, openWorld), so the bar is lower. The description adds genuinely new context: the tool is free of cost and 'last error, if any' tells the agent the error field is optional. It does not discuss auth or rate limits, but for a zero-param read tool that is minor.

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

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

Three short sentences, each earning its place: what it returns, cost, and when to use it. The return payload is front-loaded and nothing is padded.

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 the response shape. It covers purpose, trigger condition, and cost, which is everything an agent needs to call a zero-parameter read tool 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?

The tool takes no parameters, so there is nothing for the description to disambiguate; the baseline for a zero-param tool is 4. The description correctly does not waste space restating an empty 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 ('Ingestion health per source and zone') plus the exact payload ('last successful fetch timestamp and last error'). It is immediately distinguishable from siblings like get_latest or get_history, which return data rather than health metadata.

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 it to explain stale or missing values before drawing conclusions from them' gives a clear triggering condition. It stops short of naming an alternative sibling or stating when not to call it, so it falls just short of the top band.

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

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

Annotations already cover the safety profile (readOnly, idempotent, openWorld, non-destructive), and the description adds real behavioral context beyond that: strict at-or-before-now freshness, the ~30-day comparison window, generation-mix coverage limits, and full auth/rate-limit/sample-mode disclosure (500 req/day, truncated history at 50 rows, one context block in sample mode, clearly marked).

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

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

Front-loads the purpose and contents in the opening sentence, then usage, then auth/sample mode. Dense and mostly free of waste, though the auth/sample-mode passage is lengthy and somewhat secondary to tool selection.

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 a 2-parameter schema at full coverage and an output schema present, the description needn't explain return values; it still covers freshness, coverage limits, auth, and sample-mode behavior. Nothing an agent needs to call this correctly is missing.

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

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

Schema description coverage is 100%, so zone enum and api_key are already fully documented in the schema; the description adds little parameter-level detail beyond reinforcing the header-vs-argument preference for the key. Baseline 3 is appropriate 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?

States a specific verb+resource ('composite, interpretation-ready snapshot of one zone') and enumerates exactly what the snapshot contains (price/demand/carbon percentile-vs-own-history, 24h trend, generation mix, one-line summary). This clearly distinguishes it from siblings like get_latest and get_history, which return raw single points or series without context.

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 triggering questions ('is electricity cheap/clean in X right now', 'good time to run a flexible workload') and argues against the raw alternative ('A raw price means little without this context'). It does not name a specific sibling to use instead nor state when NOT to use it, so it falls short of a 5.

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

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

Annotations already declare readOnly, idempotent, non-destructive and openWorld behavior, so the safety profile is covered. The description adds value the annotations do not: 'Free, no credentials needed,' which tells the agent no auth setup is required before calling. It stops short of noting rate limits or response size, but for a 25-item static catalog that is a minor gap.

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

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

Two tightly packed sentences with the core payload list front-loaded and the routing advice last. Every clause carries information (coverage count, fields, sources, cost/auth, invocation order) with no filler.

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

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

An output schema exists, so return values need not be explained, yet the description still summarizes them helpfully for routing. With no parameters, no credentials, and full annotation coverage, 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?

The tool takes zero parameters, and the schema accepts no properties, so there is nothing for the description to disambiguate. Baseline 4 applies; the description's field enumeration describes the response rather than 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?

States a specific verb and resource ('List the 25 electricity grid zones') and enumerates exactly what each entry contains (id, name, data source, timezone, currency, licence, attribution). An agent can distinguish this catalog-lookup tool from get_zone_brief or get_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?

Explicitly prescribes a trigger condition: 'Call this first if you are unsure which zone id to use.' That is clear when-to-use guidance, though it does not name the specific sibling tools (get_zone_brief, get_latest, get_history) that consume a zone id, nor state any when-not condition.

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