ElectricityFinder

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

Annotations (readOnly, idempotent, non-destructive) only cover safety, and the description adds substantial context beyond them: free/no account, the returned link is non-expiring and re-prices on open, the broker's compensation model and that it earns $0 from providers, co-op/city-utility exclusion, and variable/indexed rate volatility. That is far more than the annotations carry.

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 tightly front-loaded — the purpose and the free/no-account fact come first, and the economics and disclaimers follow. It is long, and some sentences are agent scripting rather than tool description, but every sentence is load-bearing.

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 carries the return contract itself: cheapest plans, EFL links, a re-openable comparison link, cheapest_any_term, and interval_data.verdict semantics. An agent has everything needed to call it and to interpret and relay the result.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds real meaning: it explains that ranking uses the site's default contract length and that term='any' surfaces the cheapest_any_term alternative, and it stresses whole-month usage over a single average. Minor gap: it refers to 'term_filter' rather than the actual 'term' parameter name.

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 (ranks) plus resource (Texas retail electricity plans) and the exact criterion (projected yearly cost at the person's own monthly kWh, explicitly contrasted against the 1,000 kWh ad benchmark). It is unmistakable against the siblings how_to_get_my_usage and send_feedback.

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 gating: 'If the person has no usage numbers, call how_to_get_my_usage first.' It also names conditions that change behavior (utility_note means a co-op/city utility cannot choose; only offer the paid plan when interval_data.verdict is interval_data_can_change_the_answer). When/when-not 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 already declare readOnly/idempotent/non-destructive, and the description is fully consistent with that. It adds genuine content-level behavior beyond the annotations: the three ways usage can be sourced and the caveat about one typical month. It does not describe the shape of the response, but as a static guidance tool there is little else to warn about.

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 primary fact front-loaded and no filler. The second sentence earns its place by adding the 'when is monthly enough' condition, though the phrasing is a little dense.

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 parameters, no nested objects, and no output schema, the description carries essentially all the meaning, and it does cover what the answer will contain plus its downstream use. It could be more explicit that it returns guidance text rather than live meter data, which is the only notable 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?

The tool takes zero parameters, so the baseline is 4 and there is nothing for the description to disambiguate. No parameter-level detail is needed or missing.

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 concrete subject (obtaining 12 months of kWh usage for a Texas household) and makes clear it is an explanatory/guidance tool rather than a data fetcher. It also names the sibling tool it feeds into. It stops short of a crisp single verb-and-resource statement, but the intent is readily identifiable.

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 positions itself upstream of compare_texas_electricity_plans, which tells the agent when to reach for it, and explicitly covers 'when monthly numbers are enough' — a real usage condition. There are no explicit when-not-to-use exclusions, 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?

Annotations declare a non-read-only, non-idempotent, non-destructive write, and the description adds real behavioral context beyond them: strict privacy rules on personal details and a content-scoping rule for the message. It does not describe submission outcome, rate limits, or what happens on repeated sends, so it falls 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?

Two tightly packed sentences: purpose first, then usage constraint and privacy rule. No filler, and the most decision-relevant information (when to use) is front-loaded.

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 4-parameter write with no output schema, the description covers trigger, content scope, and privacy, which is what an agent needs. It omits any indication of what confirmation or result the caller should expect after sending, 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 coverage is 100%, so the schema already defines all four parameters, the enum values for kind, the ZIP pattern, and length limits. The description's kind examples and privacy note largely duplicate the schema descriptions ('kind' enum text and 'message' description), so it adds little beyond the structured fields.

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 ('Send feedback to the people who run ElectricityFinder') and enumerates the content domains it covers (wrong price/plan, confusing answer, missing feature, error). It is unmistakably distinct from the siblings compare_texas_electricity_plans and how_to_get_my_usage.

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 the trigger condition ('Use it only when the person asks to send feedback') and the exclusion ('send their words about the problem, not the conversation'), plus a hard privacy constraint. An agent knows exactly when to call this and what not to include.

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