generators

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

With no annotations and no output schema, the description carries the full burden, and it does disclose the shape of the response — catalog coverage, item count, last-update timestamp, and usage/licensing terms. It implies a read-only, side-effect-free metadata call. It does not state that it takes no arguments or has no side effects explicitly, keeping it below 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 front-loaded sentence fragment with no filler; the colon-plus-list structure makes the returned fields scannable. It is slightly clipped ('usage terms' is unexplained) but nothing is wasted.

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, no-output-schema tool, this description is the only source of return-value information, and it gives only a terse field list. Terms like 'coverage' and 'usage terms' remain ambiguous — an agent does not know whether to expect license text, rate limits, or scope statistics. Adequate for a trivial info tool, but not fully complete.

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. It correctly does not invent parameter discussion.

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 resource (this catalog's metadata) and enumerates the four things it exposes — coverage, item count, last update, usage terms. That is clearly distinct from the siblings (search_tools, get_tool, compare_tools, list_categories), which all operate on individual tools or categories. It loses a point for lacking a verb and for the vague term 'coverage'.

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 explicit when-to-use statement and no sibling is named as an alternative. Usage is only implied by the list of returned content — an agent can infer 'call this to learn about the catalog itself rather than to search it'. That is minimum-viable inference rather than 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?

No annotations are provided, so the description carries the full behavioral burden. 'Compare' implies a read-only operation, but the description does not state whether the tool is read-only, whether it has side effects, how many generators are allowed, or what the response includes beyond 'key specs and price.'

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 a single front-loaded sentence with no filler. It communicates the action, scope, and comparison criteria efficiently.

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 low-complexity tool with one parameter, the description gives enough to understand the basic operation and the dimensions compared. However, with no annotations or output schema, it remains thin on return format, limits, and how generator identifiers should be supplied.

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%, so the description must add meaning beyond the bare 'names' array. It does add a meaningful constraint by saying 'two or more generators,' implying the array should contain at least two identifiers, but it does not clarify identifier format, maximum count, or duplicate handling.

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 uses a specific verb ('Compare'), resource ('generators'), scope ('two or more'), and comparison dimensions ('key specs and price'). It is clearly distinct from single-item tools like get_generator, though it does not explicitly name sibling tools or contrast itself with them.

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 intended use is implied by 'Compare two or more generators side by side,' which signals multi-item comparison rather than lookup or search. However, it gives no explicit when-to-use guidance, no exclusions, and no pointer to alternatives such as search_generators or get_generator.

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

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

No annotations are provided, so the description carries the full behavioral burden. 'Get' implies a read, and 'verified record' hints at data quality, but it never explains what 'verified' means, whether a missing name errors or returns empty, or what the record contains.

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 front-loaded sentence with zero wasted words and the lookup key placed at the end. It is efficient, though the terseness leaves no room for the routing or format detail an agent would want.

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 an undocumented parameter format, the description is too thin for a lookup tool. It should say what the returned record includes and how name resolution failures behave.

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%, so the description must compensate for the single required parameter. It only echoes that lookup is 'by name' without specifying exact match, case sensitivity, slug format, or whether an ID is accepted, adding almost nothing over the bare string 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 ('Get the full verified record') scoped to a single generator keyed by name. That is enough to separate it from list_categories and search_generators, though the description never explicitly contrasts itself with those 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?

There is no when-to-use or when-not-to-use guidance. An agent must infer that this is the exact-name detail lookup versus the keyword-based search_generators and compare_generators siblings, and nothing in the text confirms that inference.

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

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

No annotations are provided, so the description carries the full disclosure burden. It conveys that results include per-category item counts, but says nothing about ordering, whether the list is complete or paginated, caching, or required permissions. For a read-only enumeration tool the risk is low, but the description adds little behavioral context beyond the payload hint.

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 with no filler, and the most useful detail (item counts) is included rather than omitted. Nothing could be removed without losing information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a parameterless, non-destructive listing tool with no output schema, the description says enough: what is listed and what each entry carries. The remaining gap is the lack of any hint about result ordering or size, which matters modestly for an agent planning a browse step.

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 there is nothing for the description to disambiguate; the baseline of 4 applies. No parameter text 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 uses a specific verb and resource ('List the catalog categories') and adds the payload detail 'with item counts', so an agent knows exactly what the call returns. It does not explicitly differentiate itself from the sibling catalog_info, which could plausibly also surface category data, so it stops short of 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?

There is no when-to-use guidance, no mention of prerequisites, and no reference to alternatives such as catalog_info or search_tools. The only signal is the implied 'browse the category taxonomy' reading, which the agent must infer.

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

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

No annotations are supplied, so the description carries the full burden. It does disclose useful behavior beyond the schema: results are ranked, compact, and include prices and links. It says nothing about how ranking works, what 'verified' means operationally, whether calls need auth or are rate-limited, or how paging/limit behaves.

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 zero filler; the primary action and scope come first, the return shape second. Nothing needs trimming and nothing is 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?

With no annotations, no output schema, and two of three parameters undocumented, the description should do more for a search entry-point tool. It omits defaults, category vocabulary, result count behavior, and how the shortlist is ranked, leaving real gaps an agent must guess around.

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%: only 'query' is documented (with examples), while 'limit' and 'category' have no description at all. The description adds no parameter meaning — no default for limit, no hint at valid category values (0 enums) or whether query and category combine or override each other.

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 (search) and a specific resource (the Home Generator HQ verified catalog of generators), and adds the result shape (ranked shortlist with prices and links). It is distinguishable from compare_generators and get_generator, though it never explicitly names those 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?

Usage is only implied: an agent can infer this is the discovery/entry point when looking for generators by keyword or category. There is no explicit when-to-use, when-not-to-use, or pointer to siblings like get_generator for details or compare_generators for head-to-head comparison.

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 supplied, so the description carries the full disclosure burden. It does indicate the tool returns reference guidance and cost ranges (read-only, informational, zero-param), but says nothing about the form of the response, whether the figures are static or regional, or any caveats on cost estimates.

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 with zero filler, covering both sizing rules and cost ranges. It is a sentence fragment rather than a statement of what the tool does, which slightly weakens clarity but costs no extra length.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter reference tool with no annotations and no output schema, the description conveys the topic adequately and an agent could call it without risk. It stops short of saying what the answer looks like or how the sizing rules and cost ranges relate, leaving a modest 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 input schema has zero parameters, so there is nothing for the description to disambiguate; the baseline of 4 applies. No parameter meaning is 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 specific resource: generator sizing rules of thumb plus typical installed cost ranges, scoped to standby generators. It is a noun phrase with no verb and does not distinguish itself from siblings such as compare_generators or catalog_info, but the content an agent would retrieve 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?

There is no guidance on when to call this versus search_generators, compare_generators, or catalog_info. An agent must infer that this is the pre-selection sizing/cost reference rather than a lookup of actual products, and nothing states whether it should be consulted before or after searching.

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