Reps

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

Annotations already declare the safety profile (readOnly=false, destructive=false, idempotent=true, openWorld=false), so the bar is lower. The description nonetheless adds real behavioral context: duplicate handling returns already_exists, creation is immediate ('created at once'), and the returned slug/exercise_id are immediately usable in save_routine, save_plan and edit_routine. It does not cover error cases or what happens with optional fields like reasoning, keeping it short of 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 prerequisite search instruction is front-loaded before the mechanics, and the closing sentence routes to update_custom_exercise. It is dense but nearly every sentence carries a distinct instruction; the 'tell the user in one sentence what you assumed' clause is slightly tangential to tool invocation.

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, yet the description usefully notes slug/exercise_id interoperability with three sibling tools. Combined with the search-first prerequisite and the update route, an agent has enough to call this correctly; only the undocumented optional parameters remain 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?

Schema description coverage is 0% across 7 parameters, so the description carries the full burden and only partially delivers. It gives actionable guidance for two of them ('Fill in muscle_groups and equipment from what the user described'), but leaves name, type, notes, reasoning and unilateral entirely unexplained in both schema and 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 states a specific verb and resource ('added to their own Reps exercises') and immediately frames the exact case it covers: an exercise the library lacks, such as a gym-specific machine or variation. It also names the sibling it is not (get_exercise_library for search, update_custom_exercise for changes), 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?

It gives an explicit prerequisite ('Search get_exercise_library FIRST'), explains why (a match returns already_exists instead of a duplicate), and names the alternative for later modification ('use update_custom_exercise'). This is a rare case of when-to-use, ordering, and when-not-to-use all being 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?

Annotations declare destructiveHint=true and idempotentHint=false, and the description goes well beyond them: it warns the write is immediate, defines the destructive replace-all semantics ('anything left out is removed'), explains the optimistic-concurrency guard and the routine_changed failure mode, and notes the change only appears after sync (up to 5 minutes). This is exactly the context an agent needs before a destructive write.

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 when-to-use clause, then prerequisites, then safety/confirmation, then data-shape rules, then return/sync behavior. Dense but every sentence carries operational weight; the only mild cost is length, which is justified for a destructive write.

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?

Despite an output schema existing, the description still surfaces the key result semantics the agent must react to (the routine as it now stands, and the routine_changed no-write outcome). Prerequisites, confirmation, data shape, failure mode and sync delay are all covered for a destructive, non-idempotent 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?

With 0% schema description coverage the description carries the load, and it does so for the highest-risk fields: exercises must be the FULL end state in order, omission means removal, and timed holds/cardio take target_duration_seconds instead of target_reps. base_updated_at is explained via the concurrency rule. It does not explain estimated_duration_minutes or nested fields like rest_seconds/notes, so it falls short of full compensation.

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 ('change one of their saved Reps routines') and enumerates what can change (swap/add/remove exercises, sets, targets, order, name). It is clearly distinguished from the sibling read tool get_routines and from save_routine by the explicit 'change ... saved' framing.

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 the trigger condition ('when the user wants to change ... a saved routine'), mandates a prior get_routines call for routine_id/exercises/updated_at, and prescribes a required confirmation step with an explicit 'yes in this conversation' before writing. Alternatives and prerequisites are both 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 declare readOnly/idempotent/openWorld=false, so safety is covered. The description adds non-trivial behavioral scope: it searches BOTH built-in and custom exercises, and returns each result's `slug` plus the user's own `note` (or null). That said, return details overlap with the output schema, keeping it just below 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?

Two sentences, front-loaded with the when-to-use trigger, then the search mechanics and return shape. Every clause adds information and nothing is redundant.

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 fully restated, and the description appropriately focuses on usage and filtering. The one gap is the unexplained `limit` parameter, which slightly under-informs the call for a moderate-complexity 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 0%, so the description must carry parameter meaning. It explains `search` (a name, any app language), `muscle_group` and `equipment`, and even adds the 'any app language' nuance, but leaves the `limit` parameter entirely undocumented in both schema and 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 (searches/Searches) and resource (built-in and custom exercises) and explicitly frames the tool's role as supplying an exercise's `slug` for other Reps tools. An agent can distinguish it from siblings like add_custom_exercise or get_exercise_progression 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 a clear triggering condition: 'Use this when you need an exercise's slug for another Reps tool, or the user asks which exercises exist for a muscle group or equipment.' It does not name an alternative tool or state when NOT to use it, so it stops short of the exclusionary guidance 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 read-only, idempotent, non-destructive, and closed-world behavior, so the baseline is covered. The description adds meaningful behavioral detail beyond annotations: the 90-day default window, the three metric options with their defaults, and the fallback behavior when an unknown exercise slug is provided (returns candidates, logged ones first).

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 usage condition, then return granularity, date defaults, metric semantics, and error handling. No redundant or filler 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?

