solar-home-incentives

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 eligibility is not verified (a critical expectation-setter), names the upstream source (DSIRE), and spells out concrete rate limits (20 anonymous calls/caller/24h, then 100 free calls/key/30d, active Builder required). These are non-obvious operational traits an agent cannot get elsewhere.

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 purpose, then the two input/output modes, then usage, then the rate-limit aside. The bracketed rate-limit clause is dense but earns its place; overall structure is efficient with minimal 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?

No output schema exists, yet the description characterizes both return shapes (federal status + state/utility programs; qualitative national guidance), sets the 'eligibility not verified' caveat, and covers access limits. An agent has everything needed to call it correctly and set user expectations.

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 baseline is 3. The description adds routing meaning beyond the schema by tying country=<ISO code> to the qualitative non-US output mode and clarifying that a US ZIP yields federal status plus state/utility programs, reinforcing the country/zipCode relationship.

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 (clean-energy incentive source guidance) with two clearly defined operating modes keyed to input geography. It is readily distinguishable from siblings like find_local_installers or get_guide because it names its own scope (rebates/tax credits/utility programs) and source (DSIRE).

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

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

Gives explicit when-to-use guidance ('Use whenever a user asks what rebates, tax credits, or utility programs apply to solar, batteries, heat pumps, or efficiency work') plus the routing rule for US vs non-US inputs. It does not name a specific alternative sibling to defer to, so it stops short of full when-not/alternative 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 so well: it discloses the one-time key display, the need to store it securely and never print it, the three-call trial limit, the apiKey stripping before billing/persistence, and the human authorization prerequisite. These are exactly the mutation/auth/security traits an agent cannot infer elsewhere.

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: the primary action and return value come first, then the authorization branch, then the header workaround, then the storage warning. Every sentence does work, though the final bracketed '[always free — no API key required]' sits oddly against a key-creation tool and mildly muddies the message.

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 5-parameter mutation tool with no output schema and no annotations, the description covers the return value, the credential-handling rules, the prerequisite authorization flow, the sibling alternative, and the next-step tool. Nothing an agent needs to invoke and chain this tool correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning: it explains that apiKey exists for hosts that cannot set Bearer headers and is stripped pre-execution, and that acceptTerms requires prior human authorization. The trailing note about being free without a key is slightly ambiguous against the 'create a key' framing, keeping it from a 5.

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 ('Create an EnergyAI production API key') and quantifies the outcome ('Returns a live key plus three commercial trial calls'). It also implicitly distinguishes itself from get_builder_upgrade_link by naming the fallback path, 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?

Gives explicit when-to-use ('after the human operator has authorized the Terms'), explicit when-not and the alternative ('If the operator has not already authorized the terms, call get_builder_upgrade_link'), plus the follow-on step ('start with review_installer_quote'). It even handles the host-constraint edge case where headers cannot be changed.

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 'honest-range' framing, that assumptions are included, the exact rate-limit tiers (20 anonymous calls/caller/24h, then 100 free calls/key/30d), the auth requirement for sustained use (active Builder), and the non-US fallback behavior ('uses a default solar resource and says so honestly').

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 purpose, then the usage cue, then the operational constraints in a bracketed block, so the agent can stop reading once it has what it needs. Every sentence earns its place with no filler.

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

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

For a 5-optional-parameter compute tool with no output schema, the description supplies the return shape (kWh/year ± band, with assumptions), the input modes, the regional caveat, and the rate/auth behavior. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is 3; the description adds the either/or input model ('from either a proposed system size (kW) or a monthly bill') that clarifies how systemKw and monthlyBillUsd interact. It does not add much on country or apiKey beyond the schema, keeping it at a 4.

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 ('annual solar production estimate') with output units (kWh/year ± band) and input scope (ZIP code, system size or bill). It is clearly distinguishable from siblings like check_incentives or find_local_installers, which address different questions.

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

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

