LiftTrack

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

The description goes well beyond the minimal annotations by explaining important behaviors: percent is passed as a percentage and the server computes weight, a missing training max produces a clear error, rest modes have precise meanings, and an unknown folder_name causes a new folder to be created. These are the kind of side effects and failure modes an agent needs to know before calling.

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 long, but every section earns its place: an approval gate up front, then parameter rules, then a concrete example. The structure is dense and scannable, and the example clarifies the conditional relationships better than prose alone would.

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

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

Given the tool's conditional complexity, the description is unusually complete. It covers prerequisites, required vs optional fields, server-side behavior, error conditions, and side effects, while the output schema handles the return shape. An agent has enough information to build a valid payload and to know when not to call the 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?

Even though schema description coverage is only 33%, the description compensates thoroughly. It explains conditional requirements (working_rest_seconds only with 'timed'), the meaning of weight=0 as bodyweight, the critical distinction between percent and computed weight, superset grouping constraints, and includes a full example JSON payload.

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

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

The description clearly states the action ('Create a workout template') and the resource domain, and then adds enough specific detail about exercises, sets, and rest modes to make the tool's purpose unambiguous. It is easily distinguished from siblings like update_workout, delete_workout, and get_workout_templates.

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

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

The description explicitly states when the tool may be called: only after the user has reviewed and approved the proposed workout. It also gives concrete workflow guidance, such as using exact exercise names from search_exercises and calling get_folders first to reuse an existing folder.

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?

Beyond the destructiveHint annotation, the description discloses that deletion is irreversible ('This cannot be undone'), cascades to schedules and the user's Garmin device, and fails when duplicates exist, listing matches for disambiguation. It also mandates a user-confirmation protocol. This is rich behavioral context that annotations alone do not provide.

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

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

The description is front-loaded with the most critical facts (permanence, irreversibility, cascade) and then structured around user confirmation, arguments, and duplicate handling. Each section is purposeful; no filler or repetition beyond reinforcing the irreversibility.

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 destructive tool with a required confirmation step and ambiguity handling, the description covers prerequisites, argument semantics, failure mode, and retry guidance. An output schema exists, so return values need no explanation. There are no significant missing pieces for an agent to invoke this safely.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, but the description adds value by noting that workout_name is case insensitive, folder_name is optional and uses 'My Workouts' for un-folder workouts, and by explaining the failure/retry flow when names are ambiguous. These details go beyond the schema 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?

The description opens with a specific verb and resource: 'Permanently delete a workout template.' It clearly distinguishes the action from siblings like create_workout and update_workout, and explicitly notes the cascade to schedules and the Garmin device, leaving no ambiguity about what the 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 clear invocation context: always confirm with the user, state exact name/folder, get explicit approval before calling. It also explains how to disambiguate duplicate names and instructs to ask the user which entry is meant. It does not explicitly name alternative tools or state when not to use it, but for a delete operation the primary guardrails are present.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description goes beyond them by clarifying that only completed workout sessions are returned and that 'full' includes sets performed vs target. No contradictions or hidden side effects are hinted at.

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

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

The description is front-loaded with behavior and usage, then lists parameters with defaults. It is slightly redundant with the schema's parameter descriptions, but every sentence contributes either semantic context or invocation guidance, so it remains appropriately sized.

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 complete input schema, output schema, and strong annotations, the description fills the remaining gaps: the completed-session scope, the detail-mode tradeoff, default date range, filters, and the get_exercise_history alternative. Nothing essential for correct invocation is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so baseline is 3, but the description adds meaning by explaining what each detail mode returns and marking summary as preferred for browsing. It also reiterates defaults clearly, adding modest value over the schema alone.

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

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

The description states it "Get[s] completed workout sessions" and elaborates the two detail modes, giving a concrete verb, resource, and scope. It also distinguishes itself from get_exercise_history by directing single-exercise progress queries there, so an agent can tell tools apart.

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

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

