get_progress

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

Goes well beyond the read-only/idempotent annotations by disclosing the exact metrics computed per exercise (sessions, working sets per week, e1RM start/end, best e1RM, % change, last date) and the smoothing methodology (median of first and last 3 sessions). It also explains the fallback for unweighted exercises (top-set reps) and the sort order (muscle group), which an agent could not infer from annotations or schema.

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 question and default window, then detail. The middle sentence is dense and wraps awkwardly with mid-sentence line breaks, but essentially every clause (metric list, smoothing rule, unweighted fallback, sort order, filter values) carries real information.

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?

Since an output schema and read-only annotations exist, the description needn't repeat return shapes or safety; instead it usefully documents computation logic that a schema cannot express. The only notable omission is date parameter formatting, which an agent would need to call correctly with non-default dates.

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?

With 0% schema description coverage, the description carries the burden and largely succeeds: it explains min_sessions as a minimum session count, muscle as a filter accepting either a muscle or a group, and start_date/end_date as the range with a 6-month default. It does not specify the expected date string format, leaving one meaningful gap.

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 opening line 'Which exercises are improving or stalled' states a specific analytical question this tool answers, clearly distinct from siblings like get_exercise_history (raw per-exercise history) or get_weekly_training (weekly rollups). It stops short of naming or contrasting those siblings explicitly, so an agent must infer the distinction.

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 clear operational context: default window is the last 6 months, a min_sessions threshold gates which exercises appear, and filtering works by muscle or coarse group (chest, back, shoulders, arms, legs, core). It does not say when NOT to use it or point to the sibling that returns raw history instead.

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