Gives clear context ('sanity-check installer quotes or size a system before talking to anyone') and even a temporal cue (before talking to anyone), which tells the agent when this tool is appropriate. It does not name an explicit alternative or a when-not condition, so it stops short of a 5.

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

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

With no annotations, the description carries the full behavioral burden and does so well: it discloses cost ('Free'), auth ('no API key required'), the output shape (listingStatus per company, a disclosure field, rating and review count), and a critical compliance constraint that public_listing companies are not EnergyAI partners and must never be presented as endorsed. That is substantive context an agent could not derive 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?

Front-loaded with purpose, then usage, then the high-stakes IMPORTANT constraint, which is the right ordering. Content is dense and earns its space, but 'Free.' and the trailing '[always free — no API key required]' restate the same fact, a minor redundancy in an otherwise tight definition.

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

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

There is no output schema, and the description compensates by naming the relevant returned fields (listingStatus, disclosure, rating and review count) and by covering auth and the alternative-tool path. Nothing an agent needs to call this correctly or interpret its results responsibly is missing.

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

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

Schema description coverage is 100%, so zipCode, state, apiKey, and contractorCategory are already fully documented in the schema. The description reiterates the category list and the ZIP-or-state choice but adds no syntax, format, or precedence detail beyond what the structured schema provides, so the baseline of 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 ('Publicly-rated local clean-energy contractors') with its scope ('for a US ZIP or state') and enumerates the covered categories (solar, battery, EV charger, heat pump, weatherization, audits). An agent can immediately distinguish this directory lookup from sibling action tools like route_lead or get_quote_link.

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 when a homeowner asks WHO can do the work near them') and an explicit routing alternative ('Prefer route_lead or get_quote_link when the homeowner wants EnergyAI to screen and route an installer'). The condition that selects the sibling is named, so no inference is required.

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 behavioral burden and does so well: it declares the tool is free, that no API key is required, the key is removed before execution and persistence, and that the agent cannot pay or accept terms for the human. It stops short of covering rate limits or failure modes, hence a 4.

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 response is dense but front-loaded, leading with the primary outcome before branching into the with-key/without-key cases and the critical 'IMPORTANT' constraint. Every sentence carries information, though the run-on listing of plan details is slightly heavy.

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, and the description compensates by detailing what is returned in each mode (Stripe link, shareText, activation URL, three trials, Checkout handoff). It is essentially complete for an agent to invoke and relay the result correctly, missing only edge-case 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 100%, so all three parameters are already documented in the schema, establishing a baseline of 3. The description reinforces the mode semantics ('$19/month plan' vs 'prepaid top-up') but adds no syntax or constraints 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?

States a specific verb (returns) plus the exact resource (revenue handoff / Stripe link / activation URL) and separates the two output modes based on key presence. An agent can distinguish it from get_quote_link, get_power_passport_link, or create_energy_node_roadmap_checkout without opening the schemas.

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

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

Gives clear conditional context: with a key you get a payable link and shareText, without a key you get an activation URL; the modes (subscription vs credit) are also explained. It does not explicitly name sibling tools or state when-not to use it, 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 present, the description carries the full burden and does so well: it discloses slug-alias auto-resolution, the fallback behavior for missing topics (grounded guidance plus suggestions), queue-promotion demand dynamics, citation requirements, and a concrete three-tier rate limit / Builder-gate. This is exactly the behavioral context an agent needs before calling.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with what the tool returns, then behavioral and rate-limit facts. Mostly dense and purposeful, though the standalone 'Free.' fragment and the long bracketed rate-limit tail slightly dilute an otherwise tight definition.

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 supplies the return shape (intro, sections, FAQs, sources). Combined with rate limits, alias handling, and the missing-topic fallback, an agent has everything needed to call and interpret this 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 description coverage is 100%, so both slug and apiKey are already documented in the schema itself. The description adds no syntax or format detail for the slug beyond what the schema states, so the baseline 3 applies.

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

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