It explicitly advises that detail='summary' is preferred for browsing and that get_exercise_history should be used "for a single exercise's progress over time." This gives both a recommended invocation style and a clear alternative condition.

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, so the safety profile is clear. The description adds valuable behavioral context beyond annotations by disclosing that an empty object is returned when no profile exists, which prevents the agent from misinterpreting an empty result as an error.

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

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

The description is two sentences of dense, useful information. The first sentence lists the returned fields in a compact, scannable format. The second sentence adds usage timing and an edge-case behavior. No filler or redundancy.

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

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

For a zero-parameter, read-only getter with an output schema, the description covers what is needed: what the tool returns, when to call it, and the special empty-object case. The presence of an output schema handles return structure, so no further detail is necessary.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so there is no schema burden on the description. The description instead clarifies what the tool returns, effectively compensating for the absence of parameter semantics. It accurately summarizes the profile contents, making the no-parameter call sensible.

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 begins with a clear verb and resource: 'Get the user's saved Coach Profile'. It enumerates the specific fields returned (experience level, primary goal, training days per week, etc.), so the agent knows exactly what this tool provides. It is distinct from all siblings, none of which claim to fetch a coach profile.

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

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

The description explicitly states when to use the tool: 'Call this early in a coaching conversation to ground advice in the user's stated goals, schedule, and equipment.' It does not name alternatives or exclusions, but there are no sibling tools that provide a similar coach profile, so the guidance is sufficient for correct selection.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior. The description adds valuable non-obvious guidance: when a session has a local_date, quote it rather than converting the UTC date field. This goes beyond structured annotations and helps the agent use results correctly.

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 tightly written and front-loaded. Each sentence earns its place: purpose, output content, a concrete use case, and an important date-handling instruction. No filler or repetition of schema details.

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 tool is simple, the input schema fully documents parameters, annotations cover safety, an output schema exists, and the description adds the one behavioral subtlety (local_date handling). This is complete enough for an agent to invoke the 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%, with both exercise_name and limit already described in the input schema. The description provides no additional parameter-level detail, so the baseline of 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?

The description opens with a specific verb and resource: 'Get performance history for a specific exercise across sessions.' It also enumerates the returned content (sets, volume, estimated 1RM, heaviest set, trends), making the tool's purpose unmistakable and distinct from sibling tools like get_training_maxes or 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 a clear usage context: 'most useful tool for coaching conversations like How's my bench progressing?' This tells an agent when to reach for it. It does not explicitly name alternatives or exclusion conditions, so it stops short of a 5.

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

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

Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds scoping context by saying the folders belong to the user, and it mentions the returned data includes workout count. It does not expose additional behavioral details beyond this, which is acceptable given the strong 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?

Two concise sentences with no filler. The first sentence states the action and output, and the second explains the practical usage context. Each sentence earns its place.

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

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

For a zero-parameter read-only tool with an output schema, the description is complete. It explains what the tool returns and exactly when the agent should invoke it. The annotations cover the safety profile, and the output schema covers return structure.

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?

This tool has zero parameters, so the empty input schema is complete and the description does not need to document parameter details. It adds useful context by tying the returned folder_name to the upcoming create_workout call, which helps the agent understand how to use the result.

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

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

The description states a specific verb and resource: 'List the user's workout folders' and explicitly names the output fields ('name and workout count'). It also connects the tool to the downstream create_workout flow, making it easy to distinguish from other get_* tools.

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

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

The description clearly states when to call this tool: before create_workout when the new workout should be placed in a folder, so the agent can pass an exact folder_name. It provides a clear trigger context, though it does not explicitly discuss when not to call it or alternatives.

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 and idempotentHint, so the base safety profile is covered. The description adds valuable behavioral detail beyond annotations: no pagination, grouping of repeated workout IDs within weeks, and cross-week reuse semantics. This helps the agent understand the exact response structure and implications.

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

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

