Povver — Strength Training

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

Annotations already declare readOnlyHint=true cutting off the main behavioral concernchers. The description adds context about what data is returned and its role as a first-call health check, but does not discuss failure modes, rate limits, or authentication behavior. With annotations present and output schema available, this is adequate but not exceptional.

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?

Two sentences, with the core purpose front-loaded and the field list compactly integrated. The follow-up 'first call' guidance earns its place by adding operational context without redundancy.

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 zero-parameter, read-only tool with an output schema, the description fully covers what the tool doesholistic, when to invoke it, and why the returned locale matters. There is no missing information an agent would need to select and call it correctly.

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 tool has zero parameterswing with 100% schema coverage, so there are no parameter semantics to explain. Baseline 4 applies because nothing additional is needed.

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 names a specific verb ('Verify') and resource ('the connection'), and immediately enumerates the exact user information returned (display name, subscription status, locale, active routine, logged workouts). It clearly differentiates itself as the integration health-check tool among siblings by framing itself as the first call.

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?

The description explicitly states when to use it: 'Use this as a first call to confirm the integration is live' and to discover the locale for localized queries. It does not explicitly list when-not-to-use or alternative sibling tools, but the primary use case is unambiguous.

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

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

The annotations already establish that this is a non-read-only, non-destructive write operation. The description adds valuable behavioral context beyond those annotations: the first created routine automatically becomes the active routine, and routines are assembled from existing template IDs. This is a meaningful side-effect disclosure that helps agents predict consequences.

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?

Four sentences, each earning its place: the core purpose, the domain definition, the prerequisite workflow, and the important side effect. There is no filler, and the most critical identifying information is front-loaded in the first sentence.

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 creation tool with 100% schema coverage, no output schema, and annotations that already signal write behavior, the description covers the prerequisites, the domain concept, and the key side effect. It is complete enough for an agent to call the tool correctly; the only minor gap is the lack of any mention of return behavior, but that is not essential here.

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 100%, so the baseline is 3. The description adds genuine semantics beyond the schema by explaining that template_ids are existing templates, that frequency means 'how many times per week to train', and that a routine cycles through workout templates. This helps an agent understand how the parameters relate to the domain model.

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 opens with a specific action and resource ('Create a new routine from existing template IDs') and immediately distinguishes this from sibling tools like create_template and create_workout by defining what a routine is. It also mentions the automatic active-routine side effect, which makes the tool's purpose 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?

The description gives explicit prerequisite guidance: use search_exercises and create_template first if new templates are needed. It clearly implies this tool should be used when templates already exist, which helps an agent decide when to call it versus setting up prerequisites. It could be stronger by explicitly naming set_active_routine as an alternative for changing the active routine, but the guidance is clear enough.

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

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

Annotations only cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false). The description supplies behavior annotations cannot: kg weights are snapped to a load the user can actually make in their own unit, so the caller should pass its best conversion and read the stored value back; the server mints element ids; and a newly created lift is user-owned and editable/deletable in the app.

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 create action, then structured by concern (ids, units, timed/distance sets, assistance, rounding, coach_note, next step). It is long, but the density is high and most sentences carry distinct guidance rather than restating the schema.

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?

No output schema exists, and the description compensates by telling the agent to read the stored (snapped) values back from the result. Combined with the nested schema's own id/measure documentation, an agent has enough to call this correctly; only the exact response shape is left implicit.

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 100%, so baseline is 3. The description still adds real meaning: units are always kg/metres/seconds, weight is null for bodyweight and never negative, assistance is a positive assist_kg, and per-exercise reasoning belongs in coach_note rather than the template description — semantics not obvious from property names alone.

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?

Opens with a specific verb+resource: 'Create a new workout template with exercises and set prescriptions.' This clearly separates it from update_template, get_template, and delete_template in the sibling list without needing the schema.

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?

Routes the agent well: exercise_id must come from search_exercises, ids are omitted on create because the server mints them, and after creating the template you add it to a routine via create_routine or update_routine. It stops short of an explicit 'use this instead of update_template when X' exclusion, but the surrounding context is clear.

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

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

Annotations only declare idempotentHint=true and destructiveHint=false; the description goes well beyond that by explaining the client_ref retry semantics (same ref updates rather than duplicates), that a bad exercise_id rejects only that workout and returns up to three suggestions, that partial success is normal and readable via results[]/next_action, and that workouts older than 7 days generate no insights or training-state changes. These are the failure-mode and side-effect details an agent actually 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 purpose and then organized into clearly labeled sections (import protocol, effort encoding, IMPORTING HISTORY). It is long, but nearly every sentence carries distinct operational content; only minor tightening would be possible without losing behavioral caveats an agent must know.

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 but deeply nested batch-mutation tool with no output schema, the description supplies the missing pieces: per-item result semantics (results[], next_action), partial-failure behavior, import chunking, and the 7-day insight rule. Nothing an agent needs to call this safely and correctly is absent.

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 100%, so the baseline is 3, but the description adds cross-field rules the schema only states piecemeal: rir vs rpe mutually exclusive ('never both'), reps 0 with duration_s or distance_m for timed/distance work, reps 0 with is_failure for a missed attempt, and reuse of the SAME client_ref on resubmission. It stops short of restating the schema's nested field details, which is appropriate.

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?

Opens with a specific verb+resource and scope: 'Record one or more COMPLETED workouts,' and immediately distinguishes the two use cases (logging a just-finished session vs importing history). The 'COMPLETED' qualifier and the contrast with the sibling list (update_workout, get_workout, list_workouts) make it unambiguous which tool an agent should pick.

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-to-use (just-finished session, import from another app), explicit routing to search_exercises for exercise IDs, explicit chunking protocol (25 per chunk, same import_id, is_final on the last chunk only), and explicit guidance to ask the user before attempting a very large migration. It even frames the honesty requirement about cost and missing insights.

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

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

The description adds substantial behavioral detail beyond the annotations: it states permanence, that the active routine is cleared if applicable, and that this cannot be undone. It also clarifies that templates are not cascade-deleted, which is exactly the kind of side-effect disclosure an agent needs for a destructive tool.

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 short sentences, each carrying essential information: the core action, the active-routine side effect, and the non-deletion of templates. There is no filler or redundancy, and the most important fact is front-loaded.

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 single-parameter destructive tool with no output schema, the description covers all critical call-time knowledge: permanence, active-routine clearing, and the boundary of what is not deleted. No additional context is required for a caller to understand the consequences of invoking it.

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 100%, with routine_id described as 'Routine ID to delete,' so the schema already documents the parameter. The description adds no extra detail about the ID format or where to obtain it, which is acceptable but does not elevate the score above the baseline.

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 opens with 'Permanently delete a routine,' a specific verb and resource that clearly distinguishes it from sibling tools like delete_template and delete_workout. It also clarifies the scope by stating that templates referenced by the routine are NOT deleted, which further sharpens the purpose.

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?

The description implies usage: use this when you want to permanently remove a routine. However, it does not explicitly contrast with alternatives such as update_routine or set_active_routine, nor does it state when not to use it. The intended context is inferable from the name and effects, but not directly articulated.

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

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

