get_training_summary

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

Annotations already declare readOnly/idempotent/non-destructive, so the description's added value is the derivation source (server-side aggregation of the activity list) and the precise default range, which an agent cannot get from the schema. It does not mention performance, caching, or data-lag caveats, but with an output schema present that omission is minor.

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?

Three tight sentences, front-loaded with the resource and its metrics, then computation source, then defaults. The '(or month/day)' parenthetical slightly duplicates the group_by enum, but nothing else is wasted.

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 an output schema and full annotations, the description needs only scope, granularity, and defaults — all present. The one remaining gap is sibling routing guidance, which is a usage concern but still affects whether an agent picks this tool 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 67%, and the description compensates for the gap by explaining that group_by selects week versus month/day granularity and by pinning the default range when start/end are omitted. The date parameters' formats ('YYYY-MM-DD', 'today', 'yesterday') are already in the schema, so no credit there.

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+resource (training volume summary) and enumerates exactly what the output covers: sessions, hours, distance, elevation, training load, TSS, HR-zone minutes, split by sport. The clause 'computed by this server from the activity list' plus the aggregation granularity clearly separates it from siblings like list_activities and get_day_detail.

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 default window ('last 8 full ISO weeks including the current one') gives implied usage context for aggregate trend questions, but the description never says when to prefer this over get_day_detail or list_activities, nor any exclusions. Routing is left to inference from the metric list.

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