The description is front-loaded with the core purpose, then adds necessary behavioral details about pagination and grouping. Every sentence contributes meaningful information for correct invocation, and there is no redundant fluff.

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

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

Given the tool's moderate complexity, the description covers all essential aspects: the compact plan nature, full week retrieval, grouping behavior, workout reuse semantics, and the routing rule for get_workout_detail. With an output schema present, no further 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 100%, with program_id described as the stable id returned by get_programs. The description adds little param-specific meaning beyond confirming it refers to a saved program, so the schema carries the semantic weight as expected.

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

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

The description clearly states the tool retrieves one saved program's complete compact plan, distinguishing it from program listing tools by emphasizing full plan details without pagination. It also explicitly contrasts with get_workout_detail, making its purpose unambiguous.

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

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

The description provides explicit when-to-use guidance by stating to call get_workout_detail once per unique workout_id only when workout names or contents are needed. This directly routes the agent between the two sibling tools, leaving no ambiguity about which tool to select.

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

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

The annotations already declare this a safe, read-only, idempotent operation, so the bar is lower. The description adds meaningful behavior beyond the annotations: the guarantee that internal lifecycle ids are never returned, and the specific status vocabulary. This helps the agent set expectations about the response without overpromising.

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

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

Three short sentences with no filler. The primary action and output fields are front-loaded, the status enum is given in a compact list, and the critical exclusion (no internal IDs) is stated directly. Every sentence contributes valuable 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?

For a simple read-only list tool with zero parameters, an output schema, and safety annotations, the description is complete. It specifies the user scope, result granularity, included fields, status values, and a key constraint. Nothing an agent needs to decide whether to call this or interpret its result 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?

With zero parameters and 100% schema coverage, there is nothing for the description to explain about parameter meanings. The baseline for 0-parameter tools is 4, and the description goes further by clarifying the output semantics (the fields and statuses returned), which is useful context even though it is not strictly parameter-related.

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'), a clear resource ('the user's saved programs'), and a precise scope: the summary level of LiftTrack's program cards. It enumerates the exact fields returned (name, status, total weeks, current week, days per week), which fully distinguishes it from the sibling get_program_detail. This is a model of purpose clarity.

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 implies this tool is for summary-level program listing, not detail retrieval, and explicitly notes that internal lifecycle ids are never returned. This gives the agent enough context to know that get_program_detail is the alternative when more than the card-level summary is needed. However, it does not explicitly name a sibling or state 'use this when...' so it stops short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds useful behavioral detail beyond annotations: returned dates are plain calendar dates exactly as scheduled, and the range starts today. This helps set output expectations without contradicting the annotations.

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

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

The description is compact, front-loaded with the primary purpose, and contains no fluff or redundant detail. The additional sentence about calendar dates adds value without bloating the text.

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 tool with one optional parameter, complete schema coverage, helpful annotations, and an output schema, the description provides enough context to call the tool correctly. The only minor gap is lack of explicit sibling differentiation, but overall nothing critical is missing for effective invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, and the description's 'days_ahead' text is essentially identical to the schema property description. It repeats the default and max values rather than adding new semantic meaning, so the baseline score of 3 is appropriate.

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

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

The description clearly states the action ('Get'), the resource ('upcoming scheduled workouts'), and the scope ('starting with today'). It is easily distinguishable from sibling tools like get_workout_detail or get_activities, so an agent can understand what this tool provides without opening other schemas.

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

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

The phrase 'upcoming scheduled workouts' implies use for future scheduled workouts, and 'starting with today' plus 'days_ahead' gives clear retrieval context. However, the description does not explicitly name alternatives or state when not to use this tool, so some usage inference is required.

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, covering the safety profile. The description adds that invoking with no filter returns all training maxes and with exercise_name returns a subset, plus clarifying that values are 1RM estimates. No side effects or edge cases are disclosed, but this is acceptable for a simple getter.

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

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

