SparkReady

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

Annotations already establish readOnly, non-destructive, closed-world behavior, and the description adds the one behavior that matters and is not obvious: an omitted rate silently falls back to a labelled 7% teaching default rather than a lender rate. That disclosure prevents the agent from presenting the output as a real quote. It does not describe what the comparison actually returns, though with no output schema that is a secondary gap for a read-only calculation 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?

Three short sentences, front-loaded with the trigger condition followed by the exclusion and the default behavior. No filler and nothing 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?

The usage boundary and the rate default are well covered, and annotations carry the safety profile. However, with no output schema present, the description never indicates what the comparison returns (figures, a table, savings vs. cost), which an agent needs in order to describe results to a caller.

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 7% default for illustrative_annual_rate_percent is already documented in the schema. The description's mention of the 7% teaching default restates the schema rather than adding new meaning, so a 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 first sentence names the specific comparison being performed (cash vs. loan vs. adding a battery later) and the constraint that it operates on figures the caller already has, which separates it from estimate_bill_savings and the explain_* siblings. It stops short of naming a sibling tool explicitly, so the differentiation is inferential 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?

Gives both a positive trigger ('Use this when comparing...') and a clear exclusion ('Do not use this to offer a rate or say they should borrow'), which is stronger guidance than most definitions provide. It does not name which sibling to route to when the caller does want a rate discussion, leaving that inference to the agent.

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

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

Annotations already declare readOnlyHint, destructiveHint false and closed-world, so the safety profile is covered structurally. The description adds a real behavioral constraint not present in annotations: this tool must not be used to gather sensitive identifiers or account data, which shapes how an agent should handle the conversation. It does not describe the shape or size of what comes back, which is the main remaining 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?

Two sentences, front-loaded with the trigger condition, no preamble or filler. The second sentence carries a long enumeration, but each listed item is a distinct sensitive data category that earns its place in a privacy-relevant guardrail.

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-required-parameter, read-only tool with full schema coverage there is little to document, and the safety constraint is well covered. However, with no output schema, the description never tells the agent what it receives back — a list of questions, a grouped checklist, a template — leaving the return value entirely 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?

The single parameter has 100% schema description coverage and an enum, and the description's 'installer, a lender, or both' merely restates the enum values already documented. The schema and description both note the 'both' default, but the description adds no new meaning about how the audience changes the returned questions.

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 says when to reach for the tool ('preparing questions for an installer, a lender, or both') and implies it produces a set of questions, but never states the verb or the resource explicitly — an agent has to infer that it returns a checklist of questions to ask rather than, say, a decision tree or a document template. It is distinguishable from the explain_* siblings only by inference, since none are named.

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 an explicit use case plus a hard exclusion ('Do not use this to collect the answers, a TFN, an SSN...'), which is genuinely useful routing guidance. It stops short of naming an alternative sibling for the excluded cases, so the agent is told what not to do but not where to go instead.

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

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

Annotations already establish readOnly, non-destructive, and closed-world, and the description adds genuinely new context: the output is an educational estimate with no guarantee or offer semantics, and no PII should be supplied. It stops short of saying what the returned figures look like (annual? per-period?), which would matter for a calculation tool with no output schema.

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

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

Three short sentences, each doing distinct work: use condition, exclusion boundary, and a safety instruction. The use condition is front-loaded and nothing is repeated from the schema.

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

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

For an eight-parameter, read-only calculation tool with rich schema descriptions and no output schema, the description covers purpose, boundaries, and input safety well. It is slightly incomplete in that it never indicates the form of the result (e.g., annual bill saving in AUD) or that unspecified rates default rather than being required.

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

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

Schema coverage is 100% and the schema already documents defaults (peak sun hours 4.2, performance ratio 0.80, self-consumption 0.30) and constraints. The description only restates three of the eight parameters at a high level, adding no unit, range, or default meaning beyond the schema, so the baseline 3 applies.

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

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

The description names the required inputs (daily kWh, tariffs, system size) and the output nature ('classroom energy-bill arithmetic'), which separates it from a quoting or credit tool. It does not name or contrast with any sibling such as compare_scenarios, so an agent still has to infer which of the nine siblings is the right entry point for multi-scenario work.

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 a clear use condition ('when you have daily kWh, tariffs, and a system size') plus explicit exclusions ('not a quote, a savings guarantee, or a credit offer') and a data-handling instruction ('do not send an account or identity number'). The one gap is that it never routes the agent to an alternative tool when the situation is comparative or decision-oriented.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so safety is covered structurally. The description adds real behavioral guardrails beyond that — no product recommendations, no bill-savings promises — which tells the agent how to frame the answer, not just that it is a safe read.

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 short sentences, zero filler, with the primary use case stated before the exclusions. Every clause carries information an agent needs to select and frame the call.

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 single-optional-parameter, closed-world explainer with no output schema, the definition covers purpose, framing constraints, and exclusions, and the schema covers the privacy constraint. Minor gap: it does not say what the agent receives back (e.g. a public explainer page vs. a tailored answer), which the schema only hints at.

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?

