Compare activities

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), but the description adds material behavior those annotations cannot express: deep=true downloads FIT files if needed, which is a network/IO side effect worth flagging and is disclosed. It also implicitly bounds input to 2–6. What's missing is any note on latency or cost of deep mode.

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?

Front-loads the capability and metric list, then the deep-mode modifier, then a worked example — a logical order with no filler. The parenthetical defining efficiency factor is long but genuinely informative for interpreting results, so it earns its space.

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?

There is no output schema, so the description carries the burden of explaining return content — and it does, enumerating the compared metrics plus what deep mode adds (aerobic decoupling, HR zone time, best efforts). An agent has everything needed to choose and 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 coverage is 67% and the one undocumented parameter (activity_ids) is compensated for by the description stating 'compare 2–6 activities', matching minItems=2/maxItems=6. deep is explained in both schema and prose. It adds value over the schema but does not, for example, clarify what activity_ids refer to or how to obtain them.

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?

States a specific verb ('compare') and resource (2–6 activities) and immediately enumerates exactly which fields come back (date, type, duration, distance, pace/speed, HR, power avg/NP, elevation, training effect/load, cadence, efficiency factor). This is clearly distinguishable from single-activity siblings like garmin_get_activity or garmin_analyze_activity.

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?

Gives a concrete usage scenario ('Am I getting fitter on my Tuesday interval run?' → list those runs, then compare them) and explains when to escalate to deep=true for FIT-based analysis. It does not explicitly contrast with garmin_analyze_activity or say when comparison is the wrong choice, so it falls short of the top band.

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