TexasHomeBills — Texas electricity plans

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

With no annotations, the description carries the full burden and it delivers real behavioral context: mandatory 'TexasHomeBills™' attribution with a link on every answer using the data, plus the free-non-commercial / Pro-commercial licensing boundary. It does not describe the shape of the returned content, which is a modest gap.

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 purpose and then the call-first directive, with the licensing/attribution constraint last. Dense but every clause carries actionable information; the ™ symbol is slightly noisy but minor.

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 no-parameter, no-annotation, no-output-schema metadata tool, the description covers what the tool is, when to call it, and the licensing/attribution obligation an agent must honor. Only the shape of the returned explanatory content is left unstated, which is a small omission.

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 takes zero parameters, so the baseline is 4. The description adds no parameter detail, but none exists to explain.

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 specifically what the tool returns — what TexasHomeBills™ is and how its numbers are computed — which is a distinct metadata/provenance purpose no sibling tool covers (all siblings are data-retrieval tools). An agent can immediately tell this apart from electricity_* and market_* tools.

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 ordering instruction ('Call this first'), states the goal (describe the service accurately), and names the required action (learn the attribution requirement). No ambiguity about when to invoke 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?

With no annotations, the description carries the full burden and does well: it discloses the data source (Power to Choose), cost boundaries (incl. delivery, excl. taxes), the estimate/non-offer caveat, and licensing constraints (free non-commercial with attribution, Pro for commercial). It omits return format and whether results are ranked or paginated.

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 dense sentences, front-loaded with the core definition and immediately followed by the estimate caveat and licensing terms. Every clause carries information, though the licensing sentence could arguably be split for readability.

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 6-param tool with no annotations and no output schema, the description covers the caveats an agent most needs (estimate, data date, EFL disclaimer, licensing). It implies per-utility results via 'in each Texas utility' but does not describe the shape or size of the return, leaving a minor 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%, so all six parameters are already documented in the schema; the baseline is 3. The description adds no parameter-level detail (kwh, months, EV fields) beyond what the schema states.

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 precise verb+resource+scope: the fixed-rate plan with the lowest estimated annual cost, per Texas utility, for a given usage. An agent can grasp the output shape from 'in each Texas utility'. It stops short of naming how it differs from the close sibling electricity_rank_plans, so 4 rather than 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?

Gives an explicit trigger ('Use for questions like "what is the cheapest electricity plan in Texas right now"') and an output-disclosure rule ('say it is an estimate as of the data date'). It offers no when-not conditions and does not route to alternatives such as electricity_compare_my_plan or electricity_rank_plans.

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 it does add a genuinely useful licensing constraint (free for non-commercial use with attribution; commercial requires Pro). However, it says nothing about data freshness, the basis of the savings estimate, or pagination/return shape, so the behavioral picture is only partially filled in.

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, zero waste, and the core action (compare my rate against cheapest plans, estimate savings) is front-loaded before the secondary licensing note. 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?

