Emission Factors

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

With no annotations, the description carries the full burden and does disclose the calculation methodology (eGRID subregion rate for location-based, Green-e residual mix for market-based) and the return shape (kg CO2e per method with factors used). It omits operational traits like determinism, rate limits, or permissions, but for a read-only computation this is solid 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?

Three sentences, front-loaded with the verb and resource, then methodology, then return value. Every sentence earns its place 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?

With no output schema, the description steps in to describe the return value (kg CO2e for each method plus factors), and it explains the calculation basis. A few details (units per input, whether year affects the market-based path beyond the schema note) are left to the schema, but nothing essential 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?

Schema description coverage is 100%, so the schema already documents zip, kwh, year, and renewable_kwh, including the market-based zero-counting rule. The description's mention of kWh 'not covered by RECs, PPAs or green tariffs' largely restates the renewable_kwh schema text, adding little beyond it. 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 (Calculate) plus a precisely scoped resource (Scope 2 CO2e for a facility) and enumerates the two GHG Protocol methods. An agent can distinguish it from calculate_fuel_emissions or lookup_emission_factor without opening the 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 clear context that this is a facility-level Scope 2 electricity calculation covering both location- and market-based methods, so no method selection is required. It does not name siblings or state when-not to use it, leaving explicit routing to inference.

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?

No annotations are provided, so the description carries the full burden, and it does disclose a lot: the emissions source/version, that biomass CO2 is reported separately as biogenic, and that it returns per-item and total CO2e. It omits operational details like the 50-item cap enforced by the schema and any error behavior, but for a read-only computation tool this is close to complete.

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 core purpose and scope, then adds unit guidance, the biogenic caveat, the stationary-vs-mobile limitation, and the sibling pairing. It is dense but every sentence contributes; a reader gets the essential constraints in the first two sentences.

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 no output schema, the description still explains the return shape (per-item and total CO2e, separate biogenic CO2). Combined with the scope, source, and unit coverage, an agent has everything needed to invoke it correctly alongside calculate_emissions.

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?

Top-level schema description coverage is 0%, but the description compensates by mapping acceptable units to fuel types (natural gas in therms/ccf/mcf/scf, propane/diesel/heating oil in gallons, coal in short tons) and showing the fuel/quantity/unit item shape via a concrete example. The nested property descriptions exist in the schema, so the description reinforces rather than duplicates.

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 (calculate Scope 1 stationary-combustion emissions) and names the exact gas species and data source (EPA GHG Emission Factors Hub 2025). It explicitly contrasts itself with the sibling calculate_emissions, which handles Scope 2 electricity, so an agent can distinguish the two without opening either 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 explicit routing: 'Pair with calculate_emissions for a facility's electricity (Scope 2)' names the alternative and the condition that selects it. It also states the exclusion clearly ('Stationary sources only') and explains why vehicle fuel is out of scope (different CH4/N2O factors), which is when-not 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?

With no annotations, the description carries the full burden and does well: it discloses the data source (EIA-930, ~7-day window), the time basis (local time), and the shape of what comes back (cleanest and dirtiest windows, % saved vs daily average, all hours ranked). It omits operational traits such as auth requirements, rate limits, or staleness/data-latency beyond the 7-day window.

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 tight sentences with the core purpose front-loaded, the data basis and timezone next, and the most important caveat ('not a forecast') closing. No filler sentences and nothing redundant.

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-optional-parameter tool with no output schema and no annotations, the description supplies everything an agent needs: what is computed, from what data, on what time basis, and what the response contains. Return-value explanation is present because no output schema exists to carry it.

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 the schema already documents ba, zip, and duration (including the default of 4). The description reinforces the 'N hours' window semantics and the ZIP-or-BA granularity, but adds little beyond what the structured fields state, so the 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?

The description opens with a specific verb and resource: 'Find the cleanest (lowest grid carbon) contiguous window of N hours in the day to run a flexible load'. It explicitly scopes itself against siblings like hourly_intensity by clarifying it is a historical scheduling guide, not a forecast, so an agent can route 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?

