entsoe-mcp

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description's added value is edge-case semantics — inclusive start vs exclusive end, rejected tz='local', and the split_periods_by_zone / series_ended_by_zone output channels. That is genuine non-obvious behavior, though nothing is said about result size, limits, or cost of comparing many zones at once.

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 purpose sentence followed by dense, backtick-anchored field names that are easy to scan; nearly every clause carries operational meaning. The parenthetical GB day-ahead-after-2020-12-31 example is a bit of an in-joke but still illustrates the series_ended_by_zone case, so it earns its place.

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 spelled out, and the description covers the trickiest result channels well. However, for a 7-parameter, 4-required comparison tool with zero schema coverage, leaving `aggregation` and `endpoint` undescribed is a real completeness gap that could produce wrong comparisons.

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 0%, so the description carries the full burden, and it only partially delivers: start/end, tz and filters get real semantic detail, but `zones`, `endpoint` and especially `aggregation` (default 'daily') are never explained — aggregation silently changes the shape of every comparison. Coverage of roughly four of seven parameters keeps this at a minimum-viable 3.

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

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

The first line gives a specific verb and resource plus scope: 'Compare one endpoint across multiple zones.' That distinguishes it from the single-series sibling get_series, which is explicitly cross-referenced for filter semantics. It stops short of a full contrast statement naming when get_series is the right call instead.

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?

Concrete guidance is present: tz='local' is rejected and an explicit IANA tz is required for wall-clock alignment, filters are scoped to every zone, and an empty `[]` under series_ended_by_zone must not be read as 'no data yet'. What's missing is an explicit when-to-use-this-instead-of-get_series rule, so the agent must infer the split from the 'see get_series' pointer.

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, idempotentHint, and destructiveHint=false, and the description does not contradict them. It adds a useful behavioral hint that this is a pre-query safety check, but it does not disclose details like how lag is measured or how missing coverage is represented.

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 a single focused sentence that front-loads the core behavior and immediately adds a practical usage tip. Every word earns its place; there is no redundancy or 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?

Given the rich annotations and the presence of an output schema, the description covers the essential purpose and the key when-to-use scenario. It does not enumerate valid endpoint or zone values, but the nullable filters and sibling list tools make that a minor gap rather than a blocking one.

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 0%, so the description must compensate. The phrase '(endpoint × zone)' communicates that both parameters jointly define the scope and that they are likely optional filters, but it does not explain null/default behavior or how the parameters interact beyond the pairing.

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 action, 'Show ingest coverage and lag,' and clearly identifies the resource scope as '(endpoint × zone)'. This makes the tool's purpose distinct from sibling tools like get_series or list_endpoints.

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 description explicitly states when to call the tool: 'call before queries if you're not sure whether the data is landed yet.' It provides clear context but does not mention when not to use it or name an alternative tool, 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?

Annotations already declare a read-only, idempotent, non-destructive operation, so the description adds non-redundant behavioral detail: UTC default, start-inclusive/end-exclusive semantics, and tz='local' resolving to the FROM-zone timezone. This helps an agent avoid timezone misinterpretation.

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

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

Three compact sentences deliver all essential semantics in a scannable format. There is no filler, repetition of schema defaults, or unnecessary detail.

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?

The description covers timezone and interval semantics, which are the trickiest parts, and output/safety concerns are covered by schema and annotations. However, the aggregation parameter remains opaque, and there is no usage guidance relative to sibling tools, leaving the definition incomplete for a six-parameter API.

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?

