Emission Factors

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

Annotations cover the safety profile (readOnlyHint=true), so the bar is lower, and the description adds real substance: it discloses that both GHG Protocol methods are computed, the factor sources (eGRID subregion, Green-e residual mix), and how renewable_kwh is treated as zero in the market-based result. It also states the return payload (kg CO2e per method with factors used), which matters since there is no 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?

Three sentences, front-loaded with the core action and inputs before method detail. Every clause carries information (methods, factor sources, REC/PPA treatment, return format) with no filler or restatement of the title.

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 calculator with no output schema, the description adequately explains inputs, methodology, and the shape of the result. Gaps are minor: no mention of the year parameter's effect on market-based results, and no note on whether results are annualized or single-period, but the essential calling information is present.

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; the schema already documents kwh, zip pattern, year enum, and renewable_kwh. The description echoes the contractual-instrument semantics of renewable_kwh but adds no syntax or interaction detail beyond what the schema states, and never mentions the year parameter.

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 names a specific verb (Calculate), a specific resource and scope (Scope 2 CO2e for a facility), and the exact inputs (ZIP, kWh) plus both accounting methods. It clearly distinguishes itself from the sibling calculate_fuel_emissions by being the electricity/Scope 2 tool.

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 only implied: the agent can infer this is the tool for electricity-based Scope 2, but nothing states when to pick it over calculate_fuel_emissions, compare_sites, or lookup_emission_factor. No exclusions or prerequisites (e.g., US-only ZIP, year constraint) are framed as usage 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 readOnlyHint=true, so safety is covered; the description goes further by disclosing the default factor set (Cornerstone/AR6) versus edition=2025 (AR5) and that CO2e shifts slightly, plus that biomass CO2 is reported separately as biogenic. It does not discuss error handling or the 50-item cap, but the substantive behavioral caveats 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?