It gives concrete use cases (batch jobs, EV charging, pumping, HVAC pre-cooling) and a clear data basis (hour-of-day pattern of the last ~7 days of EIA-930, local time), plus the crucial 'guide from recent history, not a forecast' caveat. It stops short of naming which sibling to use instead when a forecast is wanted, so no explicit alternative 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?

With no annotations, the description must carry the behavioral burden, and it does disclose a lot: the exact metrics computed, the methodology split (location-based eGRID vs market-based residual mix), input bounds (2-25 zips), and the conditional output branch triggered by annual_kwh. It does not disclose failure modes (invalid or non-US ZIPs), data vintage, or latency cost of pulling hourly grid profiles, which are notable gaps for a multi-site batch computation.

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 verb, scope and cost/carbon target, then a compact per-site metric list, then the conditional branch and the returned ranks. Three dense sentences with no filler or repetition of the tool name.

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 no output schema and no annotations, this description successfully substitutes for the return documentation by enumerating per-site fields and the ranking outputs. It is nearly complete for the call itself; only error handling and data-recency behavior are left unstated.

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 the schema already documents zips, sector, duration and annual_kwh (including the 10 MW example and the COM/IND default). The description restates the same semantics ('for the sector', 'cleanest daily window', 'With annual_kwh...') without adding format, edge-case or default-behavior detail the 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?

States a specific verb+resource+scope: 'Compare and rank 2-25 candidate US sites (ZIP codes) on grid carbon and electricity cost in one call.' It also enumerates exactly what is produced per site (eGRID CO2e, Green-e residual mix, carbon-free %, retail $/kWh, cleanest window) and what ranks are returned, so it is readily distinguishable from point-lookup siblings like electricity_rate or hourly_intensity.

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?

Frames the use case clearly ('for a facility, data center or EV/flexible load') and the 'in one call' phrasing implicitly positions it against making repeated single-site sibling calls. It gives conditional guidance ('With annual_kwh, also annual tCO2e and annual cost'), but never explicitly names an alternative tool or states when NOT to use this bundling approach.

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?

With no annotations, the description carries the full burden and does well: it discloses data provenance (EIA Form 861), temporal granularity (monthly average, latest), and an explicit accuracy caveat that the value is state-level and not ZIP- or utility-specific. It omits operational traits such as auth requirements, rate limits, or freshness lag, keeping it from 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?

Three tightly written sentences: purpose and units first, then the accuracy caveat, then the intended downstream use. Every sentence carries information 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?

For a single-parameter read tool with no output schema and no annotations, the description covers output units, granularity, provenance, accuracy limits, and use case. An agent has everything needed to call it correctly and interpret the result.

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 baseline is 3, but the description adds real meaning by explaining that the ZIP input is resolved against state-level data rather than ZIP-specific rates — an important caveat an agent cannot infer from the schema alone.

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 (Get) and resource (latest monthly average retail electricity rate), plus units, geographic scope, and sector breakdown. It implicitly separates itself from the sibling utility_tariff by clarifying the data is a state-level ballpark rather than utility- or ZIP-specific tariffs.

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 gives clear context for use (state-level approximation, pairs with emission factors for carbon-cost estimation) and implicitly signals that utility_tariff should be used when actual tariffs are needed. However, it never names the alternative or states an explicit when-not-to-use rule, 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?

With no annotations, the description carries the burden and does well: it discloses the ~24-hour data lag and that the data is not real-time, and describes the return shape (per-hour fuel mix, total generation, carbon intensity). It stops short of stating auth requirements, rate limits, or pagination/truncation behavior for large hour requests.

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?

Four sentences, each front-loaded and additive: purpose, freshness caveat, return contents, use cases, and alternative tools. 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?

