Phorme Training

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorld=false, but the description adds substantial behavior beyond them: the result cap ('up to five'), the filtering rule (same kind, equipment-allowed), the per-item demo link, and a disclosed fallback ('says so when it has to offer the nearest kind instead'). 'Changes nothing, including any saved plan' sharpens the read-only guarantee with a concrete reassurance about side effects.

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

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

Three dense sentences with no filler, and the trigger conditions are front-loaded before the return behavior and the exclusion. It is slightly long for the payload, but every clause carries distinct information, so the sizing is defensible rather than padded.

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-shape explanation is not required, and the description stays complete for the remaining gaps: trigger conditions, fallback behavior, and the safety exclusion. An agent has everything needed to decide whether to call it and what the caller will receive.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters including the reason enum and the available_equipment example array, making 3 the baseline. The description reinforces the preference/busy/equipment framing but adds no syntax, format, or constraint detail the schema lacks.

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

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

States a specific verb and resource ('a replacement for one exercise') and enumerates the exact conditions that trigger it (missing equipment, busy station, wanting a different option) with a concrete example ('no cable machine for cable rows'). Clearly distinguishable from every sibling, all of which are read/save/preview tools rather than substitution finders.

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 both when-to-use (the three triggering reasons plus the cable-row example) and an explicit when-not-to-use exclusion ('Do not use it to work around pain or injury'). This is the strongest form of routing guidance and covers the main misuse case for a fitness-tool substitution helper.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered; the description adds real context beyond that: it requires a connected Phorme account (auth prerequisite), reports weights in pounds (unit convention), and discloses the no-match fallback behavior. It does not mention rate limits or latency, but that is minor.

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

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

A single dense paragraph, but well front-loaded: the usage trigger and example phrasings come first, followed by return shape, safety, prerequisites, units and the fallback path. Every sentence carries information; the only near-redundancy is 'It reads only and changes nothing' against the readOnly annotation.

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?

Because an output schema exists, return-value details need not be documented, yet the description still summarizes them. It covers the aspects an agent actually needs to invoke correctly: trigger phrasing, fuzzy movement matching, auth prerequisite, units, and the no-match recovery path.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema: 'finds the lift in their Phorme log by the words they use' clarifies that 'movement' is a fuzzy natural-language match rather than an exact ID, and it notes weights are in pounds, which is not encoded in the schema.

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

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

States a specific verb+resource ('find the lift in their Phorme log... returns one point per session... shows a chart card') and backs it with concrete user-phrasing examples ('how is my bench going'). An agent can distinguish this analytics/charting tool from siblings like get_training_history or find_exercise_swap without opening the schema.

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

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

Gives an explicit trigger condition ('when the user asks how one of their lifts is progressing or wants it graphed') plus a worked fallback path when the lift is not matched — list logged lifts and ask which one. It does not name competing siblings (e.g. get_training_history for whole-log views), so routing against alternatives 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 only say readOnlyHint=false, destructiveHint=false, openWorldHint=false. The description goes well beyond them by disclosing the non-obvious write side effect (the pick is recorded privately so the coach gets credit), the exact return scope (first week only, not the whole program), and two negative guarantees about pricing and purchasing. These are behaviors an agent could not infer from structured fields.

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 triggering condition, then what is returned, then the constraints. No sentence is redundant and nothing is buried.

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

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

For a one-parameter read/get tool with a full output schema, the description covers trigger, return scope, side effect and boundaries. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100% for the single program_id parameter, whose schema description already states where the id comes from. The description merely repeats that provenance in narrative form and adds no format, length, or validity 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?

