Read the health record

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, not open-world), yet the description adds substantial non-obvious behavior: superseded rows persist with status 'entered-in-error', the current flag marks the value the plan counts, sync bookkeeping is excluded, measurements are normalized to SI while unknown labs keep their reported unit, and on Dropbox the result additionally lists folder files not in the record with a do-not-import-unasked rule. This is exactly the kind of context annotations cannot carry.

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?

It opens with what is returned and then layers the non-obvious rules; every sentence carries distinct information (status semantics, current flag, SI units, Dropbox folder listing). It is a dense block rather than bulleted, but there is no filler, so it stays appropriately sized for the amount of behavior disclosed.

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?

Given an existing output schema, the description need not restate the return shape, yet it adds the interpretive layer that matters: which rows represent current truth, how status values should be read, and how units are treated. Combined with annotations carrying the safety profile and full schema coverage on parameters, an agent has everything needed to call this correctly.

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% and both parameters (since, metric) are fully documented in the schema, establishing the baseline of 3. The description's line about optionally narrowing to one metric or to rows on or after a date largely restates the schema's own semantics rather than adding syntax, edge cases, or format detail.

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 verb and resource: it returns the user's health-roadmap.json and enumerates the data domains (profile, measurements, lab values, medications, supplements, screenings, documents). This is far beyond a tautology. However, it never explicitly contrasts itself with siblings like get_plan or correct_value, so an agent must infer the boundary from the content list alone.

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?

It gives clear in-tool usage rules (read status:active rows as current, use the current flag, optionally narrow by metric or since date), but it never states when to choose this tool over a sibling such as get_plan or file_results. The one routing-adjacent instruction ('offer to import them, never do it unasked') concerns import_documents behavior, not tool selection, so usage guidance is implied rather than explicit.

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