OKC HVAC Calculator | Repair or Replace Decision Tool

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

With no annotations, the description carries the full burden of behavioral disclosure. It accurately conveys a read operation and what the response includes (content, direct answer, FAQ), but it does not mention error behavior for nonexistent slugs, whether unpublished articles are accessible, or any access 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 a single, efficient sentence with all key facts front-loaded: what is retrieved, the scope, and the primary access identifier. No filler or redundant phrasing.

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-parameter fetch tool with no output schema, the description covers the essential return value (full content, direct answer, FAQ) and the required input. It is not overly elaborate, but it is adequate; missing only minor details like not-found behavior or response format.

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 schema provides no description for the slug parameter, and the tool description only says 'by its slug,' which essentially repeats the parameter name. It does not clarify slug format, examples, or edge cases, so it adds minimal meaning beyond the schema.

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

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

The description names a specific verb ('Get'), a specific resource ('full content of a single published HVAC insights article'), and a unique access method ('by its slug'). It clearly distinguishes itself from sibling tools like search_hvac_decision_content or get_okc_hvac_business_info.

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 clearly indicates this tool is for retrieving a full article when the slug is already known. It does not explicitly name alternatives or exclusion conditions, but the context is unambiguous enough that an agent can infer when to use it over a search 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?

No annotations are provided, so the description carries the full disclosure burden. The verb 'Get' and the enumerated fields make clear this is a read-only look-up with a predictable payload, which is adequate for a zero-parameter tool, but it adds no context beyond that (e.g., whether the data is static, whether any external call is made, or response formatting).

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 sentence that is front-loaded with the verb and resource, with the parenthetical field list adding concrete value. Every word earns its place; the provenance note 'powered by Covington Heat & Air' clarifies the data source without bloat.

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 tool with no output schema and no annotations, the description is largely sufficient: it tells the agent exactly which data fields come back, partially substituting for a return-value schema. The only real gap is the unaddressed relationship with get_okc_hvac_service_area, which is minor for such a simple getter.

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 has zero parameters, so the empty schema fully covers the input side and the rubric baseline for 0 params is 4. The field list in the description concerns the return payload rather than parameters, so no parameter explanation 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?

States a specific verb and resource — 'Get business information for the OKC HVAC Calculator' — and enumerates the return fields (name, phone, email, website, service area), so the agent knows exactly what it produces. It does not explicitly differentiate itself from the sibling get_okc_hvac_service_area, which overlaps on the service-area field, so it stops just 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?

No guidance on when to use this tool versus the closely related get_okc_hvac_service_area or any other sibling. The description is a pure imperative with no context, exclusions, or alternative routing, leaving the agent to infer the selection logic.

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 behavioral burden. The verbs 'Get' and 'check' establish that this is a read-only lookup, and the optional city/ZIP filtering is disclosed. However, it does not describe the response format or any edge cases such as unlisted ZIPs or partial coverage.

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, well-structured sentence that front-loads the primary purpose and then adds the optional behavior. Every word earns its place, with no repetition or 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 simple tool with one optional parameter and no output schema, the description covers both invocation modes: retrieving the service area and checking a specific city/ZIP. It does not detail the return shape, but the purpose and parameter semantics are sufficiently complete for an agent to use it correctly.

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

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

The schema provides only a parameter name 'cityZip' with zero description coverage. The description adds meaningful semantics by explaining that it is a city or ZIP code used for an optional coverage check. It lacks concrete format examples or accepted value styles, but it does give the agent enough to infer what to pass.

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

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

The description states a specific action ('Get'), a clear resource ('the Covington Heat & Air service area'), and an optional sub-behavior (checking whether a city or ZIP is covered). This is distinct from the sibling tools, which deal with articles, business info, repair analysis, and booking/lead requests.

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 clearly indicates when to use the tool: when you need the service area or need to check coverage for a specific city/ZIP. It does not explicitly name alternatives or exclusions, but the sibling tools are sufficiently distinct that no confusion is likely.

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 disclosure burden. It clearly indicates this is a metadata-retrieval operation and enumerates the categories of information returned. It does not describe potential implicit behavior such as whether the tool runs any analysis or only returns static information, but the phrasing strongly implies a read-only informational call.

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, focused sentence that front-loads the tool's core purpose and then provides a concise list of the metadata categories. Every word contributes meaning, with no repetition or 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?

Given the tool's simplicity (zero parameters, no output schema), the description is complete enough: it tells an agent what the tool returns and the scope of that content. It leaves no major ambiguity about what the agent will get by invoking it.

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 has zero parameters, so the baseline is 4. The description adds context by mentioning that the tool's input schema is part of the returned metadata, which is sufficient given that no parameters need explanation.

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: 'Get metadata about the repair-or-replace decision tool.' It further clarifies the exact contents (what it does, assumptions, thresholds, fees, input schema), making the tool's purpose unambiguous and distinguishable from sibling tools like run_hvac_repair_or_replace_analysis.

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

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

The description implies the tool is used when an agent needs metadata about the repair-or-replace decision tool, but it does not explicitly state when to use it versus siblings such as run_hvac_repair_or_replace_analysis or search_hvac_decision_content. There is no direct comparison or exclusionary 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 burden. It clearly discloses the output composition, the estimates-only nature, and the limitation that final diagnosis, equipment recommendations, availability, and pricing require on-site evaluation. This is substantial behavioral disclosure beyond a simple 'runs analysis' statement.

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

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

