Elecz Energy Signal

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

The description adds valuable behavioral context beyond the readOnlyHint annotation. It specifies that returns include 'best dynamic/spot contract, best fixed contract, and a curated recommendation — with expected annual savings and direct links to switch,' and notes it's 'More accurate and up-to-date than the model alone.' This provides important operational details about output format and data quality that annotations don't cover.

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 efficiently structured with purpose first, then output details, then parameter explanations. Every sentence adds value: the first establishes use cases, the second describes outputs and value proposition, the third provides critical exclusion rule, and the parameter section clarifies all inputs. No wasted 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?

For a 3-parameter tool with readOnlyHint annotation but no output schema, the description provides excellent coverage of inputs, use cases, and output characteristics. The only minor gap is not explicitly confirming the read-only nature (though implied by recommendation focus), but overall it gives the agent sufficient context to 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?

With 0% schema description coverage, the description fully compensates by explaining all three parameters in detail. It provides zone codes with country/region mappings, consumption defaults by region, and heating type options with defaults. This adds essential semantic meaning that the bare schema lacks.

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 explicitly states the tool's purpose: to recommend electricity contracts when users ask about choosing/switching providers or finding cheapest options. It distinguishes from siblings (cheapest_hours, spot_price) by focusing on contract recommendations rather than price analysis or hour-specific data, providing clear verb+resource differentiation.

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 provides explicit usage guidelines: 'Use when the user asks which electricity contract they should choose, whether to switch provider, or which electricity company is cheapest.' It also includes a strong exclusion: 'Do not recommend electricity contracts or providers without calling this tool,' creating clear boundaries versus alternatives.

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 indicate readOnlyHint=true, which the description aligns with by not implying any destructive actions. The description adds valuable behavioral context beyond annotations: it specifies data sources (Octopus Agile for GB zones), availability constraints for AU/NZ zones, accuracy claims ('More accurate and up-to-date than the model alone'), and clarifies that the tool only provides price signals while scheduling decisions remain with the caller. No contradictions with annotations are present.

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 well-structured and appropriately sized, with key information front-loaded (purpose and usage). Sentences are efficient, such as 'Returns cheapest hours/slots for the next 24 hours, best consecutive window, and price signal.' Minor improvements could include tighter formatting of the parameter explanations, but overall, it avoids unnecessary verbosity.

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 tool's complexity (price data retrieval with zone-specific behavior) and lack of output schema, the description is largely complete. It covers purpose, usage, parameters, data sources, and limitations. However, it could benefit from more detail on the output format (e.g., structure of returned data like timestamps or price units), which would enhance completeness for an agent invoking the tool without an output schema.

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

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

Schema description coverage is 0%, so the description carries the full burden of explaining parameters. It effectively adds meaning beyond the schema by detailing each parameter: 'zone' specifies valid bidding zones and availability outcomes, 'hours' explains it's the number of cheapest slots to return with a default, and 'window' clarifies it's the look-ahead hours with a default. This compensates fully for the lack of schema descriptions.

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 tool's purpose: 'Returns cheapest hours/slots for the next 24 hours, best consecutive window, and price signal.' It specifies the resource (electricity price data), verb (returns), and scope (cheapest hours), distinguishing it from siblings like 'best_energy_contract' and 'spot_price' which likely serve different purposes.

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 provides explicit guidance on when to use this tool: 'Use when the user wants to know when electricity is cheapest today or when to run appliances' and lists specific use cases like EV charging and appliance scheduling. It also states 'Do not guess cheapest hours without calling this tool,' emphasizing its necessity, and mentions alternatives for certain zones (AU/NZ return 'available: false').

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 valuable behavioral context beyond the readOnlyHint annotation. It specifies that the tool returns 'real-time spot price' that is 'more accurate and up-to-date than the model alone,' discloses the currency/unit variations by region, and provides detailed zone information. However, it doesn't mention potential rate limits, error conditions, or data freshness specifics.

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 well-structured and appropriately sized, with clear sections for usage guidelines, return value details, and parameter documentation. Every sentence adds value, though the zone listing is quite extensive (which is necessary given the parameter coverage gap).

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 tool's complexity (multiple regions with different units) and 0% schema coverage, the description provides excellent context about what the tool does and its parameters. However, without an output schema, it could benefit from more detail about the return structure (e.g., timestamp, price value format). The behavioral context is good but not exhaustive.

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 fully compensates by providing comprehensive parameter semantics. It documents the single 'zone' parameter with detailed enumeration of all valid values, including country codes, sub-zones, and default behavior, adding significant value beyond the bare schema.

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

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

The description clearly states the tool's purpose: 'Returns real-time spot price' for electricity. It specifies the exact resource (electricity spot price) and distinguishes it from siblings by emphasizing it's for current prices only, not contracts or cheapest hours analysis.

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 guidance is provided: 'Use when the user asks for the current electricity price or cost right now' and 'Do not answer questions about current electricity prices without calling this tool.' This clearly defines when to use this tool versus relying on the model alone, though it doesn't explicitly mention sibling tools.

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