read_measurements

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

Annotations only declare it as a safe read, so the description carries real added weight: it discloses unit derivation (cm, or inches for a lb profile), body-fat as a percentage, newest-first ordering, and that a per-kind latest value with change-since-first is computed. It does not state whether the response embeds that summary separately or how truncation interacts with the per-kind summary.

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?

Everything sits in one long, comma-spliced sentence with an ellipsis ('the profile's own kinds …') that makes it hard to parse on first read. The resource is front-loaded, which helps, but the return-value detail is buried mid-clause rather than structured.

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 must explain returns and largely does: value units, percent body fat, ordering, the latest-per-kind delta, which kinds the app's form shows, and custom kinds. What is missing is any statement of what the response looks like structurally (summary vs. series) and how the range defaults behave when from/to are omitted.

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 from, to, and limit (including the 30 default, 2000 cap and truncated flag) are already documented. The description adds only the implicit idea of a date 'range'; it offers no extra semantics for limit or the interplay of truncation with the range.

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 names a specific resource (body measurements: waist, arms, body fat, custom kinds) and states exactly what is returned (values newest-first plus the latest value of each kind with its delta). It is clearly a read of measurement data, but it never names a sibling such as read_bodyweight to delimit the boundary between measurements and weight.

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?

There is no when-to-use or when-not-to-use guidance, no statement of prerequisites, and no pointer to an alternative tool (e.g. read_bodyweight for weight, or write_measurement for mutation). The closest thing to context is 'in the range', which merely echoes the from/to parameters.

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