Joey George Plumbing

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

With no annotations at all, the description carries the full burden, and it partially meets it by disclosing a key constraint: the website is the only contact channel, which stops an agent from promising a phone number. It does not say whether the data is static or live, nor anything about freshness or failure behavior.

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

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

Two tight sentences, front-loaded with the entity identity and followed by the return contents. Nothing is redundant or padded.

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 trivial no-param read tool with no output schema, the description does the necessary work by listing the four returned categories. It is complete enough to call correctly, with only minor gaps around data freshness and the shape of the nested lists (services, 13 cities).

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

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

The tool takes zero parameters, so the baseline is 4. The description correctly presents it as a no-argument lookup that returns a fixed set of facts, consistent with an empty schema.

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

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

States a concrete verb and resource (get facts about the business) and enumerates exactly what comes back: services, service area, hours, website. An agent can tell it apart from check_water_hardness and water_heater_check by content, though the description never explicitly routes questions like 'what services do you offer?' away from plumbing_question.

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

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

Usage is only implied: the returned fields suggest the agent should call it for business-detail questions. There is no statement of when to use it versus plumbing_question, which is the closest sibling and could plausibly overlap for service-area or hours questions.

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 burden and does so well: it discloses the return payload (gpg value, interpretation for a home, treatment guidance) and a genuine fallback behavior — unknown cities get an honest area range, 'never an invented number'. What's missing is any note on exact-match expectations for city names or what an unsupported input looks like.

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 action and scope, and every sentence contributes (scope, return contents, recommendation rule, fallback). It is dense but single-paragraph and slightly overloaded with brand specifics (HALO 5, H2 Zero Scale Media) that help a domain agent but lengthen the read.

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 no output schema and no annotations, the description covers purpose, returns, and edge-case behavior adequately. The only residual gap is input-matching behavior (spelling/case/aliases) and whether the same guidance applies to non-hard-water cities.

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 goes beyond the schema by constraining the valid domain to South Orange County plus Irvine — something the schema's bare examples ('Laguna Niguel', 'Mission Viejo') do not state. That materially changes how an agent fills 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?

States a specific verb and resource ('look up tap-water hardness') and bounds the scope precisely to 'a South Orange County city (plus Irvine)'. That geographic scope alone separates it from plumbing_question and water_heater_check 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?

Usage is implied by the geographic scope, and the description notes that out-of-dataset cities still return a general range, so the agent knows it can still call the tool. However, no alternative is ever named — it never says to route general water-treatment questions to plumbing_question or business questions to business_info.

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 disclose two real traits: the answer style ('short, plain-language, teach-first') and the out-of-scope fallback behavior. It omits any statement about side effects, auth, or answer depth, but for a stateless Q&A tool those are minor.

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?

Purpose is front-loaded in the first sentence, followed by scope and then off-topic handling. The topic enumeration is long but each item functions as a scope boundary, so it earns its space; only slight trimming would be possible.

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, no-output-schema, unannotated tool, the description covers purpose, scope, answer style, and out-of-scope behavior. The only material omission is how it relates to the overlapping water_heater_check sibling.

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?

Only one parameter with 100% schema description coverage, so the schema already documents it; baseline is 4. The description adds domain framing ('common homeowner plumbing question', 'plain words') that constrains what a valid question looks like beyond the schema text.

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 ('Ask a common homeowner plumbing question and get a short, plain-language, teach-first answer') and enumerates the covered topics, so the agent knows exactly what domain it serves. It stops short of differentiating from the sibling water_heater_check, which overlaps with the listed water-heater topics (sediment/popping, rotten-egg smell).

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 covered-topic list plus 'Off-topic questions get an honest list of what is covered' gives clear context for when to call it. There is no explicit exclusion or routing rule pointing to the siblings (check_water_hardness, water_heater_check, business_info), which is the remaining gap.

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 burden of behavioral disclosure. It usefully clarifies that output is general guidance rather than a diagnosis or quote and that the $99 flush price is mentioned only when sediment/flush guidance applies. However, it does not state whether the tool is read-only or has any side effects, leaving some behavioral traits implicit.

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 sentences, front-loads the core purpose, and avoids unnecessary repetition. Every clause contributes useful scoping or caveat information. It is appropriately sized for a simple two-parameter tool.

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

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

For a low-complexity tool with full schema coverage and no output schema, the description sufficiently explains what the tool returns: maintenance and troubleshooting guidance, not a diagnosis or quote. It also explains the conditional pricing mention. It lacks explicit alternative-tool guidance, but is otherwise complete for the task.

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 parameters are already documented. The description adds example symptom types such as popping/rumbling noises, running out of hot water, leaking, rusty water, and no hot water, which helps interpret the optional 'symptoms' parameter beyond the schema. It does not add format or syntax details 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?

The description states a specific verb and resource: 'Get maintenance and troubleshooting guidance for a tank water heater.' It clearly scopes the tool by age and optional symptoms. It does not explicitly name or distinguish itself from the sibling 'plumbing_question', though the tank-water-heater focus provides implicit 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 implies the tool is used when seeking maintenance or troubleshooting guidance based on a tank water heater's age and symptoms. It also sets a boundary with 'General guidance, not a diagnosis or a quote,' but it does not explicitly state when to use this tool versus siblings like 'plumbing_question' or 'business_info'.

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