LiftTrack

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

Annotations only indicate readOnlyHint=false and destructiveHint=false, so they carry minimal behavioral info. The description extensively discloses behavior: rest mode semantics ('off' continues straight, 'lap' waits for button), percent is a percentage of training max (not computed weight), server computes weight from training max, superset grouping behavior, folder creation if not exists, and step counting rules. This goes well beyond 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 lengthy but well-organized: it starts with the core purpose, then details each exercise component, rest modes, superset rules, folder handling, and ends with a concrete example. Every sentence adds value, though some redundancy exists (e.g., repeating rest mode definitions in the schema and description). Given the tool's complexity, the length is justified and the structure is clear.

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 covers nearly all operational aspects: exercise structure, rest mode semantics, superset grouping, folder creation, training max dependency, and step counting. It also provides a worked example. With an output schema present, return values need not be explained. Minor gaps: it doesn't mention error cases beyond the training max issue, and the phrase 'user-approved' is not elaborated, but these are negligible for a creation tool.

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 67%, so some parameters lack descriptions. The description fills these gaps by explaining 'weight is in the user's units (0 = bodyweight)', 'percent is the percentage of training max itself, e.g. 65 for 65%', the meaning of 'off' and 'lap' rest modes, and the constraint that working_rest_seconds is required when mode is 'timed' and omitted otherwise. It also clarifies superset label constraints and the step counting rule.

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+resource: 'Create a user-approved workout template with exercises, sets, loads, rest modes, and optional supersets.' It clearly distinguishes from sibling tools like update_workout and delete_workout by focusing on creation, and it names the exact input domains (exercise names, sets, loads, rest modes, supersets).

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 states prerequisites like 'Exercise names must be exact display names from the catalog or the user's custom exercises' and explains conditions like 'fails with a clear error if the exercise has no training max set.' However, it does not explicitly compare to update_workout or mention when to use this tool versus siblings, leaving usage context implicit rather than explicit.

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 destructiveHint=true and idempotentHint=true, but the description adds substantial context beyond them: irreversibility ('This cannot be undone'), cascading effects ('removes it from any schedules and from the user's Garmin device'), a hard constraint (app default workouts), and the atomic behavior on name collisions.

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 action and its irreversibility, then cascading effects, then constraints, then parameter notes. Every sentence carries distinct information (undoability, schedule/device cleanup, defaults, collision handling) with 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?

An output schema exists, so return-value detail is unnecessary; the description fully covers the mutation semantics, side effects, preconditions, and error behavior an agent needs to invoke this destructive tool 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 meaning the schema lacks: workout_name matching is case insensitive, and the special sentinel value 'My Workouts' for folderless workouts is explained in prose. This is slightly richer than the schema text 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?

The description opens with a specific verb and resource: 'Permanently delete a user-approved workout template.' The 'Permanently' qualifier and 'workout template' scope immediately distinguish it from siblings like update_workout, create_workout, and get_workout_detail.

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 preconditions for a successful call ('user-approved', 'App default workouts cannot be deleted') and explains the duplicate-name failure path. It does not, however, explicitly contrast with an alternative tool or say when to prefer this over update_workout, so it stops short of full routing 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, idempotentHint, non-destructive and closed-world, so the safety bar is low. The description adds genuinely useful behavior: the summary/full payload distinction (implied cost of detail='full'), the 30-day default window, and the 100-result cap. It does not mention auth or rate limits, but those are minor against the annotation coverage.

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-loads purpose in the first sentence, then the detail-mode semantics, then the args list — a sensible order with no wasted prose. The Args block is redundant with a 100%-covered schema, which is the only structural inefficiency.

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 values need not be explained, and the description covers date defaults, the result cap, filtering, and the summary/full tradeoff. An agent has enough to call it correctly; only explicit sibling routing 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 description coverage is 100%, so the schema already documents all five parameters and the baseline is 3. The description largely restates the same fields and defaults; its only modest addition is enumerating the fields returned under each detail mode, which is not parameter-level syntax the schema lacks.

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 completed workout sessions' — and the detail-mode elaboration (name/date/duration/sets) makes the payload scope concrete. It doesn't explicitly name which sibling to use instead (get_workout_detail, get_exercise_history), leaving differentiation to inference from the resource phrase.

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 context through date-range defaults and a workout_name filter, and explains what the detail modes yield, which helps choose a mode. But there is no explicit when-to-use/when-not guidance or naming of alternatives among the many get_* 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, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds genuine value beyond that by disclosing the empty-object edge case when no profile exists, which annotations cannot convey; it stops short of noting any auth or scope requirements.

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, purpose first, edge case second — well front-loaded with no filler. The long enumeration of returned fields slightly overlaps the output schema, but it is readable and not 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 zero-parameter read with an output schema present, the description need not explain return values, and it correctly spends its words on the empty-profile case. It is complete enough to invoke correctly; only sibling differentiation 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?

The tool takes zero parameters, which is the baseline-4 case; there is nothing for the description to disambiguate. The schema is empty by design, so no semantic gap exists.

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 user's saved Coach Profile') and enumerates exactly what is returned, so the agent knows what data it yields. It does not, however, differentiate itself from lookalike siblings such as get_user_settings or get_training_maxes, leaving the agent to infer the boundary.

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?