Two crisp, purposeful sentences. The first states the action and output; the second immediately qualifies the output with the estimates/on-site caveat. No filler or repetition.

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 output schema, and minimal schema descriptions, the tool description is not complete enough for an agent to confidently populate all inputs or interpret the full output. The return-value summary is helpful, but the parameter semantics and sibling routing remain under-explained.

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 only 23% (3 of 13 parameters have descriptions), and the tool description adds no parameter-level meaning. It references a multi-year cost comparison but does not explain how fields like repairCostInput, replaceCostInput, safetyFlags, priorRepairs, or utilityBill factor in. The description fails to compensate for the low schema coverage.

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?

Description names a specific verb ('Run'), a specific resource ('repair-or-replace decision engine'), and the exact output (REPAIR, REPLACE, DEPENDS, or IMMEDIATE_SERVICE) with reasoning and a multi-year cost comparison. This clearly distinguishes it from siblings like get_repair_or_replace_tool_info and search_hvac_decision_content.

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

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

The description implies this is the tool to use when an HVAC repair-or-replace recommendation is needed, but it does not explicitly state when to use it over sibling tools, nor does it give exclusion criteria. The 'Estimates only' caveat provides some context for expectations, but no explicit alternatives or when-not-to-use 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. It adds useful behavioral context by noting the search is limited to 'published' articles and that the return value is 'summaries' rather than full content. Yet it does not disclose pagination, default limit behavior, or what happens with no query/filters.

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 two short sentences with no wasted words. It front-loads the core action and resource, then adds the return type. Every phrase earns its place.

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

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

For a simple search tool with four optional parameters and no output schema, the description provides adequate basics but leaves gaps: the 'limit' parameter is unexplained, there is no mention of result ordering or pagination, and no guidance on when to prefer this over the sibling get_hvac_article. It is serviceable 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?

Schema description coverage is 0%, so the description must compensate. It successfully explains the meaning of query, category, and author as filter dimensions, but it does not mention the 'limit' parameter or explain how the parameters combine. This is partial compensation for the missing schema descriptions.

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

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

The description states a specific verb ('Search') and resource ('published HVAC insights articles'), and identifies the filtering dimensions (keyword, category, author). This clearly distinguishes it from sibling tools like get_hvac_article, which presumably retrieves a single article rather than searching a set.

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

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

The description implies the tool is for exploratory search by returning summaries, which hints at a different use case than fetching full articles. However, it never explicitly names alternatives or conditions for when to use this tool over get_hvac_article or other siblings.

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 disclosure burden. It usefully discloses that an API key and explicit consent are required, which is relevant behavioral context for a submission tool. But it does not explain side effects, irreversibility, failure behavior, or what happens after the request is submitted, so the transparency is only partial.

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

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

The description is a single dense sentence that front-loads the action and target, then adds the two critical prerequisites. There is no filler and every word contributes.

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

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

For a tool with nine parameters, zero schema descriptions, no annotations, and no output schema, this description is not complete enough for reliable invocation. It does not specify parameter formats, allowed service types, consentText semantics, preferredTime syntax, or response/confirmation behavior; it only establishes the basic purpose and key prerequisites.

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

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

Schema description coverage is 0%, and the description adds no meaning for any of the nine parameters. It only implies consent is required, leaving fields like serviceType, cityZip, consentText, and preferredTime entirely unexplained. The description does not compensate for the lack of schema-level documentation.

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

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

The description clearly states the action (submit a booking/appointment request), the target (Covington Heat & Air), and the appointment framing distinguishes it from the sibling lead-request tool. However, it does not explicitly call out the sibling or say 'use this for bookings, not leads,' so it stops just short of full differentiation.

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 prerequisites ('requires an API key and explicit user consent') but no guidance on when to use this tool versus submit_covington_lead_request or the other HVAC tools. There are no when-to-use, when-not-to-use, or alternative-selection instructions.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It adds the useful prerequisites of an API key and explicit consent, but it does not describe the external side effects of submitting a lead, any response/return behavior, error conditions, or what happens after submission. For a mutation-like action this is a significant 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?

The description is two tight sentences with no filler. The primary action is front-loaded and the key prerequisites are stated immediately after, making it easy to scan.

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

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

For a 7-parameter tool with no output schema and no annotations, this description is minimal. It omits response format, error handling, consent text requirements, and guidance on how this lead submission relates to the booking sibling. An agent would need to make assumptions or inspect external documentation.

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

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

Schema description coverage is 0% and the description adds little parameter-level meaning. It clarifies that consent is required, but leaves email, phone, cityZip, message, and consentText unexplained. The parameter names are somewhat self-evident, but the description does not compensate for the missing schema documentation.

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

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

The description clearly states the action ('Submit a lead') and the target ('Covington Heat & Air'). It distinguishes this from the sibling booking tool by describing the resource as a lead/contact request, though it does not explicitly contrast itself with alternatives.

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

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

The description implies usage for lead/contact requests and gives some logical prerequisites ('Requires an API key and explicit user consent'). However, it does not state when to prefer this tool over submit_covington_booking_request or other siblings, nor does it mention exclusions or fallback scenarios.

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