States a specific verb and resource (retrieve one Phorme program's details) and immediately scopes the payload: the program plus every session of its first week and a descriptive link. It is clearly distinguishable from the sibling search_phorme_programs because it names that tool as the source of the id.

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 condition: 'when the user picked one program from search_phorme_programs and wants its details.' It also states the boundaries of what will happen ('never shows prices or starts a purchase'), so an agent knows this is not a purchase or pricing path.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the read-only claim is partly redundant, but the description adds genuinely new context: a connected Phorme account is required and weights are returned in pounds. That auth prerequisite and unit convention are not derivable from the structured fields, which lifts it above the annotated baseline.

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 condition and example, then constraints and the alternative — logical order with little waste. The 'reads only and changes nothing, including the plan' clause is slightly redundant against the annotations, keeping it short of perfect.

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-shape explanation is not required, yet the description still summarizes contents. With auth need, unit convention, usage trigger, and sibling routing all present, an agent has everything needed to call 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?

Schema description coverage is 100% and the single 'days' parameter is fully documented there (range, default 7), so the schema carries the burden. The description only implies a forward-looking window ('today or the coming days') without adding constraints or format detail beyond the schema, matching the baseline for high-coverage schemas.

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

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

States a specific verb+resource (get planned Phorme sessions) and immediately scopes what a session contains (exercises, sets, reps, auto-set loads). It also explicitly routes away from the sibling preview_workout_import for non-plan sessions, so an agent can distinguish it without opening any schema.

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

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

Gives an explicit trigger ('when the user asks what their Phorme plan has for today or the coming days'), a concrete example utterance, and an exclusion ('Do not change the loads; for a different session, build one with preview_workout_import'). This is the when/when-not/alternative pattern in full.

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/openWorld=false/destructive=false, and the description usefully adds that it 'changes nothing,' that it only returns training owned by the connected account, and that it depends on an id produced earlier in the same conversation. This is meaningful context beyond the safety hints, though it says nothing about behavior when the id is stale or belongs to another account.

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 short sentences, front-loaded with the trigger condition, then return value, then prerequisite, then exclusions. No filler or repetition.

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

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

An output schema exists, so return contents need not be over-explained, and the description still summarizes them (title and open link). With annotations covering safety and the schema covering both params, an agent has everything needed to call 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?

Schema coverage is 100%, so both training_id and the training_kind enum are already documented in the schema. The description reinforces that training_id must come from a save tool, which is a mild provenance constraint, but adds no format or value semantics beyond the schema. Baseline 3 applies.

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

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

States a specific verb and resource (retrieve a previously saved workout or program) and scopes it precisely to items 'a save tool already saved in this conversation.' It carves a clear niche against siblings like save_workout_to_phorme (the creator of the id) and get_phorme_program (account-level programs).

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 ('when the user asks about a workout or program that a save tool already saved in this conversation') and a concrete example use case (getting the Phorme link again). It also rules out list/search/edit/delete, but never names the sibling tool to use instead for those cases, so the routing is partial.

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?

Adds real context beyond the annotations: it requires a connected Phorme account, weights are in pounds, results should be grounded ('Answer from these numbers only'), and it reads only/changes nothing. The 'reads only' clause partly restates readOnlyHint=true, so it is good rather than purely additive.

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 usage trigger, then return contents, then constraints and the sibling handoff. Dense and purposeful, though it restates return fields that the existing output schema already conveys, adding mild 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 read-only, zero-required-param tool with a full output schema, the description covers everything an agent needs: when to use it, auth prerequisite, units, grounding rule, and routing to the import-preview sibling.

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?

Only one parameter (limit) and the schema documents it at 100% coverage including the default of 10. The description adds nothing about the limit, so this is the baseline for a fully schema-covered parameter.

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 combo (return the user's own logged training in Phorme) and enumerates the concrete questions it answers (last session, frequency, PRs, next-workout basis). This distinguishes it from siblings like get_planned_sessions, get_lift_progress and get_saved_training without needing their schemas.

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

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

Opens with an explicit when-to-use trigger ('when the user asks about their own training logged in Phorme') and names a concrete downstream alternative: pass the result to preview_workout_import to build a next workout. Both the selection condition and the handoff are 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 declare the generic read/destructive/open-world flags, but the description adds substantive behavior: the preview is private, expires in 24 hours, nothing is saved to any account, every week and workout is validated, exercises are matched against the movement library, and all warnings must be surfaced before saving. That is exactly the pre-write workflow context an agent needs and cannot get from 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?

Five sentences, each doing distinct work: use case, behavior/TTL, non-persistence, required user confirmation, and exclusions. Front-loaded with the trigger condition and free of filler.

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

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

An output schema exists, so return values need not be described. Given the nested input, preview TTL, no-account guarantee and the confirmation handoff to save_program_to_phorme are all covered, 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?

Schema coverage is 100% with deep nested descriptions, so the schema documents the program structure fully and baseline is 3. The description only adds that the program is 'from this conversation' and that exercises get matched to the library, which is useful but modest added meaning over the schema.

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

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

States a specific verb and resource ('turn a multiweek training program ... into trackable Phorme training') and explicitly scopes it away from preview_workout_import and save_program_to_phorme by excluding single workouts. An agent can distinguish it from every sibling without opening a schema.

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

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

Gives an explicit when ('user wants to turn a multiweek program from this conversation into trackable training'), explicit when-not ('Do not use it for a single workout, nutrition plans or medical questions'), and the required follow-up step of asking before calling save_program_to_phorme. 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 readOnlyHint=true and destructiveHint=false, and the description reinforces this with 'reads only and changes nothing in any account.' It earns credit for disclosing non-obvious behavior beyond the annotations: what happens when no program exists (match_quality and limits report it) and the rule never to present another sport's program as a match.

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

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

The description is front-loaded with the triggering condition and the primary behavior, then layers routing and exclusions. It is on the longer side, but nearly every sentence carries distinct operational value; only the read-only restatement is somewhat redundant with the annotations.

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

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

For a 3-parameter read-only tool with an output schema, the description covers everything an agent needs: when to invoke, what is returned (sets, reps, coach notes, demo link), the no-match fallback, exclusions, and the downstream save path. Return-value detail beyond this is handled by the output schema.

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

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

Schema description coverage is 100%, so the schema already documents sport, season_phase, and gym_days_per_week, including the enum. The description adds only the general notion that output is 'sized to the days the user has' and never mentions season_phase, so the baseline 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?

States a specific verb and resource: it selects the closest coach-built Phorme sport program and returns one week of gym sessions sized to the user's available days. This clearly separates it from siblings like preview_program_import, preview_workout_import, and search_phorme_programs.

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 triggering condition (user plays a sport and wants a week of gym days planned around it) and gives a concrete scenario. It names three exclusions (injury rehab, children's team practice plans, nutrition) and routes the save path to preview_workout_import with origin "sport_week".

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

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

Annotations only give readOnly=false/destructive=false/openWorld=false, but the description discloses the actual behavior: it validates the workout, matches exercises to the movement library with demo links, flags equipment/time violations, stores a private 24-hour preview, and explicitly does not save training to an account. The 24-hour retention and 'ask before saving' flow are behavioral facts the 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?

Front-loads the use case before capabilities and constraints, and every sentence carries distinct information (trigger, behavior, side effect, downstream step, exclusions). It runs five sentences and is slightly dense, but there is little 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?

An output schema exists, so return values need not be described. Given the complex nested workout schema, single-param requiredness, and the mutation-adjacent 24-hour preview, the description supplies the trigger, side effects, warning-handling expectation, and exclusions needed to call it correctly.

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

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

Schema description coverage is 100%, so the schema documents all four params, setting a baseline of 3. The description adds meaning by explaining why time_limit_minutes and available_equipment matter (they drive the runs-past-time and equipment-not-listed warnings) and how origin ties to preview_sport_week, exceeding the schema's own text.

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 (preview/check) and resource (a single workout to follow and track in Phorme) and enumerates the accepted origins (written in conversation, pasted from notes, built to fit time/equipment). It clearly distinguishes itself from program-scale and other sibling tools by scoping to 'a single 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?

Opens with an explicit when-to-use trigger, names the downstream alternative (save_workout_to_phorme) and the origin link to preview_sport_week, and closes with explicit exclusions ('Do not use it for multiweek programs, nutrition plans, or pain and injury questions'). Routing is unambiguous.

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

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

Annotations already declare readOnlyHint/destructiveHint, but the description adds the non-obvious behavioral fact that it only renders the values supplied and neither fetches nor mutates anything in Phorme. That is real context beyond the annotations, though it says nothing about rendering failure or validation behavior.

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

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

Three short sentences, front-loaded with the purpose and trigger, then the input sourcing, then the safety clarification. No sentence 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, the description needn't explain return values, and it covers the trigger, input source, and side-effect profile. The remaining gap is the undocumented non-enum parameters, which is minor for a display-only 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 43%, below the 50% threshold, so the description should compensate more than it does. It only says to pass the matching fields from the prior result; it adds no meaning for training_kind, warning_count, exercise_count, or estimated_duration_minutes.

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: show the user a compact Phorme training card. It also distinguishes this display-only tool from the tools that produce its inputs (save tools, get_saved_training, preview_program_import), so an agent can pick it 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?

It gives explicit trigger conditions: call after a save tool or get_saved_training has returned, or after preview_program_import, and pass the matching fields from that result. It names the source tools clearly but does not state when not to use it or what to do if no such result exists.

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

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

Annotations already declare idempotentHint=true and destructiveHint=false, so the description's main added value is the undisclosed operational context: it requires a connected account with training:write plus a membership that already includes programs, and it fails loudly with no side effect otherwise. It also confirms no purchase flow is triggered, which no annotation conveys.

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 precondition sentence and each sentence carries distinct information. Minor redundancy: the retry/idempotency sentence restates both idempotentHint and the schema's own description of idempotency_key, and the link-sharing instruction is stated twice in effect.

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, yet the description usefully notes a link is returned and to share it. Combined with permission requirements, failure behavior, and idempotency, an agent has everything needed to invoke this mutation 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 all three parameters are already documented in the schema, including the idempotency_key reuse rule. The description only reinforces the retry semantics rather than adding new parameter meaning. Baseline 3 is appropriate.

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

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

States a specific verb+resource (saves a previewed program to the connected Phorme account as a private program) and names the sibling it depends on, preview_program_import. An agent can distinguish it from preview_program_import and save_workout_to_phorme without opening any schema.

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

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

Gives an explicit gating condition ('only after preview_program_import returned a preview and the user clearly said to save it') and an explicit exclusion ('It never starts a purchase'). The alternative path is named, so the when/when-not is fully determined.

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

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

Goes well beyond annotations by disclosing the required OAuth scope (training:write), the created resource's visibility (private workout), the return payload (a link to share with the user), and retry semantics for idempotency_key. Annotations only cover the generic write/idempotent/safe profile; the description supplies the operational detail an agent needs.

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

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

Four short sentences, each carrying distinct content: prerequisite gate, action and output, permission requirement, retry semantics. The gating condition is front-loaded, and nothing is redundant with structured fields.

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

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

For a write tool with a confirmation gate, an output schema present, and full schema coverage, the description covers the preconditions, permissions, side effects, and downstream instruction (share the link). 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 100%, so all three parameters are already documented, including the idempotency_key reuse rule and the confirmation gate. The description restates the idempotency behavior but adds no syntax or format detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb+resource ('saves that workout to the connected Phorme account') and scopes it precisely as the second half of a two-step flow. It clearly distinguishes itself from preview_workout_import, which it names as the prerequisite.

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 gives the when-to-use condition ('only after preview_workout_import returned a preview and the user clearly said to save it') and names the alternative tool the agent should have already called. It also implies the when-not condition: do not call before a preview and explicit user confirmation.

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, destructiveHint=false and openWorldHint=false, so the description's 'changes nothing' is largely redundant. It does add genuinely new behavioral context beyond the annotations: result count cap (five), a sample session from week one, fit-based (non-commission) ranking, and the membership/pricing disclosure policy.

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

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

Purpose and use condition are front-loaded in the first sentence, followed by return shape and then policy constraints. Four sentences for a policy-laden tool is justified, though 'changes nothing' mildly restates the readOnly annotation.

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 spelled out, yet the description still summarizes the payload (up to five programs with a first-week sample). Combined with annotations and schema, an agent has enough to call it correctly; only edge behavior (empty results, what happens if no sport/goal given) 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 description coverage is 71%, so most parameters (goal, creator, equipment, experience, schedule_days) are already documented in the schema. The description only implicitly maps to sport and goal ('for their sport or goal') and adds no format, default, or combination guidance for the seven optional filters. Baseline 3 is appropriate.

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

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

The description names a specific verb (search/find), the resource (coach-built Phorme training programs) and the trigger (user asks for a program for their sport or goal), with a concrete example ('structured volleyball program'). It is clearly distinguishable from siblings like get_phorme_program (fetch a known program) and save_program_to_phorme (persist one).

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 use condition ('when the user asks for an existing coach-built training program for their sport or goal') plus negative guidance about pricing and purchase flows. It stops short of naming alternatives such as get_phorme_program for retrieving a specific program, so it is clear context without full sibling routing.

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