Calculate Pool

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

Annotations already declare this is read-only, idempotent, non-destructive, and closed-world. The description adds useful behavioral context by naming the returned fields (amount, readable amount, common packages, factor used, safety line) and clarifying that it is a calculation helper rather than a shock or LSI 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?

The description is front-loaded with the use case and is generally dense with relevant information. The chemical list is long but largely earns its place because it maps products to treatment goals; slightly tighter structure could improve readability.

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 rich annotations, 100% schema coverage, and presence of an output schema, the description is complete enough for correct selection and invocation. It covers purpose, supported scenarios, exclusions, units, and return content without requiring the agent to infer missing 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 coverage is 100%, so the baseline is already 3. The description still adds semantic mapping beyond the enum names, explaining which chemicals correspond to free chlorine, salt chlorination, alkalinity, stabilizer, calcium hardness, and pH changes, and clarifying units as ppm or pH.

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 and resource: calculating how much pool chemical to add to move from a current to a target level. It enumerates the supported chemical/use cases and explicitly excludes shock targets and water-balance (LSI) questions, making its scope clear.

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 opens with a clear use condition ('Use this when someone asks how much...') and lists the supported chemical scenarios. It also gives explicit exclusions ('Not for shock targets or water-balance (LSI) questions'), so the agent knows when not to invoke it.

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, idempotentHint, and destructiveHint=false, so safety is covered. The description adds useful behavioral context: defaults for hours and buffer, and what the output includes (BTU/h, size with buffer, total BTU, heat pump equivalent).

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, front-loaded with the usage trigger, followed by inputs, outputs, and exclusions. No wasted words; each sentence carries distinct information.

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

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

The tool has an output schema and rich annotations, and the description still covers purpose, inputs, outputs, and exclusions. Nothing essential for correct invocation 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 schema already documents all parameters and defaults. The description repeats the defaults and mentions the buffer's purpose, but adds little semantic depth beyond the structured fields.

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: 'what size pool heater (BTU per hour) they need to raise the water a number of degrees Fahrenheit in a given time.' It clearly distinguishes from heating cost and model recommendations, and implicitly from volume calculation by referencing gallons as input.

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 asks...') and clear exclusions ('Not for heating cost per month or heater model recommendations'), but does not name a specific alternative sibling tool for those excluded tasks.

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 read-only, idempotent, closed-world, non-destructive behavior, so safety is covered. The description adds real context beyond that: exactly which dimension ranges, depths, and wall heights the tables cover and that the factors used are returned. It doesn't state whether the results are exhaustive/finite or that no computation is performed on custom sizes, but the scope enumeration largely implies this.

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 usage trigger, followed by return contents and the alternative routing. The dimension enumerations are dense but each earns its place by telling the agent exactly which sizes are answerable; minor verbosity in listing ranges twice.

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?

Output schema exists and annotations cover the safety profile, so the description only needs purpose, scope, and routing — all present. An agent knows when to call it, what it will get back, and where to go otherwise.

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 `kind` enum is fully documented in the schema, including the default. The description indirectly maps its two table families to the enum values but adds no syntax or format detail beyond the schema, so 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 resource (standard pool size gallon tables) with the coverage scope (inground rectangles and above-ground round/oval) and names the sibling tool to use for anything else. An agent can distinguish it from pool_volume 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?

"Use this when someone asks how many gallons a common pool size holds..." gives concrete triggering examples, and "For any other size or shape use pool_volume" explicitly routes to the alternative with the deciding condition.

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 readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered and the description's job is lighter. It adds real context beyond that: the exact outputs returned (gallons, litres, cubic feet, cubic metres, surface area, formula) and the shape/depth input modes it accepts. It does not discuss error behavior or what happens with mismatched shape/dimension combos, keeping it off 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?

One dense, front-loaded paragraph that begins with the trigger condition and ends with the sibling routing rule; every clause carries information. It is list-heavy (shape names, unit names, wall heights) and slightly overpacked for a single sentence, but there is no filler to remove.

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 an output schema present, return values needn't be spelled out, yet the description still names them, and it covers the input-mode space (all shapes, three depth configurations, ft/m). The one omission is that freeform shapes require a supplied area — visible only in the schema — so the description is nearly, but not entirely, self-sufficient.

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 83%, so the schema already documents most parameters and a baseline 3 would be acceptable. The description adds value by tying the shape enum to the depth configurations available (single depth, shallow + deep end, or above-ground 48/52/54 in wall height) and by stating that dimensions may be in feet or metres, which clarifies parameter interactions rather than restating individual fields.

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 precise verb and resource — compute gallons/litres/cubic feet a pool holds from shape and size — and enumerates the supported shape, depth and unit variants. An agent can distinguish it immediately from chemical_dose, pump_size and heater_size, which are sizing/chemistry tools rather than geometry calculators.

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 opens with an explicit trigger ('Use this when someone wants to know how many gallons...') and then names the three sibling tools plus the selecting condition: 'use it before chemical_dose, pump_size or heater_size when only dimensions are known.' That is a clear when-to-use rule with an explicit alternative.

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 this a read-only, idempotent, closed-world computation, so the safety profile is covered. The description adds scope boundaries (no cost or model advice) and flags that turnover hours defaults to 8, which is behaviorally useful. It doesn't note any assumptions or limits on the horsepower rule-of-thumb, which would have pushed this higher.

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 triggering condition, followed by a single tight sentence of exclusions. The long enumeration of return values ('gallons per minute, gallons per hour, a rule-of-thumb horsepower range, filter areas, pipe velocities') is the weakest part since an output schema already exists.

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?

An output schema exists, so the return-value list is largely redundant, but the description still conveys the key thing an agent needs: the tool computes from gallons plus turnover hours with a default, and refuses cost/model advice. Nothing essential about invocation 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% and both parameters are already documented with units, ranges, and defaults, so the baseline applies. The description restates the default of 8 for turnover hours and adds a use-case hint for heavy use only indirectly; it adds little 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?

States a specific computation (pool pump size / flow rate for a given turnover) with the concrete inputs involved, so it is clearly distinct from chemical_dose, heater_size, and pool_facts. An agent can route 'what pump do I need' questions here without opening the 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 an explicit triggering situation ('when someone asks what size pool pump they need or what flow rate turns their pool over') plus exclusions ('not for electricity cost or pump model recommendations'). It stops short of naming a sibling alternative — pool_volume is only referenced inside the parameter description, not in the usage guidance.

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