For a tool with no output schema and no annotations, it covers purpose, latency, return contents, and intended analyses, which is sufficient for correct invocation. Minor gaps remain around error behavior when ba/zip are both omitted and any volume limits, but nothing essential 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 all four parameters (ba, zip, hours, aggregate) are already fully documented in the schema. The description adds only the 'any US ZIP code' scoping and units (kg CO2e per kWh), which don't extend parameter semantics, so the 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 ('Get hourly grid carbon intensity ... for any US ZIP code') and names the underlying data source (EIA-930 hourly fuel-mix). It is clearly distinguishable from siblings like cleanest_hours and lookup_emission_factor 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?

Gives explicit use cases (backtesting demand response, post-hoc time-weighted Scope 2 emissions, analyzing grid carbon patterns) plus a when-not-to-use signal pointing to WattTime/Electricity Maps for live or forecast data. The ~24h lag note further defines the valid use window.

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?

No annotations are provided, so the description carries the full behavioral burden. The only trait it discloses is the 100-ZIP cap, which is already encoded as maxItems in the schema, and it says nothing about permissions, error handling for malformed or unknown ZIPs, or whether one bad ZIP fails the whole batch. Adequate but thin for an annotation-free tool.

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, front-loaded with the core purpose, then the routing rationale, then the constraint. Every sentence earns its place and there is 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?

For a single-parameter read lookup with no output schema, the definition covers purpose, alternative, and limit, which is nearly everything an agent needs. It leaves the partial-failure semantics (a bad ZIP in the array) unstated, which is the one remaining gap.

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% (the single 'zips' parameter is documented as an array of 5-digit US ZIP codes with a pattern and maxItems). The description only restates that multiple ZIPs are accepted, adding no syntax or format detail beyond the schema, so the 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 (look up) and resource (emission factors) with scope (multiple ZIP codes, single call), and explicitly names the sibling lookup_emission_factor as the per-item alternative. An agent can distinguish it from lookup_by_coordinates and lookup_emission_factor 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 says it is more efficient than calling lookup_emission_factor in a loop, which gives the agent a clear selection rule between the batch and single-item tools. It does not state an exclusion (e.g. that a single ZIP should go to lookup_emission_factor) or note behavior when some ZIPs are unknown, so it stops short of full when/when-not 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?

Without annotations, the description reveals the key behavioral trait that it performs an external geocoding step (US Census Geocoder) to resolve ZIP before lookup, which affects latency and failure modes. However, it does not mention potential limitations such as accuracy, rate limits, or error handling for failed geocoding.

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 sentences with zero waste, front-loading the primary purpose and then the mechanism and use case. Every sentence 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?

Given no annotations, no output schema, and high schema coverage, the description covers purpose, mechanism, and use case well. It could be more complete by mentioning error conditions (e.g., what happens if geocoding fails) or result format, but it is sufficient for an agent 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?

Schema coverage is 100%, and the description mentions 'latitude/longitude' but adds no new semantic detail beyond the schema's 'Latitude (decimal degrees)' and 'Longitude (decimal degrees)'. It does clarify that these coordinates are used for geocoding, which gives some context, but the baseline of 3 for high coverage 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?

The description states a specific verb and resource ('Look up emission factors by latitude/longitude') and explicitly explains the mechanism by referencing a sibling tool ('returns the same data as lookup_emission_factor'). This makes the tool's distinct purpose immediately clear compared to lookup_emission_factor.

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 provides an explicit condition for use: 'Useful when you have a facility address or lat/lon but no ZIP.' This directly tells the agent when to choose this tool over lookup_emission_factor without needing to infer.

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?

