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

Annotations only declare it is a non-read-only, non-destructive write; the description supplies the substantive behavior: batching (a whole lab report as one card), and the retroactive rescoring of every power ride from an FTP row's date to the next FTP row (IF, TSS, zones, calendar repaint). That is exactly the kind of side effect an agent cannot infer from annotations. It stops short of saying what happens on duplicate dates, invalid kinds, or beyond the 20-row cap.

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 the batch behavior, then the profile distinction, then the FTP side effect — a sensible ordering where each sentence carries operational content. It is dense and leans on caps, backticks, and a long run-on clause ("never today-because-that-is-when-they-told-you"), which makes it slower to parse than it needs to be.

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 write tool with no output schema, the description covers purpose, dating, provenance, batching, and the main side effect, so an agent can call it correctly on the happy path. Gaps remain around the `kind` enum (19 values with no per-kind unit or valid-range guidance), the 20-item cap, and what the tool returns or does on partial failure.

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?

The description adds meaning the schema does not: `note` is provenance ("Trisystems СПб, step test to exhaustion"), never athlete interpretation, and `date` is the measurement date rather than the reporting date, reinforced with the FTP backdating rule. It does not compensate for the absence of enum/unit guidance for `kind` or the unit table for `value`, which remain only in the schema.

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?

"Record a MEASUREMENT with its date" is a specific verb+resource, and the examples (lab test, blood panel, weigh-in, field-test) plus explicit enum-like kinds make the scope unmistakable. It also draws a hard line against profile mutation by naming update_athlete_profile. It loses a point for not distinguishing itself from the sibling log_lactate, despite listing "a lactate draw" as an example of what this tool takes.

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?

Explicit when-not guidance: "This is history, not the profile: it does NOT change what the app plans against — if the test says the threshold moved, propose update_athlete_profile as well." It also prescribes the correct date semantics via a concrete case (backfilled FTP should be dated to when it was measured, source self-report) and warns against defaulting to today.

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