List Apple Health Workouts

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

Annotations already indicate readOnly, idempotent, non-destructive. The description goes far beyond by disclosing the cost of reading the whole file per query (with timing estimates), caching of identical queries, that start/end do not shorten the read, and that limit only caps the list not the aggregate. This is exceptional transparency about performance and semantics, fully complementing the 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?

The description is long but every sentence earns its place. It is front-loaded with the primary purpose, then systematically covers limit semantics, cost, and caching. The structure is logical and efficient, with no filler or repetition.

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 tool with 5 optional parameters, no output schema, and rich behavioral nuances, the description covers all critical aspects: purpose, parameter effects, performance cost, caching, and what the aggregate block returns. An agent can safely call this tool and interpret the response without additional clarification.

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 only 40% (end and start). The description significantly compensates by detailing the `limit` parameter's exact effect (caps the list, not the aggregate) and explaining the aggregate block fields and truncation indicators. It does not explain privacy_mode or response_format beyond their enums, but the default mention of summary mode adds context. Overall, it adds substantial meaning beyond the schema.

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 lists workouts from a local Apple Health export.xml, specifying the resource and source. It distinguishes the tool from siblings like apple_health_list_records by focusing on workouts, and the detail about privacy modes and aggregate behavior makes its purpose unmistakable.

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 provides clear context on when to use it (to list workouts from an export) and important usage constraints (bounded list, cost implications, caching behavior). It does not explicitly name alternative sibling tools or say 'use X instead', but the purpose and cost notes effectively guide usage without confusion.

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