For a read-only progression query with rich annotations and an output schema, the description covers the remaining gaps: default date window, metric meanings, and unknown-slug fallback. An agent has everything needed 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?

With 0% schema description coverage, the description fully compensates: it explains exercise_slug, specifies that from/to default to the last 90 days, and lists metric values and defaults (max_weight default, estimated_1rm as Epley, volume). All four parameters are given semantic context beyond their bare types and enum.

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: it returns one point per training day tracking an exercise's progression over time. It also includes a concrete user-query example, making the purpose immediately clear and distinguishable from sibling tools like get_personal_records or get_stats_overview.

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 a clear trigger condition: 'Use this when the user asks how one exercise has progressed over time.' However, it does not name alternatives or state when not to use this tool, so the routing guidance is clear but not exhaustive.

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 real behavioral context beyond that: the meaning and units of each record_type, the shape of value, and the fallback that an unknown slug returns `candidates` rather than an error. No mention of pagination or result-size limits.

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 usage trigger and then the data model. The parenthetical examples and unit annotations all earn their place; there is 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?

With an output schema present, return values needn't be spelled out, yet the description still documents record fields and the unknown-slug candidate behavior. For a two-param, no-required-param read tool it is close to complete; only ordering/pagination behavior is unaddressed.

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 0%, so the description must carry the burden, and it largely does: it defines each record_type value with units ('max_weight' kg, 'max_volume' weight×reps, 'estimated_1rm' kg) and explains the AND/omit semantics of exercise_slug and kind. It never describes the expected format of exercise_slug itself, leaving that parameter partly opaque.

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 (retrieve personal records) and grounds it with concrete user phrasings ('what are my PRs?', 'what is my heaviest squat?'), which cleanly separates it from neighbors like get_exercise_progression or get_stats_overview. An agent can match an intent to this tool 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?

Provides an explicit activation trigger ('Use this when the user asks about their personal records') and explains the filtering decision: filter by exercise_slug and/or kind, or omit both for all. It does not state when to prefer a sibling tool (e.g. progression or stats) instead, so it falls short of the 5 bar.

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, idempotent, non-destructive), yet the description adds real behavioral value: return shape, the in_plans cross-reference, and the optimistic-concurrency contract where updated_at must be passed as base_updated_at or the edit is refused. That last point is non-obvious and operationally important.

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 densely packed sentences, front-loaded with the usage trigger followed by return contents and the edit_routine handoff. No filler; each sentence carries distinct information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return values needn't be explained, and the description goes beyond that with filtering rules and the concurrency contract. The only gap is the undocumented `limit` parameter, which an agent may need to understand for large result sets.

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 0% schema description coverage the description must carry the load, and it explains routine_id filtering, name search, and the omit-both-for-all default. However, the `limit` parameter is never mentioned in the description or schema, leaving one of three parameters undocumented.

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 ('Returns routines') with explicit scope ('in any plan or none') and details the returned content (exercises, default_sets, notes, in_plans with day_of_week). This clearly distinguishes it from edit_routine and save_routine among the 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?

Gives a concrete trigger ('when the user asks about their saved routines') and a workflow role ('before changing one'), and routes the mutation to edit_routine via base_updated_at. It lacks explicit when-not guidance versus siblings like get_training_plan or get_exercise_library, so it falls just 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 readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuine behavioral context beyond that: the aggregation is a total across an inclusive from/to window, and the window defaults to the last 30 days when omitted. It does not mention pagination, limits, or empty-result behavior, but the annotated tool needs less of that.

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. The usage trigger is front-loaded and the second sentence delivers scope, defaults, and return contents compactly.

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 the enumerated return values are supplementary rather than load-bearing, and usage plus default window are covered. The remaining gap is the accepted date string format for from/to, which is undocumented in both schema and description, plus no guidance on zero-data ranges.

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 carry both parameters — and it does define their roles ('Totals from `from` to `to`') plus the default window. However, both are typed only as plain strings with no format guidance (ISO date? relative?), which is the critical missing detail for a date-range tool, so it compensates only partially.

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 (retrieve training stats overview over a period) and enumerates exactly what is produced: workouts, volume, weekly volume trend, muscle distribution, top 5 exercises. This distinguishes it from siblings like get_weekly_summary and get_workout_history without the agent needing to open 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?

