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

Annotations already declare readOnlyHint=true and non-destructive, and the description goes well beyond them: it discloses the error behavior for missing exercise_id, the per-kind return composition (top set, Epley est-1RM, PRs, trend %), and the non-obvious merging behavior where one movement logged under several catalogue rows is treated as one history with same_movement_ids listing them. That is real behavioral context an agent cannot get from 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?

Front-loaded with the core distinction and dense with useful facts; the anti-hallucination note ('named `kind`, not stat_type/stat/type/metric') earns its place as a guardrail. Minor redundancy in restating get_coaching_context at both the start and the end, which slightly dilutes the structure.

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?

An output schema exists and the description still usefully explains what each kind yields, and the required-vs-ignored parameter logic is fully covered for a zero-coverage schema. The only real hole is date_from, whose range semantics are left entirely unexplained for a tool whose whole point is time-series statistics.

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 must carry the load, and it does for two of three params: `kind` is fully enumerated with what each value returns and which needs an exercise_id, and exercise_id's requirement/ignored conditions are spelled out. The third parameter, date_from, is never mentioned, leaving its filtering semantics undocumented in both schema and description.

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?

Opens with a specific resource and scope: 'Statistics for ONE exercise, or for training as a whole', immediately covering both modes. It names the sibling it is not (get_coaching_context) and what that sibling adds, so an agent can route without opening either schema.

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 explicit when-to-use routing for get_coaching_context (task='weekly_review'), per-kind guidance for which kind to pick, and a hard exclusion rule: exercise_id is REQUIRED for progression/prs and ignored for volume. It even states the failure mode ('without an exercise_id is an error, not a whole-library default') and points to list_exercises for ids.

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