With 0% schema description coverage, the description must compensate for parameter meaning. It explains start, end, and tz well, and from_zone/to_zone are contextually clear, but aggregation is completely undocumented with no allowed values or examples.

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: cross-border physical flow in MW between two adjacent zones. It is unambiguous and clearly distinct from sibling tools like get_generation or get_load.

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 intended use is implied by the resource definition, but the description never explicitly says when to choose this tool over alternatives or what it is not for. No exclusionary or comparative guidance is provided.

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 the description adds substantive behavior: start inclusive / end exclusive, the silent-truncation pitfall of end=2026-04-30, local-vs-UTC tz conversion at the boundary, and the series_ended response when a window passes a series' end. This is context 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-loaded with the core semantic (currency) then range semantics, then alternatives. Dense and mostly earning its space, though the GB/UK paragraph is long relative to its share of calls and could be one sentence shorter.

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 needn't be explained, yet the description helpfully clarifies the `period` block, `unit`, and per-row `currency`. Nearly complete except for the unexplained `aggregation` parameter, which matters for a tool whose default is raw rows.

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 0%, so the description must carry parameter meaning — and it thoroughly explains start, end, and tz (including accepted "local" / IANA forms and conversion semantics). However the `aggregation` parameter (default "raw") is never mentioned, leaving one of five parameters undocumented anywhere.

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 — day-ahead clearing price for a bidding zone — and immediately names the currency dimension that distinguishes it. It also explicitly separates itself from get_series (GB after 2020) and get_derivation (weighted metrics), so an agent can route 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?

Explicit when-not guidance: for GB windows after 2020-12-31 use get_series(endpoint="day_ahead_price_imrp"), and for generation-weighted metrics use get_derivation(slug="capture_price"). Both alternatives are named with concrete invocation hints.

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 read-only, idempotent, closed-world profile, and the description adds substantial behavior the annotations cannot: server-side aggregation limits, the series_ended signal with the GB/ENTSO-E cutoff and the capture_price_mid carry-on, per-slug row shapes, and the mixed_currency split-row rule with the warning not to average price columns across currencies.

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 the client-side-vs-server-side routing, then broken into labeled sections per slug and per caveat, which makes it scannable despite its length. The currency section is genuinely long and could be tightened, but each block carries non-redundant 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 9-parameter, multi-mode tool with an output schema, the description covers output columns, units, filtering, failure/ended-input semantics, and worked examples in three regimes. The remaining gap is the unexplained `to_zone`/`from_zone` pair, which leaves the caller guessing about a documented capability.

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?

With 0% schema description coverage, the description carries the burden well: it enumerates all slug values, explains that only tb_spread accepts `aggregation` (monthly vs annual) and multi-zone `zone` ('all', list, or CSV), and demonstrates `psr_types` with both names and raw B-codes plus `tz`. However, `to_zone` and `from_zone` are never mentioned at all, and `start`/`end` format is only inferable from examples.

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

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

Names the specific resources (capture price, capture rate, TBx spreads, emissions) and the specific operation (server-side generation-weighted aggregation from landed Parquet). It enumerates the exact slugs available and distinguishes each slug's output, so an agent knows precisely what it gets 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?

Explicitly says when to use it over the alternative workflow ('instead of fetching hourly prices + hourly generation yourself and weighting them client-side') and names the concrete reason (no row cap, no pagination). It also routes to siblings: list_derivations() for slugs and get_tb_spread for a single day's top/bottom hour timestamps.

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, so the bar is lower, and the description still adds real behavior: `end` is EXCLUSIVE while `start` is inclusive, `tz` switches between UTC defaults and wall-clock interpretation, and an out-of-range window returns a `series_ended` response naming the endpoint. It stops short of stating pagination or row limits for this tool (only implying them by contrast with get_derivation), so not a 5.

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

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

Front-loaded with the resource and unit, then temporal semantics, then two clearly delineated routing cases. Every sentence is functional — no restating of the name or filler — despite covering a lot of ground.

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 no explanation, and temporal semantics are well covered. But three of six parameters (including `aggregation`, which changes the result granularity) are undocumented in both schema and description, and `psr_types` is only implicitly pointed at via a GB-specific aside about list_psr_types.

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 0%, so the description must carry the load. It explains start/end/tz thoroughly, including the month-boundary trick and timezone interpretation, but says nothing about `zone`, `psr_types` (which looks up the accepted codes), or `aggregation` — the last is a string with default "raw" and no enum, leaving the agent guessing at valid values and their effect on output shape.

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

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