There is a single optional parameter whose schema description already covers its purpose, emptiness semantics, and the sensitive-data exclusion at 100% coverage. The description contributes nothing about the parameter, which is acceptable given the schema does the work, but it adds no extra meaning.

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 (a home battery) and the specific content to be explained (what it stores, why backup is a separate feature), which is well beyond restating the name. It does not explicitly contrast with the sibling explainers (explain_solar, explain_hesl), so the boundary between this and adjacent topic pages is left implicit.

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 a clear trigger ('use this when explaining...') plus two explicit exclusions: recommending a product and promising bill savings — those map onto siblings like product_faq and estimate_bill_savings. It stops short of naming those alternatives directly, so the routing is inferable rather than stated.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so safety is covered by structured data. The description adds real behavioral context beyond that — it explicitly declines to make eligibility determinations and gives a redirection target, plus the schema note that identity numbers and approval requests are refused. What it does not describe is the shape of the answer returned (for example, whether it is prose, cited figures, or a fixed template).

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, no filler. The positive use case and the scope list come first, followed by the exclusion and redirect, so the agent reads the selection rule before the caveat.

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 one-optional-parameter, read-only explainer with no output schema, the description supplies what matters: what topics are in scope and what decisions are out of scope, including the redirect. The only gap is that it does not say what the answer looks like when the question parameter is left empty versus supplied, beyond the schema hint.

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

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

Schema coverage is 100% and the single 'question' parameter already carries a detailed description covering its optionality, the empty-value behavior, and the PII prohibition. The description adds nothing about the parameter, so the baseline 3 applies; it neither compensates nor needs to.

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 gives a specific verb ('explaining') tied to a named program (NSW Home Energy Saver) and enumerates the covered scope: loan cap, published income thresholds, funding use, and delivery. That scope list distinguishes it by content from generic siblings such as explain_loan_basics and explain_loan_options, though it never names a sibling explicitly to route the agent.

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?

Both directions are stated: use it when explaining the program's parameters, and do not use it to decide eligibility or approval. It even supplies the escalation path ('Send them to energy.nsw.gov.au'), which removes any guesswork about what to do with an eligibility question.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description contributes a useful scope boundary — this tool will not emit product specs or savings figures — but says nothing about what kind of response it produces (guidance text vs. structured list) or how the NSW loan list is surfaced.

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 short sentences, front-loaded with the positive trigger and followed by the exclusion, with zero filler or restated field labels. Every clause constrains agent behaviour.

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-required-parameter, read-only knowledge tool with no output schema, this covers what the tool explains and what it refuses to do. A brief note on what a returned answer looks like would make it complete, but 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?

The single optional 'question' parameter is documented at 100% coverage in the schema, including the PII refusal rule, so the description carries no burden and adds nothing beyond it. The baseline of 3 applies: schema does the work, description is silent on the parameter.

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

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

The description names a specific subject domain (ceiling insulation and draught-proofing) and adds coverage scope ('including the NSW loan list'), which is far more than a restatement of the name. It does not explicitly distinguish itself from overlapping siblings such as explain_loan_basics or explain_loan_options, which also touch the loan list, so it falls 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?

It gives a clear positive trigger ('when explaining ceiling insulation and draught-proofing') plus explicit exclusions ('do not use this to specify a product or print a savings figure'), which implicitly routes product questions to product_faq and figures to estimate_bill_savings. It stops short of naming those siblings, leaving the agent to infer the mapping.

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

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

Annotations already establish readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so safety of the call is covered. The description adds real behavioral guardrails on top: no eligibility or approval claims, no personal rate quotes, and an explicit PII exclusion list (TFN, SSN, Medicare, bank details, card numbers). What it does not disclose is the shape or length of the returned explanation, though 'short' gives a rough signal.

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, both earning their place: the positive trigger is front-loaded and the prohibitions follow immediately. No restating of the title, no filler, and the constraint boundaries are unambiguous.

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 one-parameter, read-only explanatory tool with full annotation coverage and no output schema, the description supplies everything needed to invoke it correctly and to avoid misuse. The only shortfall is the absence of any signal about how to choose between this and explain_loan_options for loan-mechanics questions.

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

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

Schema description coverage is 100% and the single 'topic' parameter is a fully enumerated, self-documenting field, so the schema carries parameter meaning on its own. The description adds nothing about topic selection (e.g., when 'both' beats 'solar' plus 'battery'), 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?