Opens with an explicit trigger condition ('Use this when the user asks for an overview of their training over a period, such as volume trends or muscle-group balance'), which is strong when-to-use guidance. It does not name or exclude the overlapping siblings (get_weekly_summary, get_workout_history), so routing between near-duplicates is left to inference.

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, idempotentHint=true and destructiveHint=false, so the safety profile is covered without description help. The description adds real behavioral value by explaining the computed `next_routine` semantics (today's routine in a fixed-day plan vs. the next in a rotation), which is logic an agent cannot infer from annotations alone.

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 waste: the usage trigger is front-loaded, then the return content. Every clause carries information the agent needs to decide to call it and to interpret next_routine.

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 enumerated, and the description instead covers the one non-obvious semantic (how next_routine is derived). For a no-argument read tool this is complete: an agent knows when to call it and how to read the answer.

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 is 4 and there is no parameter meaning the description needs to supply. It neither overstates nor misdescribes any input.

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 ('Returns the active plan, its routines and exercises') rather than restating the name. It also implicitly distinguishes itself from the sibling get_routines by scoping the result to the *active* plan plus a next_routine decision.

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 an explicit, natural-language trigger ('when the user asks what to train today or next, or about their current training plan'), which is exactly the routing signal an agent needs. It stops short of naming an alternative or exclusion (e.g., when to prefer get_routines or get_workout_history instead), so it is clear context but not full when/when-not 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, so safety is covered. The description adds genuinely new behavioral context beyond the annotations: the Monday–Sunday week boundary and the is_partial=true flag for the in-progress week, which the agent could not infer otherwise.

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 usage trigger, then packs the offset semantics and return fields into one tight sentence. The field enumeration is partly redundant with the output schema, which is the only mild waste.

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, read-only summary tool with an output schema covering return values, this covers when to use it, what the parameter means, and the one non-obvious behavior (partial current week). Nothing an agent needs 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 0%, so the description must carry the parameter. It does: 'week_offset 0 = this week, -1 = last week' gives direction and sign convention, enough to call the tool correctly without opening 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 retrieval: totals for one Monday–Sunday week, and enumerates the exact aggregates returned (workouts_count, total_volume_kg, total_duration_seconds, muscle_distribution). The weekly granularity inherently separates it from siblings like get_stats_overview and get_workout_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?

Gives an explicit trigger with a concrete user utterance ('how was last week?'), which tells the agent exactly when to reach for this tool. It stops short of naming when NOT to use it or pointing at an alternative like get_stats_overview.

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, and the description adds substantial context beyond them: ordering (newest first), default window (last 30 days, 20 workouts), hard cap (100 per call), and the data-provenance limitation (only what was logged in the Reps app). This tells the agent both what it will get and what it will silently not contain.

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 trigger and the return payload, with the exclusion note last. It is dense and information-rich, though the middle sentence packs ordering, defaults, and caps into a long clause chain that reads slightly run-on.

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, the description needn't detail return values, yet it still characterizes them (finished workouts, newest first, with routine_name nullable). Coverage of triggers, exclusions, filters, defaults, and limits makes it complete enough 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 coverage is 0%, so the description must compensate, and it does for three of four parameters: from/to filtering, exercise_slugs filtering, and limit defaults/caps (30 days, 20, max 100). It does not specify the date string format for from/to nor the slug format, leaving a small gap on the wire format.

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 (retrieve finished gym workout history) with the exact payload returned: exercises, sets, reps, weights and routine_name. It clearly distinguishes itself from siblings like get_stats_overview, get_weekly_summary and get_exercise_progression by scoping to logged workout sessions and naming the example questions it answers.

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 triggers with quoted user utterances ("show my last 5 workouts", "what did I do this week?") and an explicit when-NOT-to-use boundary: no heart rate, pace, GPS, or data from a watch/other app, so do not call it for those. The alternative condition is stated even though sibling names are not.

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 declare destructiveHint=true and idempotentHint=false, and the description supplies the context that makes those hints actionable: it 'writes straight away', it deactivates the previously active plan unless activate:false, the replaced plan is named in replaced_plan, and the result only appears after an app sync of up to 5 minutes. That is exactly the extra behavioral detail annotations cannot 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?

It is long, but nearly every sentence adds distinct operational value and it is front-loaded with the confirmation requirement before the field-level detail. A slight trim of the sync/app-reopen clause would tighten it without losing 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 write tool with no schema descriptions, a 4-parameter nested schema and a sibling save_routine, the description covers prerequisites, side effects, error behavior (unknown exercise refused with candidates), and the activation outcome. The output schema covers return shape, so no return-value explanation is needed.

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 carry the load and does: it explains schedule_type's two enum values and the day_of_week constraint under fixed_days (distinct day per routine, 1 = Monday), the link-vs-copy semantics of routine_id, the slug/id requirement for exercises, and the target_duration_seconds alternative to target_reps.

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+resource ('save a whole training plan ... to their Reps account') and immediately distinguishes it from the sibling save_routine by stressing 'several routines on a schedule, such as a push/pull/legs split'. It also enumerates the input modalities (photo, PDF, spreadsheet, pasted text), so an agent can tell exactly which tool handles whole-plan ingestion.

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 when-to-use and when-not guidance: confirm with the user and 'wait for an explicit yes in this conversation' before writing, and route to get_routines for existing routine ids, get_exercise_library for slugs/ids, and add_custom_exercise for anything the library lacks. The condition for passing routine_id vs name+exercises is 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 only cover the generic write profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false); the description adds the operationally important facts: it writes immediately, it requires an explicit in-conversation confirmation, unknown exercises are refused with `candidates`, and the routine will not appear in the app for up to ~5 minutes or until the app is reopened. That is exactly the behavioral context structured fields cannot express.

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 trigger, then the confirmation requirement, then parameter semantics — the priority ordering is right and every clause carries information. It runs long for a 3-parameter tool, and 'The result lists what was saved by name' is partly redundant given an output schema exists.

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 write flow, confirmation gate, identifier validation, timing-vs-reps semantics, and the async sync caveat, which is more than enough for an agent to call it correctly. Two minor gaps remain: the meaning of `estimated_duration_minutes`, and no explicit handoff naming edit_routine for modifying an existing routine.

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 full load and does most of it well: it explains exercise_slug/exercise_id sourcing from get_exercise_library, the target_reps vs target_duration_seconds split with a worked example (45 for '45 s'), and that rest_seconds may be 0 for a superset. Only `notes` and `estimated_duration_minutes` go unexplained, which keeps it short of a 5.

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

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