No annotations are provided, so the description carries the full load; it does so reasonably by spelling out the full return payload, the eGRID vintage, and a market-based factor alongside the location-based one. It leaves implicit that this is a read-only, idempotent lookup and says nothing about latency, caching, or coverage gaps for ZIPs that don't map to a subregion.

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 sentences, front-loaded with the action and scope, then a return-value inventory that earns its place because no output schema exists. The middle enumeration is long but each item is a distinct, non-redundant output.

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 no output schema, the description usefully compensates by listing the return fields, and it covers scope and usage context. It is not fully complete for a lookup in a crowded sibling set — it omits the coordinate-based and batch variants and gives no pagination or coverage caveats — but nothing essential for invoking it 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 both the zip pattern and the 2023/2024 edition semantics (including that 2024 is preliminary and not official EPA) are already documented. The description adds no parameter-level detail beyond what the schema provides, so the 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 — 'Look up EPA eGRID electricity emission factors for a US ZIP code' — and enumerates exactly what comes back (CO2e, CH4, N2O, NOx, SO2, mix, subregion, year, Green-e residual). This clearly separates it from lookup_by_coordinates and lookup_batch, the nearest 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?

Provides a concrete context — 'Use this for Scope 2 location-based and market-based emissions accounting' — which tells the agent when the tool applies. It never names the alternative (e.g., lookup_by_coordinates when a lat/long is available, or lookup_batch for many ZIPs), so routing between siblings is left to inference.

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?

With no annotations, the description carries the full behavioral burden and discloses key traits: quarterly CAMD publication, default window of the last 7 days of the latest published quarter, that later dates are unavailable, the per-facility summary default, and hourly unit records for small windows. It omits authentication, rate limits, error behavior, and rules for combining state and facility_id, but covers the main operational constraints well.

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 layers coverage, output fields, temporal constraints, format behavior, and use cases without repetition or filler. Every sentence contributes actionable context for selecting and invoking the tool.

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 complex EPA data source, no annotations, and no output schema, the description is largely complete: it lists returned fields, explains temporal availability, and contrasts summary versus hourly formats. It leaves a gap around required parameters—schema declares none required, but the description implies at least state or facility_id is needed—and does not address error handling or rate limits.

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 the baseline is 3, but the description adds meaning beyond the schema: it explains the default temporal window, that format=hourly returns unit-hour records suitable for small windows, and that state produces a state-wide aggregate. It also points to the summary_by_facility output for finding facility_id values, which is useful context not in the 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 opens with a specific verb and resource ('Get hourly unit-level emissions from EPA Clean Air Markets Division (CAMD) for a specific US power plant or state') and scopes the data source and reporting population. The specificity of the EPA CAMD source and plant/state-level actual reported data implicitly distinguishes it from generic computation siblings like calculate_emissions, even without naming them explicitly.

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 provides clear intended use cases: 'Use for plant-specific carbon accounting, state-level fossil emissions and "dirtiest plants in [state]" queries.' However, it does not name alternative sibling tools or state when not to use this tool, so it stops short of explicit when/when-not routing.

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?

No annotations exist, so the description carries the full burden and does so: data source (OpenEI URDB, NREL-hosted), ~85% utility coverage, fallback behavior when no tariff is flagged default (returns most recent and flags it in warnings), and expired-tariff warnings. It also enumerates the return fields, which substitutes for the missing output schema.

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 purpose and result shape before the caveats, and every sentence carries distinct information (coverage, source, fallback, exclusion). It is dense and somewhat long, but given the absence of annotations and an output schema the length is largely earned.

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 no annotations and no output schema, the description must explain both behavior and returns, and it does: return fields, data provenance, coverage limits, non-default fallback with warnings, and the deregulated-market exclusion. Nothing an agent needs to invoke it correctly appears 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 baseline is 3. The description adds non-obvious semantics beyond the schema: a ZIP resolves to the ZIP's utility by EIA ID, tying the zip and eiaid parameters together, and clarifying that matches are by utility rather than geography. It leaves sector/limit/utility to the schema, which is acceptable given full coverage.

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 ('Get the actual utility-specific electricity rate') and immediately scopes it ('not state average', 'for a US ZIP code or named utility'). It names the sibling it is not (electricity_rate for Texas deregulated retail) so the agent can route 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?

Gives an explicit when-not condition ('Does not cover Texas retail electric providers') plus the alternative to use instead (electricity_rate). It also describes the ZIP resolution path (ZIP matched to utility via EIA ID), so the agent knows which input form to prefer.

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