Long but dense and front-loaded: purpose first, then defaults, then input format with examples, then scope exclusions, then return values and sibling pairing. Every sentence carries information, though the description sits at the upper end of acceptable length.

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 only a readOnlyHint annotation and no output schema, the description carries the burden well: it states the returned shape ('per-item and total CO2e'), the default and alternate editions, the biogenic reporting convention, and the boundary against vehicle-fuel and Scope 2 use cases.

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 50% (quantity is undocumented), so the description must add meaning, and it does: it maps fuel classes to plausible units ('natural gas in therms/ccf/mcf/scf, propane/diesel/heating oil in gallons, coal in short tons') and explains the edition switch's effect on CO2e. This exceeds the baseline for a half-documented schema, though it does not fully document the quantity parameter's bounds.

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 with precise scope: 'Calculate Scope 1 stationary-combustion emissions (CO2, CH4, N2O and CO2e) for fuels burned on site.' It names the factor source and explicitly confines itself to stationary sources, which distinguishes it from calculate_emissions (Scope 2 electricity) named in the same description.

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-to-use ('fuels burned on site', 'stationary sources only'), when-not ('for vehicle fuel the CO2 per gallon is the same, but CH4/N2O factors differ and are not included'), and the alternative to pair with ('Pair with calculate_emissions for a facility's electricity (Scope 2)'). Routing is unambiguous.

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 only carry readOnlyHint, so the description does real work: it discloses the data source (last 7 days / 168 hours of EIA-930), the local-time basis, and that results are historical rather than predictive. It does not mention auth requirements, rate limits, or fallback behavior when a ZIP cannot be mapped to a BA.

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?

Purpose and scope are front-loaded in the first sentence, with data basis and return values following. The third sentence is a dense semicolon-joined run-on that packs return contents and the `between` behavior together, which is efficient but slightly harder to parse.

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 compensates by enumerating the returns (cleanest and dirtiest windows, % saved vs daily average, all hours ranked) and by stating the data vintage, timezone, and forecast caveat. The only minor gap is geo-resolution failure behavior, which is not essential to 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 100%, so all four parameters are already documented in the schema, making 3 the baseline. The description adds only a paraphrase of the `between` semantics (window limited to given local hours, e.g. overnight) and the default duration, which the schema already states; no extra syntax or interaction rules (e.g. zip vs ba precedence) are contributed.

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 — find the cleanest contiguous N-hour window for a flexible load — and immediately scopes it to a ZIP code or balancing authority. The parenthetical '(lowest grid carbon)' removes ambiguity about what 'cleanest' means, and the wording separates it from sibling tools like hourly_intensity or calculate_emissions.

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 concrete use cases (batch jobs, EV charging, pumping, HVAC pre-cooling) and explicitly says it is 'a scheduling guide from recent history, not a forecast,' which is the key decision boundary against forecast-style siblings. It stops short of naming an alternative tool by name and offers no explicit when-not-to-use case beyond the forecast caveat.

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 only readOnlyHint available, the description carries real behavioral weight: it discloses nullability rules (lowest_cost and best_combined are null unless every site has a rate; best_* = null with *_tied lists on ties), data sources and vintages (eGRID, Green-e residual mix, EIA-861 annual, ZIP's own 2023 utility average), and the time-zone basis for the daily 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?

Front-loaded with the action and scope before the dense per-site output inventory. The single paragraph is information-dense with little filler, though the long chain of returned fields pushes it toward the verbose side.

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?

No output schema exists, so the description must describe returns, and it does so thoroughly: per-site metrics, rankings, gap percentages, tie handling, and the annual figures gated by annual_kwh. An agent has everything needed to invoke and interpret 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 coverage is 100%, so the 3 baseline applies, but the description adds genuine meaning beyond the schema: it explains that $/kWh is the state-level latest full-year EIA-861 average with the ZIP's own 2023 utility average as reference, that duration maps to the cleanest daily window from a 7-day hourly profile, and that annual_kwh yields annual tCO2e and cost.

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 (Compare and rank) plus resource (candidate US sites / ZIP codes) with explicit scope (2-25, grid carbon and electricity cost). This clearly distinguishes it from siblings like lookup_batch and lookup_by_coordinates, which operate on single locations.

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 phrase 'in one call' and the target use cases (facility, data center, EV/flexible load) imply this is the batch siting tool, and the duration/annual_kwh params hint at when extra detail is wanted. However, no alternative sibling is named and no when-not-to-use condition is stated, leaving 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?

Annotations only declare readOnlyHint=true; the description adds the material behavioral fact that the underlying data is state-level from EIA Form 861, so ZIP-level precision should not be assumed. That granularity caveat is exactly the kind of context an agent needs, though it says nothing about freshness lag or coverage gaps for non-US ZIPs.

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 tight sentences, front-loaded with the resource and units, then the caveat and sibling routing. No filler and nothing repeated from the schema.

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 carries the return-value burden and does so: it specifies units ($/kWh and cents/kWh), the sector dimension, the monthly averaging period, and the geographic granularity. Nothing needed to call or interpret the tool 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?

Only one parameter, and schema description coverage is 100% (the ZIP pattern and format are fully documented in the schema). The description adds no parameter-level meaning 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 and resource (get the latest monthly average retail electricity rate) plus units, geography, and the sector breakout. It also names the sibling it is not (utility_tariff), so an agent can distinguish it without opening schemas.

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

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

Explicitly frames the when-not case ('a ballpark, not utility- or ZIP-specific tariffs') and routes to the correct alternative by name ('use utility_tariff for those'). The condition selecting each tool is unambiguous.

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 only declare readOnlyHint=true, so the description carries the behavioral load and does it well: it discloses staleness (data lags up to a day, not real-time), what the response contains (per-hour fuel mix, total generation, carbon intensity), and the methodology caveat (fixed per-fuel combustion factors on in-BA generation, no imports, so values won't match eGRID annual factors). These are exactly the traits an agent needs to avoid misusing the output.

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, zero filler, and front-loaded: the core capability and scope come first, followed by latency, output shape, and the fit/exclusion guidance. Every sentence carries distinct decision-relevant 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?

No output schema exists, yet the description states the return shape (time series with per-hour fuel mix, total generation, carbon intensity). Combined with latency, methodology, and alternative routing, an agent has everything needed to select and call this correctly.

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

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

Schema coverage is 100%, so the baseline is 3 and the schema already documents ba/zip/hours/aggregate. The description adds genuine meaning on top: it clarifies aggregate's semantics (24-hour average profile over the trailing 168 hours), warns that buckets are UTC, and redirects local-time windows to cleanest_hours. It adds little on hours/ba/zip, keeping it just above baseline.

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

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

States a specific verb+resource+scope: hourly grid carbon intensity (kg CO2e/kWh) for any US ZIP code, derived from EIA-930 fuel-mix data. It also names the specific alternative tools (cleanest_hours, WattTime, Electricity Maps) and the data source, so an agent can distinguish it from siblings like calculate_emissions or lookup_emission_factor 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?

Gives explicit when-to-use (demand response, load shifting, grid pattern timing/analysis) and when-not (inventory reporting, because methodology differs from eGRID). It routes the agent to alternatives for live/forecast data (WattTime, Electricity Maps) and to cleanest_hours for local-time scheduling windows. This is as complete as usage guidance gets.

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 only readOnlyHint=true in annotations, the description carries most of the behavioral burden and does it well: it lists the exact returned fields per row, explains the full=true switch and its ~2 KB per-ZIP payload size, and flags the 100-item cap. It omits error behavior (e.g., unmatched or invalid ZIPs), which keeps 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?

Purpose and batch limit are front-loaded in the first clause, and the second clause packs the return shape, the full flag, and a payload estimate with no filler. Two sentences, zero waste.

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?

There is no output schema, and the description compensates by enumerating the compact row fields and the fields returned when full=true, so the agent knows what it gets. Combined with the read-only annotation and 100% parameter coverage, nothing needed 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 coverage is 100%, so baseline is 3, but the description adds meaning beyond the schema by quantifying full=true output (~2 KB per ZIP, every field) and by restating the 100-ZIP batch limit for zips. The size/field detail is genuinely incremental over the schema's terse parameter 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?

Specific verb (look up) plus resource (emission factors) with an explicit batch scope (up to 100 ZIP codes in one call). An agent can distinguish this from single-value siblings like lookup_emission_factor or lookup_by_coordinates purely from the description.

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 a concrete usage rule — batch up to 100 ZIPs per call and split longer lists — which tells the agent when this tool applies. It does not, however, explicitly name the alternative for single-ZIP lookups or state exclusions, so it stops short of full 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?

readOnlyHint=true already covers the safety profile, and the description adds real behavioral context: an external US Census Geocoder round-trip before the lookup, and equivalence of output to lookup_emission_factor. It omits failure behavior (non-US coordinates, geocode misses), which keeps it short of 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 short sentences, front-loaded with what it does, then the mechanism, then the use case. No filler and every sentence carries distinct 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?

With no output schema, the description usefully states the return equals lookup_emission_factor's data, and explains the geocoding step. The main unaddressed gap is that the US Census Geocoder is US-only, so non-US coordinates fail silently as far as the description tells the agent.

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 both parameters (lat, lon) are documented in the schema. The description restates 'latitude/longitude' without adding units, range, or formatting guidance, so baseline 3 applies.

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

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

States a specific verb and resource ('look up emission factors') plus the input dimension ('by latitude/longitude'), and explicitly distinguishes itself from the sibling lookup_emission_factor by noting it returns the same data after geocoding. An agent can tell the two apart 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 a clear selecting condition: 'Useful when you have a facility address or lat/lon but no ZIP,' which implicitly routes ZIP-holders to lookup_emission_factor. It never states that alternative as an explicit instruction, so the guidance is clear but not fully closed-loop.

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 establish readOnlyHint=true, so the safety profile is covered, but the description adds real value beyond that: it discloses the distinction between location-based and market-based Scope 2 factors, the presence of the Green-e residual mix rate, the data year, and the important provenance caveat about the 2024 eGRID edition not being EPA-published. That provenance detail is behaviorally meaningful and not derivable 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?

It is front-loaded with purpose, then output contents, then alternative routing — a sensible order with no filler sentences. The long enumeration of return values is somewhat dense, but since no output schema exists, the listing is largely justified rather than wasteful.

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 appropriately carries the burden of describing return values, and it does so comprehensively. Both parameters are covered by a 100%-coverage schema, and the alternative tool is named, so an agent has what it needs to call this correctly; only the coordinate/batch variants are unaddressed.

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

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

Schema description coverage is 100%, and the schema itself already explains the ZIP pattern and the 2023/2024 edition enum in detail, so the baseline is 3. The description adds essentially no parameter-level detail beyond what the schema provides, leaving the schema to do all the work.

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 EPA eGRID electricity emission factors for a US ZIP code') and immediately enumerates the returned quantities, so the agent knows exactly what domain this covers. It is clearly distinguishable from siblings like utility_tariff or electricity_rate, which are about rates rather than emission factors.

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 explicitly routes the agent: 'For Scope 2 emissions from a kWh total, use calculate_emissions, which does the arithmetic for both methods' — naming the alternative and the condition that selects it. However, it is silent on the other closely related siblings (lookup_by_coordinates, lookup_batch) that an agent might otherwise confuse with this ZIP-based lookup.

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 readOnlyHint=true, the description discloses substantive behavior an agent cannot get from annotations: data availability is capped by the latest published quarter, later dates are unavailable, the default is the last 7 days of that quarter, and format=hourly returns large unit-hour records (with a concrete size example) that demand narrow windows. These are real operational constraints that shape how the tool should be called.

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 what the tool does, followed by output contents, availability constraints, then formats and use cases. Every sentence carries information, though the single dense paragraph is longer than strictly necessary and the return-field list partially duplicates schema documentation.

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 compensates by enumerating the return fields (CO2 in short tons, gross generation, heat input, NOx, SO2, primary fuel type, operating hours, derived kg CO2/MWh). Combined with the zero-required-parameter defaults and the publication-window caveat, an agent has everything needed to call it 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 100%, so the baseline is 3, but the description adds cross-parameter context the schema does not: the quarterly publication logic behind the days default, and how format=hourly should be paired with facility_id and 1-2 days. It also enumerates the returned measure set, which supports interpreting the facility-level 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?

States a specific verb and resource ('Get emissions from EPA Clean Air Markets Division (CAMD)') and narrows the universe precisely: fossil units over 25 MW reporting to the Acid Rain Program and CSAPR. This distinguishes it cleanly from calculation siblings like calculate_emissions or calculate_fuel_emissions, which derive values rather than retrieve reported CAMD data.

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?

Names concrete use cases ('plant-specific carbon accounting, state-level fossil emissions and "dirtiest plants in [state]" queries') and explains the default lookback window via the quarterly publication cadence. It does not explicitly say when to prefer a sibling (e.g., calculate_emissions) or when this tool is the wrong choice, so it stops 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?

Goes well beyond the readOnlyHint annotation: discloses the data source (OpenEI URDB/NREL), the fallback behavior when no default tariff exists (returns most recent and flags it in warnings), and the expired-tariff warning case. This is exactly the behavioral context a safe-read annotation does not provide.

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 what it returns and the data source, then layers fallback and exclusion notes. Dense and information-rich, though a few clauses (e.g., the expired-tariff parenthetical) could be tightened. Every sentence still carries distinct 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?

With no output schema, the description compensates by enumerating the returned fields (effective rate, fixed monthly charge, tier count, TOU indicator, effective date). Combined with the fallback/warning behavior and data source, an agent has everything needed to call and interpret 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 coverage is 100%, so the baseline is 3; the description adds meaning by explaining that a ZIP is resolved to the ZIP's utility via EIA ID, tying the zip and eiaid parameters together. It does not clarify utility-name matching, but the schema already documents all five 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?

States a specific verb+resource (get the utility-specific electricity rate) and sharply distinguishes itself from the state-average rate and from the sibling electricity_rate tool. An agent can tell exactly what this returns and how it differs from alternatives 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?

Explicitly names the when-not case and the alternative: 'Does not cover Texas retail electric providers (deregulated market) - use electricity_rate there.' This routes the agent away from the wrong tool. Input-method selection (ZIP vs eiaid) is also touched on via the ZIP-to-EIA-ID matching note.

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