The description names a specific verb and resource ('short explanation of how an Australian household solar or battery loan fits together'), so an agent knows exactly what the tool produces. It scopes the domain to Australian household solar/battery loans, but never differentiates itself from the close sibling explain_loan_options, leaving that boundary 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?

It gives an explicit trigger ('Use this when someone wants a short explanation...') and explicit exclusions ('Do not use this to say they are eligible or approved, or to quote a personal rate'), which is exactly the when/when-not split an agent needs for routing. The only gap is that no sibling tool is named as the alternative for those excluded cases.

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

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

Annotations already establish read-only, non-destructive, closed-world behavior. The description adds that results are not a cheapest-option ranking or a rate offer, which is useful domain-specific context, but it does not explain the form of the response or any limitations on advice or accuracy beyond that.

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, front-loaded with the use case and a concise prohibition. There is no filler or repetition, and the exclusion is placed immediately after the intended use.

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 and a crowded explain/compare sibling set, the description should clarify what the explanation contains and when to choose explain_loan_basics, explain_hesl, or compare_scenarios. It covers scope and a key exclusion but leaves return nature and sibling routing under-specified.

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 single optional question parameter has 100% schema description coverage, including sensitive-data refusal behavior and empty-parameter behavior. The description adds no parameter semantics beyond the schema, so the baseline of 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?

The description lists the concrete options it covers (cash, personal or green loan, installer finance, home-loan top-up, and the NSW Home Energy Saver Loan) and frames the use case as comparing them, so the resource is identifiable. It never states explicitly that it returns explanatory or educational content rather than a recommendation, and it does not name the overlapping siblings, so sibling differentiation is only partial.

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 a clear when-to-use case and an explicit when-not-to-use restriction against ranking a cheapest option or presenting a rate as an offer. It does not route the agent to compare_scenarios, explain_loan_basics, or explain_hesl, which is a gap given the overlapping sibling set.

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

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

Annotations already establish that this is a safe, closed-world read (readOnlyHint true, destructiveHint false, openWorldHint false), so the safety profile is covered. The description adds a useful boundary — this is explanatory, not a quote or site assessment — but says nothing about what a response contains or how the explanatory content is scoped. Adequate, not rich.

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 filler. The positive trigger comes first, the scope details second, and the do-not-use clause last, which is the right ordering for an agent scanning for routing cues.

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

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

For a read-only, single-optional-parameter explanation tool with no output schema, the description supplies enough to select and invoke it correctly. The only material omission is which sibling to use instead when the user actually wants a quote, savings estimate, or site assessment.

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

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

Schema description coverage is 100%, and the single optional 'question' parameter is fully documented in the schema, including the PII refusal behavior and the empty-value behavior. The description adds nothing beyond that, which is acceptable at full coverage but caps the score at baseline.

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

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

Names a specific verb and subject (explaining rooftop solar) and narrows the scope to bill mechanics: imports, exports, and STCs. This is far more specific than the sibling explain_* tools, though it never explicitly contrasts itself with estimate_bill_savings or compare_scenarios, which sit closest to the same topic.

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 this when explaining how rooftop solar meets a household bill") plus an explicit exclusion ("Do not use this as a quote or a site assessment"). It stops short of pointing the agent at the correct sibling tool for quoting or assessment work, so routing is only partly resolved.

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

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

Annotations already establish that this is a safe, read-only, closed-world lookup, so the safety bar is low. The description adds real behavioral context beyond that: the hedging 'the public FAQ may cover it' warns that a miss is possible, and the explicit prohibition on eliciting tax IDs, Medicare numbers, or payment details is a behavioral constraint not captured in the annotations.

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, no filler. The applicability condition comes first and the prohibitions follow, which is the right ordering for an agent deciding whether to call.

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 one-parameter lookup with full annotation and schema coverage, only two things matter: when to call and what not to send — both are present. The residual gap is that with no output schema, the description does not say what a successful return looks like or what to do when the FAQ has no matching entry, though 'may cover it' gestures at the latter.

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?

There is a single parameter with 100% schema description coverage, including length bounds and the sensitive-data prohibition, so the schema carries the load. The description's only additional note on the parameter is the same sensitive-data rule restated, adding no new meaning. 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?

The description identifies the resource as the public FAQ about SparkReady and household solar/battery loans, so the agent can grasp what is being queried. However, it never states a verb (search, look up, retrieve) and never distinguishes this from the numerous explain_* siblings (explain_solar, explain_loan_basics, explain_hesl) that cover overlapping ground, leaving the boundary unclear.

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

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

It explicitly says when to reach for it ('when the question is about SparkReady or how household solar and battery loans usually work') and gives three concrete exclusions: do not use it to invent an answer, to assess an application, or to collect TFN/SSN/Medicare/bank/card data. What is missing is routing to a specific alternative — the agent is told what not to do but not which sibling to call instead.

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