States a specific resource and metric — aggregated generation in MW per production type — which an agent can distinguish from get_series, get_load, and get_derivation without opening any schema. The description also names the sibling tools that take over in the cases where this one is the wrong call.

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 rules: use get_series(endpoint="generation_mix", zone="GB") for GB windows after 2021-06-15, and use get_derivation(slug="capture_price") for generation-weighted price metrics. Both name the alternative and the condition that selects it, which is exactly what an agent needs to avoid the wrong tool.

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 mark the tool as read-only, idempotent, and non-destructive. The description supplements this with meaningful behavioral detail: `start` is inclusive while `end` is exclusive, the UTC default is stated, and timezone interpretation via `tz` is explained. It also gives a concrete calendar-month example, which goes well beyond the structured annotation data.

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 compact, front-loaded with the core purpose, and uses clear formatting to separate the `kind` options from the time semantics. The calendar-month tip is the only extra detail, and it is practical and relevant. No sentence is wasted.

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 the output schema exists and annotations cover safety, the description explains most of what an agent needs: purpose, units, `kind` choices, time boundaries, and timezone handling. The main gap is the `aggregation` parameter, whose values and effect are never described, plus the format of `zone` is left to inference despite the `list_zones` sibling.

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 0%, so the description carries the burden of explaining parameters. It does explain `kind`, `start`, `end`, and `tz` clearly, including boundary and timezone semantics. However, it omits any meaning for `zone` and `aggregation`, and accepts having no enums for those fields, leaving the agent without guidance on valid aggregation values.

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 'Actual or forecast load (MW)' and immediately defines the key discriminator `kind = actual | forecast | both`. This names a specific resource (load) and a specific unit, clearly distinguishing it from sibling tools like `get_generation` or `get_day_ahead_prices`.

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 description gives operational context: it explains that `kind` selects actual, forecast, or both, and explains the time window semantics. However, it never states when to prefer this tool over alternatives or when not to use it, leaving the choice to be inferred mainly from the resource 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 cover read-only/idempotent/non-destructive, and the description adds substantial non-obvious behavior: start is inclusive while end is EXCLUSIVE, results are overlap-based rather than containment-based, tz changes whether start/end are UTC instants or wall-clock, and a data-quality caveat flags zones whose upstream feed stopped (GB, 2021-06-15) so missing announcements are not mistaken for zero outages. That last item is exactly the kind of silent-failure disclosure an agent needs.

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?

Dense and front-loaded: the resource identification comes first, then boundary semantics, then the timezone rule, then the data-gap caveat. No filler, though the telegraphic phrasing and unexplained 'UMM' acronym cost a little clarity.

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?

Because an output schema exists, return values need not be described, and the description handles the trickiest aspects (boundary inclusion, overlap, timezone, stale feeds). It is incomplete on the non-time parameters (min_mw, kind, zone), which is the remaining gap for a 6-parameter 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 description coverage is 0%, so the description must carry all six parameters — it explains start, end, and tz well, but zone, kind (default 'generation', implying other values exist) and especially min_mw (units/meaning of the threshold) are undocumented anywhere. Partial compensation only.

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 precisely — 'Generation-unit unavailability events (UMM)' — which clearly differentiates it from the sibling get_generation (actual generation output). It does not explicitly name the sibling it could be confused with, and the UMM acronym is left unexplained, so it falls just short of a 5.

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

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

Usage is implied by the window semantics ('An outage is returned if it overlaps the window'), which tells the agent how to query but not when to prefer this tool over get_generation or compare_zones. No explicit when-to-use or exclusion guidance is given.

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?

The description adds substantial behavioral context beyond the annotations: end is exclusive, tz controls wall-clock interpretation, aggregation meanings are explained, currency/unit behavior is documented, split_periods and series_ended responses are described, and process-type distinctions are spelled out. It also correctly stays consistent with readOnlyHint, idempotentHint, and destructiveHint=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?

