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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered; the description adds the actual computation model, including default assumptions and the mg/L ÷ 17.1 conversion, which is genuinely useful behavioral context. It stops short of describing output shape (e.g., whether results are labeled per formula) but the deterministic, formula-driven nature is fully disclosed.

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 outcome, then follows with the exact formulas, with no filler sentences. It is dense and formula-heavy, but each line maps to a computed output or input relationship, so nothing is wasted.

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, the description carries the burden of describing returns, and it does so by naming the three computed quantities and their formulas. Minor gaps remain around output formatting and units of returned values, but an agent has enough to call it correctly given all six parameters are defaulted.

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% with defaults documented per-parameter, so a baseline of 3 is guaranteed; the description goes further by placing parameters inside named formulas (people × gal/person/day × hardness), explaining that hardness can be supplied in gpg or mg/L and how they convert, and flagging rated_capacity_grains as the spec-sheet input that drives the regeneration calculation.

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 pair ('size a water softener') and then enumerates exactly the three quantities it returns: grains/day, grain capacity for the regen interval, and regeneration frequency. That is distinguishable at a glance from every sibling calc_* tool, which cover unrelated building/pool/electrical domains.

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 inputs (household size, hardness, regen interval), so an agent can infer this is for residential softener sizing. However, there is no explicit statement of when to prefer this over related tools, no prerequisites, and no note that rated_capacity_grains is only needed for the regeneration-frequency output.

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