Mark an exercise as a favourite or unmark it to move it to the top of the exercise picker, helping users find preferred exercises first.
Mark an exercise as a favourite (sorted to the top of the exercise picker) or unmark it.
| Name | Required | Description | Default |
|---|---|---|---|
| favourite | Yes | ||
| exerciseId | Yes | Exercise id, e.g. "0025" (see read_exercises) |
Changes observed during successful MCP inspections.
v1.1.0Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already disclose the write/reversibility profile (readOnlyHint=false, destructiveHint=true), so the description's main addition is the side effect that favourites are sorted to the top of the picker. It does not mention idempotency (repeating favourite=true is a no-op) or that the boolean toggle restores prior state, which would have been useful given the alarming destructiveHint=true on what is a trivially reversible setting.
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?
A single sentence with the two operation modes front-loaded and the effect in a parenthetical; every clause carries information and nothing is 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?
For a two-parameter, low-complexity toggle with no output schema, the description covers both directions of the operation and its visible consequence. Missing only minor context such as idempotency and whether the favourite persists across the account.
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 50% and only exerciseId is documented there (with pattern and example pointing to read_exercises). The description compensates by defining what the bare boolean favourite means in each state — set versus unset — plus the resulting ordering effect, which the schema does not explain.
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 description gives a precise verb pair (mark/unmark) on a specific resource (exercise favourite) and names the observable effect: sorting to the top of the exercise picker. The 'or unmark it' clause is important because the name write_favourite alone would suggest only setting, not clearing, and no sibling tool overlaps this behaviour.
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?
Usage is implied rather than stated: the agent can infer this is the tool for toggling favourite status, but there is no explicit when/when-not guidance and no alternative named (the schema points at read_exercises only for id lookup, not as a usage alternative). Adequate but with an obvious gap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.