mfp_get_water

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

Annotations already declare the tool read-only, idempotent, and non-destructive, so the safety profile is covered. The description adds useful behavioral context by specifying that the return value is the number of cups/glasses logged. It does not disclose edge cases like missing data or default zero behavior, but the annotation coverage lowers the need for that detail.

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 compact and front-loaded, leading with the purpose and then covering return value, arguments, and return type in a scannable structure. It slightly duplicates the date default info already present in the schema, but there is no filler or unrelated detail.

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 read tool with rich annotations and an output schema, the description covers the essential facts: resource, date scope, return units, and return type. Minor gaps like behavior when no water is logged remain, but they are not critical for a correctly annotated, idempotent read operation.

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?

With reported schema description coverage at 0%, the description compensates by explaining the `params: GetWaterInput` wrapper and the `date` parameter's format and default behavior. It repeats some of the schema's own property description, but the wrapper guidance and the explicit optional-default note help an agent construct the call correctly.

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 opens with 'Get water intake for a specific date' – a specific verb, resource, and temporal scope. It adds that the result is 'the number of cups/glasses of water logged for the day,' which makes the resource concrete. It does not explicitly differentiate from siblings like mfp_get_diary, so it stops short of a 5.

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 intended use case is stated clearly: retrieve water intake for a specific date, with an optional date defaulting to today. There are no explicit exclusions or alternative routing instructions, but the context is clear enough for an agent to pick this over the broader diary or write-oriented sibling tools.

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