Hyperhuman

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

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds nothing behavioral beyond that: it never says whether the original plan is mutated in place or a new derived plan is produced, whether team_id is required for authorization, or what constraints (e.g., week ranges) apply. "Adapts" is ambiguous about mutation semantics, which is exactly the gap an agent needs filled for a write tool.

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

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

Two short sentences, front-loaded with the action and followed by the trigger; nothing is padded or redundant. The brevity is appropriate in form, though it is brevity purchased at the cost of specification rather than earned through tight expression of complete information.

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

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

An output schema exists, so return values need not be described, and the annotations handle the safety profile. But for a mutation tool with 10 fully undocumented parameters, no statement of in-place vs. derived output, and no guidance on week-range or team scoping, an agent has too little to call it correctly without guessing.

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

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

Schema description coverage is 0% across 10 parameters, so the schema provides type and enum information but no meaning. The only hint the description offers is "for a user profile," which loosely gestures at end_user_age, end_user_gender and end_user_fitness_levels without explaining them, and says nothing about min_weeks/max_weeks interaction or user_requirements. This is a substantial shortfall given the parameter count.

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 ("Adapts an existing program") plus a scope ("for a user profile"), which is clearly distinguishable from siblings like adapt_workout or generate_program by the word "program." It stops short of explicitly contrasting itself with adapt_workout, which adapts a single workout rather than a whole program, so an agent must infer the boundary.

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

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

"Use when the user wants to customize a program" gives a positive trigger condition, but it names no alternatives and no exclusions. An agent cannot tell from this whether to prefer adapt_plan over update_program (edit in place) or generate_program (build fresh) when a user asks to 'change my program.'

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 non-destructive, non-read-only, closed-world behavior, so the description adds the key detail that it operates on an existing workout rather than producing one. It does not say whether the original workout is mutated in place or an adapted copy is returned, nor what prerequisites exist (valid workout_id, ownership/team scoping).

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

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

Two tight, front-loaded sentences with no filler: purpose first, usage trigger second. Brevity tips toward under-specification given nine parameters, but nothing is wasted.

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

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

For a 9-parameter mutation tool with zero schema description coverage, the description covers only a fraction of the customization surface and never explains how the optional parameters combine or which are required beyond workout_id. The output schema covers return values, so that gap is excused, but the input-side gaps are not.

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

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

Schema description coverage is 0% across 9 parameters, so the description must compensate and largely fails: it names duration and difficulty (mapping roughly to duration_min/max and end_user_fitness_levels) and 'equipment', which is not an input parameter at all. Six parameters — locale, team_id, end_user_age, end_user_gender, user_requirements — go unexplained, and the min/max pairing of duration is never clarified.

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 ('Adapts an existing workout for a user profile') and implicitly contrasts with generation ('without generating from scratch'). It is distinguishable from create_workout/generate_workout conceptually, though no sibling is named directly.

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

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

Gives a usage trigger ('when the user wants to customize a workout') and an implied exclusion (not from scratch), but never names the alternatives an agent would actually choose between, such as generate_workout, create_workout, or adapt_plan.

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

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