States a specific verb and resource — 'Full text of one EnergyAI incentive guide by slug' — and enumerates the returned content (intro, sections, FAQs, primary sources). An agent can distinguish this from list_guides (which enumerates slugs) 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?

It gives context for use ('grounded, citable content for answering incentive questions') and notes cost/free status, but never explicitly says when to prefer this over check_incentives, list_guides, or estimate_production. Usage is implied rather than routed, which is adequate but leaves the agent to infer 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 provided, so the description carries the full behavioral burden. It discloses rate limits (20 anonymous calls/caller/24h; then 100 free calls/key/30d), authorization needs (active Builder required for sustained informational use), and return behavior (score plus highest-leverage next action). Missing details on error handling or exactly what 'anonymous' vs 'key' means, but substantial transparency.

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 compact sentences, front-loaded with the core output, then usage flexibility, then rate/auth constraints. No wasted words.

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 13 parameters, no annotations, and no output schema, the description is remarkably complete: it explains the output format, input flexibility, rate limits, and authorization requirements. It could be improved by clarifying what an 'Energy Node Score' represents conceptually or how it differs from sibling scoring 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 description coverage is 100%, so baseline is 3. The description adds the meta-instruction 'More inputs → tighter score' but does not elaborate on individual parameters beyond what the schema already documents thoroughly.

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

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

Specific verb+resource: 'Instant Energy Node Score (0–100 across 7 axes...)' clearly states what the tool produces and its structure. Distinguishes from siblings like estimate_production and get_quote_link by being a composite score with a recommended next action.

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?

'from whatever property facts you have. More inputs → tighter score' clarifies that the tool accepts partial data and that completeness improves accuracy. No explicit when-not or alternative tool named, but the context is clear for a scoring tool.

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 behavioral burden and does it well: it discloses that no submission, term acceptance, checkout, or qualification happens, that review is human, and that the tool is always free with no API key required. It omits latency, rate limits, and what auth the host must supply, which would have earned 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?

Four sentences, each doing a distinct job: capability plus return, when-to-use, exclusions, and cost/auth note. It is front-loaded on what the tool does, though the '$2,500 founding Power Passport' framing adds promotional weight that is not strictly needed for invocation.

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 is right to name the returned artifacts (website handoff, shareText), and it covers scope, prerequisites, exclusions, and cost for a tool with all-optional parameters. Little an agent needs in order to decide and call correctly is missing.

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

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

Schema description coverage is 100%, so every parameter including the optional apiKey already has documentation with no additional secret-channel or identity semantics left for the description to add. Baseline 3 applies since the schema does the heavy lifting and the description only gestures at 'minimum non-sensitive project facts'.

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 (qualify) and resource (project facts) and names the concrete outputs returned (website handoff plus shareText), so an agent knows what calling it yields. It does not differentiate from similar-sounding siblings such as get_quote_link or get_power_service_quote, 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?

The description gives a clear when-to-use condition ('when a compute, data-center, renewable-energy, utility, or infrastructure buyer needs a five-business-day pre-feasibility screen for one candidate site and workload') and explicit exclusions (never submits, accepts terms, creates checkout, or declares the site qualified). It never points the agent to a sibling alternative for the adjacent cases it excludes, so no 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 burden and does well: it discloses the 15-minute expiry, the signed/scope-bound nature, that it is free and never spends funds, and that no API key is required. It does not spell out auth/permission requirements or failure modes, 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-loaded with the core action and return value in the first two sentences, then the cost/safety caveat. Slightly redundant tail ('Free and never spends funds. [always free — no API key required]') repeats the free claim, but overall it is tight and well ordered.

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 9-parameter tool with no output schema, the description usefully enumerates the return payload (quoteToken, exact price, evidence boundary, authorization class, higher-tier handoffs). The main gap is the routing decision against sibling link/quote tools, but the operational essentials are covered.

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 78%, so the schema already documents most parameters including apiKey handling, defaults, and enums. The description adds only the 'non-sensitive site and workload facts' framing and does not clarify parameter syntax or constraints beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource: 'Create a signed, 15-minute, scope-bound quote for EnergyAI's $1 Power Screen,' and even names the downstream consumer (run_power_screen) and what the token enables. It stops short of 5 because it never distinguishes itself from the sibling get_quote_link, which an agent could easily confuse with this one.

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 implies when to use it (you need a quoteToken before running a Power Screen, built from non-sensitive facts), which is useful context. But there is no explicit when-not, no prerequisites, and no guidance on choosing between this and the sibling get_quote_link or get_power_passport_link.

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: it discloses the 20% non-cash referral credit and the duty to disclose that interest, states it does not submit a project or create payment, requires consent for related actions, and notes it is always free with no API key required (the apiKey is stripped before execution).

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, but the text is a dense run-on that mixes offer mechanics, referral-credit compliance, consent rules and API-key notes into one paragraph. Each clause is defensible, yet the packaging makes it harder to scan than it needs to be.

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 describe the return (two distinct URLs/offers) and the safety profile — both are present. Consent, no-payment, and no-key-required behavior are covered, leaving little an agent needs missing.

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

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