There is no guidance on when to reach for this tool versus get_user_settings or get_training_maxes, nor any stated preconditions. The only condition mentioned ('empty object when the user has not set up a profile yet') describes an outcome, not when to use the 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 declare readOnlyHint, idempotentHint, non-destructive, and non-open-world, so the safety profile is covered. The description adds meaningful behavioral context: it explains what data is returned (sets, volume, 1RM, heaviest set, trends) and clarifies the local_date vs date semantics, which is not repeated elsewhere. The remaining gap is the absence of explicit mention of the session limit default or pagination behavior, though the schema covers limit.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, front-loaded with the core purpose, then output contents, then a precise timezone clarification. 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?

The description covers purpose, output fields, and timezone semantics. Since an output schema exists, return values need not be fully explained, and annotations cover safety. The only minor gap is not explicitly stating that limit defaults to 10 and maxes at 50, but that's already in the 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 coverage is 100%, so both parameters (exercise_name and limit) are already documented. The description adds context about the output fields (sets, volume, 1RM, etc.) but doesn't extend parameter meaning beyond the schema. Baseline 3 is appropriate when the schema does the heavy lifting.

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 ('Get') and resource ('performance history for a specific exercise across sessions'). The description clearly distinguishes it from sibling search_exercises (which finds exercises) and get_workout_detail (which covers a workout, not exercise history).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied by the description (retrieve history for a named exercise), but there's no explicit when-to-use versus alternatives like get_workout_detail or validate_exercise_names. An agent can infer the right context from the purpose, but no exclusions or alternative routing 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 already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered by structured data. The description adds only that names are exact and counts are included, which is output detail rather than behavioral context such as scoping or pagination behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single short sentence that front-loads the verb and resource with zero filler. Every word 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?