The annotations already declare destructiveHint=true and idempotentHint=true, so the description builds on that by adding valuable context: deletion is permanent, cannot be undone, and automatically removes the template from referencing routines. This is meaningful behavioral disclosure beyond the structured annotations.

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?

Two short sentences, zero filler. The core action is stated first, followed by the most important side effect and irreversibility warning, all without redundancy.

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 one-parameter destructive operation, the definition is complete: it names the target, the cascade behavior, and the permanence. With annotations covering destructiveness and idempotence, no critical information is missing for an agent to invoke it correctly.

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 100%, and the only parameter, template_id, is already described as 'Template ID to delete.' The description adds no additional parameter-level detail, so the schema carries the full explanatory burden.

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 uses a specific verb and resource: 'Permanently delete a workout template.' It also clarifies scope by describing the cascading effect on routines, making the tool's purpose unmistakable and distinct from sibling delete tools for routines and workouts.

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?

The description clearly signals this is the operation for permanently removing a template and states the consequence for routines that reference it. It does not explicitly name alternatives like update_template or delete_routine, but the resource-specific action leaves little ambiguity about when it applies.

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

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

The description explicitly states permanent deletion, irreversibility ('cannot be undone'), and cascading removal of analytics data. This adds valuable behavioral context beyond the destructiveHint and readOnlyHint annotations, which the agent can use to anticipate side effects.

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 short sentences, each adding critical information with no filler. The main action is front-loaded, followed by irreversibility and cascade effects. This is efficient and easy to parse.

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 simple destructive tool with one required parameter, no output schema, and annotations already indicating destructive and read-only behavior, the description covers what the agent needs: what is deleted, that it is permanent, and that analytics data is also removed. Nothing essential is missing.

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 input schema already covers 100% of the one parameter, workout_id, with a clear description. The tool description does not add new parameter-level meaning, but with full schema coverage, a baseline score of 3 is appropriate.

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 uses a specific verb (delete) and resource (logged workout), and distinguishes from sibling tools like delete_routine and delete_template by focusing on workouts. 'Logged workout' clearly signals the target resource without ambiguity.

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?

The description makes clear this tool is for deleting workouts, not for updating or creating them. It does not explicitly name alternatives or say 'use update_workout to modify instead', but the context is clear and no exclusion is needed for this simple destructive action.

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

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

Annotations cover only readOnlyHint/openWorldHint, and the description adds meaningful behavior beyond that: an unknown topic returns the full topic index with one-line rules, so calling once with any word is a valid discovery strategy. It also prescribes output voice and formatting (cite evidence by author and year, answer in the user's language, convert kg to the user's units), which materially shapes correct use.

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 purpose, then usage, then parameter guidance, so an agent can stop reading early. The long enumeration of trigger topics is functional but makes the middle paragraph dense; a tighter grouping would lose little.

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?