The description adds helpful context by defining the target entity (the user's team) and the nature of the source (publisher programs). This defines the scope of the clone operation but doesn't detail specific constraints or implementation behavior beyond the general concept.

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 highly efficient, using two short sentences to define the action and the user's specific intent without any unnecessary padding.

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

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

For a low-complexity tool with basic annotations, the description is largely complete. It tells the agent what the tool does and why it would be chosen in a conversational context.

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

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

With 0% schema description coverage, the description is minimally helpful. It confirms that the operation targets 'programs' rather than just generic objects, but the schema already defines the parameter type as an ID array.

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 identifies the action (Clones), the source (stock programs), and the destination (user's team), distinguishing it from simple creation or retrieval methods like create_program or list_team_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?

It provides clear intent guidance by stating when the tool should be used: when the user wants to add publisher programs to their library, which gives strong context for choosing it over alternative creation tools.

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=false, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds nothing beyond that: it does not say whether the drop is published immediately or only drafted, whether repeated calls create duplicates, or what permissions/team scoping apply. For a mutation tool that generates outward-facing content, that is a real gap.

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

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

Two short sentences with the action statement first and the usage condition second; no filler. It could have been tighter with a third line covering the single-vs-batch source option, but nothing present is wasted.

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

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

An output schema exists, so return values need not be explained. Still, with six completely undocumented parameters, an unusual anyOf requirement structure, and no behavioral detail about what creating a drop actually does, the description leaves an agent under-equipped for a mutating, content-generating tool.

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

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

Schema description coverage is 0% across six parameters. The description only implicitly ties source_type to the four source kinds; it does not explain the anyOf choice between source_id and source_ids, the 7-item cap on source_ids, or what title, locale and team_id control. It compensates for only a small fraction of the missing schema documentation.

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

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

The description gives a specific verb plus a well-scoped resource ('Creates a social drop') and enumerates the four valid source kinds, which maps directly onto the source_type enum. It is clear what the tool produces, but it does not differentiate itself from nearby siblings such as export_drop, update_drop, or regenerate_drop_copy.

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?

'Use when the user wants to create social media content from existing content' supplies a clear triggering intent. However, there are no exclusions and no named alternatives, so an agent must infer on its own why it would pick this over export_drop or regenerate_drop_copy.

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 this a non-destructive, closed-world write, so the safety profile is covered. Beyond that the description adds nothing behavioral: the only extra statement ("Requires at least 2 exercise IDs") merely restates the schema's minItems/required constraints, and there is no mention of permissions, side effects on existing workouts, or whether the created group is later updatable.

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 verb and resource, with no filler. The final sentence is partly redundant with the schema's minItems constraint, which keeps it from being maximally tight.

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 6-parameter mutation with zero schema documentation and no parameter guidance in the prose, the description is thin. An output schema exists so return values need not be explained, but an agent still lacks enough context to fill rounds, group_type, team_id, or rest_seconds 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 0% across 6 parameters, so the description must carry the load and it does not. It only implies that exercise_ids holds exercise identifiers; name, rounds, team_id, group_type, and rest_seconds get no explanation of format, defaults, or effect on the created group.

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 ("Creates an exercise group") and clarifies the two variants it can produce (circuit or sets). It does not explicitly distinguish itself from the neighboring create_exercise_instance or update_exercise_group, so it falls short of a 5.

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

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

"Use when the user wants to group exercises for circuits or micro-workouts" gives a clear triggering context, which is more than most definitions offer. However, it names no alternatives or exclusions — nothing says when to use update_exercise_group instead, or that the referenced exercises must already exist.

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 disclose that this is a non-read-only, non-destructive, closed-world creation tool, and the description is consistent with that. The description adds workflow context about creating instances before create_workout and using exercise_id for stock/team exercises. However, it does not mention validation behavior, permissions, or what happens when the time_based/reps conditional is not satisfied.

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 tight sentences with no wasted text, and the core action is front-loaded. The follow-up sentence carries actionable workflow guidance rather than 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 explained, and annotations cover the safety profile. Still, this is a 10-parameter tool with complex conditional requirements and 0% schema description coverage, and the description does not explain the time_based/reps/duration_seconds conditional or several optional parameters.

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

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

Schema description coverage is 0%, so the description must compensate for 10 parameters. It explains the meaning of duration/reps, pace, weight, and RPE, which is useful, but omits important semantics for time_based, amrap, team_id, skip_intro, and the conditional relationship between time_based and duration_seconds versus reps.

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

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

The description states a specific verb and resource (creates an exercise instance) and lists the key configurable dimensions: duration/reps, pace, weight, and RPE. It distinguishes the tool from create_workout by explaining that exercise instances are built first and their IDs are then passed into a 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?

It gives clear usage context: use when building a workout manually, create instances per exercise, then pass instance IDs to create_workout. It also notes that stock and team exercises can be referenced directly via exercise_id. It does not explicitly exclude sibling tools such as create_rest_instance, so it falls short of fully explicit when-not guidance.

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

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

Annotations already cover the safety profile (not read-only, not destructive, not open-world), so the description only needs supplementary context. It discloses the dependency on existing team workouts but says nothing about permissions, what happens if goal/workout IDs are invalid, or side effects on the source workouts.

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 action and the use case, with constraints appended. No filler, though the required-params sentence is where the inaccuracy creeps in.

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, but for a 9-parameter creation tool with zero schema descriptions the definition covers only a fraction of the surface. The misleading 'requires' statement leaves an agent with an incomplete and partly incorrect picture of what to supply.

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 9 parameters and 0% schema description coverage, the description must carry the load, but it only constrains goal_ids (1-2) and workout_ids (min 2). Seven parameters (name, team_id, difficulty, visibility, description, duration_in_weeks, workouts_per_week) are undocumented anywhere; worse, 'Requires goal_ids and workout_ids' contradicts the schema where only name is required.

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 ('Creates a workout program') and adds the source ('from team workouts'), which separates it from generate_program/generate_workout in spirit. It never names the closest sibling explicitly, so the distinction from generate_program must still be inferred.

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?

'Use when the user wants to organize workouts into a multi-week program' gives a concrete trigger condition. No when-not or explicit alternative (e.g., generate_program, create_workout) is mentioned, so ambiguity remains for adjacent tools.

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 a non-read-only, non-destructive, closed-world mutation. The description adds meaningful behavioral context beyond that: rest instance IDs must be wired into create_workout's exercise_map, and rest cannot be at the start or end of a workout. It does not discuss permissions, team scoping, or whether instances are reusable, but the key placement constraint is disclosed.

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

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

The description is two tight sentences with no wasted words. The purpose is front-loaded, and the workflow constraint follows immediately.

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 two-parameter creation tool with annotations and an output schema, the description covers the central workflow and the start/end constraint well. However, it leaves team_id's role and optionality ambiguous, which matters for correctly invoking a team-scoped create operation.

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

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

Schema description coverage is 0%, so the description must compensate. It does not explain what team_id means or when it should be supplied, nor does it clarify the duration_seconds minimum of 1 beyond the property name itself.

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: 'Creates a rest/break instance for use between exercises in a workout.' It clearly distinguishes this from the sibling create_exercise_instance tool by emphasizing rest/break usage between exercises.

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 to use this when building a workout manually, describes the sequence of creating rest instances and including their IDs in create_workout exercise_map, and names the create_workout sibling. It also states the important restriction that a workout cannot start or end with rest.

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 it is a mutating but non-destructive, non-open-world operation, so the description only needs to add context — and it does, with the ordering constraint "Workout cannot start or end with rest," a validation rule an agent would otherwise discover via a failed call. It omits permission/scope behavior around team_id and default visibility, which keeps it from a 5.

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

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

Four tight sentences with no filler: purpose, trigger, input choice, and constraint, in that priority order. The most consequential rule (can't start/end with rest) is placed last where it stands out as an exception rather than 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?

An output schema exists, so return values need not be explained, and the core input decision plus the rest-position constraint are covered. But for an 8-parameter creation tool with 0% schema description coverage, the absence of any guidance on team_id or visibility defaults leaves real gaps.

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

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

Schema coverage is 0%, so the description must carry parameter meaning, and it does resolve the most important ambiguity by explaining the exercise_map vs instances alternative and the provenance of instance IDs. However, six of eight parameters (team_id, difficulty, visibility, description, category_ids, name) get no mention at all, leaving the description partial against a 0% coverage 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 ("Creates a workout") and names the building blocks it consumes (exercise and rest instances). It implicitly separates itself from generate_workout by framing this as the path for a "custom workout," but it never names the generation sibling explicitly, so the differentiation is inferential rather than stated.

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?

"Use when the user wants to build a custom workout" gives a clear triggering condition, and it further says to supply either exercise_map or instances, mirroring the anyOf. It stops short of naming an alternative tool (e.g. generate_workout) that an agent should pick instead when it does not have pre-built instances.

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 destructive=false, openWorld=false, and notably readOnlyHint=false, so the agent knows this is non-destructive but not a pure read. The description adds the useful fact that the tool yields concrete assets (video/cover URLs, copy pack), but says nothing about whether the export renders asynchronously, consumes credits, or has latency limits — relevant given the non-read-only hint.

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

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

Two sentences, zero filler, with the resource and its outputs front-loaded before the usage trigger. Nothing redundant is repeated from the schema or annotations.

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

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

Output schema and annotations cover return shape and safety, but four of five parameters — including the constrained duration and aspect_ratio that materially change the export — are undocumented in both schema and description. An agent can pick the right tool but cannot confidently parameterize it.

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

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

Schema description coverage is 0% across 5 parameters, so the description must compensate and largely does not. "For a channel" only vaguely gestures at channel_preset; drop_id, team_id, duration (15–60, presumably clip length), and aspect_ratio are entirely unexplained.

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

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

Specific verb ("Exports") plus resource ("drop assets") with an explicit enumeration of what is produced: video URL, cover URL, copy pack. That distinguishes it from create_drop and the regenerate_drop_* siblings, though no sibling is named outright.

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?

"Use when the user wants to download assets or prepare a drop for external publishing" gives a concrete trigger condition for selection. It stops short of exclusions or naming alternatives (e.g. when to regenerate copy instead of exporting), so it is clear context without routing rules.

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=false, destructiveHint=false, openWorldHint=false, so the agent knows this is a non-destructive creation call. The description adds that the program is AI-generated from team workouts, hinting at a non-trivial generation step, but says nothing about latency, cost, idempotency, or whether the generated program is persisted or merely returned — meaningful gaps for an AI-generation operation.

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

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

Two tight, front-loaded sentences with no filler — the purpose leads and the usage cue follows. It is efficient, though arguably undersized for a 13-parameter generative tool where a little more structure would have earned 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?

An output schema exists, so return values needn't be described, but the tool's complexity (13 all-optional params, AI generation, enum constraints, age/gender/fitness-level targeting) is not reflected at all. An agent has no basis from the description for deciding which parameters matter or what a sensible call looks like.

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 13 parameters at 0% schema description coverage and zero required fields, the description carries the full documentation burden and provides almost none of it — no mention of team_id, goal_ids, week ranges, difficulty, end-user attributes, or user_requirements. The only hint is "multi-week," which loosely gestures at min_weeks/max_weeks. This is a serious gap for a tool the agent could easily call with wrong or incomplete inputs.

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

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

States a specific verb and resource ("Generates an AI training program using team workouts") and scopes it to multi-week programs built from the user's existing workout library. However, it does not differentiate itself from the very similar sibling `create_program` (nor `generate_workout`), so an agent must infer which one produces an AI-generated vs. manually created program.

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?

"Use when the user wants to create a multi-week program from their workout library" gives implied usage context, which is better than nothing. But with `create_program`, `generate_workout`, `recommend_plans`, and `adapt_plan` all in the sibling set, the description offers no when-not guidance or alternative routing for the near-identical `create_program`.

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

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

Annotations declare a non-read-only, open-world, non-destructive operation; the description usefully adds the external AI dependency and the image-source inputs. However, it omits that this is an expensive, long-running generation job whose result must be fetched via get_video_generation_status — a material behavior for an openWorldHint=true tool. No cost, latency, or failure-mode context.

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 capability then the trigger then the prerequisites — no filler. Slightly dense with parentheticals, but every clause carries operational 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?

Output schema exists so return values needn't be explained, and the required exercise_id plus image source precondition are covered. But for a 9-parameter, long-running generation tool, the description leaves the async lifecycle and half the parameters unaddressed, which is not enough for confident standalone invocation.

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

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

Schema description coverage is 0%, so the description must carry all nine params. It explains trainer_image_url (HTTP URL or data:image base64), trainer_image_id (sourced from Workout Defaults), and user_requirements in effect, but leaves team_id, equipment, exercise_type, target_muscles, and exercise_description entirely unexplained in both schema and description.

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

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

States a specific verb and resource ("Generates an AI exercise video from a trainer photo") and names the underlying service (CloneMotion). The framing "create exercise videos without filming" tells an agent exactly what unique capability this tool owns versus the many list/create workout siblings.

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

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

Provides an explicit trigger condition ("Use when the user wants to create exercise videos without filming") and concrete preconditions (have the target exercise and an image source before calling). It does not name the follow-up sibling get_video_generation_status, so the agent must infer that generation is asynchronous and needs polling.

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=false, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds useful context that output is AI-generated and non-persisted, but says nothing about generation latency, cost/quota via the Content API, or whether team_id changes the persistence outcome — a real ambiguity given the parameter exists.

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 that lead with the action and end with the persistence caveat — no filler. It could be tightened slightly by merging the use-case and persistence clauses, but nothing here is wasted.

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

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

An output schema exists, so return shape needn't be described, and the persistence caveat is a valuable addition. However, with 12 mostly-optional inputs and zero schema documentation, an agent gets no help choosing which optional parameters to populate or when the defaults are appropriate.

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

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

Schema description coverage is 0% across 12 parameters, and the description supplies no parameter meaning at all. It does not explain the duration_min/duration_max pairing, what exercise_sources control, or how end_user_* fields shape the result, so the burden of low coverage is not met.

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 ('Generates an AI workout via Content API') and identifies the backend. It also says the output is returned but not persisted by default, which implicitly separates it from create_workout. It never names an alternative sibling outright, so sibling differentiation is only partial.

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?

'Use when the user wants to create a personalized workout on-the-fly' gives a usage condition, and 'not persisted by default' hints at the distinction from create_workout. But there is no explicit when-not, no mention of recommend_workouts or generate_program as alternatives, and no guidance for the mandatory category_id lookup 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, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds only the team-level scoping as extra context; it says nothing about time-range defaults, how granularity affects aggregation, or how much data comes back.

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

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

Two short sentences with zero filler; the resource and scope come first, the trigger condition second. Nothing to trim.

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

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

The output schema covers the return shape, but with 0 required params and 0% schema coverage, the agent cannot tell what happens with no dates supplied (all time? default window?) or how granularity interacts with the range. For a stats/aggregation tool these are decisions the caller must get right.

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

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

Schema description coverage is 0%, so all three parameters (start_date, end_date, granularity) are undocumented except their types and the hourly/daily enum. The description adds no format guidance, no default behavior when dates are omitted, and no note on which granularity applies by default — a real gap for a time-series stats call.

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 ('Returns API key usage statistics') plus the scope ('current user's team'), which is more than a restatement of the title. It does not differentiate from the similar sibling 'get_team_usage', leaving ambiguity about which to pick.

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

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

Explicitly names the trigger conditions: user asks about API usage, request counts, or rate limits. Clear usage context, but no exclusions or pointers to the near-duplicate alternative 'get_team_usage'.

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 clear. The description adds that the response includes recent workouts and downloadable items, but it does not explain defaults, ordering, pagination, or omitted settings for the optional filters.

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

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

Two sentences, front-loaded with the return value and followed by a concise usage cue. There is no redundant or filler 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?

An output schema exists, so return-value details need not be repeated, and annotations cover the safety profile. However, with five optional parameters and zero schema descriptions, the description is only minimally complete for invocations that need filtering or inclusion controls.

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

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

Schema description coverage is 0% and all five parameters are undocumented. The description mentions no parameter names or meanings, so an agent gets no guidance on limit, days_back, or the include_* flags beyond the bare schema types.

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

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

The description states a specific verb and resource: it returns a dashboard summary containing latest workouts with stats and ready-to-download items. This clearly distinguishes the tool's core purpose, though it does not explicitly contrast itself with related workout-listing or detail tools.

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

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

It gives clear triggering contexts: when the user asks about the dashboard, recent workouts, or content ready for download. It does not state when not to use it or name alternative sibling tools, but the usage context is explicit enough.

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

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

The annotations already establish that this is a read-only, non-destructive, closed-world operation. The description adds meaningful context beyond that: samples are static templates, contain only placeholder values like YOUR_ORG_ID and YOUR_API_KEY, and no real credentials are fetched or transmitted.

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

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

The description is front-loaded with the core purpose and key safety detail, and the enumeration of sample types is useful rather than wasteful. The exclusionary routing sentence is also compact and purposeful.

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 do not need explanation, and the annotations cover safety. However, the optional identifier and browse parameters remain unexplained despite being part of the tool's schema, leaving a notable gap for correct invocation.

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

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

Schema description coverage is 0%, so the description must compensate for four undocumented parameters. It explains the default for sample_type and loosely describes sample categories, but it does not explain program_id, workout_id, or browse_tool, nor does it fully map the sample_type enum values to their meanings.

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: returning static copy-paste code templates for workout embeds, program page embeds, custom player JavaScript, and Content API cURL snippets. It clearly distinguishes this from sibling tools such as get_integration_plan.

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 to use this as the primary tool when the user asks for embed code, iframe HTML, or API snippet examples, and explicitly excludes integration strategy or step-by-step plans by directing those requests to get_integration_plan.

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

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

Annotations already establish readOnly/non-destructive/openWorld=false, so the description only needs to add what the annotations cannot: that the response is a strategy plus a step-by-step plan, and the three integration paths considered. It stops short of describing how the plan varies by platform or use_case, or whether any external account/auth is implied by 'stream videos', leaving a small gap.

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 purpose and supported modes, then usage triggers, then the parameter guidance, then the exclusion — a logical order with no filler. Dense but every sentence carries information; the parenthetical mode list runs slightly long.

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

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

With an output schema present, return format needn't be described, and the annotations cover the safety profile. Purpose, triggers, exclusions, and both parameters are all addressed; only the relationship between parameter values and plan output (e.g., what changes for 'hardware' vs 'cms') is left implicit, which for a read-only advisory tool is acceptable.

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

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

Schema description coverage is 0%, so the description must carry the parameter burden, and it does: it names both parameters and enumerates accepted platform values (web/mobile/hardware/cms) and gives concrete use_case examples (mvp, programs, ai_generated, corporate_wellness, vod). It adds meaning beyond raw enum text by linking them to the plan selection, though it doesn't explain defaults or how an invalid/unknown use_case is treated.

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 ('Returns an integration strategy and step-by-step plan for Hyperhuman workouts or programs') and enumerates the three integration modes it covers (iframe embed, VOD export, custom player/API). This clearly distinguishes it from siblings like get_embed_code_samples and adapt_plan without requiring the schema to be opened.

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

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

Gives explicit trigger conditions ('Use when the user asks how to integrate Hyperhuman or what integration options exist') plus an explicit exclusion with a named alternative ('Not for copy-paste embed HTML snippets (use get_embed_code_samples for those)'). Both when-to-use and when-not-to-use are covered.

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

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

Annotations already declare readOnlyHint, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered without the description. The description adds only mild scoping context ('for the connected account') and an invocation constraint; it discloses nothing about auth, data freshness, or quota-window semantics beyond that.

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

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

Two sentences, zero filler, with the return payload stated first and the usage restriction second. Nothing repeats the annotations or the empty schema.

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

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

With an output schema present, the description needn't explain return structure, and zero params and full annotation coverage keep the burden low. What is missing is only the boundary between 'usage limits' here and the usage-statistics siblings, which an agent could still trip over.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate and no schema gap to compensate for. Baseline 4 applies; the description correctly implies the account is inferred from context rather than supplied as input.

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

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

A specific verb and resource ('Returns team name, plan label, and usage limits') with the target scoped to 'the connected account', so the agent knows exactly what comes back. It is clear on its own but never names or distinguishes itself from near-neighbors like get_team_usage or get_api_usage_stats, leaving overlap ambiguity.

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

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

Explicit positive trigger ('when the user explicitly asks about their team, plan, or usage quotas') plus an exclusion-by-implication ('Use only when...'), which limits spurious proactive calls. It stops short of naming the alternative tool to use when the user asks about usage stats rather than limits, which would have earned a 5.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=false, and destructiveHint=false, so the safety profile is known. The description adds that the exercise comes from the 'team library,' but does not explain team scoping, locale behavior, or error conditions.

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

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

Two short sentences with no waste. The return value is front-loaded, followed by usage context.

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

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

The output schema covers return values and the annotations cover safety, but the optional team_id and locale parameters are unexplained and no alternative tool is mentioned. It is minimally adequate rather than complete.

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

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

Schema description coverage is 0%, so the description must explain the three parameters. It never mentions exercise_id, locale, or team_id; 'exercise from the team library' only loosely hints at exercise_id and team scope.

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

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

The description uses a specific verb and resource: 'Returns full details of an exercise from the team library.' It clearly indicates a detail-retrieval tool, but does not explicitly distinguish it from the sibling list_team_exercises tool.

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: 'Use when the user selects an exercise or asks for exercise details.' It does not state when not to use it or name the list_team_exercises alternative for browsing.

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 safety is covered. The description adds only that it returns 'full details' and 'program structure', which is modest extra context; it says nothing about permissions, scoping, or cost that the annotations don't already imply.

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

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

Two short sentences with the resource description front-loaded and the usage trigger second; no filler. Slightly imprecise wording ('workout program') keeps it from a 5.

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

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

The output schema and annotations relieve the description of return-value and safety disclosure, and the usage trigger is present. The unresolved gap is parameter meaning for locale and team_id, plus no differentiation from get_team_workout, which leaves the definition only minimally complete for a 3-param tool.

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

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

Schema description coverage is 0% across three parameters, and the description never explains what locale or team_id do, nor how team_id interacts with program_id resolution. Only program_id is weakly implied by 'a workout program', leaving two parameters undocumented in both schema and prose.

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 ('Returns full details of a workout program from the team'), which contrasts reasonably with list_team_programs. However, the phrase 'workout program' blurs the line with the sibling get_team_workout, so the distinction requires the agent to infer that this returns a program, not a 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?

'Use when the user selects a program or asks for program structure' gives a clear triggering context. It stops short of naming alternatives or exclusions, so an agent deciding between get_team_program and get_team_workout gets no explicit routing guidance.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered by structured data. The description adds only the detail that quotas are scoped to the authenticated team, which is useful but thin; it says nothing about response freshness, caching, or units of the quotas.

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

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

Two short sentences with zero waste, and the purpose is front-loaded before the usage hint. It could have used the second sentence more productively to disambiguate from get_api_usage_stats, but nothing is redundant.

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

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

With an output schema present, return values needn't be explained, annotations cover safety, and there are no parameters to document. The only meaningful gap is the lack of disambiguation from the sibling usage tool, which is a minor omission for an otherwise simple read-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?

The tool takes zero parameters, so there is nothing for the description to clarify and the baseline is 4. No parameter claims are made or needed.

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

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

States a specific verb and resource ("Returns usage quotas for the authenticated team") and gives concrete examples of what's included (social drop export count and limits). It's clear what the tool does, but it doesn't differentiate itself from the sibling get_api_usage_stats, which an agent could easily confuse it with.

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?

"Use when the user asks about usage, quotas, or limits" gives an implied trigger, but it offers no when-not guidance and doesn't address the obvious alternative, get_api_usage_stats. The agent is left to guess which of the two usage tools to pick.

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 and scope profile is covered. The description adds only "returns full details," without noting whether team_id is required for scoping, whether results are localized by locale, or any not-found behavior — modest added value over 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?

Two short sentences with the return behavior front-loaded and the usage trigger following. No filler, though the second sentence could have carried parameter or scoping detail at no length cost.

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

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

An output schema exists, so return-value explanation is not needed, and annotations cover safety. The gap is on the input side: an optional team_id and a locale with no stated effect leave real ambiguity about how to call this tool correctly in a team context.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning and it does not. It never explains what workout_id refers to, when the optional team_id matters, or how locale affects returned content — all three parameters are silent in both schema and description.

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

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

States a specific verb and resource ("returns full details of a workout from the team"), which is clearly distinct from list_team_workouts. However, it does not distinguish itself from the sibling get_workout_details, leaving ambiguity about which detail-fetching tool applies to team vs. non-team 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?

Gives a clear trigger condition: use when the user selects a workout or asks for details about a specific workout. It stops short of naming alternatives or exclusions (e.g., when to prefer get_workout_details instead), so the agent must infer the boundary.

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/non-destructive/closed-world, and the description adds genuinely new behavior: generation takes a few minutes, statuses include pending/running, and the agent should tell the user to come back later. It does not describe failure/error statuses or whether results ever expire, which is the remaining gap.

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, front-loaded sentences: what it returns, when to use it, and the async waiting caveat. Tight and useful, with no filler, though the middle and last sentences overlap slightly on the 'check back later' idea.

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

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

An output schema exists, so return values need no explanation, and the polling semantics are the main thing an agent needs. The only real omission is the origin of job_id and behavior on a non-success status.

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

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

Schema description coverage is 0% for the single job_id parameter, so the description must carry the load. It implicitly frames job_id as identifying a 'CloneMotion video generation job' but never says where the id comes from (presumably the generate call) or what form it takes, so it only partially compensates.

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 ('Returns status and result of a CloneMotion video generation job') and scopes it to the polling side of video generation, which cleanly separates it from the sibling generate_video_clip. An agent can identify the resource and outcome 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 clear use conditions: 'Use when the user wants to check if a generated video is ready or view the generated variants,' plus explicit polling guidance for pending/running states. It does not name the sibling that starts generation (generate_video_clip) or state what to do on a failed status, so the routing is implied rather than exhaustive.

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

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

Annotations already cover the safety profile (readOnly, non-destructive, closed world), and the description adds real context beyond them: sample-* ids need no auth, team paths require API entitlement, and two different backends serve the data. It stops short of error behavior or rate limits, keeping it at 4 rather than 5.

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

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

Three sentences, zero filler, and the return content and usage trigger are front-loaded before the routing/entitlement details. Every sentence carries actionable information.

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

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

An output schema exists, so return values need no further explanation, yet the description still summarizes them. Auth, entitlement, and backend routing are covered; the only gap is the unexplained locale parameter, which matters for a localized content API.

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

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

Schema coverage is 0%, so the description must carry parameter meaning. It does a good job for workout_id by explaining the sample-*, connected-team, and org id forms, but the locale parameter is never mentioned, leaving one of two params entirely undocumented.

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

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

States a specific verb and resource ('Returns workout metadata, preview assets, and summary') and names the exact content it yields. It also disambiguates from siblings by referencing get_team_workout for connected team workouts, so an agent can route between them without opening schemas.

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

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

Gives an explicit trigger ('Use when the user selects a workout or asks for details about a specific workout') plus id-type routing rules: sample-* ids, connected team workout ids, and other org ids. It names the alternative (get_team_workout) and the entitlement precondition for the Content API 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 readOnly/openWorld=false, and the description layers on genuinely new behavior: media URLs are progressive MP4/M4A and expire in roughly 7 days, sample-* ids need no auth and return no live media URLs, and connected org ids require Content API entitlement. These are exactly the runtime traits (expiry, auth, entitlement fallback) an agent cannot 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?

Four sentences, each carrying distinct information, with the return content front-loaded before the id/auth special cases. Dense but no filler; a small cost is that the auth/entitlement clauses arrive before the plain 'use when' statement.

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 detail is correctly omitted, and the description still covers the non-obvious edges (media expiry, sample ids, entitlement). It falls short only on the unexplained locale and browse_tool inputs for a 3-parameter tool.

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

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

Schema description coverage is 0%, so the description must carry all parameter meaning. It does well on workout_id by explaining the sample-* prefix convention and org-id behavior, but says nothing about locale or browse_tool (the one enum-constrained parameter), leaving two of three undocumented.

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

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

States a specific verb+resource (returns playlist segments) and enumerates what they contain: timing and media pointers. The closing clause, 'see the segment structure or how to play a workout', distinguishes it from metadata-oriented siblings like get_workout_details, though it never names that sibling explicitly.

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

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

'Use when the user wants to see the segment structure or how to play a workout' gives a real use-condition, but there is no explicit when-not and no named alternative among the close siblings (get_workout_details, get_team_workout). Usage is implied rather than fully routed.

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 carry the full safety profile (readOnly, non-destructive, closed-world), so the bar is lower. The description still adds real context by disclosing that the response is a static 'fixed ready message' rather than a deep dependency probe, which shapes how an agent should interpret the result.

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

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

Two short sentences, zero waste, with the capability stated first and the usage condition second. Nothing could be removed without losing information.

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

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

An output schema exists, so return-value detail need not be repeated, and annotations cover the safety profile. For a zero-parameter, no-side-effect health probe this description contains everything an agent needs to select and invoke it.

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

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

The tool takes zero parameters, which is the baseline-4 case. The description correctly implies no inputs are needed, matching the empty 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 ('Returns MCP server readiness status') and immediately clarifies the output shape ('with a fixed ready message'). No sibling tool overlaps, so an agent can unambiguously distinguish this ping-style tool from the workout/program 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?

Explicitly names the trigger conditions: user asks if the Hyperhuman app is 'working, reachable, or connected'. That is a clear when-to-use statement, though it gives no when-not guidance or alternatives (there effectively are none among siblings).

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds nothing behavioral beyond that — nothing about result size, ordering, or whether the equipment list is fixed reference data or team-configurable. A read-only lookup with annotations earns a low bar, but this barely clears it.

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

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

Two tight sentences with no padding and the core purpose front-loaded. The second sentence is vague rather than wasteful, so it doesn't cost much.

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

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

An output schema exists, so return values needn't be explained, but the definition leaves two undocumented optional parameters unexplained and never says what the equipment list represents or how it differs from sibling list tools. For a lookup tool with zero schema coverage, it should do more.

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

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

Schema description coverage is 0% for two parameters (locale, category_id), so the description is the only place that could explain them — and it doesn't mention either. "Filtering exercises" gestures at category scoping but never states what locale or category_id actually control or how they affect the returned equipment.

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 says it "Returns equipment for exercises," which names the resource but doesn't clarify the shape (a flat reference list of equipment types?) or scope (team vs. global). With siblings like list_muscle_groups and list_workout_categories doing the same job for other taxonomies, a one-clause nod to those distinctions would help.

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?

"Use when updating exercise metadata or filtering exercises" gives an implied context, but it never names the alternative tools (e.g. list_team_exercises, update_exercise_metadata) or states when NOT to call it. The agent must infer whether this list is global or team-scoped.

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

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

The annotations already establish that this is a safe read-only operation with no destructive or open-world behavior. The description aligns with that and adds usage context, but it does not add behavioral details beyond the annotations, such as localization behavior or result characteristics.

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 compact sentences with the purpose front-loaded and usage immediately following. There is no redundant or wasted 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?

The tool is simple, has an output schema, and has strong safety annotations, so the description does not need to explain return values or mutation risk. However, it omits the only parameter entirely and provides no sibling differentiation, leaving meaningful gaps for an agent invoking it.

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

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

The sole parameter, locale, is undocumented in both the schema and the description. With schema description coverage at 0%, the description should explain what locale controls and what format is expected, but it never mentions the 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?

The description states a specific verb and resource: it returns muscle groups for exercises. That is clear enough to distinguish it from most mutation siblings, but it does not explicitly differentiate itself from adjacent reference-list tools such as list_equipment or list_workout_categories.

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 concrete usage contexts: updating exercise metadata and filtering exercises. It does not state when not to use it or name alternative tools, so it falls short of full routing guidance, but the use cases are clear.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=false, so the safety profile is covered; the description goes further by disclosing that auth mode changes both the source (Internal API vs. curated guest set) and the result cap (8 vs. 6), and that guest results carry an embedDemoUrl. It also flags the Bearer-token-only constraint, which is real operational context not present in the annotations. Only error/fallback behavior when OAuth is present but the team has no workouts is left unstated.

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 primary outcome, then auth-mode behavior, then use cases, then exclusions — a good information hierarchy. Dense but every sentence carries routing or behavioral signal; the parenthetical about Bearer tokens is the only slightly awkward insertion.

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 needn't be explained, and the two-mode behavior is well covered. But with five optional filters at 0% schema coverage, an agent has no idea from this description what filtering is possible or whether the filters are ignored for guest samples — a meaningful gap for a list tool with that many knobs.

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

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

Schema description coverage is 0% and the description never mentions any of the five filters — locale, difficulty, category_id, duration_min, duration_max — nor whether they apply to guest samples at all. The only constraint documented anywhere (duration_min <= duration_max) lives in the schema's top-level description, not here. For a 0%-coverage schema, the description should be carrying this burden and does not.

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

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

States a specific verb and resource ('Returns a workout carousel for sample-workout prompts') and immediately splits the behavior into two concrete modes: OAuth-connected team workouts vs. unconnected guest samples. The final sentence names the sibling tools it is not, so an agent can distinguish it from list_team_workouts without opening either schema.

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

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

Explicit positive triggers ('when the user asks for sample workouts, a workout carousel, or embed demo preview') and explicit negative routing with the correct alternatives for each case: list_team_workouts for full team-library views, get_integration_plan for plans, get_embed_code_samples for copy-paste HTML. 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, destructiveHint=false, and a closed-world scope, so safety is covered. The description adds nothing beyond that: no mention of pagination behavior, default page size, or how the platform catalog is scoped (locale), which would be useful for a 10-parameter list endpoint.

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

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

Two short sentences with the resource identified first and the usage trigger second, so nothing is buried. Slightly weak because the 'clone' clause is misleading rather than additive.

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 (return values need no explanation) and annotations cover the safety profile, so the essential framing is present. For a listing tool with ten optional filtering/sorting/pagination parameters at 0% schema coverage, however, the description is too thin to tell an agent how to narrow results.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning, and it explains none of the ten parameters. It gives no hint that goal_ids, difficulties, duration_in_weeks, workouts_per_week, search_text, sorting, or pagination exist, leaving the agent to infer everything from bare parameter names.

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 (returns/lists) and resource (platform stock programs), and the parenthetical '(publisher programs)' disambiguates the term. It implicitly distinguishes from list_team_programs by qualifying 'platform stock', but never explicitly names the sibling.

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

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

The 'Use when the user wants to browse or clone stock programs' clause gives a trigger context, but the cloning reference is ambiguous because clone_stock_programs exists as a separate tool and this one does not perform the clone. No exclusions or explicit alternative routing are provided.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds useful context about the returned asset types and team scope, but does not disclose pagination, filtering, or sorting behavior beyond what the schema shows.

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 that front-load what the tool returns before giving usage guidance. There is no wasted text, and the structure is easy to scan.

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 six-parameter listing tool with no schema descriptions, the description is under-specified: it does not explain filtering, pagination, or sorting. Output schema and annotations reduce the burden, but important invocation details are still missing.

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

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

Schema description coverage is 0% across six parameters, and the description does not mention any of them. It gives no guidance on page, per_page, status, sort_by, sort_order, or team_id, leaving the agent to infer all parameter semantics from names and enums alone.

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

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

States a clear verb-resource pair: returns social drops (videos, covers, copy) scoped to the team. An agent can distinguish it from create_drop, update_drop, or export_drop by the listing action, though it does not explicitly name those siblings.

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

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

Gives a concrete usage context: use when the user asks about drops, social assets, or ready-to-download content. It does not specify when to avoid this tool or when to prefer alternatives such as export_drop for actual downloading.

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 safety and scope are covered. The description adds only that results come from the team library, and says nothing about pagination defaults, result limits, or how the 12 filters combine — modest added value over 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?

Two tight sentences with the core behavior front-loaded and no filler. Its brevity is the problem only in the sense of under-specification, not verbosity.

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 need not be described, but for a 12-parameter, zero-required filtering tool with 0% schema coverage the description is far too thin. An agent cannot tell which filters are combinable, what "availability" values mean, or how pagination behaves.

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

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

Schema description coverage is 0% across 12 parameters, so the description carries the full burden — and it documents none of them. Filters like search_text, categories, availability (an ambiguous enum), equipment_ids, collection_names, muscle_group_ids, coach, skill_level, locale, team_id, page and per_page are entirely unexplained.

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 ("Returns exercises from the team library"), which is clear enough to tell it apart from listing tools like list_stock_programs or list_team_workouts. It does not, however, distinguish itself from the singular sibling get_team_exercise.

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 three usage contexts (browse, find exercises for workouts, manage the library), which implies when to call it. It never names an alternative or a when-not condition, e.g. when to prefer get_team_exercise for a single item or search_text filtering over list_sample_workouts.

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, openWorldHint=false, so the safety profile is covered. The description adds the practical rationale (valid goal IDs for program creation), but says nothing about ordering, locale effects, pagination, or coverage. With an output schema present, the bar for return-format disclosure is lower, so a 3 is fair.

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

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

Two short sentences, zero waste, with the capability statement front-loaded and the usage trigger following. Nothing to trim.

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

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

Output schema exists and annotations are complete, so the description only needs to justify a simple read. It covers what the tool returns and why, but the undocumented `locale` parameter and the team-vs-global scope ambiguity are small remaining holes.

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 single parameter `locale` has 0% schema description coverage, and the description never mentions it – no allowed values, no default, no statement that it is optional. With low coverage the description is supposed to compensate, and it does not.

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

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

Specific verb+resource: returns fitness goals available for programs. It is clearly distinguishable from sibling list tools (list_equipment, list_muscle_groups, list_stock_programs). Minor friction: the name says 'team goals' while the description says 'fitness goals', leaving a small ambiguity about whether the list is team-scoped or global.

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 states when to use it: "Use when creating or generating programs to get valid goal IDs." That connects it to generate_program/create_program siblings without naming them directly. No when-not-to-use or exclusion guidance, which keeps it below a 5.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds the team-scoping constraint, but says nothing about pagination defaults, result-set size, or how an empty team is handled — mild added value only.

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

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

Two sentences, zero filler, with the core purpose front-loaded before the usage hint. Nothing could be cut without losing information.

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

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

An output schema exists so return values need not be described, but with seven undocumented parameters and a paginated list operation, the description leaves key calling details (page size limits, sort behavior, whether team_id overrides the authenticated team) unexplained. Inadequate for the schema's complexity.

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

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

Schema description coverage is 0% across seven parameters, so the description carries the full burden and provides nothing: page, per_page, sort_by, sort_order, search_text, locale and team_id are all left for the agent to guess. Notably it never explains whether team_id is required or how it interacts with 'authenticated user's team'.

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 ('Returns workout programs (collections)') and scopes it to the authenticated user's team, which implicitly separates it from list_stock_programs and list_sample_workouts. It does not explicitly name a sibling to contrast against, but the team scope is 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 second sentence gives trigger phrasings ('see programs, training plans, or workout collections'), which is useful intent matching. However, it never says when NOT to use it or points to alternatives like get_team_program for a single program, so the agent must infer the boundary itself.

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), and the description adds real context beyond them: 'Requires OAuth' and the implicit scope of the caller's own team. It does not mention pagination defaults or result-size behavior, which is a minor gap given the per_page maximum of 100.

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 tight sentences, each doing distinct work: purpose, trigger phrasing, auth requirement, exclusion. The purpose and the exclusion bracket the text, so the most decision-relevant information is front-loaded and restated at the end.

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

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

With an output schema present, return values need no explanation, and the read-only annotations cover the safety profile. However, for a 7-parameter filtered-list tool with zero schema coverage, the description leaves all filtering and pagination behavior undocumented, which is a meaningful completeness gap for practical invocation.

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

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

Schema description coverage is 0% for 7 parameters, so the description carries the full burden and provides nothing: team_id, page, per_page, sort_by, sort_order, locale, and search_text are never mentioned or given semantics. An agent must guess, for example, whether team_id overrides the authenticated user's default team or whether search_text is server-side filtering.

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 ('Returns workouts for the authenticated user's team') and scopes it to the caller's team via Internal API. It explicitly names the sibling it is not (list_sample_workouts), so an agent can separate it from the many other list_/get_team_ tools 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 concrete trigger phrasing ('my team's workouts, my team workouts, or their organization workout library') plus an explicit exclusion with the correct alternative tool ('Not for curated sample workouts or guest embed demo (use list_sample_workouts)'). Nothing is left to inference about when to pick this over a sibling.

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 that the result is meant to supply valid category_ids for workout creation/updating, but it does not describe locale behavior or any other operational nuance beyond 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?

Two short sentences, front-loaded with the purpose and immediately followed by the actionable usage context. There is no filler or repetition.

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

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

For a low-complexity lookup with an output schema and read-only annotations, the description is nearly complete: it explains what is returned and why an agent would call it. The main remaining gap is the optional locale parameter, which is undocumented in both schema and description.

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

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

There is one optional parameter, locale, with 0% schema description coverage, and the description never mentions locale or whether category labels are localized. The description therefore does not compensate for the schema gap.

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 verb and resource: it returns workout categories for workouts. The resource is distinct from siblings like list_equipment or list_muscle_groups, but the description does not explicitly differentiate against those alternatives.

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

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

It gives a concrete usage condition: use when creating or updating workouts to get valid category_ids. It does not state when not to use it or name alternative category sources, so it falls short of full routing guidance.

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

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

Annotations already cover the safety profile (readOnly, non-destructive, closed-world), so the description's real contribution is the non-obvious capping behavior: max 12 items returned even though limit can go to 20 at the API. That is exactly the kind of quirk an agent would otherwise get wrong. It does not explain ranking criteria or whether results are personalized.

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

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

Two sentences, front-loaded with what is returned and its cap, then the usage cue. The parenthetical earns its place because it documents the 12-vs-20 discrepancy. Slightly dense but no wasted 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?

An output schema exists, so return values need no explanation, but for a 7-parameter personalization tool with zero schema coverage the description is thin. It never says how age/gender/goals/fitness levels shape the ranking, nor what team_id scopes, which is essential to invoking 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 0% across 7 parameters, so the description must carry the burden — but it only addresses limit. The six personalization/scope parameters (team_id, locale, end_user_age, end_user_gender, end_user_goal_ids, end_user_fitness_levels) are never mentioned, leaving the agent to guess whether recommendations are personalized or org-wide.

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 — 'ranked program recommendations from the organization library' — which is far more informative than the tautological title. An agent can distinguish it from list_team_programs or generate_program by the 'ranked/recommendation' framing, though the description never explicitly names those alternatives.

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

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

'Use when the user wants instant program suggestions' gives a clear trigger condition, and 'instant' implicitly contrasts with generate_program. However, there is no when-not guidance, no mention of the parallel recommend_workouts sibling, and no stated prerequisites (e.g., whether team_id is needed for library scoping).

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

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

Annotations already cover the read-only, non-destructive, closed-world safety profile, so the bar is lower. The description earns credit for disclosing a genuinely non-obvious quirk: the response is truncated to 12 workouts even though a limit up to 20 is forwarded to the API — that would otherwise cause silent miscounts.

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

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

Two sentences, zero filler, with the result-shape constraint front-loaded ahead of the routing advice. Every clause carries distinct information.

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

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

The output schema exists, so return values need not be described, and the limit-capping behavior is well covered. But for a 7-parameter tool with zero schema descriptions, leaving six parameters entirely unexplained — including how goal IDs and fitness levels actually influence ranking — is a real gap.

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

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

Schema description coverage is 0% across 7 parameters, so the description must carry the load, and it only explains 'limit' (both its API ceiling of 20 and the 12-item response cap). The six profile and scoping parameters — locale, team_id, end_user_age, end_user_gender, end_user_goal_ids, end_user_fitness_levels — are never mentioned; 'based on profile' is the only, very indirect, hint that they drive ranking.

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 — 'ranked workout recommendations from the organization library' — and frames the output as profile-based suggestions rather than generated content. It differentiates from the generate_* siblings via 'faster than generate', but never mentions the very close sibling recommend_plans, so the agent must infer which recommendation surface to pick.

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

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

Explicitly gives the trigger condition ('user wants instant suggestions based on profile') and names the alternative (generate) with the trade-off that selects it (speed). Missing any when-not guidance and silent on recommend_plans, which is the closest alternative in the sibling list.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, but the description never explains what is destroyed — i.e., that existing stored copy is replaced/overwritten, and whether the prior version is recoverable. It also says nothing about cost/rate limits (relevant given sibling get_api_usage_stats) or whether team_id scoping changes behavior. For a destructive mutation this is a real gap.

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

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

Two sentences, zero filler, with the action and the trigger condition front-loaded. It is appropriately sized for the amount of content it chooses to convey, though it is under-specified rather than overwritten.

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 need not be explained, but for a destructive 3-parameter mutation with 0% schema coverage the description is missing overwrite semantics, parameter meaning, and scoping behavior. An agent could call it correctly on the happy path but has no basis for judging side effects.

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

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

Schema description coverage is 0% across 3 parameters, so the description is the only place meaning could be added — and it isn't. Only 'for a drop' loosely implies drop_id; team_id and channel_preset (which presumably shapes tone/channel of the generated copy) are entirely unexplained, making channel_preset especially opaque.

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

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

The description uses a specific verb + resource ('Regenerates AI copy pack') and enumerates the artifacts produced (hook, caption, hashtags, CTA). It does not distinguish itself from the sibling 'regenerate_drop_cover', which is a similar regenerate-a-drop-artifact tool, so it falls short of a 5.

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

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

'Use when the user wants to refresh or improve the social copy' gives an implied trigger condition, but no when-not-to-use guidance and no routing versus update_drop or regenerate_drop_cover. The agent must infer the boundaries from sibling names alone.

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

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

The annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is partly covered. However, the description adds no behavioral detail beyond the annotations: it does not say whether the existing cover is replaced, whether generation is asynchronous, or whether there are cost or rate-limit 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?

Two short sentences, front-loaded with the core action and followed by the usage condition. There is no wasted wording.

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?

This is a destructive five-parameter generation tool with no schema parameter descriptions, yet the description provides no parameter guidance. The output schema and annotations cover return values and safety flags, but the description is still too thin for the tool's complexity.

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

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

Schema description coverage is 0% and the description explains none of the five parameters. It mentions only that the operation is for a drop, which does not clarify team_id, duration, aspect_ratio, or channel_preset.

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: regenerates an AI cover image for a drop. This naturally separates it from regenerate_drop_copy, but it does not explicitly name siblings or clarify boundaries beyond the object being different.

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: use when the user wants a new cover for the social asset. It does not state when not to use it or name alternatives, but the intended trigger is easy to infer.

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=false, openWorldHint=false and destructiveHint=true, so the write/overwrite profile is carried by structured data. The description's contribution is narrowing the mutated surface to title and channel preset, which is genuinely useful, but it never explains what an overwrite means (does an omitted field reset? does changing the preset affect already-exported drops?). With annotations covering the safety bar, 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?

Three short sentences, no filler, and the field scope is front-loaded ahead of the routing hint. 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?

The presence of an output schema removes the need to describe return values, and annotations cover the safety profile. However, for a four-parameter mutation with 0% schema coverage, the description leaves the required drop_id and team_id semantics plus the accepted channel_preset values unexplained, which is a real gap for correct invocation.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning, and it only names two of the four parameters (title and channel_preset). The required drop_id and the team_id scoping parameter are entirely undocumented in both schema and description, leaving an agent to guess whether team_id is needed for visibility and what channel_preset values are legal.

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?

"Updates a drop title or channel preset" gives a specific verb plus the exact resource and enumerates the mutable fields, so the agent knows precisely what is touched. It distinguishes itself from regenerate_drop_copy, though it does not differentiate from other drop siblings such as export_drop or regenerate_drop_cover.

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?

"Use when the user wants to change drop display title or default export channel" states the triggering intent, and the follow-up sentence names an explicit alternative for a nearby case (regenerate_drop_copy). It stops short of covering the other adjacent choose-points (cover images, exporting), so it is clear but not exhaustive.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is known; the description adds nothing beyond it. For a destructive mutation it never says whether exercise_ids replaces or appends to the existing list, whether omitted fields are preserved, or what permissions are required — the exact behavior an agent most needs here.

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

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

Two short sentences, verb and scope first, trigger condition second. No filler or repetition of the schema.

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

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

An output schema exists so return values need no explanation, but for a destructive 7-parameter mutation with 0% schema coverage the description is too thin. Replacement vs. merge semantics and the required group_id handling are left entirely to inference.

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

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

Schema description coverage is 0%, so the description must compensate and it only covers four of seven fields (name, exercises, rounds, rest time). It omits the required group_id, team_id, and the group_type enum, and critically never clarifies whether exercise_ids is a full replacement or a delta.

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 ('Updates an exercise group') and enumerates the mutable fields, so the agent can distinguish it from create_exercise_group. It does not explicitly name or exclude a sibling, which keeps it short of a 5.

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

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

'Use when the user wants to change name, exercises, rounds, or rest time' gives a concrete trigger condition. It offers no exclusions or alternatives (e.g., when to use create_exercise_group instead, or what to do for group_type changes), so it stops at clear-context-no-exclusions.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false; the description adds real value beyond them by disclosing the ownership constraint (team-owned only, stock read-only) and the minimum-payload rule. It does not say whether omitted fields are left untouched or cleared, which matters given destructiveHint=true on a metadata patch.

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, no filler: purpose and field list first, trigger second, hard constraints last. Every sentence carries distinct information an agent needs.

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

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

With an output schema present, return values need not be described, and the description covers ownership, minimum payload, and field scope. The remaining gap is the undocumented team_id parameter and the merge-vs-replace behavior on a destructiveHint mutation.

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

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

Schema description coverage is 0%, so the description must carry the load; it explains five of seven fields in plain language (name, muscle groups, categories, equipment, skill level) but says nothing about team_id, and gives no guidance on the ID-array fields beyond their names or on whether partial updates replace or merge. Helpful but incomplete compensation.

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

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

States a specific verb (updates) and resource (exercise metadata) and enumerates the mutable fields (name, muscle groups, categories, equipment, skill level), which an agent can map to the exercise domain immediately. It does not explicitly distinguish itself from near siblings like update_exercise_group or update_workout, so it falls short of a 5.

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

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

Gives a concrete trigger ('user wants to fix or improve exercise tagging'), an explicit exclusion ('stock exercises are read-only'), and a precondition ('provide at least one field to update besides exercise_id'). It stops short of naming the alternative tool to use when the exercise is stock (e.g., cloning a stock exercise into a team one).

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 flag destructiveHint=true, but the description adds the non-obvious and critical trait: the caller must supply full program data and merge edits, implying omitted fields are dropped/overwritten. That is real behavioral value beyond structured fields. It omits permission requirements and recovery options, so not a 5.

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

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

Three short sentences: purpose, trigger, then the full-payload requirement. Front-loaded and every sentence earns its place. The final sentence is dense enough that it could be split for readability.

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

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

An output schema exists, so return values need no explanation, and annotations cover the safety profile. What remains for a 10-parameter destructive mutation — the read-then-merge workflow — is exactly what the description supplies.

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

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

Schema description coverage is 0%, so the description carries the burden. It names six of the ten fields (duration_in_weeks, workouts_per_week, goal_ids, workout_ids, visibility, difficulty) but says nothing about name, team_id, description, or program_id, and omits constraints like the two-goal cap and the two-workout minimum. Partial compensation only.

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 ('Updates an existing program') and enumerates the mutable facets (duration, workouts per week, metadata), which clearly separates it from create_program and update_workout. It does not explicitly name a sibling as the alternative, so it stops short of a 5.

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

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

'Use when the user wants to set duration, workouts per week, or edit program metadata' gives a concrete trigger condition, and the description names the prerequisite read tool (get_team_program) needed before calling. No when-not guidance or explicit alternative tool is offered, so 4 rather than 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 destructiveHint=true and openWorldHint=false, so the safety profile is covered. The description adds genuinely non-obvious behavior beyond that: partial payloads trigger a fetch-and-merge against current workout data. It omits the flip side — that supplying instances or category_ids appears to replace those collections wholesale — which matters given the destructive hint.

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

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

Two sentences, front-loaded with the action, then the usage trigger and the merge caveat. No filler. Slightly compact for an 8-parameter mutation, but nothing is wasted.

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

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

An output schema exists, so return values need no explanation, and the merge behavior is a useful addition. Still, for an 8-param destructive mutation with zero schema descriptions, the definition leaves key fields (workout_id, team_id, category_ids) and the replace-vs-merge semantics of arrays unexplained.

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

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

Schema description coverage is 0%, so the description must carry all parameter meaning, and it only partially does. It names name, description, difficulty, visibility and "exercise structure" (instances), but never explains the required workout_id, team_id, or category_ids, nor whether array fields replace or merge.

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 ("Updates an existing workout") and enumerates the mutable surface: name, description, difficulty, visibility, exercise structure. That is enough to distinguish it from update_program, update_drop, and update_exercise_group by resource, though it never names a sibling explicitly.

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

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

"Use when the user wants to change ..." gives a concrete trigger condition tied to user intent. It does not cover when-not cases or route to alternatives such as adapt_workout for adaptive changes or create_workout for new workouts, so it stops short of full routing guidance.

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