With a full output schema present, return values need no explanation, annotations cover safety, and there are no parameters to document. The description is nearly complete; the only minor omission is any hint about folder scope or ordering.

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 and schema description coverage is 100%, so there is nothing for the description to disambiguate. The baseline of 4 applies for a parameterless tool.

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 ('List') and resource ('the user's workout folders'), and even names the returned fields (exact name and workout count). It is clear enough to distinguish from get_programs, get_workout_templates, and get_workout_detail, though it never explicitly contrasts itself with those 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?

There is no statement of when to call this versus alternatives such as get_programs or get_workout_templates, and no prerequisites or exclusions are given. Usage is only implied by the tool name and the word 'List'.

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 (readOnly, idempotent, non-destructive) and openWorldHint=false, so the bar is lower. The description still adds real behavioral detail beyond them: no pagination regardless of week count, how repeated workout_id uses collapse into one item with day labels, and that the same workout_id across weeks denotes reuse of one saved workout.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, front-loaded with the core action, and every sentence carries information: scope, no-pagination guarantee, and the grouping/reuse semantics of the returned structure. 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?

With an output schema present, return-shape explanation is optional yet the description usefully clarifies the compact grouping model. The only real gap is failure behavior for an unknown program_id, which is minor for a read-only single-resource fetch.

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 program_id's type, minLength and 'Stable id of the saved program' meaning are already documented. The description adds nothing about the parameter (e.g., where the id comes from), 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: fetching one saved program's complete plan. The word 'one' and 'complete' implicitly contrasts with the sibling get_programs listing tool, but no sibling is named explicitly, so it stops short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is only implied by the word 'one saved program': an agent infers this is the drill-down after get_programs. There is no explicit when-to-use, when-not, or named alternative such as get_programs or get_workout_detail.

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 the safe-read profile (readOnlyHint, idempotentHint, destructiveHint=false), so the description is not obligated to restate it. It adds a genuine behavioral guarantee not found in annotations or schema: 'Internal program lifecycle ids are never returned,' plus the enumerated status vocabulary.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single dense sentence front-loads the scope and then enumerates returned fields; every clause carries information. It is slightly list-heavy and leans on the LiftTrack UI metaphor ('program cards'), which costs a little clarity for no benefit.

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 and annotations covering the safety profile, the description need not explain return values, and it doesn't over-explain. It supplies the status enum and the lifecycle-id exclusion, which is enough for an agent to call and interpret this 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 takes zero parameters, so per the rubric the baseline is 4. There is nothing for the description to clarify about inputs, and it correctly doesn't invent any.

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 (List) and resource (user's saved programs) and pins down the altitude: summary level, not detail. That wording implicitly separates it from the sibling get_program_detail, which returns the full record.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied by 'summary level ... as LiftTrack's program cards' versus the detail-oriented sibling, but there is no explicit when-to-use statement, no condition selecting this tool over get_program_detail, and no mention of prerequisites (e.g. auth or empty-state behavior).

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 readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds a genuinely non-obvious behavioral trait — returned dates are plain calendar dates with no timezone conversion — which an agent could not infer from the annotations or schema.

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 operation and scope, then a useful date caveat. The repeated 'Args:' block duplicates the schema almost exactly, which is mild waste, but the description is short overall.

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 explanation is unnecessary, and the single optional parameter is fully specified. Minor gaps remain around what 'today' means (timezone/boundary) and behavior when no workouts are scheduled.

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 only parameter is fully documented there. The description restates days_ahead verbatim without adding format, edge-case, or boundary meaning beyond the schema, which is the baseline 3 case.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description gives a specific verb and resource: retrieve upcoming scheduled workouts. It is clearly distinguishable from mutation siblings like create_workout/update_workout, though it never explicitly contrasts with the other read tools (get_workout_detail, get_programs) that could also return workout information.

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 phrase 'starting with today' and the days_ahead window imply the intended use case, but there is no explicit when-to-use/when-not-to-use guidance and no named alternative for related queries such as fetching a single workout.

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, idempotentHint, non-destructive, and closed-world, so the safety profile is covered by structured data. The description adds only that results are either the full set or filtered, which is useful scope context but not deep behavioral disclosure. Output schema handles return format.

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 tight sentences front-load the purpose and scope. The Args section duplicates the schema parameter description without adding value, which is mild redundancy, but overall the text is compact.

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 handling return structure and annotations covering the safety profile, the description supplies enough for an agent to invoke this single-parameter read correctly. Only explicit sibling routing 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 description coverage is 100% for the single optional parameter, so the schema already documents it fully. The description's Args block restates the same text and example ('Barbell Back Squat') verbatim, adding no meaning beyond the schema. 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 ('Get training max (1RM estimate) values for exercises'), and the parenthetical clarifies what a training max is. It is distinguishable from siblings like get_exercise_history or set_training_max, though it never names them explicitly.

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 ('Returns all training maxes, or filter by exercise name') but gives no explicit when-to-use condition, prerequisites, or guidance on choosing between this and set_training_max/get_exercise_history. Adequate but thin.

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, idempotentHint, and destructiveHint=false, so the safety profile is fully covered by structured data. The description adds only the shape of the returned data (unit preference, rounding), which is modest value beyond what annotations 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?

A single front-loaded sentence naming the resource first, then the returned fields. No filler, no repetition of the tool name or annotations.

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 no elaboration, and with zero parameters and full annotation coverage there is little left to document. It is nearly complete; the only missing piece is any hint of when this is the right call versus similar getters.

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 the baseline of 4 applies; there are no parameter semantics to explain and the description correctly does not invent any.

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?

Specific verb+resource ('Get the user's workout settings') with examples of the returned fields (unit preference lbs/kg, weight rounding). It does not differentiate from potentially overlapping siblings like get_coach_profile, so it stops short of a 5.

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?

No statement of when to use this versus alternatives, no prerequisites, no exclusions. Usage is only inferable from the name, which is the minimum needed for a zero-parameter getter but still counts as no 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 readOnly/idempotent/non-destructive/openWorld=false, so safety is covered. The description adds non-obvious behavior beyond the annotations: the three-tier timezone precedence (client-reported > argument > UTC) and that the resolved timezone is echoed in week.timezone. No rate limits or pagination notes, but the added context is 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 summary contents are front-loaded in the first sentence, followed by behavioral rules and then args. It is well organized with no filler, though the trailing Args block partially duplicates the fully-documented schema, slightly blunting conciseness.

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 documented, and the annotations carry the safety profile. The description still enumerates the returned summary components and resolves the timezone ambiguity that would otherwise trip up an agent. Nothing needed to invoke 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 description coverage is 100%, so the schema already documents both parameters including the same timezone precedence rule. The description's Args block largely restates the schema (Monday format, defaults, precedence) and adds little syntax or meaning the schema doesn't already carry. 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 (Get) and resource (weekly training status) and then enumerates exactly what the coaching summary contains: workouts vs goal, days left, set counts, credited sets vs four-week average, and movement patterns. This is far more specific than the sibling get_* tools and lets an agent distinguish it 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?

The description clearly establishes the scope (one Monday-Sunday week) and details the argument resolution rules (client timezone > timezone arg > UTC), which is genuine usage context. It stops short of explicitly naming when to prefer this over siblings like get_schedule or get_training_maxes, so it lacks exclusions, but the 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 already declare readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds real behavioral context beyond that: id returns at most one record, name returns every match each with its folder, and an empty workouts array is returned on no match.

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 dense sentences, front-loaded with the core purpose, and each subsequent sentence adds non-redundant information about parameter rules and return multiplicity. No filler or restatement of the title.

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 re-explained, yet the description still supplies the multiplicity and empty-result behavior an agent needs to interpret that output. Nothing needed to call the tool 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 baseline is 3, but the description adds meaningful semantics the schema does not: the mutual-exclusion rule (either/or, not both) and the differing cardinality of results per parameter. This clarifies the XOR constraint that a flat two-optional-string schema leaves ambiguous.

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 (get) and resource (workout template detail) and enumerates exactly what the payload contains (display names, sets, loads, rest modes, supersets, RPE, percentages). This differentiates it from the list-oriented sibling get_workout_templates without needing to open either 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?

Explains the selection rule between the two parameters (either workout_id or exact workout_name, but not both) and the consequence of each choice. It does not explicitly name the alternative tool for listing templates, so the when-to-use-this-vs-sibling guidance is implied rather than spelled out.

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

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

Annotations already cover read-only, idempotent, safe behavior. Description adds useful context: returns at most limit, default/max limits, truncation via total_count, and optional folder filtering. Goes beyond structured fields without 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?

Front-loaded with purpose and fields, efficiently states limits and filtering. Slightly verbose but every sentence adds information; no wasted words.

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?

Covers the tool's function, output fields (though output schema exists, so less critical), pagination/truncation behavior, and exclusion of details. Given annotations already handle safety, this is nearly complete; missing only explicit alternative tool guidance.

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. Description repeats limit defaults and folder_name optionality, adding little beyond the schema. No extra syntax or format details.

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?

Clear verb (List) and resource (workout templates) with explicit scope: high-level summary fields. Distinguishes from get_workout_detail by stating it excludes individual exercises and sets, though it doesn't name the sibling directly.

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?

Implies usage for getting a summary list, but doesn't explicitly say when to use this vs get_workout_detail or search. The exclusion note provides some context but no clear when-to-use or alternative routing.

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 idempotentHint=true, covering the safety profile. The description adds useful return-format context ('Returns display name, muscles, and equipment, best matches first, max 20 results'), but this is arguably also covered by the output schema which exists. It does not discuss pagination behavior or how 'best matches' ranking works.

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-loads the core purpose, then adds return info, then parameter descriptions. Reasonably efficient, though the parameter section duplicates the schema and the catalog-membership note could be tighter.

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 annotations (read-only, idempotent) and an output schema, the description covers what an agent needs to select and call the tool correctly. The catalog-membership constraint is valuable context for a workout-building workflow. Minor gap around result ranking or pagination semantics, but overall complete for a search tool.

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 all three parameters are already documented in the schema including enum values. The description repeats the parameter purposes without adding syntax, format, or interaction details beyond what the schema provides. 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 ('Search the exercise catalog') plus the facets it searches on (name, muscle group, equipment). This distinguishes it from siblings like validate_exercise_names and get_exercise_history, which serve different purposes.

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 clarifies implicit usage context with 'Every exercise in a workout must come from this catalog or the user's custom exercises,' which explains when this tool is relevant (constructing workouts). However, it does not explicitly name an alternative 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 provide mutation/idempotency safety profile. The description adds valuable context beyond annotations: the critical side effect that updating an existing training max recalculates the weight of every workout using percentage of training max. This is exactly the kind of impact disclosure the annotations don't 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?

Front-loaded purpose, then side-effect disclosure, then arg documentation. Efficient with no filler. Slightly verbose in restating both parameters, but the restatement adds the exact-name constraint.

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?

Output schema exists so return values needn't be explained. For a mutation tool with annotations covering safety, the description adds the key side effect (recalculation of dependent workouts) and parameter matching constraints. Missing explicit permission/auth requirements and no rollback/reversibility note, but otherwise complete.

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 meaning: exercise_name must be an exact display name from the catalog or user's custom exercises (a matching constraint), and training_max is in the user's configured units (lb or kg). These clarifications go beyond the schema's field 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?

States a specific verb+resource (set training max for an exercise) and adds definitional context that the training max is the estimated one-rep max used for percentage-based loads. This distinguishes it clearly from siblings like get_training_maxes (read) and get_exercise_history.

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?

Says it's 'intended for a user-approved training max change,' implying a confirmation context, but offers no explicit when-not-to-use or routing to alternatives. The relationship to get_training_maxes (read counterpart) is implied but not named.

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 destructiveHint=true, readOnlyHint=false, and idempotentHint=true, so the mutation/safety profile is established. The description adds valuable context beyond this: 'Progression links are preserved for exercises that keep their name' and 'Notes appear on the watch in the workout step description.' The replacement semantics ('replaces the entire exercise list, including all exercises and sets to retain') align with the destructive hint without contradicting it — no annotation 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?

The description is organized into purposeful paragraphs: purpose/identity, update semantics, then the rename-only shortcut. The main purpose is front-loaded. It is longer than average but the complexity of replace-list semantics and partial-update behavior justifies the length; every sentence carries operational meaning.

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 rich schema (100% coverage, detailed per-parameter descriptions) and the presence of an output schema, the description covers the remaining nuances well: identity resolution, replacement semantics, progression-link preservation, and the rename-only path. The only mild gap is that 'exercises absent from this array are removed' is stated explicitly in the schema but only implied in the description — a minor redundancy handled by the 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 coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by explaining the identity semantics ('workout_name is the exact current name'; folder name 'does not change folder membership') and the over-arching update model ('Omitted fields keep their current values'). It also synthesizes the rename-only vs. full-replacement usage patterns that the schema's per-field descriptions don't convey as a whole.

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 opening sentence states a specific verb+resource: 'Apply a user-approved change to an existing workout template.' This clearly distinguishes it from siblings like create_workout and delete_workout. The term 'existing template' and the mutation framing leave no ambiguity about what this tool does.

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 when-to-use guidance for the key decision: 'A rename-only request contains workout_name and name... it does not require exercises' versus a full replacement that must list 'all exercises and sets to retain.' It also explains when workout_folder_name is needed. It stops short of explicitly naming alternatives (e.g., 'use create_workout for new workouts'), but the sibling names are self-evident and the partial-update semantics are thoroughly covered.

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 readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds genuinely new behavior: case-insensitive exact matching against a catalog plus the user's custom exercises, and suggestion generation (up to 3 close matches) for invalid entries. It does not mention the 50-name cap, which is minor.

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 tight sentences: what it checks, the input constraint, and the return contract, in that order. Nothing redundant and no preamble.

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 not required, yet the description still names the key fields (all_valid, invalid names, suggestions). Combined with annotations covering the safety profile and a fully documented single parameter, an agent has everything needed 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?

Schema coverage is 100% with a single well-documented parameter, so the baseline is 3. The description earns above baseline by clarifying that the strings must be exact display names and that matching is case-insensitive, which the schema description ('Exercise display names to validate') 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 (validate/check) and resource (exercise names) with explicit scope: existence in the catalog or the user's custom exercises. This cleanly separates it from siblings like search_exercises or get_exercise_history without opening their 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?

Implied usage is clear (pre-flight validation before referencing exercise names), and it notes names must be exact display names. However, it never states when to prefer this over search_exercises, nor any prerequisite such as needing names in hand first, so usage is inferred rather than directed.

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