get_exercise_analytics

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

With no annotations, the description takes on the burden of behavioral disclosure. It conveys per-second granularity, equipment-dependent channel availability ('whatever the equipment reports'), and the downsample mechanism that controls data volume. This is meaningful context beyond the schema, though it does not discuss auth or rate limits.

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 overview sentence is dense and front-loaded, with ellipses signaling non-exhaustive lists rather than adding noise. Each argument gets a single, purposeful line with no filler.

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 an output schema, so return-value details are already covered. The description provides the required input source and behavior controls, and the parameter explanations leave no ambiguity about how to call the tool.

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 0%, so the description fully carries parameter documentation. It explains both analytics_id's provenance and sample_every_seconds as a downsample factor with concrete examples, making correct invocation clear.

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 'Per-second analytics for one exercise,' which names the exact verb, resource, and scope. It further distinguishes itself from session-level siblings by enumerating machine channels, heart-rate samples, HR zones, and summary metrics specific to a single exercise.

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 clearly states the analytics_id comes from get_workout_session, giving the agent a concrete prerequisite and sourcing path. It does not explicitly name alternatives or when-not-to-use cases, but the intended context is unambiguous.

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