Three short sentences front-load the core behavior and then cover the optional parameter. No filler, no redundant background, and the structure flows naturally from purpose to filtering 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?

For a single-optional-parameter read tool with an output schema and readOnly/idempotent annotations, the description is complete. It states both invocation modes (all vs filtered) and clarifies the data meaning (1RM estimate). Nothing needed to call it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%; the schema already fully documents exercise_name as an optional display-name filter. The description repeats that same example ('Barbell Back Squat') without adding additional meaning, so it meets the baseline but adds little beyond the schema.

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

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

The description opens with a specific verb and resource: 'Get training max (1RM estimate) values for exercises.' It also states the two modes (all values or filtered by exercise name), clearly distinguishing this read tool from the sibling set_training_max and other get_* tools.

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

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

The description clearly establishes retrieval context: use it to read training maxes, with an optional filter. It does not explicitly name alternatives such as set_training_max or spell out when not to use the tool, but the read-vs-write contrast is obvious from the sibling context.

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, covering the safety profile. The description adds only timing advice, not additional behavioral traits such as authentication needs, rate limits, or what entities are affected. Since it doesn't contradict annotations, a 3 is appropriate.

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, no filler. The first sentence front-loads the operation and examples; the second gives actionable usage guidance. Every clause 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?

For a simple, read-only, zero-parameter getter with an output schema present, the description is sufficient: it defines purpose and provides invocation timing. It doesn't explicitly contrast with sibling tools, but the uniqueness of 'user settings' is clear enough that this omission is minor.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so schema coverage is trivially 100% and the description cannot add parameter-level meaning. The description does clarify the type of data returned (workout settings such as units and rounding), which is relevant to context even though it's not parameter-related. Baseline 4 applies for zero-parameter tools.

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 ('Get') and resource ('user's workout settings') and gives concrete examples (unit preference, weight rounding), making the tool's role unmistakable. It reads as distinct from the various sibling get_* tools by focusing on global user preferences rather than domain-specific entities.

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

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

The description explicitly says to call this tool early in a conversation to have context for subsequent responses, which is clear when-to-use guidance. However, it does not name alternatives or provide any exclusions (e.g., 'use get_coach_profile for coach-specific settings'), so it falls short of a perfect 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 mark the tool as read-only and idempotent. The description adds meaningful behavior beyond that: current-week defaults, timezone-dependent week boundaries, days_left calculation, and UTC fallback behavior. This is exactly the kind of extra context agents need.

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

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

The description is front-loaded with a clear purpose and use case, followed by useful timezone context. The 'Args' block at the end is slightly redundant with the input schema, but the overall structure is organized and free of fluff.

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

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

Given the output schema, read-only annotations, and thorough description covering default behavior, timezone edge cases, and parameter usage, nothing critical is missing for an agent to select and invoke this 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 description coverage is 100%, so the schema already fully documents week_start and timezone. The description mostly paraphrases the schema, adding only modest nuance about timezone affecting week selection and days_left. This is marginal value beyond structured input definitions.

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

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

The description opens with a specific verb and resource: 'Get a coaching summary for one Monday-Sunday training week.' It then enumerates the exact content areas returned, making it easy to distinguish from siblings like get_schedule or 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 explicitly says 'Use it when planning a workout' and explains when to pass timezone vs when UTC will be used. It does not name alternative sibling tools or state when not to use this tool, but the contextual guidance 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 indicate readOnlyHint, idempotentHint, and non-destructive behavior. The description adds useful behavioral detail beyond annotations: id returns at most one workout, name returns every matching workout, and results include the folder. This is meaningful context without contradicting annotations.

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

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

Three compact sentences, front-loaded with the primary purpose and output shape, followed by lookup rules. Every sentence adds value; the model-summary note is slightly extra but not distracting.

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

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

Given the read-only annotations, output schema presence, and simple two-parameter input, the description is complete. It covers output shape, identification approach, matching behavior, and per-result folder context. No critical details are 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 parameters are already documented. The description adds important semantics: mutual exclusivity, preference for workout_id when available, exact-match requirement for name, and different cardinality results. This goes beyond the schema.

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

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

The description states a specific verb and resource: 'Get the full structured detail of a workout template.' It also specifies the exact output shape, listing representative fields, which distinguishes it from sibling listing tools like get_workout_templates.

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

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

The description gives clear guidance on identifier selection: use workout_id when available, otherwise exact workout_name, and not both. It also clarifies cardinality differences. It does not explicitly route to or away from sibling tools, but the lookup guidance is strong.

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?

Beyond the readOnly/idempotent annotations, the description discloses that results are high-level summaries, that limit caps the result count, and that total_count signals truncation. These behaviors add meaningful context not available in the annotations.

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

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

The description is four concise, purposeful sentences: action and output, limit/truncation behavior, filtering, and the alternative endpoint. No filler or redundant content; each sentence earns its place.

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

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

With an output schema present and read-only annotations, the description covers all essential behavior: summary fields, truncation via total_count, optional folder filter, and the path to full detail. There are no required parameters or hidden prerequisites to disclose.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and both parameters are already documented with their exact semantics (default/max for limit, optional filter for folder_name). The description repeats this information without adding new parameter-level meaning beyond the schema.

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

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

The description states a specific verb and resource ('List workout templates as a high level summary') and enumerates exact output fields (name, folder, exercise count, total_count). It also differentiates from get_workout_detail by explicitly noting it does not show full structure.

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

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

It explicitly names the alternative endpoint (get_workout_detail) and the condition for using it ('to see a template's full structure'). It also identifies the folder_name parameter as an optional filter, giving the agent a clear decision rule.

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?

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses return fields, 'best matches first' ordering, a 20-result cap, and the catalog/custom-exercise sourcing constraint. These details add meaningful behavioral context without contradicting the annotations.

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

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

The description is compact and front-loaded, with the core purpose and key constraints in the first sentence followed by a clean Args block. There is no filler or redundant repetition of schema details.

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 search tool with fully documented optional parameters and an output schema, the description covers the necessary behavioral details: result cap, ordering, return fields, and catalog constraints. The custom-exercise nuance is acknowledged, making the description effectively 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?

The schema documents all three parameters with 100% coverage, so the baseline is 3. The description adds value with concrete query examples like 'bench press', clarifies that query is free-text, and signals that filters can be combined via 'and/or'.

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 clear verb–resource pair ('Search the exercise catalog') and specifies the three filter dimensions: name, muscle group, and equipment. It also states return fields and sorting behavior, making it easy to distinguish from sibling tools like validate_exercise_names.

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

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

The description provides practical context: this tool finds catalog exercises for workout use, and it notes the important rule that workout exercises must come from this catalog or custom exercises. It does not explicitly name sibling alternatives or say when not to use it, so it stops 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?

Beyond annotations, the description discloses the upsert behavior (creates or updates), the significant side-effect that updating recalcs every affected workout's weights, and the need to confirm with the user before changing an existing value. This is rich behavioral context that annotations alone do not provide, and it does not contradict them.

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 well-structured and front-loaded with the core purpose. The Args section is somewhat redundant with the schema's parameter descriptions, but the rest of the content—definition, side effects, and confirmation rule—earns its place without unnecessary fluff.

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

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

For a two-parameter write operation, the description covers purpose, creation/update behavior, side effects, units, and the user-confirmation requirement. It also tells the agent how to source exercise_name. Since an output schema exists, the lack of a return-value description is not 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 coverage is 100%, so both parameters are already documented. The description adds value by explaining the conceptual meaning of 'training max' as an estimated one-rep max and its role in percentage-based workout calculations, which goes beyond the schema's bare parameter descriptions.

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

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

The description opens with a specific verb ('Set') and a clear resource ('the training max for an exercise'), then clarifies that it creates or updates an existing entry. It also defines what a training max is, so the agent understands exactly what this tool does and how it relates to workouts.

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

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

The description makes the context obvious: use this when the user wants to set or update a training max, and it notes that exercise_name must come from search_exercises. It also gives an important usage rule to confirm with the user before overwriting an existing value. It does not explicitly mention alternatives, but no sibling tool provides this same function.

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

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

Annotations already mark this non-read-only and destructive, so the description's job is to add context, and it does extensively: partial-update semantics ('omitted fields keep their current values'), full-replacement behavior for exercises, preservation of progression links for exercises that keep their name, and the identity-only role of workout_folder_name (never a move). No contradiction with annotations — idempotentHint is consistent with the full-array replacement semantics, since re-sending the same complete array yields the same state.

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

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

Long, but every sentence carries load for a genuinely complex tool with nested exercise arrays, supersets, rest modes, and two distinct update paths (rename vs. full replace). The approval gate is front-loaded, and the labeled name:/exercises: list makes the two modes scannable. The density of parentheticals costs it the last point, not the overall length.

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

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

Given an output schema, 100% schema parameter coverage, and annotations, the description covers every operational decision: when the call is permitted (after explicit approval), how to identify the target (exact current name, folder only for disambiguation), what to omit (unchanged fields), what to read first (get_workout_detail), and when no read is needed (rename-only). Routing to server instructions for the shared approval workflow is acceptable delegation rather than a gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3; the description earns a 4 by adding cross-parameter semantics the schema cannot express: 'provide only what changes; omitted fields keep their current values' governs how to treat every parameter, and the rename shortcut ('pass workout_name and name only') is stated in the description. The exercises paragraph reinforces the schema's read-modify-write loop rather than duplicating field-level formats.

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

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

Opens with 'Update an existing workout template' — a specific verb and resource — and immediately differentiates from siblings: partial updates versus create_workout's creation, the get_workout_detail read-first prerequisite versus direct reads, and the explicit note that this tool never moves workouts between folders. There is no ambiguity about what operation this performs or which sibling it is not.

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

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

Explicitly gates invocation: 'Only call this after the user has reviewed the proposed change and approved it,' and routes the agent to create_workout's approval workflow. It states the prerequisite read ('First call get_workout_detail and edit the object it returns') and the exclusion case ('A rename needs no prior read: pass workout_name and name only'), plus the exact condition for adding workout_folder_name. An agent can decide precisely when this tool rather than a sibling is the right call.

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 signal read-only, idempotent, and non-destructive behavior. The description adds valuable behavioral detail beyond that: exact display-name matching is case-insensitive, and the tool returns an all_valid indicator plus invalid names with up to 3 close catalog matches as suggestions. This clearly sets expectations for how the tool behaves.

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 concise and front-loaded: it starts with the core purpose, then covers matching rules, return behavior, and workflow guidance. Every sentence adds relevant information without redundancy or filler.

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

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

Given the simple 1-parameter schema, existing output schema, and clear annotations, the description is complete enough. It explains what the tool validates, how names are matched, what it returns, and when it should be used in the broader workout-creation workflow.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema already describes the single parameter as 'Exercise display names to validate' with 100% coverage. The description adds meaning by specifying that names must be exact display names, case-insensitive, and that invalid entries will receive suggestions. This enriches the schema's basic 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 clearly states the tool's purpose: checking whether exercise names exist in the exercise catalog or custom exercises. It specifies the exact matching criteria and distinguishes the validation role from sibling tools like search_exercises and create_workout.

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

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

The description explicitly instructs when to use this tool: before proposing a workout with create_workout, and provides an alternative path by taking names directly from search_exercises results. It also sets a firm rule that proposals must never contain nonexistent exercises, leaving no ambiguity about the tool's intended workflow placement.

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