Although long, the description is front-loaded with the core purpose and then organized by argument shape, time semantics, aggregation, and edge cases. For a 10-parameter generic tool spanning 14 endpoints, the length is justified and every section supplies actionable invocation guidance.

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-value structure need not be restated, yet the description still explains important response nuances such as currency units, mixed_currency, split_periods, related_series, and series_ended successors. Combined with full parameter guidance, it is complete enough for an agent to invoke the 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?

Schema description coverage is 0% across 10 parameters, so the description carries the full burden and does so effectively. It explains endpoint selection, start/end semantics, tz, aggregation, zone vs from_zone/to_zone shapes, psr_types, and filters with concrete examples and constraints.

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 states a specific verb and resource — a generic time-series query over any registered non-outage endpoint — and explicitly excludes the outage family. It clearly distinguishes itself from get_outages and list_endpoints, but it does not address when to use it versus specialized siblings such as get_day_ahead_prices, get_generation, get_load, or get_crossborder_flow.

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 description gives clear usage context: call list_endpoints to see available endpoints, choose argument shapes based on endpoint type, and use get_outages for outage-family endpoints. However, for a generic tool surrounded by specialized siblings, it does not explicitly say when to prefer those siblings over get_series, leaving the main alternative-routing question partially unanswered.

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/idempotent annotations, it discloses market-day semantics (23/25 hours on DST transitions), strict date validation that rejects time-bearing strings, currency behaviour per zone (EUR vs GBP), and a non-error `series_ended` response path with a pointer to the alternative endpoint. That is substantial behavioural context an agent could not infer 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 formula is front-loaded in the first two lines, then edge cases and currency semantics follow. Every sentence carries information not available in the schema or annotations — none of it is 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?

For a three-parameter derived-metric tool with an output schema and full annotation coverage, the description leaves no material gap: computation, units, validation rules, DST handling, currency, and the series-ended fallback are all addressed.

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?

With 0% schema description coverage, the description carries the load and does so for all three parameters: `x` is defined as the top/bottom count with common values 1, 2, 4; `date` is constrained to bare YYYY-MM-DD; `zone` determines the trading currency. It does not describe the accepted zone identifier format, which list_zones presumably supplies.

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 gives a precise verb-and-resource definition with the actual formula (TBx = sum of top X priced hours minus bottom X priced hours over day-ahead clearing prices for zone/date). It is clearly a derived benchmark, distinguishable from sibling get_day_ahead_prices, which returns raw prices.

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 establishes the context (daily battery-arbitrage benchmark over SDAC market days), typical X values, and what happens past a zone's series end, including that the response names the endpoint holding the prices. It stops short of explicitly stating when to prefer a sibling such as get_day_ahead_prices for raw prices.

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 mark the tool as read-only, non-destructive, and idempotent abstract. The description adds behavioral context beyond that by noting derivations are 'computed on-the-fly' from Tier-2 Parquet endpoints, and by clarifying the quirk that the JSON response calls 'capture rate' by 'quality_factor'. The 'Today:' qualifier also signals the set of derivations may evolve.

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 core purpose and then gives a detailed but purposeful enumeration of the available derivations. It is longer than a simple list, but each parenthetical adds meaningful semantic value, such as unit context, IPCC factors, and zone behavior. It could be restructured for readability, 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 parameterless catalog tool with a rich output schema And annotations, the description is complete: it names every current derivation, explains what they compute, relates them to get_derivation(), and flags naming quirks. An agent has enough context to call the tool and interpret the returned derivation 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?

