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

Annotations already declare readOnlyHint and openWorldHint=false, so the safety profile is covered. The description goes further by publishing the exact formula and the ceiling-rounding rule for bags, letting the agent predict the output precisely. It doesn't note the defaults or edge cases (e.g. current above target), but adds real value beyond 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?

Three sentences, front-loaded with the outcome, then the formula. Every element earns its place; no filler or repetition of 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?

No output schema exists, and the description fully specifies the return values (pounds of salt and whole bags) plus the rounding convention. An agent has everything needed to call it and interpret the result.

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 baseline is 3. The formula adds genuine meaning by showing how each parameter is used and clarifying that target_ppm comes from the chlorine generator's requirements, which is more than the schema's unit labels alone convey.

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 (compute pounds and bags) and resource (pool salt for a saltwater pool), with the exact quantity returned. It is clearly distinguishable from siblings like calc_pool_chlorine and calc_pool_volume without opening any 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?

The context ('raise a saltwater pool from its current salt level to the target your chlorine generator needs') implies when the tool applies, but it never explicitly routes the agent away from siblings such as calc_pool_chlorine or states prerequisites. Usage 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.