For a 4-parameter tool with no output schema, the description conveys the input concept and the headline result (yearly savings), and the schema documents utility and usage inputs well. What is missing is any sense of the returned comparison detail or how current the plan data is, which an agent would want before promising results.

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 75%, with the required current_cents_per_kwh left undocumented in the schema; the description usefully defines it as an all-in cents-per-kWh figure taken from the bill or EFL. That compensates for the gap and adds meaning beyond the schema, though it offers no guidance on the optional usage 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 verb (compare) and resources (household's current all-in rate vs. the cheapest plans in their utility) plus the output (yearly savings estimate). It is clearly distinguishable from bare listing tools like electricity_cheapest or electricity_rank_plans, though it never names the sibling it differs from.

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 must infer that this tool applies when the user supplies their own rate from a bill or EFL and wants savings rather than a raw plan ranking. There is no explicit when-to-use/when-not guidance and no pointer to alternatives such as electricity_cheapest.

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 provided, the description carries the full burden. It discloses important behavioral traits: data is computed daily, returns a summary by default with optional row-level data via include_rows, includes provenance (Power to Choose, EFL, EIA, BLS), and specifies licensing terms (free for non-commercial, Pro for commercial). It also notes data limitations (e.g., 'not verified by the FCC') and calculation methods. However, it doesn't describe response format, pagination, or rate limits, which are relevant for a data-heavy 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?

The description is extremely long, with a single paragraph-like block listing all 11 slugs and their definitions. While informative, it is not front-loaded: the core purpose ('original data products about Texas electricity plans') is buried at the start, followed by a massive enumeration. It would benefit from better structure, such as a bulleted list or separate sections, and the license and citation info at the end feels tacked on. The length is disproportionate to the tool's complexity (2 parameters).

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 complexity—a multi-dataset tool with 11 distinct products—the description provides comprehensive details about each slug, including data sources, update frequency, and limitations. Since there is no output schema, the description adequately explains what each slug returns (e.g., 'returns the summary'). It also covers licensing and citation requirements. However, it could be more complete by clarifying whether the summary includes metadata or row counts, and by explicitly stating the return format (e.g., JSON structure).

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 50%; the slug parameter has an enum but no description in the schema, while include_rows has a description. The description enumerates all possible slug values with detailed explanations, effectively compensating for the missing schema description. However, it doesn't add syntax or format details beyond what the enum provides. For include_rows, the description says 'set include_rows=true for every plan row', which is slightly more contextual than the schema's 'Also return every plan row (large).'

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 what the tool does, which is to return original data products about Texas electricity plans computed daily. It distinguishes itself from siblings by enumerating 11 specific slugs, each with a detailed definition, making it clear this is a catalog of datasets rather than a computation tool. However, the purpose could be more succinctly stated at the top, and the distinction from other market_* tools is implied but not explicit.

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 guidance is implicit: by listing all slugs, the description tells the agent what data is available, but it does not explicitly state when to use this tool versus siblings like market_grid_demand or electricity_price_trends. The agent must infer that this is for accessing original, precomputed data products. The inclusion of 'Cite the page url' and license terms adds some operational context but not selection 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 disclose real behavioral traits: the response structure (per-plan cost with/without EV, cost per mile, time_of_use section with exact free hours from each Electricity Facts Label or exclusion reason), data source (EPA efficiency from fueleconomy.gov), and licensing terms (free non-commercial, Pro for commercial). It does not cover failure modes or rate limits, 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?

Front-loaded with the core purpose and cost outputs before the finer time_of_use details. It is dense and long, packing three distinct response concerns plus licensing into one block, but nearly every sentence carries information relevant to calling or interpreting 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?

With nine parameters, no output schema, and no annotations, the description compensates well by explaining the response sections (fixed-rate costs and time_of_use) and licensing. It leaves some gaps, such as error conditions and whether results are scoped to a specific plan count, but is largely complete 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 100%, so the schema already documents all nine parameters including defaults and enums. The description restates several of these (ev_night_share default 0.80, home_night_share, ev_kwh_per_mile) without adding syntax or meaning beyond the schema, 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 precise verb+resource: the monthly/yearly cost of home EV charging on cheapest fixed-rate plans in a Texas utility, including cost per mile and a time_of_use section. The EV-charging scope is specific enough to distinguish it from the generic electricity_cheapest and plan-comparison siblings, and it explicitly rules out a gasoline comparison.

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 input selection guidance ('Give ev_miles plus a vehicle ... or ev_kwh_per_mile') and a scope exclusion ('No gasoline comparison (we do not collect gasoline prices)'). It stops short of routing against siblings like electricity_cheapest, but the intended use 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?

With no annotations, the description carries the burden and discloses several useful behavioral traits: empty result semantics, split ZIP codes between utilities, and commercial licensing restrictions. It still does not state read-only safety, return format, or error behavior beyond the empty case.

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 in the first sentence, followed by compact caveats about empty results, split ZIPs, and licensing. Every sentence carries useful information with no redundancy.

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 simple lookup with no annotations and no output schema, the description covers the core purpose and empty-result behavior. It is incomplete on parameter requirements since both are optional, and it does not describe the returned utility representation.

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%, with zip documented but city undocumented. The description adds that ZIP is the most precise option and city is an alternative, but it does not explain city format or clarify that at least one of the two optional parameters should be supplied.

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 utility/TDU serving a Texas ZIP code or city. It is clear what the tool returns, but it does not explicitly distinguish itself from siblings like electricity_utilities or market_texas_retail.

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 description: use ZIP for precision or city as an alternative, and interpret an empty result as outside the competitive market. However, there is no explicit when-to-use, when-not-to-use, or named alternative tool 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 it does add genuinely useful non-schema context: a licensing constraint (free for non-commercial use with attribution, Pro required for commercial). However it says nothing about freshness, pagination, or what a result looks like, so the behavioral picture remains thin for a content-retrieval 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?

Two tight sentences, with the subject matter front-loaded before the licensing note. Nothing is redundant, though the space saved could have been spent documenting the two parameters.

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 annotations, no output schema, and zero parameter descriptions means the description is the only source of behavioral information, and it omits the parameters entirely. For a tool with an enum parameter and a bounded limit, an agent cannot call it confidently without opening the 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% and neither parameter is mentioned in the description. The agent gets no explanation of what 'lang' controls (output language? source language?) or that 'limit' defaults to 10 and caps at 50, information that exists only in the raw 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?

States a specific resource — news and guides about Texas electricity — and enumerates the covered topics (rates, contracts, saving energy, outages, rules). It is distinguishable from the sibling data/market tools by being editorial content, though it never uses an explicit verb like 'retrieve' or 'list'.

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 pick this over the numerous electricity_* or market_* siblings, nor any exclusion or prerequisite (e.g. that this is editorial content rather than pricing data). The context is only implied by the word 'news'.

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. It usefully discloses a real constraint beyond the schema: free for non-commercial use with attribution, commercial use requires Pro. However, it says nothing about authentication, rate limits, read-only nature, or what happens with an invalid id, so the transparency is partial.

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?

A single front-loaded sentence that leads with the core action before listing returned fields. It is dense but every clause names a distinct output artifact; the trailing licensing sentence is justifiably separate.

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, so the description must describe returns, and it does so thoroughly (prices at three usage tiers, term, fees/credits text, parsed bill credit, EFL link, monthly and annual estimates). The main gap is operational detail: valid id format, error behavior, and when to prefer sibling tools.

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 67%: kwh and months are documented in the schema, while id is a bare integer. The description adds some value by linking usage to output ('estimated monthly bill at several usage levels and the annual estimate for the given usage'), clarifying what kwh/months drive, but it adds no format or constraint detail beyond the 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 opens with a specific verb+resource combo ('One plan by id') and enumerates the plan attributes returned, so an agent immediately understands this is a single-plan lookup. It implicitly separates itself from list-oriented siblings like electricity_cheapest or electricity_rank_plans, but never names them, so the differentiation is inferred rather than stated.

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: you fetch a single plan when you already have its id. There is no explicit guidance on when to reach for this versus electricity_cheapest, electricity_rank_plans, or electricity_compare_my_plan, nor any statement about how to obtain a valid id. The licensing note (free non-commercial, Pro for commercial) is the only explicit usage constraint, and it concerns compliance rather than tool selection.

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, so the description carries the burden. It usefully discloses data sources (BLS CPI, EIA Texas average) and a commercial-use/licensing constraint, which is real behavioral context. However it omits update cadence/freshness and doesn't state the read-only nature explicitly, leaving gaps for a no-annotation 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?

Front-loaded with the inflation-comparison framing, then the datasets, the anchor question, and licensing. Slightly dense in one run-on sentence but every clause carries information; 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 annotations and no output schema, the description must convey what is returned, and it does: three named datasets (CPI comparison, Texas EIA average, monthly index series). Adequate for a zero-param retrieval tool, though freshness/cadence is not stated.

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 takes no parameters, so there is nothing to document; the baseline for a zero-param tool applies. The description correctly spends its words on output content instead.

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 (electricity price trends) and scope (inflation-adjusted: CPI electricity vs all items, Texas residential EIA average, monthly index). This clearly differentiates it from siblings like market_wholesale_prices and electricity_cheapest, which cover prices but not the inflation-comparison angle.

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 an anchor question ('are electricity prices going up in Texas?') that implies when to reach for it, but names no alternatives or exclusions. An agent must infer that this is the trends/inflation tool versus the snapshot tools — usable but not explicit 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?

With no annotations, the description carries the full burden and does well: it discloses annualization methodology, month-by-month bill-credit cliff modeling, the exclusion policy, per-item URL citation, and a licensing constraint (free non-commercial with attribution, Pro for commercial). It omits permissions/auth mechanics and any rate limits, but the modeling behavior is unusually well explained for an unannotated 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?

Front-loads the differentiator (annual cost, not the 1,000 kWh price) before the methodology and caveats, and each sentence is information-dense. The licensing sentence is somewhat tangential but still earns its place for commercial users.

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 10-parameter ranked-list tool with no output schema, the description covers the ranking basis, exclusion semantics, return shape (items with urls), and usage rights. Combined with 80% schema coverage it gives an agent enough to call correctly, though it doesn't explain pagination or default limit behavior.

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 80%, so the schema already documents most parameters (kwh, term, months, utility, EV fields). The description reinforces include-driven exclusions and the annual-cost vs sticker-price distinction but adds no syntax or default details beyond the schema. Baseline 3 is appropriate.

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 (Rank), resource (every electricity plan), and scope (a Texas utility, by ESTIMATED ANNUAL COST). The clause 'not just the 1,000 kWh price' actively distinguishes it from generic cheapest-price tools like electricity_cheapest, so an agent can route correctly 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?

Explicitly states when the tool's default behavior applies and what it excludes (variable, prepaid, time-of-use, short-term <6 month) 'unless requested', which maps to the include parameter. It lacks explicit routing to sibling tools, but the context is clear enough to select 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?

With no annotations, the description carries the full burden. It usefully discloses the licensing/attribution constraint, which is genuine behavioral context an agent should surface. However, it is silent on return shape, pagination, and freshness of the price data, which matters for a market-data listing.

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?

One dense but front-loaded sentence states the resource and payload, and the licensing clause is a legitimate second point. Slightly list-like, but nothing is wasted or buried.

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 zero-parameter, read-only listing with no output schema, the description conveys enough to call it correctly and understand the returned metrics. The remaining gap is that it never clarifies its relationship to electricity_find_utility or the scope (statewide vs. per-city).

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 takes zero parameters, so the schema has nothing to document and the baseline of 4 applies. The description's value lies in defining the returned metrics rather than argument semantics.

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 resource (Texas TDUs in the competitive market) and enumerates the exact payload: cities served, plan counts, and lowest/median fixed price at 1,000 kWh. That is far more concrete than a tautology. It stops short of distinguishing itself from the sibling electricity_find_utility, so an agent must guess which of the two to call for utility lookup.

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 when-to-use guidance, no exclusion of related siblings such as electricity_find_utility or electricity_plans, and no stated prerequisites. The only conditional statement concerns licensing (commercial requires Pro), not tool selection.

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. It discloses the returned metadata dimensions (unit, cadence, date range, row count, publisher, latest value) and the licensing/access constraint (free non-commercial with attribution, Pro required for commercial). It omits pagination or bulk-response behavior, but it goes well beyond a bare 'lists things' statement.

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 action and then a long parenthetical enumeration of source families; dense but every clause tells the agent what data exists. The two trailing sentences on usage and licensing are short and earn their place, though the first sentence is heavier than strictly necessary.

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, no output schema, and zero parameters, the description must stand alone, and it does: it explains what is listed, what metadata accompanies each entry, how to use the result, and the licensing terms. Only the exact response structure and any size limits remain 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?

The tool takes zero parameters, so the baseline is 4. The description correctly implies a parameterless, whole-catalog listing with no filtering arguments, which matches the empty schema and leaves no ambiguity.

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 ('List') and a precisely scoped resource (every Texas energy market and public data series collected), then enumerates the source families. It also positions itself as the discovery meta-tool ('Call this first to pick a series'), which clearly separates it from all retrieval 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 instruction 'Call this first to pick a series' gives explicit sequencing guidance that tells the agent when to invoke this versus the retrieval tools. It stops short of naming specific alternatives or when-not conditions, but the placement guidance 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?

With no annotations, the description carries the full burden and does disclose notable behavior: it returns two sources side by side with a comparison, defaults to current values, and has licensing constraints (free non-commercial with attribution, Pro for commercial/older dates). It omits read-only/write semantics and any response format or rate-limit detail, but the licensing and dual-source disclosure is genuinely beyond the 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 core purpose, then mode definitions, defaults/history, and licensing in a compact block of sentences. Dense and slightly run-on, but essentially every sentence carries information an agent needs; little 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?

No output schema exists, so the description must cover returns, and it does explain the side-by-side source comparison, which is the key output differentiator. Combined with licensing terms and default/history semantics for a 4-param optional-parameter tool, it is nearly complete; only the exact response fields are unspecified.

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 75%, so the baseline is 3, but the description adds real meaning by defining what each type enum value returns (TDU per-utility PUCT charges vs municipal residential components) and reinforcing default vs history behavior for start/end. The utility parameter values are left entirely to the schema, which is acceptable given its enumerated description.

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 — retrieval of utility delivery (TDU) and municipal rate charges with effective dates — and distinguishes the two data modes by the 'type' enum. It is clearly separable from siblings like market_gas_prices or market_wholesale_prices because it names PUCT rate reports and specific utilities (Oncor, Austin Energy, CPS Energy).

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 mode-selection guidance: type=tdu for PUCT/EFL delivery charges, type=municipal for Austin Energy and CPS Energy residential components, plus default (current values) vs start/end (history). It does not name a sibling alternative to use instead in any scenario, 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?

With no annotations, the description carries the full burden and does well: it discloses the source (EIA), the free/Pro access boundary, that values are exact as published with unit, date and source URL, that incomplete days are flagged rather than filled, and the licensing terms. The only gap is that read-only/no-mutation nature and any rate limits are not stated, though the latter is strongly implied.

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?

A single dense paragraph with the resource and its relevance front-loaded, followed by access, quality and licensing details. Every sentence is informative, though the free/commercial licensing clauses could be tightened without losing 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?

With no output schema or annotations, the description still tells the agent what comes back (exact values with unit, date, source URL), how gaps are handled, and what access level is needed. That is close to complete for a 5-parameter data-feed tool; only the offset parameter and any rate limits are left 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 coverage is 60% and the description's parameter-relevant content ("daily or monthly", the 30-day free window) largely restates what the schema and enum already say, while offset remains undocumented in both places. It adds marginal value over the structured fields, so the baseline 3 is appropriate.

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 (Henry Hub natural gas spot price, $/MMBtu, EIA) with daily/monthly granularity, and frames its relevance to Texas power prices. It does not explicitly name or contrast a sibling such as market_wholesale_prices, but the resource is specific enough that an agent can tell it apart from the electricity-series tools.

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 important context — the free tier exposes the most recent 30 days while a Pro key unlocks full history — but this is a data-availability constraint rather than when-to-use guidance. There is no explicit statement of when to pick this over market_wholesale_prices or other market_* tools, so usage is only implied.

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 so well: it discloses the free-tier truncation to the most recent 30 days per series, the Pro requirement for older data, that values are exact-as-published with unit/date/source URL, that incomplete days are flagged rather than filled, and the licensing terms (non-commercial with attribution; commercial needs Pro). These are exactly the access, data-quality, and legal traits an agent cannot get from the 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?

Dense but front-loaded: resource and scope first, then fuel codes, then the alternative product, then access tiers, then data-quality and licensing. Nearly every clause carries information, with minor redundancy between the opening 'Free (no key or free key)' and the closing licensing sentence.

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 and no annotations, so the description must carry a lot, and it covers access tiers, units, data provenance, and licensing. It does not describe the shape of a returned row beyond 'unit, date and original source URL', and never explains limit/offset behavior, leaving a small gap for a 6-parameter data 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 coverage is 83%, so the baseline is 3, but the description adds meaning beyond the schema: it expands the fuel codes (NG = gas, COW = coal, SUN = utility-scale solar only) and fixes the unit (thousand MWh = GWh), plus the geographic scope of 'state'. It says nothing about limit/offset pagination semantics, which the schema handles.

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 with verb-like framing: 'Net electricity generation by state and fuel from the EIA,' plus scope (50 states, DC, U.S.; monthly since 2001) and unit convention (thousand MWh = GWh). This clearly separates it from demand, price, or retail siblings, though it never explicitly contrasts itself with market_grid_demand or market_wholesale_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?

Given an explicit alternative for one case ('For 12-month shares use data product us-electricity-generation') and clear access-tier conditions (free = latest 30 days; Pro key = full history). No exclusions or routing guidance relative to the other 20+ market_* siblings, 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 full behavioral burden and does so well: it discloses the free-tier cap (most recent 30 days per series), that a Pro key unlocks full history, the licensing terms (free non-commercial with attribution, commercial requires Pro), and the data-quality policy (exact as published with unit/date/source URL; incomplete days flagged, never filled). Gaps remain around rate limits and error behavior, but this is substantive 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?

A single dense paragraph, front-loaded with the data scope before moving to access tiers and quality guarantees, so the most important information lands first. It is information-rich rather than padded, though the licensing sentence is the least essential element an agent needs to invoke 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?

For a 7-parameter, no-annotation, no-output-schema tool, the description does meaningful work: it explains the data series, the free/Pro boundary on history, and the completeness policy for partial days. It stops short of explaining return shape and sibling routing, but the core calling context 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 coverage is 71%, above the baseline threshold, and the schema already documents start, end, limit, fuel, and granularity. The description's only real param-level contribution is reinforcing that older start dates need a Pro key, which the schema already states. It adds no syntax or format details for fuel, limit, or offset beyond what the schema provides.

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 the specific resource (ERCOT grid) and enumerates the three data series returned: generation by fuel, hourly system load with forecasts, and EIA daily demand/generation. That is enough for an agent to know what it fetches. However, it never distinguishes itself from siblings like market_grid_demand or market_generation, which appear to cover overlapping ground, so the separation is left to inference.

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 — one gets ERCOT grid data here. There is no explicit when-to-use or when-not-to-use, and no routing to alternatives such as market_grid_demand or market_generation, despite those siblings plausibly overlapping with the load and fuel_mix datasets. The free/Pro tier explanation is a constraint, not selection 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 at all, the description carries the full burden and does substantial work: it discloses data provenance (EIA-930, preliminary), that values are exact as published and never back-filled, that incomplete days are flagged, and it spells out the free/Pro access boundary and licensing terms. It stops short of covering pagination/offset behavior or error modes, 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?

The definition is front-loaded with the resource and scope, then tiers, then data-quality guarantees. It is dense but every clause carries information, except that the free/Pro availability point is stated twice (once in the access section, once in the licensing sentence), which is mild redundancy.

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, so the description must describe returns, and it does: values include unit, date and original source URL, and incomplete days are flagged rather than filled. Combined with the documented defaults and access tiers, an agent can invoke this correctly without further inference.

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 already 80%, yet the description still adds real semantic value the schema lacks: it maps respondent codes to operating names (ERCO=ERCOT, CISO=CAISO, SWPP=SPP), states the default respondent set (ERCO,PJM,MISO,CISO), and explains that the 30-day default window is the free-tier boundary. That meaningfully reduces the chance of a malformed call.

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 precise verb+resource (daily electricity demand in MWh) plus the source (EIA-930), time basis (Central-time days), coverage start (2019) and the full set of respondent codes. It is unambiguous what an agent gets back. It does not differentiate itself from lookalike siblings such as market_grid or market_generation, which is the only thing keeping it from 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?

Access conditions are stated clearly (free tier = most recent 30 days, Pro key = full history; commercial use requires Pro), which tells the agent when a request will fail. However, there is no explicit guidance on when to prefer this tool over the many sibling market_* tools, and no statement of exclusions or alternatives. Usage is implied rather than directed.

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 delivers: provenance ('every value has its document URL'), freshness caveats ('records are unofficial until final settlement'), data-integrity policy ('incomplete days are flagged, never filled'), and the auth/tier model ('free: most recent 30 days; Pro unlocks full history'). It does not cover error behavior or rate limits, 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 tool's purpose and dataset taxonomy before the licensing boilerplate. A single dense paragraph, but it earns most of its length; the provenance claim is repeated twice ('every value has its document URL' / 'with unit, date and original source URL'), which is mild redundancy.

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 and no annotations, so the description must do the work — and it covers dataset semantics, tier limits, caveats, and a hint at row contents (unit, date, source URL). What remains unstated is pagination/return-shape behavior and failure modes.

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 60% and the 'dataset' enum has no description in the schema at all, yet the description defines all five enum values (monthly, queue, batch_zero, peak_demand, forecast) and explains the date-range gating on 'start' tied to the free tier. That materially exceeds the schema, though start/end/limit/offset still rely on 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?

States a specific verb and resource — ERCOT large loads (data centers and other 75 MW+ loads), peak demand records and forecasts — and enumerates exactly which series it serves. An agent can distinguish this from market_grid_demand or market_outlook purely from the description, without any sibling differentiation sentence.

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 routing context ('for the page with context see electricity_data_product slug large-load-demand') and states the free-vs-Pro gate that determines which date ranges are usable. It lacks an explicit 'use X instead when Y' exclusion, 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 full behavioral burden and does so well: it discloses free-tier limits (most recent 30 days), that a Pro key unlocks full history, that 'projection' rows are forecasts not observations, that incomplete days are flagged and never filled, and the licensing terms. It omits any explicit read-only statement or rate-limit detail, keeping 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?

The content is front-loaded with the data source and coverage before the caveats, and each sentence (projections, access tiers, data quality, licensing) carries distinct information. It is dense but not 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 tool with no output schema and no annotations, the description covers source, coverage, forecast vs observed distinction, access tiers, and data-integrity behavior. Return-shape and pagination specifics are only lightly touched, but the essentials an agent needs to invoke it correctly are 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 coverage is 83%, so the schema already documents most parameters, and the baseline is 3. The description mentions the series covered and the projection status but adds no id format, date syntax, or topic-to-series mapping beyond what the schema provides.

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 data source (EIA Short-Term Energy Outlook) and enumerates the exact content covered: electricity prices by ISO, ERCOT load/generation, U.S. generation shares, and Henry Hub. It is clear what the tool returns, though it never distinguishes itself from overlapping siblings such as market_wholesale_prices, market_generation, or market_gas_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 implies usage via its content scope and the projection/free-tier caveats, but offers no explicit when-to-use or when-to-prefer-a-sibling guidance. An agent must infer that this is the STEO-specific feed rather than one of the narrower market_* tools.

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 6-month window, the critical limitation that no per-customer rate is computable because PUCT publishes no customer counts, and the free/pro and commercial-use restrictions. It omits pagination/return-shape behavior, keeping 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?

Front-loads the core resource and scope, then adds licensing and tier caveats. Dense but each sentence carries information; no filler, though the licensing sentences are somewhat tangential to calling 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?

No output schema or annotations exist, so the description must stand alone, and it adequately explains what is returned (complaint counts by category, entity, and brand) plus data limitations. The main gap is the undocumented pagination parameters.

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 only 33% and the description does not compensate: limit and offset are never explained, and the provider filter is only obliquely hinted at via 'per Texas retail electric provider'. It adds essentially no semantics beyond the single schema-documented 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?

States a precise verb+resource: PUCT customer complaint counts per Texas retail electric provider, broken out by category and with associated Power to Choose brands. An agent can immediately distinguish this from price/grid/plan siblings such as electricity_plan or market_grid.

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 tier conditions (free = latest window, Pro = older windows) and licensing terms, which imply when the tool is usable. However, it names no sibling alternative and gives no explicit 'use this instead of X when Y', so routing guidance is only implied.

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 ('values are exact as published with unit, date and original source URL') and a completeness guarantee ('incomplete days are flagged, never filled'). It leaves rate limits and pagination behavior unexplained, 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?

The purpose is front-loaded in the first clause and the sentences are dense but purposeful. The licensing/attribution sentence is somewhat tangential to invocation but is legitimate disclosure, so it stays efficient overall.

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 6-parameter, no-annotation, no-output-schema tool, the description covers returned fields, tier limits, and data fidelity constraints adequately. Remaining gaps (pagination via limit/offset, search semantics) are minor but real.

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 67%, and the description largely restates what the schema already documents (30-day default window, Pro needed for older dates). It adds a small amount of meaning about date scoping and source URLs but does not cover the undocumented 'offset' or clarify 'q' matching 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 names a specific source and content type ('Public Utility Commission of Texas news releases and rule changes') and even the returned fields ('title, date and link'), which separates it from generic siblings like electricity_news. It stops short of explicitly contrasting itself with those siblings, so it earns a 4 rather than 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?

It explains tier-based access ('most recent 30 days' free, 'a Pro key unlocks full history') and licensing ('commercial use requires Pro'), which implicitly tells the agent when a result will be truncated. However, it never says when to prefer this tool over electricity_news or another sibling, so usage guidance is only implied.

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 so substantively: it discloses the free/Pro data-window constraint, that values are exact as published with unit/date/source URL, that incomplete days are flagged rather than filled, and the licensing terms (free non-commercial with attribution, commercial requires Pro). It omits rate limits and refresh cadence, but the disclosure of access boundaries and data-integrity behavior is strong.

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 but front-loaded: it leads with what the data is, then the access window, then integrity/licensing. Every sentence carries information, though the free-window constraint is stated twice (latest month and 'most recent 30 days'), a minor redundancy.

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 an 8-parameter, no-output-schema tool with no annotations, the description covers the critical context: data domains, free vs Pro window, data-integrity guarantees, and output-value shape (unit, date, source URL). Parameter mechanics are delegated to a fairly complete schema, so the definition is close to complete without redundancy.

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 75%, so the schema already documents most parameters (end, limit, start, sector, series, dataset, measure). The description mostly restates the same data domains rather than adding syntax or format meaning beyond the schema. Baseline 3 is appropriate.

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 (official Texas retail electricity statistics) and enumerates the exact metrics covered (EIA monthly average price, sales, customers, revenue by sector; BLS CPI electricity and all items; BLS price per kWh). This is well beyond a tautology. It does not, however, differentiate itself from siblings like market_catalog or market_us_states, so an agent must infer the boundary.

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 meaningful access-tier guidance: the free window is the latest month / most recent 30 days, and a Pro key unlocks full history. That tells the agent when this tool will actually return usable data. But there is no explicit when-to-use-vs-alternative routing (e.g. versus market_catalog), leaving usage largely implied.

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 does so well: it discloses the free window (latest month / most recent 30 days), that a Pro key unlocks full history, the licensing terms, and a data-integrity guarantee ('flagged, never filled', exact as published with source URL). This is genuine context beyond a bare read-only claim; a brief note on pagination/rate limits would round it out.

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?

Information-dense and front-loaded with the core purpose, but the free-tier rule is stated twice ('the free window is the latest month' and 'the most recent 30 days of each series'), and the licensing sentence is a full trailing block. Slightly redundant rather than wasteful, but not tight.

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 correctly explains return content (unit, date, original source URL, incomplete-day flags). Combined with 86% schema coverage and the free/Pro access model, an agent has nearly everything needed to call it correctly; only pagination edge behavior is 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 already 86%, so the baseline is 3. The description adds value by restating the default state/sector selections and tying the start parameter's historical reach to the free-vs-Pro key boundary, which clarifies a constraint the schema only partially encodes ('Older dates need a Pro key').

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: U.S. retail electricity statistics by state from the EIA, enumerating the four measure families (price, sales, revenue, customers) and sector breakdown. It also names the sibling tool (electricity_data_product with slug 'us-electricity-prices') for the ranked-table alternative, so an agent can distinguish it from other electricity_* 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?

Explicit defaults (Texas + U.S. residential price) and a clear routing rule to electricity_data_product for a ranked all-states table. It also surfaces the free/Pro boundary condition. It stops short of distinguishing itself from trend-oriented siblings like electricity_price_trends, so it is clear context but not exhaustive 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?

With no annotations, the description carries the full burden and does meaningfully: it discloses the data source, unit conventions, that incomplete days are flagged and never filled, and the licensing/tier constraints. It omits auth mechanics (how a Pro key is supplied), rate limits, and error 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?

Information-dense but front-loaded, leading with what the tool returns before tier and licensing details. The parenthetical '(no key or free key)' is slightly awkward and the free/Pro theme recurs, but every sentence carries real content.

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 6-parameter read tool with no output schema and no annotations, the description supplies the source, coverage windows, unit, licensing and data-integrity behavior an agent needs to call it correctly. Return-shape and pagination details are the only notable gaps.

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 83%, so the schema already documents start/end/city/station/limit/offset. The description reinforces the date-range semantics and the Pro-key history limit but adds little syntax or format detail beyond what the schema already provides; baseline 3 is appropriate.

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 precise resource (daily high/low temperature and cooling/heating degree days, base 65°F) with an explicit source (NOAA NCEI) and the exact station scope (8 named Texas airports). An agent instantly knows what this returns and can distinguish it from the electricity/market 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?

Clear access-tier context: free keys get the most recent 30 days, a Pro key unlocks full history, and commercial use requires Pro. There is no weather sibling to route against, so explicit alternatives are unnecessary, but it stops short of the full when/when-not statement.

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 does so well: it discloses tier/rate limits (30 days free), data-integrity guarantees (values exact as published, incomplete days flagged and never filled), and licensing constraints (attribution required, commercial use needs Pro). It omits pagination or response-shape behavior, keeping 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?

A single dense paragraph that front-loads what the tool returns before moving to tier and licensing terms. Most sentences earn their place, though the licensing/attribution sentence is more legal boilerplate than task-relevant 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?

For a 7-parameter read tool with no annotations and no output schema, the description covers the key gaps: data semantics, tier limits, integrity handling, and partial return content. It could say more about pagination (limit/offset) and default date behavior, but an agent has enough 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 coverage is 71%, and the description meaningfully augments it: 'real-time or day-ahead' clarifies the market enum and 'daily avg/min/max or hourly' explains what day vs hour granularity actually yields beyond the bare enum values. It also conveys units and the presence of completeness flags, adding return-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 states a specific resource (ERCOT wholesale electricity prices in $/MWh) and scope (trading hubs and load zones), with concrete modes (real-time/day-ahead, daily avg/min/max or hourly). An agent can immediately distinguish it from siblings like market_gas_prices and electricity_price_trends. The verb+resource+scope combination is unambiguous.

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 useful access conditions — 30-day free window vs Pro for full history — but frames them as pricing tiers rather than when-to-use guidance. It never names an alternative or states when a sibling tool (e.g., electricity_price_trends) would be more appropriate. Usage is implied rather than instructed.

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 so well: it discloses that FCC does not verify complaints, that counts are not per-subscriber rates and name no carriers, that free access is limited to the last 30 days while a Pro key unlocks history, that incomplete days are flagged rather than filled, and that values carry unit/date/source URL. These caveats are exactly the context an agent needs to interpret results responsibly.

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 a single dense paragraph, but content is front-loaded with the dataset definitions before caveats and licensing. Nearly every clause adds usable information (sources, units, tier limits), though the licensing sentence could be trimmed.

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 multi-dataset retrieval tool with six optional parameters, no annotations, and no output schema, the description covers sources, dataset semantics, tier limits, caveats, and the shape of returned values (unit, date, source URL). Only pagination behavior and error cases are left implicit.

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 67% and the description fills much of the gap: it explains the meaning of each dataset value, restricts state to 'complaints only' with US default, and ties start to the free/Pro history boundary. Only limit/offset go unexplained in prose, but limit has a schema description, so the residual gap is small.

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 resource (U.S. government mobile phone service data) and enumerates the three datasets it can return, so an agent knows exactly what the tool produces. It does not explicitly contrast itself with the many sibling tools, but the domain is distinctive enough that confusion is unlikely.

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?

Dataset semantics implicitly route usage ('complaints' for FCC counts, 'issues' by complaint type, 'cpi' for BLS price index) and it states that state=US is national vs. a state code. It never gives explicit when-to-use/when-not guidance relative to alternatives, leaving the agent to infer selection from the dataset labels.

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