Given a single required string parameter, an output schema, and full schema coverage, the description supplies everything else an agent needs: the trigger condition, the topic-key convention, the unknown-key fallback, and the answering style. Nothing needed for correct invocation or downstream phrasing is missing.

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 100% with one parameter, so the baseline is 3, but the description adds value beyond the schema: a second example key ('when_weight_goes_up') and, critically, the semantics of an unrecognized value (returns the topic index rather than erroring). That fallback behavior is not derivable from the schema alone.

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 ('Get the evidence card behind one of Povver's training rules') and enumerates exactly what the card contains: the rule, the research-backed why, the user-facing meaning, and sources. This is clearly distinct from siblings like get_recommendations or get_training_insights, which surface computed data rather than the rationale behind a rule.

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 an explicit trigger ('Call it BEFORE answering any question about why Povver does something') and then enumerates the concrete question classes that route here (set counting, warm-ups, 1RM/effort targets, weight/reps progression, step sizes, deloads, variations, drop sets). It also states the when-not: answer from the card, not from general training knowledge, even where literature disagrees.

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

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

Annotations only supply readOnlyHint and openWorldHint, so the description carries real weight and delivers: strength_state is classified over a 6-week window defined by window_weeks, data provenance is precomputed_series, hard_sets may be fractional, and the response's resolution block reports ambiguity. Much of the remaining text is return-field semantics rather than operational behavior, which is why this is not a 5.

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?

The opening sentence is well front-loaded, but the body is a dense run-on that mixes routing guidance, parameter selection, and detailed output-field semantics (bests, line, line.trend, basis) into one block. Since an output schema exists, the extended return-field exposition is partly redundant and inflates length.

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 complex analytics tool with 4 parameters, an output schema, and several near-neighbor siblings, the description covers triggers, exclusions, selector tradeoffs, ambiguity recovery, and the meaning of the headline strength_state signal. An agent has everything needed to select and call it correctly.

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 100% so the baseline is 3, but the description adds genuine decision guidance: pass EITHER exercise_id (exact) OR exercise (fuzzy), prefer exercise_id because a name can match several trained variants, and re-query with the exact id when resolution reports ambiguous. It also states exercise_ids precedence over the other two selectors.

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?

Opens with a specific verb and resource ("Get 8-week progress for a specific exercise") and enumerates the concrete outputs it returns: weekly e1RM trend, PRs, plateau detection, last session, strength_state. It explicitly contrasts itself against three siblings (get_strength_climb, get_muscle_state, get_muscle_group_progress), so an agent can route without opening any schema.

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 an explicit trigger ("Use when the user asks about a specific lift") with two concrete example utterances, plus when-not guidance routing to get_strength_climb for % gain/8-week state, get_muscle_state for muscle-group analysis, and get_muscle_group_progress for raw time-series. It even explains why the two strength states can differ (differing windows).

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

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

The readOnlyHint annotation already covers the operation's non-mutating nature, so the description only needs to add context beyond that. It adds workflow context and field specifics but does not describe error behavior, auth requirements, or additional behavioral traits.

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?

Two concise sentences pack the resource, the returned fields, and the recommended usage without repetition. The information is front-loaded and every clause contributes.

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?

Given the tool's simple single-parameter interface, the existing readOnlyHint annotation, and an output schema, the description sufficiently covers identification, field scope, and invocation context. Nothing essential is missing for an agent to call it correctly.

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 schema has one required memory_id with only a type and no description, and the description never mentions the parameter by name or explains how to identify the memory. With 0% schema description coverage, the description was expected to compensate, but it does not.

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 uses a specific verb–resource pair ('Get full details on a single memory') and enumerates the returned fields, making it easy to distinguish from list_memories and other siblings. It also grounds the purpose in a concrete workflow by naming update_memory_status as the follow-up call.

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 explicitly states when to use the tool: before calling update_memory_status on a specific memory. It does not spell out when not to use it or point to list_memories as the alternative for browsing multiple memories, so it falls short of full exclusionary guidance.

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

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

Annotations only declare readOnlyHint and openWorldHint, so the description carries the interpretive burden and meets it. It discloses subtle behaviors: hard_sets meaning (RIR≤3), the warning to never quote volume ('never volume'), the precedence rule for flags.plateau vs state.plateau_status, and role labels on top_exercises rows. No contradiction with the read-only annotation.

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?

The purpose is front-loaded in the first sentence, and every subsequent clause carries disambiguation value. However, the middle section reads as a dense payload unpacking that could have been tightened into an organized list, which slightly reduces scannability for an agent.

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?

With a full output schema present and read-only annotations covering the safety profile, the description supplies everything needed to select and invoke the tool correctly: field semantics, interpretation warnings, the alternative tool, and the intended use case. Nothing needed for correct usage is missing.

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 100% (group and weeks both documented), so the baseline of 3 applies. The description adds little parameter-level detail beyond the schema, though 'Get weekly progress series' implicitly ties group to muscle-group selection and weeks to the series length.

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?

Opens with a specific verb and resource: 'Get weekly progress series for a muscle group.' It also disambiguates against siblings by stating that interpreted assessments belong to get_muscle_state and that this tool returns raw time-series data, which differentiates it from get_exercise_progress and get_strength_climb.

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?

The description gives an explicit exclusion and alternative: 'For TIE's interpreted assessment (fatigue, plateau, effective volume), use get_muscle_state instead.' It closes by naming the intended use case ('raw time-series data useful for charting and external analysis'), leaving no ambiguity about when to choose this tool.

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

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

Annotations already cover the safety profile (readOnlyHint=true), so the bar is low, and the description adds substantial interpretive guidance: which axis is authoritative, that 'above MRV alone is NOT overreach', that weekly_effective_volume is secondary and must not be compared to landmarks, and that e1rm_trends and strength_climb can legitimately disagree because their windows differ. It does not disclose rate limits or latency, but for a read-only analytics tool the added semantic warnings are meaningful.

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?

The description is bloated and heavily repetitive: the weekly_effective_volume warning ("SECONDARY weighted metric — never compare it to the landmarks or call it 'sets'") appears twice, and the volume_zone_v2 'trust it, don't reconstruct' instruction is repeated. The core purpose is not front-loaded, so an agent must parse cautions before learning what the tool does.

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 complex analytics tool with an output schema present, the description supplies the interpretive context an agent needs to read the returned fields correctly (which axis governs, which metrics are comparable, why trend windows differ). It is arguably over-complete, restating return-field semantics that the output schema already covers, but nothing essential is missing.

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?

There is one parameter (muscle_group) with 100% schema description coverage, including the enumerated muscle list, so the schema already carries the semantics. The description adds no additional meaning about the parameter itself, which matches the baseline 3 for fully documented single-param schemas.

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 does state the specific verb and resource: "Get TIE's synthesized assessment for a muscle group," and it distinguishes itself from get_exercise_progress ("For exercise-specific trends, use get_exercise_progress"). However, the purpose statement is buried in the middle of a dense wall of axis/field cautions, so an agent scanning the opening lines sees warnings rather than what the tool returns.

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 usage: prefer weekly_fractional_sets + volume_zone_v2 + landmarks_v2, fall back to the legacy axis only when the v2 fields are absent, and never mix them. It also names the sibling alternative for a different question type (get_exercise_progress), which is exactly the when-to-use / when-not-to-use guidance this dimension rewards.

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

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

Annotations already declare readOnlyHint=true, and the description adds useful behavior beyond that by explaining the plan's possible origin and what the response contains (structure, phases, policy, status). It does not go into edge cases such as no-existing plan, but that is not essential given the read-only annotation.

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 short sentences each add value: what the plan is, what the response contains, and when to call it. It is front-loaded with the core purpose and contains no filler.

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 read-only, zero-parameter tool, the description is complete: it identifies the resource, the result fields, the generated-or-authored semantics, and the verification workflow after setting the plan. No output schema exists, but the description enumerates enough of the return shape for the agent.

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 tool has no parameters and the schema covers everything at 100%, so the zero-parameter baseline applies. The description sensibly focuses on return content instead of parameter documentation.

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 uses the specific verb 'Get' with the resource 'current periodization plan' and states the two plan variants (auto-generated or authored) plus the returned sections. This distinguishes it from sibling tools like preview_periodization_plan by emphasizing 'current' and the post-set verification use.

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 explicitly tells the agent to verify with this tool after set_periodization_plan and to confirm source == 'authored', which is clear contextual guidance. It does not state exclusions or name the preview alternative for planning scenarios, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true, so the read-only nature is covered. The description adds return behavior details: 'Returns exercise names plus full memory summaries (body_area, severity, status).' This goes beyond the annotations, revealing what the output contains and the memory fields included.

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?

The description is two concise sentences, front-loaded with the core purpose and immediately followed by concrete use cases and return content. No wasted words or redundant schema repetition.

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?

With an output schema present, return-value documentation is not needed. However, the description omits any explanation of the 'limit' parameter, and it does not clarify what 'recent' means or whether results are scoped to the current user. These gaps make it only partially complete for an agent to call the tool confidently.

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% and the description does not mention the 'limit' parameter at all. Since there is one parameter with no schema description, the description fails to compensate by explaining what 'limit' controls (e.g., number of results, pagination).

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 clearly states the specific verb and resource: 'List recent recommendations that were suppressed because of injury memories.' It distinguishes from siblings like get_recommendations and list_memories by specifying the suppression reason and injury-memory gating.

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?

The description gives explicit use cases: 'Use to answer why didn't my bench press progress?' and 'to understand which memories are actively gating training.' It provides clear context for when the tool is appropriate, though it does not name alternative tools or exclusion conditions.

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

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

Annotations already establish readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds real behavioral context beyond that: the shape of a hold/carry measure_progression (target_unit_measure, target_duration_s, target_distance_m, suggested_weight in kg), which an agent needs to interpret the response.

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 purpose and followed by payload detail and the sibling handoff. The middle sentence is dense and jargon-heavy ('hold or carry progression') but every sentence carries 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 need not be fully specified; the description nonetheless previews the important fields. Combined with a single schema-documented parameter and clear annotations, the definition is sufficient, only missing guidance on when the include_all flag is appropriate.

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?

There is a single parameter with 100% schema description coverage, so the schema already documents include_all's meaning and default. The description adds no parameter detail, so the baseline 3 applies.

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+resource+scope: 'Get pending training recommendations from TIE,' and describes the payload ('actionable suggestions with rationale and confidence'). It differentiates itself from the acting sibling review_recommendation, though 'TIE' is unexplained jargon.

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 review_recommendation to accept or reject,' which names the alternative and the condition that selects it. It does not, however, state when to use include_all=true versus the pending-only default, leaving that to the schema.

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

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

Annotations already mark it as read-only and non-open-world; the description adds the scoping behavior of include_templates=false ('if you only need the routine metadata') and what data is returned. No hidden side effects are left unaddressed.

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 efficient sentences with the core purpose first, then the usage condition, then the flag behavior. No filler or repetition of schema content.

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?

The output schema exists, there is only one required parameter, and the description fully covers the main optional-parameter decision. An agent has enough context to call this tool correctly without additional explanation.

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 100%, so the baseline is 3; the description adds value by explaining that include_templates controls whether template exercise summaries are returned versus only routine metadata. This clarifies the runtime effect beyond the schema description.

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 names a clear verb and resource: 'Get a specific routine' with its template names and exercise summaries. It also conveys the routine's structure (templates and order), which distinguishes it from list-level and template-level sibling tools.

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 explicitly says when to use the tool: when you need the structure of a particular routine. It gives a concrete condition for toggling include_templates, but it does not name alternative tools or state when not to use it.

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

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

Annotations already mark readOnlyHint=true, and the description adds valuable behavioral detail beyond that: every state carries window_weeks=8, median_n can be as low as 1 and should not be read as typical across lifts, and an empty result means no qualifying progressing lifts yet. These behaviors directly affect how an agent should interpret and act on the output, and nothing in the description contradicts the annotations.

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?

Although the description is longer than average, every sentence earns its place: it front-loads the purpose, then covers window semantics, sibling distinction, return-field meanings, and the empty-result fallback. The structure is organized into clear thematic segments and avoids repetition or fluff.

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?

The description is complete for a read-only, parameterless data-retrieval tool. It covers the key question the tool answers, the interpretation of the main metrics (median_pct, median_n, counts), the meaning of an empty response, and the appropriate fallback. Because an output schema exists, the detailed field list is welcome context rather than a gap.

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 tool has zero input parametersabbeding, so the description has nothing to add beyond the schema's already-complete 100% coverage. The description instead focuses on output semantics, which is appropriate for a parameterless tool. A baseline of 4 is warranted because parameter guidance is non-applicable rather than deficient.

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 opens with a specific verb and resource: 'Get the user's Strength Climb — the headline strength-progress signal.' It clearly identifies the 8-week window and explicitly distinguishes the tool from get_exercise_progress/list_trained_exercises, whose per-lift states use a 6-week window. This makes the tool's purpose and scope unambiguous relative to siblings.

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?

The description gives direct usage routing: prefer this over the deprecated composite training_score, and if the result is empty, fall back to get_exercise_progress per lift. It also explains how to interpret disagreements between the 8-week climb and the 6-week per-lift state, telling the agent which window to quote. This is explicit when-to-use and fallback guidance.

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

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

The read-only safety is already declared by annotations, and the description adds meaningful behavioral context beyond that: it explains the coach_note field's purpose, warns to read it before proposing changes, and cautions that omitting it on update_template will erase it. This is valuable, non-redundant behavioral guidance with no contradiction.

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, each earning its place: definition, usage trigger, and the critical coach_note preservation warning. It is front-loaded with the core action, and the warning is concise rather than bloated.

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?

Complete for a single-parameter read tool with an output schema present. The description covers what the tool returns, when to use it, and the key caveat about preserving coach_note on updates. Nothing needed to call it correctly is missing.

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 100% for the single parameter, so the schema already documents template_id sufficiently. The description reinforces that the ID refers to a specific template and that the result includes exercises and prescriptions, but it does not add parameter-format details beyond 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?

States a specific verb and resource: 'Get a specific template with its full exercise list and set prescriptions (reps, weight, RIR).' This clearly distinguishes it from list_templates and other get_* siblings, while the mention of 'full exercise list and set prescriptions' makes the tool's scope concrete.

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?

Provides an explicit usage trigger: 'Use when you need to see or discuss the contents of a specific workout template.' It does not explicitly name alternatives or exclusions, such as 'use list_templates for browsing,' but the context is clear enough to guide selection.

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

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

Annotations only cover readOnlyHint/openWorldHint, and the description goes well beyond them: it flags four deprecated fields to avoid, warns that muscle_volume/volume_zone are calendar-week-to-date and will read below_mev mid-week unless partial_week/days_into_week are checked, and warns that top_primary_movers states use a different window than strength_climb.

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?

The content is valuable but poorly structured and heavily redundant: the DEPRECATED warning appears twice (top and bottom), 'Lead with strength_climb + training_context + muscle_volume' appears twice, and the calendar-week-to-date/partial_week caution is stated twice. A single well-ordered paragraph could carry the same information at roughly half the length.

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 no-argument, output-schema-backed tool with a dense and trap-laden payload, the description covers everything an agent needs: which fields to lead with, which are deprecated, how the volume axes are computed, and when to defer to sibling tools.

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 tool takes zero parameters, so there is nothing to document and the baseline is 4. The description spends its space on field semantics of the response instead, which is appropriate here.

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 ('Get AI-generated training insights and latest weekly review') and enumerates the payload (guardrail alerts, volume flags, strength_climb, training_context, muscle_volume). It also distinguishes itself from siblings by routing muscle-specific questions to get_muscle_state and recommendations to get_recommendations.

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 an explicit use case ('Use for retrospective questions') plus named alternatives with selection conditions: get_muscle_state for muscle-specific questions, get_recommendations for recommendations, get_strength_climb for the underlying signal. It even caveats that the latest review may be the in-progress week.

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

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

Annotations already declare readOnlyHint=true, so the description doesn't need to restate safety. It adds valuable behavioral context: the include_data_quality=true option triggers an extra set-history scan and yields a data_quality block, and it explains what that block contains (e1RM coverage, fragmented variants, etc.). This goes beyond the annotation and helps the agent anticipate cost and output shape.

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?

The description is front-loaded with the core purpose, then usage guidance, then the parameter explanation. It is a bit long but each sentence earns its place—no filler. The sibling routing is compact and helpful.

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 an orientation snapshot tool, the description covers all essentials: what it returns, how to use it, the optional parameter and its cost/benefit, and how it differs from related tools. The output schema exists, so return-format details need not be spelled out. Nothing critical is missing for a correct first call.

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 schema already describes include_data_quality as 'Also compute and attach the data_quality block (adds one set-history scan).' The description enhances this by listing the exact contents of the block and framing it as 'the coverage context that tells you which numbers the data actually supports.' This adds practical meaning beyond the schema's terse note.

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 clearly states the tool returns a 'compact overview' of the user's training setup and recent activity, enumerating specific contents (profile, routine, next workout, last 10 summaries, records). It also distinguishes itself from siblings like get_training_insights and get_training_status, so an agent can tell them apart without opening schemas.

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 instructs to 'Use this as a first call to orient yourself on who the user is and what they're doing.' It also names alternatives for specific needs: deeper analysis via get_training_insights, adherence via get_training_status, full per-exercise list via list_trained_exercises. This gives clear when-to-use and when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint=true, so the read-only nature is covered. The description adds useful context about what data is returned and the 'one lightweight call' performance characteristic, going beyond the structured annotations.

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?

The definition is compact and front-loaded: the result is summarized in one sentence supported by example user intents. It includes only relevant operational details, though the listed fields could be slightly more scannable.

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 read-only, zero-required-parameter call, the description plus schema and output schema cover what the tool returns, when to use it, and how it differs from a sibling. No critical behavioral or invocation information is missing.

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 schema description covers 100% of the single optional parameter (weeks, default 12, max 52). The description itself does not mention the parameter, but the schema fully documents it, so the baseline applies.

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 states a specific verb and resource ('Get training status overview') and explicitly enumerates the returned fields: weekly adherence, next scheduled workout, last workout date, days since last workout, and active routine. It also differentiates from get_training_snapshot by positioning itself as 'much lighter'.

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?

The description gives explicit use cases in quoted natural-language queries ('what should I do today?', 'am I being consistent?', 'when did I last train?') and names the sibling tool get_training_snapshot as a heavier alternative. It does not explicitly state when not to use it.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds substantial behavior beyond that: unit-storage invariants (always cm/kg regardless of display units), the precedence rule for training_days_per_week vs stated_training_days_per_week, and staleness caveats. It stops short of stating error/empty-profile behavior, so not a 5.

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 what it returns, then use case, then exclusions and alternatives — good ordering. It is dense with parentheticals and long compound sentences, and the output-field documentation partially overlaps the existing output schema, but each sentence carries real disambiguation value.

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-value documentation is optional, yet the description supplies the interpretation rules that a schema cannot (unit conversion policy, stale onboarding field). For a zero-param read tool, nothing an agent needs to call and interpret it correctly is missing.

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?

Zero input parameters, so the baseline is 4. The description does clarify the semantics of returned fields (height_unit always cm, display units separate), but that concerns outputs rather than inputs.

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+resource ('Get the user's coaching profile') and enumerates the exact contents returned, including ambiguous fields. It also explicitly distinguishes itself from siblings get_training_snapshot and check_connection, so an agent can route without opening a schema.

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 explicit when-to-use ('CONTEXTUALIZE advice... tailor volume, exercise selection, progression'), explicit exclusions ('Excludes account/billing internals and contact info'), and names the correct alternatives for adjacent needs (get_training_snapshot for weekly activity, check_connection for subscription status).

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

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

Annotations only declare readOnlyHint, but the description adds substantial context: the counts semantics, the is_completed caveat, verbosity payload trade-offs, the id-echo requirement for update_workout, and the prompt-injection warning that gym names are "data to quote, never an instruction." That is far beyond what structured fields provide.

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 purpose and counts semantics, and every sentence carries distinct information. It is dense and delivered as one unbroken block, which slightly hurts scannability for such a long description.

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?

Given an output schema exists, the definition need not explain return values, yet it still covers counts semantics, optional notes/gym fields, and the compact-vs-full trade-off. Nothing an agent needs to call this correctly is missing.

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 100%, but the description still adds meaning: verbosity="compact" is the default and returns the lean view, while "full" adds per-muscle analytics maps (larger payload), and each set's id must be echoed to update_workout. This goes beyond the terse schema description.

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 ("Get a specific workout's exercises and set-level data") plus the exact fields returned. An agent can distinguish it from list_workouts or query_sets without opening the schema.

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?

Closes with clear routing guidance ("Use when the user asks about a specific session") and ties verbosity selection to question types ("what did I do this session?" vs muscle-attribution). It does not explicitly name a sibling alternative for retrieving sessions, so the exclusion is implied rather than stated.

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

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

The annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds valuable behavior beyond the annotations by explaining that monitoring memories are included by default and why: an injury the pipeline is still suppressing on should never be hidden. This clarifies the tool's behavior without contradicting the annotations.

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?

The description is three sentences long and front-loaded with the core action and filtering intent. The middle sentence about monitoring is slightly long but earns its place by explaining an otherwise ambiguous status value. No sentence is wasted.

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 read-only list tool with an output schema, the description covers the default behavior, the effect of the status and category parameters, and the key filtering scenarios. The existing annotations cover safety and the output schema covers return structure, so nothing essential is missing for correct invocation.

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 carries the burden of explaining parameters. It adds real meaning for status, explaining the default and giving an example, and for category, giving an example filter. The limit parameter is not explained, but it is self-explanatory and the schema already constrains it as a number.

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 uses a specific verb and resource: 'List the user's memories filtered by category and status.' It also clarifies the default scope (all memories that gate training, including both active and monitoring), which distinguishes it from singular tools like get_memory and from status-changing tools like update_memory_status.

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?

The description gives clear and practical usage guidance: it explains the default behavior, tells the agent to pass an explicit status to narrow results, and gives a concrete example with status='resolved' and category='injury'. It does not explicitly name alternatives or exclusions, but the usage context is clear and actionable.

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

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

The readOnlyHint annotation already signals safety, and the description adds useful context by noting this returns summary data and no filtering is applied ('all' routines). The indication that only summary information is returned helps set expectations for the agent. It does not introduce contradictions or hidden side effects.

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?

The description is compact and front-loaded: the first sentence states what the tool lists and the key fields. The next two sentences provide usage guidance and point to the alternative. Every sentence earns its place without redundancy or filler.

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 zero-parameter, read-only listing tool with an output schema, the description covers all necessary context: what data is returned, when to use it, and when to prefer get_routine. The presence of an output schema means the description does not need to enumerate return types. No important information for correct invocation is missing.

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 tool has zero parameters, so parameter semantics are largely moot; the baseline of 4 applies. The description adds value by explaining what fields the response will contain, which indirectly clarifies what the tool offers despite having no inputs. There is no parameter ambiguity to resolve.

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 states a specific verb and resource: 'List all of the user's routines.' It enumerates the returned fields (name, ID, template IDs, frequency, active status), making the purpose concrete. It also distinguishes itself from get_routine by clarifying this returns summary data, not full template details.

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?

The description gives explicit usage triggers: when the user asks 'what routines do I have?' or when a routine ID is needed. It also names the alternative, get_routine, and explains when that tool is appropriate (full template details). This leaves no ambiguity about when to select this tool over its siblings.

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

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

Annotations already declare readOnlyHint=true, so the read-only nature is covered. The description adds useful behavioral context by specifying the output shape (names + IDs only) and the absence of exercise details, which is valuable since there is no output schema. Minor omissions like pagination or ordering are acceptable for this simple listing tool.

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 front-loaded sentences, each earning its place: the first states the action and output scope, the second gives concrete use cases, and the third names the sibling alternative. No fluff or repetition.

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 zero-parameter, read-only listing tool, the description fully covers what the agent needs to call it correctly: what it returns, when to use it, and when to use get_template instead. The lack of an output schema is compensated by the explicit output-shape hint.

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 tool has zero parameters and schema coverage is 100%, so the baseline is 4. There are no parameters to document, and the description's mention of needing template IDs for creating/updating routines indirectly reinforces why the output is useful rather than duplicating 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?

The description states a specific action and resource: 'List all workout templates (names + IDs only, no exercise details).' It clearly differentiates from get_template by noting the lack of exercise details, so an agent can select it without inspecting schemas.

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?

The description gives explicit trigger conditions ('when the user asks "what templates do I have?" or you need template IDs for creating/updating a routine') and explicitly routes to get_template when full exercise prescriptions are needed, making when-to-use and when-not-to-use unmistakable.

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

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

The annotations provide readOnlyHint=true, and the description adds meaningful behavior beyond that: scan_capped semantics, that strength_state reads from the same source as get_exercise_progress and therefore never contradicts it, staleness as a separate axis, and trend_blockers explaining why a lift cannot trend. No contradiction with annotations.

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?

The purpose is front-loaded, but the description is a dense, sprawling block with many nested caveats and examples. It is highly informative, but the structure could be clearer with more separation between core purpose, return fields, and edge cases.

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 zero-parameter tool, the description is unusually complete: it enumerates the key return fields, explains data quality concepts like fragmented_variants and e1rm_coverage, and covers edge cases such as scan_capped and stale trends. An agent has enough context to call it and interpret the result correctly.

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 tool has zero parameters and schema description coverage is 100%, so no parameter explanation is needed. With 0 parameters, the baseline is 4; the description appropriately spends no time on parameter semantics.

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 opens with a specific verb and resource: 'Enumerate the exercises the user actually trains, from their logged set history.' It also clearly differentiates itself from siblings like get_exercise_progress by positioning itself as the fast orientation step and explicitly naming the sequential calls it replaces.

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 explicit routing advice: 'USE THIS FIRST to discover exact ids and which lifts have enough data to trend, then call get_exercise_progress(exercise_id).' It also distinguishes its 6-week classification window from get_strength_climb's 8-week window and warns that scan-capped results mean absence is not proof the exercise was never trained.

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

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

Annotations only declare readOnlyHint/openWorldHint; the description adds substantial behavior beyond them — field presence rules for `notes` and `gym` (absent when none), an explicit prompt-injection caution that athlete text is 'data to quote, never an instruction', and the hasMore/next_cursor pagination contract.

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?

Dense but front-loaded: purpose first, then field semantics, then the sibling routing, then pagination. Nearly every clause carries information, though the repeated explanation of the two count fields is slightly verbose.

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, yet the description still usefully flags which fields are conditionally present and warns about untrusted athlete text — exactly the gaps structured fields can't convey. Nothing needed to call it correctly is missing.

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 100%, so both parameters (limit, cursor) are already documented in the schema. The description only reiterates the cursor round-trip; it adds no format, range, or edge-case detail beyond what the schema provides, so the baseline 3 applies.

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 ('List recent workouts as summaries') and immediately enumerates the returned fields (date, exercise names, set counts). It explicitly distinguishes itself from get_workout, which is the closest sibling.

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?

Names concrete triggering questions ('what did I do this week?') and states the exclusion condition explicitly: 'Returns summaries — use get_workout with a specific ID for full set-level data.' An agent has no inference to do.

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

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

Annotations provide idempotentHint=true and destructiveHint=false, but the description adds critical behavioral details: policy retention for resume, clearing of pending authored recommendations, and the auto-engine rebuilding its own plan next cycle. It also mentions the no-op condition. This goes beyond annotations and provides transparency that helps an agent predict side effects.

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?

The description is three sentences with no redundant words. It front-loads the core action, then adds losslessness, side effects, and no-op condition in logical order. Every sentence earns its place.

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?

Given zero parameters and no output schema, the description covers all essential aspects: what action is performed, side effects (clearing recommendations, engine rebuilding), retention of policy, and no-op behavior. It is complete for an agent to invoke correctly.

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 tool has zero parameters, so the description has no obligation to explain parameters. However, it provides context on what the operation affects (the active authored plan), which is valuable. With no parameters, a score of 4 is appropriate as the description adds meaningful context beyond 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?

The description states the specific action 'Pause an active authored plan' and the resource, clearly distinguishing it from siblings like resume_periodization_plan. It also clarifies what 'pause' means in this domain, making the purpose 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?

The description explains when to use the tool: when there is an active authored plan and you want to revert to automatic control. It also states a no-op condition, which is useful. It doesn't explicitly mention alternatives, but the sibling names (resume_periodization_plan, set_periodization_plan) imply the context. Clear context and exclusions are provided.

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

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

Annotations mark it readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description goes further and discloses the validity-gated behavior: a preview is returned only if valid, otherwise ok:false with errors, and nothing is persisted. It does not describe what the preview contains, but the behavioral contract is well disclosed.

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 compact clauses, front-loaded with the core action (dry-run without saving) and the outcome branches. No filler; every sentence carries signal.

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?

With no output schema, the description carries the return-shape burden and does so partially (ok:false with errors, preview only when valid). The deep nested policy semantics are fully documented in the schema, so this is adequate for a validation tool, though the preview payload shape is not described.

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?

Single nested 'plan' parameter with 100% schema description coverage, so the schema already documents goal, policy, phases, and deload rules. The description adds no additional parameter meaning beyond the schema, so the baseline 3 is appropriate.

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 ('Dry-run a plan') plus the exact scope ('WITHOUT saving it', validates, returns a preview). This distinguishes it cleanly from the save-side sibling set_periodization_plan without needing to name it.

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?

The 'Dry-run ... WITHOUT saving it' framing tells the agent this is the pre-flight/validation step rather than committing a plan. There are no explicit exclusions or a named alternative, but the context for use is clear.

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

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

Annotations only declare readOnlyHint/openWorldHint; the description carries the real behavioral load. It defines null semantics for rest_s ('null means not a rest, never 0'), pagination truncation behavior, muscle_group/muscle matching that includes synergists, meta.counting_basis and meta.resolution provenance, and the fact that reps/e1rm are meaningless on duration or distance sets.

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?

Long but information-dense, with purpose front-loaded and the pagination rule and provenance caveats each earning their space. Some return-field detail (rest_s/rest_target_s null cases, measure/e1rm notes) overlaps with what an output schema should carry, which keeps it from a 5.

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?

Given an output schema and read-only annotations exist, the description is complete enough for correct invocation: filtering semantics, pagination mechanics, provenance caveats, and the trap cases (duration/distance sets, ambiguous names) are all covered.

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 100%, so the baseline is 3. The description still adds value beyond the schema: it warns that sort must stay constant across a paginated sequence, that cursor pairs with truncated/next_cursor, and that muscle_group filtering has a non-obvious any-involvement semantics that the schema's 'Muscle group' description does not convey.

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 ('Query raw set-level training data') plus its filter dimensions (exercise name, muscle group, muscle, exercise IDs). It explicitly contrasts itself with 'the higher-level tools' in the sibling list, so an agent can distinguish it from get_exercise_progress or get_muscle_group_progress without opening a schema.

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 contexts ('custom analysis, data export, or when you need granular training data that the higher-level tools don't cover') and operational guidance for pagination (pass next_cursor, keep all other args identical including sort) and for re-querying by exercise_ids when a name match is ambiguous. It stops short of naming a specific sibling tool for each alternative scenario, which is what a 5 requires.

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

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

Annotations already declare idempotentHint=true and readOnlyHint=false, so the description doesn't need to add much. It adds the no-op behavior when there is no retained policy, which is useful beyond annotations. However, it doesn't add detail on state changes or side effects, but the annotations cover the basics.

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?

Two sentences, both purposeful. The first states the primary action and value proposition; the second clarifies a boundary condition. No fluff, no redundancy. It is front-loaded with the core purpose.

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 zero-parameter operation with annotations covering idempotency and read-only, the description is fairly complete. It could mention the effect on the plan's state or any prerequisites, but the no-op clause covers the main edge case. Slight gap on what 'resume' means functionally, but sufficient.

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 100% but there are 0 parameters. The description correctly omits parameter details since there are none. With no parameters, a baseline of 3 is appropriate; the description could add context about how the tool identifies the plan, but that is implicit. No additional value needed.

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 clearly states the action (resume), the specific resource (periodization plan), and the key benefit (no re-authoring). It distinguishes from create/set operations like set_periodization_plan, and the sibling pause_periodization_plan is implicitly the inverse. Slight deduction because it doesn't explicitly mention 'resume' as the inverse of 'pause' or list alternatives.

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 context (re-activate paused policy) and mentions a no-op condition (no retained policy), providing clear guidance on when the tool is effective. It doesn't explicitly state when NOT to use it (e.g., use set_periodization_plan if no prior plan exists), but the context is clear enough.

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

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

Annotations already declare mutation (readOnlyHint=false) and non-destructive (destructiveHint=false), so the description adds valuable extra context beyond the structured metadata: the requirement to confirm with the user before calling and that template mutations are immediate. This disclosure of human-in-the-loop and timing behavior is exactly the kind of behavioral context annotations alone do not provide.

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?

Two sentences, zero filler, with the critical usage constraint front-loaded. The first sentence states the action compactly and the second explains why confirmation is non-negotiable. Every sentence earns its place.

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?

Given only 2 required parameters and no nested objects, plus annotations covering safety, the description is complete. The agent knows what action to take, what input to use, and the confirm-before-calling requirement, leaving no critical decision-influencing information missing.

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 100% and the schema documents both parameters: recommendation_id and action with its accept/reject/revert enum. The description adds little parameter-specific meaning beyond what the schema provides; the only extra cross-reference ('Recommendation ID from get_recommendations') is in the schema, so the description rides the schema baseline of 3.

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 uses a specific verb ('Accept, reject, revert') with a clear resource ('training recommendation'), making the tool's action unmistakable. The three enumerated actions differentiate it from siblings like get_recommendations, which merely fetches recommendations rather than acting on them.

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?

The description provides a clear precondition and timing constraint: 'Always confirm with the user before calling' – essential context for an AI agent deciding when to call. It lacks explicit exclusions or naming of alternatives, but the parameter description 'Recommendation ID from get_recommendations' implies the upstream fetch step, and the mutation warning suggests caution versus read-only siblings.

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

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

Annotations already indicate this is a write operation (readOnlyHint=false), and the description adds meaningful behavioral detail beyond that: severity levels map to concrete outcomes ('mild' note only, 'moderate' suppress progression, 'severe' suppress + safety disclaimer). It also discloses that alias forms like 'shoulder_left' are accepted, which is useful behavioral nuance. No contradiction with annotations.

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?

The description is front-loaded with the core purpose and trigger, and the longer controlled-vocabulary list is necessary because the schema itself does not provide that information. The structure is efficient and every part earns its place, though the vocabulary list makes it slightly longer than a minimalist description.

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?

The description sufficiently covers the purpose, trigger condition, body_area constraints, and severity behavior, and annotations cover the mutation profile. The lack of guidance on the required 'content' parameter and on idempotency semantics means an agent may still be uncertain about how to fully construct a valid call, especially with no output schema.

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 carries the burden of parameter documentation. It explains body_area and severity in useful detail, including the controlled vocabulary and severity enum semantics. However, it does not explain the required 'content' parameter, nor the optional 'idempotency_key' and 'affected_exercises', leaving a meaningful gap in agent understanding.

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 opens with a specific verb and resource: 'Report a new injury or pain.' It also states exactly when to call the tool ('when the user describes physical discomfort that should affect training'), clearly distinguishing it as the tool for recording new injuries rather than updating memory status or other memory operations.

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?

The description explicitly states the triggering condition for use: when the user describes physical discomfort that should affect training. It does not mention when not to use it or point to alternatives, but the context is clear enough for a write tool of this kind.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds valuable behavioral context: it explains the distinction between 'trains' and 'involves', how results are ranked, how muscle-group queries spread results across distinct movements, and how locale affects returned names. This goes beyond what annotations provide, though it doesn't detail pagination or exact result structure.

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?

The description is dense but well-organized, front-loading the core purpose and then layering behavioral details. Every sentence adds information, though the length is substantial. It could be slightly more concise, but the detail is relevant and earns its place.

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?

Given the tool's complexity (natural-language queries, ranking nuances, locale behavior) and the presence of an output schema, the description covers all the essential context an agent needs to select and invoke the tool correctly. It explains the key behavioral distinctions, usage context, and parameter semantics without needing to describe return values since the output schema exists.

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 100%, so the schema already documents all three parameters. The description adds meaning by explaining how the `query` parameter handles natural language and how `locale` interacts with translation. It doesn't add much beyond the schema for `limit`, but the added context for query and locale justifies a score above baseline.

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 states a specific verb ('Search') and resource ('exercise catalog'), and immediately clarifies the search dimensions: name, muscle group, or keyword. It also distinguishes itself from getExercise by noting that only `fields: full` carries the full involvement list, which helps an agent differentiate this tool from its siblings.

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?

The description explicitly says when to use this tool: 'Use when building or modifying templates, or when acting on a recommendation that names a muscle group.' It also provides guidance on natural-language queries and explains ranking behavior, which helps an agent decide when this tool is appropriate versus alternatives like getExercise.

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

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

Annotations already cover idempotent, non-destructive, and read/write characteristics. The description adds value beyond these by explaining the behavioral effect: the active routine governs which workout the user should do next. It does not discuss overwriting the previous active routine, but this is a small omission for a simple setter.

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?

Two focused sentences with no filler. The main action is front-loaded, and the second sentence provides a useful prerequisite (how to find routine IDs) without unnecessary elaboration.

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 tool with one required parameter, no output schema, and annotations indicating idempotency and non-destructiveness, the description is complete enough for an agent to call it correctly. It states what the tool does, why it matters, and where to source the required ID.

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 100%, and the parameter description already states that routine_id is the 'Routine ID to set as active.' The description adds the practical detail that IDs can be found via list_routines, but does not add new meaning about the parameter's format or constraints, so it stays at the baseline.

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 names a specific verb and resource: 'Set which routine is the active routine.' It also clarifies the operational consequence, that the active routine determines the user's next workout, making it easy to distinguish from update_routine or list_routines.

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 clear functional context and explicitly directs the agent to use list_routines to find valid routine IDs. However, it does not state when to prefer this tool over related setters or alternative routines, though the purpose is straightforward enough that the gap is minor.

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

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

Annotations cover the safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false), and the description adds substantial behavioral context beyond them: immediate activation (current_week resets to 1), supersession of the auto-engine until paused, the confirmed:true gate for active-plan edits, deload precedence semantics, and that progression_rule values all collapse to double progression. This is unusually rich disclosure.

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 purpose before the exclusions and behavioral rules, and every sentence is relevant rather than boilerplate. It is long and dense, but the length is carrying real semantic load (deload precedence, progression fallback, muscle group list) rather than padding.

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 deeply nested authoring tool with no output schema, the description covers activation side effects, the confirmation requirement, deload conflict resolution, progression fallback behavior, and how to verify the result. Nothing needed to invoke it correctly appears missing.

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 100%, so baseline is 3, but the description adds value the schema lacks: the enumerated valid muscle groups for per_muscle_overrides (chest, back, shoulders, ...), progression/deload semantics, and a worked example JSON. It also clarifies that rep ranges derive from goal and exercise type rather than being set here.

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 ('author a periodization POLICY that steers your EXISTING routine') and immediately bounds what it does not do ('CANNOT define exercises, sets, or weights'). An agent can distinguish it from update_template, create_template, and get_periodization_plan purely from the text.

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 update_template to define exercises/sets/weights, get_periodization_plan to verify, preview_periodization_plan to dry-run, and confirmed:true only when editing an already-active authored plan. When-to-use and when-not-to-use are both present.

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

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

Annotations provide idempotentHint=true and destructiveHint=false, and the description adds extra behavioral context: updates are tagged with source='external_mcp' in the audit trail, and monitoring status is normally auto-transitioned by the pipeline. This goes beyond the structured metadata without contradicting it.

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?

The description is compact and front-loaded with the primary action. Every sentence serves a purpose: stating the action, explaining the three status choices, and noting the audit trail behavior. There is no filler or repetition.

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 operation with no output schema, the description covers the core decision space: which status to set, when each is appropriate, and a relevant audit side-effect. It does not mention the return value or the optional idempotency_key, but those are less critical given the annotations and schema.

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 compensate for the parameters. It thoroughly explains the status enum's values and when to use each, which is the most semantically rich parameter. The remaining parameters (memory_id, note, idempotency_key) are left to their names and annotation context, which is acceptable but not fully elaborated.

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 opens with a specific verb and resource: 'Update an injury memory's lifecycle status.' It also names the exact statuses and their meanings, making the tool's purpose unmistakable and clearly distinct from generic update or memory retrieval siblings.

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?

The description gives concrete guidance for each status value: 'resolved' when the injury is gone, 'monitoring' for ambiguous cases, and 'active' to revert if pain returns. It also warns that monitoring is 'typically the pipeline auto-transitions,' which helps the agent decide when manual intervention is appropriate. It does not explicitly contrast with siblings like save_injury_memory, so it falls short of a 5.

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

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

Annotations already indicate idempotent, non-destructive, and non-read-only behavior. The description adds meaningful behavioral details beyond that: partial updates are supported, template_ids must include the entire list to overwrite, and reading current state before updating is recommended. No contradiction with annotations.

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 short sentences, front-loaded with the core action, followed by targeted usage rules. Every sentence earns its place; there is no redundancy or filler. The structure is easy for an agent to parse and apply.

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?

The definition covers the main behavioral nuances (partial update, full array for templates, prerequisite get_routine) and relies on the schema for parameter details. While there is no output schema and the description doesn't state what a successful response contains, the tool is still fully callable with the provided information.

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 100%, so the baseline is 3. The description adds value by explaining the semantics of the updates object ('pass only the fields to change') and the special requirement for template_ids to be a full replacement array. This clarifies usage beyond the individual schema descriptions.

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 clearly states a specific verb and resource: 'Update an existing routine' with the exact editable aspects (name, template IDs order, frequency). It also names the sibling get_routine, which helps disambiguate from read-type tools. This is a precise, action-oriented definition.

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?

The description gives strong operational guidance: pass only changed fields, pass the full template_ids array to add/remove templates, and call get_routine first to see current state. It does not explicitly contrast with alternative update tools (e.g., update_workout), so it stops short of full exclusionary guidance, but the context is clear enough for correct invocation.

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

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

Goes well beyond the annotations by disclosing non-obvious mutation semantics: the exercises array fully REPLACES the existing list, coach_note is cleared for any exercise that omits it, and an element sent without an id is treated as NEW and gets a fresh id. These are exactly the data-loss and identity pitfalls an agent needs warned about before mutating a nested structure.

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?

Purpose is front-loaded in the first clause and every subsequent sentence carries real information, but the second clause is a heavily nested parenthetical chain that is harder to scan than it needs to be. Dense rather than wasteful.

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 tool with a deeply nested 2-parameter schema, no output schema and 100% schema coverage, the description covers the hardest parts: whole-list replacement, id identity, coach_note clearing, and the get_template prerequisite. It omits error behavior and whether partial field updates are permitted, which would complete the picture.

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 100% schema description coverage the baseline is 3, but the description adds meaning the schema does not state, notably that the exercises array replaces rather than merges, that id round-tripping from get_template preserves identity, and the assist_kg-vs-negative-weight convention. This is genuine additive semantics over the structured fields.

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 (update) and resource (template) and enumerates the mutable fields: name, description, exercise list. The resource noun cleanly separates it from update_routine, update_workout, create_template and delete_template, so an agent can route without opening the schema.

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 an explicit prerequisite workflow ('Use get_template first to see the current state') and clarifies when the full exercises array must be passed. It does not, however, explicitly exclude misuse (e.g. create_template for new templates) or contrast with the other update_* siblings.

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

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

Annotations already declare idempotency, non-destructiveness and openWorld=false; the description corroborates idempotency and goes well beyond by disclosing the guard rail that a replacement dropping most logged sets is rejected, the wholesale-replacement behavior of the exercises array, and the omit-keeps / null-clears preservation rules. This is rich behavioral context the structured fields do not convey.

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?

Long, but front-loaded with purpose and patch semantics and every sentence carries a distinct rule (get_workout first, list_workouts trap, replacement behavior, id echo, idempotency, delete alternative). Slightly verbose and could be tightened, but there is no filler.

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 complex mutation tool with no output schema, the description covers the full call contract: prerequisite read step, replacement vs omission semantics, set identity handling, rejection conditions, idempotency, and the removal alternative. Nothing an agent needs to invoke this correctly is missing.

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 100%, so the per-field omit/null semantics are already documented. The description nonetheless adds the holistic model an agent needs: exercises replaces wholesale, set ids must be echoed from get_workout, and sets without ids are treated as new — synthesizing rules that span multiple parameters rather than restating 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?

States a specific verb and resource ('Correct a workout that is already recorded') and immediately disambiguates with concrete examples (fix a weight, add a note, adjust reps). The patch semantics ('supply only the fields to change') and the explicit sibling routing ('use delete_workout instead') make it unmistakable versus create_workout/delete_workout.

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 prescribes the workflow ('Call get_workout first'), names an exclusion ('Do NOT build an exercises array from list_workouts'), and points to the alternative for removal ('use delete_workout'). It even explains why the exclusion exists (list_workouts returns counts, not sets), which is exactly the kind of guidance an agent needs.

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