The tool has zero parameterscm in its input schema, so the baseline is 4. The description does not need to explain parameters; it instead documents what derivations will appear, which is the relevant semantic content for a list operation. The passing mention of zone='all' for tb_spread is about a derivation's behavior via get_derivation(), not about this tool's parameters.

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 the specific verb 'List' and the resource 'computed-metric derivations available via get_derivation()', which is a concrete, non-tautological statement. It also distinguishes itself from sibling tools by framing its output as the catalog of derivations used by get_derivation, not as endpoints or data series.

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 description makes the usage context clear: use this tool to see which computed-metric derivations exist for get_derivation(). It does not explicitly state 'use this before calling get_derivation' or contrast with list_endpoints, but the connection to get_derivation and the enumerated list strongly implies the intended workflow.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds domain scope ('ENTSO-E') and the meaning of the listing, but it does not disclose additional behavior such as pagination, response size, or filtering semantics.

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

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

The description is a single, tightly worded sentence with no filler. The primary action is front-loaded and every word contributes to the meaning.

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 listing tool with an output schema, a no-argument invocation is usable, but the optional 'family' parameter is not explained and there is no usage context relative to sibling tools. This leaves a material gap for an agent deciding whether and how to filter.

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 0%, so the description must compensate for the undocumented 'family' parameter. The phrase 'endpoint families' weakly implies that 'family' relates to endpoint families, but it never explains accepted values, formatting, or filtering 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 description clearly states the action ('List') and the object ('supported ENTSO-E endpoint families'), which is a specific resource. It does not fully distinguish itself from sibling list_* tools beyond the word 'endpoint', so it falls just short of a 5.

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

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

There is no guidance on when to use this tool versus siblings, nor any explanation of when to supply the optional 'family' filter. The description only states what the tool does, not when or how to choose 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, and the description adds substantial behavioral context beyond them: source-native codes are not interchangeable, counts_as_generation=false means net flow/storage not production, and passing zone= yields taxonomy_note and endpoints. This is valuable, non-obvious behavior.

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 longer than average, but every sentence earns its place: it front-loads the core purpose, then provides essential caveats about taxonomy interoperability and generation semantics. No filler or redundant restatement of the schema is present.

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 the simple single-parameter schema, the existence of an output schema, and strong safety annotations, the description covers all relevant behavior: scoping, taxonomy differences, per-zone notes, endpoints, and counts_as_generation semantics. Nothing critical is missing for an agent to call the 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?

Schema description coverage is 0%, so the description must compensate. It explains that zone scopes the answer and that providing it adds taxonomy_note and endpoints. However, it does not specify the expected zone value format or what happens when zone is omitted, leaving a small semantic gap.

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 immediately states the specific verb and resource: 'List production-type (psr_type) codes.' It also clarifies the optional scope via zone and distinguishes the tool's content from siblings like list_zones and list_endpoints by describing the code-focused output.

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 description clearly tells the agent when to pass zone= and warns about cross-zone comparison caveats. It does not explicitly name alternative tools or state when not to use this tool, but the usage context is strong enough for an agent to decide correctly.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds the 'registered' scope, implying that the result is limited to registered zones, but it does not disclose behaviors like the active_only default or any filtering semantics. No contradiction with 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 a single, tightly written sentence with no fluff. Every word contributes, and 'registered ENTSO-E' adds meaningful specificity beyond the title. It is appropriately concise for a simple list operation.

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?

While an output schema exists and annotations cover safety, the description and schema together fail to explain the two optional parameters. An agent cannot determine what 'cluster' should be set to or what active_only=true means. The missing parameter semantics and lack of usage guidance make the tool definition incomplete for 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 description coverage is 0%, and the description is silent about both parameters. The schema provides only types and defaults for 'cluster' and 'active_only', with no explanation of what values they take or what effects they have. This leaves the agent unable to correctly set or interpret these parameters.

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 action ('List') and resource ('registered ENTSO-E bidding zones'), which clearly distinguishes it from sibling tools like compare_zones or list_derivations. The addition of 'registered ENTSO-E' goes beyond the title and gives concrete 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?

No guidance is provided on when to use this tool over alternatives. It does not mention that one might first list zones before using get_day_ahead_prices or compare_zones, nor does it give any exclusions or preferences. The agent must infer usage entirely from the tool name.

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