States a specific verb and resource ('save a new workout routine to their Reps account') and separates it from the finished-workout logging case ('a routine is a reusable template, not a log of a finished workout'). It implicitly distinguishes itself from edit_routine via the word 'new', but it never explicitly contrasts itself with the similarly-named sibling save_plan, so an agent must infer that 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?

Gives an explicit when-to-use trigger with a concrete user utterance ('build me a 60-minute push routine and save it'), an explicit prerequisite (describe it, then wait for an explicit yes), and an explicit retry/abandon policy when an exercise slug is refused (retry only when it is clearly what the user meant, otherwise ask). Nothing is left to inference.

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 discloses behavior well beyond the annotations: `note` replaces the whole note rather than appending, an empty string clears it, the change is applied immediately with no confirmation step, and the agent should report the new text back. This explains the destructiveHint=true replacement semantics in concrete terms the annotations cannot.

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?

It is one dense paragraph, but it is front-loaded with the trigger and every sentence earns its place: scope, sibling exclusion, prerequisite, replacement semantics, and confirmation instruction. No filler despite the length, which is justified by the destructive replacement behavior.

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 explained. The description covers trigger, prerequisites, mutation semantics, and sibling routing, which is everything an agent needs to invoke 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?

With 0% schema description coverage, the description carries the full burden and does so: it explains that `note` replaces the entire note (and how to append), that an empty value clears it, and that `exercise_slug` should come from `get_exercise_library`. Both parameters are given meaning absent from 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 a specific verb and resource ('add, change or clear their own note on an exercise, built-in or custom') and explicitly distinguishes this from the sibling case where a custom exercise's how-to belongs in `notes` on `update_custom_exercise`. An agent can identify the tool's scope 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?

It gives explicit when-to-use ('user asks to add, change or clear their own note'), the counter-case (custom exercise how-to goes elsewhere), the prerequisite workflow (fetch slug and current note via `get_exercise_library`), and the invocation condition ('when the user asks for the note or has just agreed to it'). Nothing is left to inference.

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, so safety is partly covered. The description adds meaningful behavior beyond them: changes are 'applied at once, with no confirmation step', only changed fields should be sent (partial update), and built-ins return a not_custom outcome. It stops short of describing any rate limits or full validation error surface.

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 triggering condition, then slug lookup, then mutable fields, then the no-confirmation caveat. Dense and largely waste-free, though packing the slug-validation parenthetical and the post-edit sentence into one block slightly dilutes scanability.

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 explanation, and the description covers trigger, prerequisite, mutable fields, and the no-confirmation behavior. The only gaps are the unexplained 'reasoning' parameter and the exact required-vs-optional framing for the mutation body.

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 0% schema description coverage, the description carries the burden and does: it enumerates the mutable fields (name, muscle_groups, equipment, type, unilateral, notes) and clarifies notes is the step-by-step how-to, one step per line. It does not explain the 'reasoning' parameter or explicitly tie exercise_slug to the required-key role.

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 set (rename, re-file, rewrite the how-to) and a precise resource scope (one of their OWN custom exercises). It distinguishes from built-ins and points to get_exercise_library, so an agent can tell it apart from add_custom_exercise or set_exercise_note 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?

Explicit when-to-use ('when the user asks to rename/re-file/rewrite' or 'has just agreed to it') and a clear exclusion rule ('only is_custom: true rows qualify; built-ins return not_custom'). It also names the prerequisite tool (get_exercise_library) to obtain the slug.

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