Get Gas Intelligence

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

Annotations already provide readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds far beyond that: the DCGI withdrawal/restoration history, the still-withdrawn gas_to_grid $/MWh, the instruction not to quote cached scores, the honest null-handling of delivered_price, and the warning to read dcgi_status and gas_to_grid_status independently. This is exceptional behavioral disclosure.

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 dense and information-rich but overly long and unstructured. It front-loads the use case well, but then dumps a long return-object fragment and a complex index-correction history in a single run-on paragraph. The key warnings ('do not compare pre-2026-08-08 figures', 'do not quote cached DCGI scores') are buried mid-text. Every sentence earns its place, but the lack of paragraph breaks and ordering hurts scannability.

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, rich output schema, and many sibling tools, the description is remarkably complete. It covers the return shape, field semantics, omitted data (gas storage, LNG, firm capacity), data provenance via data_basis, current index statuses, and exclusions. The output schema also exists to document return values, so the description doesn't need to restate them. Nothing critical is missing for an agent to call this 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 coverage is 100%, giving a baseline of 3. The description adds value by explaining that 'state' is an alias for 'region' and giving examples of accepted values ('TX' | 'Texas' | 'Virginia'). It does not go into deeper semantics for each field, but the schema already documents both parameters, so the added alias/example clarification justifies a 4.

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: answering human questions about gas-fired or behind-the-meter power economics for US data centers. It explicitly names the GAS analogue of get_grid_intelligence and differentiates itself from get_gas_index and get_grid_intelligence. This is a clear, specific purpose that an agent can easily distinguish from siblings.

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 opens with 'Use when a human asks about gas-fired or behind-the-meter power economics' and gives concrete example user questions. It explicitly states exclusions: 'Do NOT use for electricity grid headroom (use get_grid_intelligence) or the DCGI score alone (use get_gas_index)'. This is excellent when-vs-when-not routing with named alternatives.

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