calculate_ph

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 includes the formula and return elements but does not disclose behavior when both or neither input is provided, which is a notable gap for a conversion 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?

Three sentences, each serving a purpose: explaining the function, listing use cases, providing formula and return info, and directing to related tools. No superfluous content.

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 two optional parameters and an output schema (not detailed in the description). The description covers basic usage but fails to explain behavior when both parameters are supplied or neither, nor does it handle error conditions. Given the output schema exists, it partially compensates, but the missing edge-case clarity lowers completeness.

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 parameter descriptions. The description adds context that inputs are mutually exclusive (pH or [H+]), which is valuable beyond the schema. It also provides the formula and use cases, enhancing understanding.

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 it computes pH from H+ concentration or vice versa, with specific use cases (chemistry, aquarium care). However, it does not explicitly differentiate from sibling tools like calculate_soil_ph_amendment, merely pointing to list_bundles for related calculators, which slightly diminishes distinction.

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 mentions when to use (chemistry, aquarium care) and what it returns (missing value and acidity class). However, it lacks explicit guidance on when not to use or alternatives, leaving implied context rather than clear direction.

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