prepare_exercise_result

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description reinforces this with 'Sends no write,' removing any ambiguity about side effects. It adds behavior annotations cannot express: a hard prerequisite (user-confirmed gym time zone) and a mandatory confirmation workflow before the execute step, which is exactly the kind of procedural context an agent needs.

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 action and scoping, then the prerequisites and the confirmation gate — a sensible order with no filler. The field enumeration overlaps the schema slightly, which keeps it from being maximally tight, but every sentence carries actionable 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?

An output schema exists, so return values needn't be described, yet the description still tells the agent to surface the exact preview including the current latest 1RM. Combined with the time-zone prerequisite and confirmation gate, an agent has everything needed to call this correctly in a two-step prepare/execute flow.

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 80%, so the baseline is 3; the description earns above that by tying exerciseId to its source (find_exercise_1rm) and restating the 'today or earlier' constraint on date in the context of a real workout record. It does not add unit or format nuance for sets/reps/load beyond what the schema already documents, so it stops short of a 5.

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 and resource — preview recording a strength result for one exercise — and enumerates the inputs (date, sets, reps, load in kg) plus the app semantics ('as the AimHarder app saves a PR'). It is clearly separable from the sibling execute_exercise_result, which the description names as the follow-on action.

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?

Explicitly routes the agent: use find_exercise_1rm to obtain the exercise ID, require a user-confirmed gym time zone, then show the preview and get explicit confirmation before calling execute_exercise_result. When-to-use and the alternative are both stated, not inferred.

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