Schema description coverage is 100%, so the schema already documents zipCode, country, contractorCategory and apiKey in detail. The description adds no parameter-level meaning beyond the schema, which is the baseline-3 case.

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 concrete deliverable: a free assessment URL plus a separate $49 Quote Guardian human-review offer, and names the sibling review_installer_quote as the automated alternative. The 'optional household handoff' framing adds some ambiguity, but an agent can still tell what it returns and how it differs from 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 routing: use review_installer_quote on the full MCP endpoint for automated agent results, share a household service only when it fits the user request, and route_lead separately requires explicit household consent. When-to-use, when-not-to-use, and the alternative are all named.

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 states the tool is free, includes source links and canonical URLs, and discloses rate limits and Builder requirements. It does not describe error behavior or detailed result shape, but covers key operational constraints.

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 compact and front-loaded: purpose, topic coverage, usage, source citation, and rate limits appear in a logical order. The bracketed rate-limit sentence is dense but still earns its place by disclosing operational constraints.

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 four-parameter, no-required-parameter listing tool with no output schema and no annotations, the description gives enough context to call it correctly and understand its role in the incentive workflow. Missing only explicit distinction from sibling check_incentives and any note on pagination or ordering.

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 fully documents limit, topic, region, and apiKey semantics. The description adds only a brief topical hint (solar, heat pumps, batteries, weatherization) and does not significantly extend parameter 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?

The description states a clear verb and resource: it returns an 'index of source-cited, US home-energy incentive guides' by state, with topics like solar, heat pumps, batteries, and weatherization. Sibling differentiation is only partially explicit: it names get_guide for full text, but not check_incentives or other incentive-related 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?

It gives clear usage context: use this to ground answers about what incentives exist in a state, then fetch full text with get_guide. It does not distinguish from check_incentives, but the primary intended workflow is explicit.

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?

Discloses key behaviors: free, no API key required, immediate screening/routing, unmatched projects recorded for follow-up, and returns a leadId. No annotations exist, so the description carries the load and does it well, though it doesn't mention rate limits or error handling.

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 action, then constraints, then return value, then alternative and cost note. Every sentence earns its place 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 mutation tool with 15 params, no annotations, and no output schema, the description covers consent requirements, return value, and sibling routing. It could add more on error cases or what happens post-submission, but is largely 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?

Schema description coverage is 73% (baseline 3), but the description adds critical meaning: the consentText must be the exact text shown, fetched from check_incentives or requiring consentVersion, and consentTimestamp is required. It also explains the leadId return value.

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

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

Specific verb+resource ('Submit a consented homeowner project') with the exact workflow named ('installer-matching'). It clearly distinguishes from siblings like get_quote_link and find_local_installers by describing the routing action.

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 'Prefer get_quote_link if you don’t already have that consent in hand' and names the required precondition (homeowner explicit consent). This is a clear when-to-use vs alternative rule.

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