get_exercise_history

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower. The description still adds genuine behavior beyond them: results are ordered newest first, the payload includes a summary plus per-workout rows with specific metrics, and include_sets=true expands to every set including warm-ups. It does not disclose what happens on an ambiguous partial-name match (error vs. best guess) or how limit truncation behaves.

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 sentences, front-loaded with the return shape, then the parameter notes, then the include_sets flag. Every sentence carries information. The first sentence is dense with metric names but not padded.

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?

A read-only history tool with no output schema and 5 fully undocumented params needs the description to cover date filtering and result-count limits, and it doesn't — the default limit of 100 and the empty-string date defaults are left for the agent to guess at. It is adequate for the shape of the response, thin on how to scope the query.

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. It meaningfully explains `exercise` (name/id/partial matching) and `include_sets` (warm-ups included), which are the two non-obvious parameters. But `limit`, `start_date` and `end_date` get no syntax or behavior treatment — notably the date format and whether an empty date means all-time — so the compensation is only partial.

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 the specific resource (one exercise's history over time) and precisely describes the return shape: a summary plus one row per workout, newest first, with top set, e1RM, working sets and volume. An agent can distinguish it from get_sessions (all sessions) and get_progress. The retrieval verb itself is only implied by the name, but the resource and output are unambiguous.

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 gives real guidance on *how* to address the exercise (name, partial name if unambiguous, or id), which is usable context. It never states when to prefer this over siblings like get_progress, find_exercises or get_sessions, nor any prerequisite (e.g. resolve an ambiguous name first). Usage is implied rather than spelled out.

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