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

Annotations declare non-idempotent (idempotentHint=false, destructiveHint=false, openWorldHint=true), and the description adds meaningful context beyond them: the created routine starts disabled, a magic confirmation value is required, and retries may duplicate records. The duplication warning reinforces the non-idempotent hint with actionable consequences. It stops short of describing permissions or the returned object.

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

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

Three compact sentences, front-loaded with the core action, then the two most consequential caveats (disabled state, confirmation requirement) and the retry risk. No filler.

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

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

An output schema exists, so return values need no explanation, and the description covers the non-obvious operational facts an agent needs before calling. The only omission is the structure/requirements of the 'routine' argument, which the schema does convey structurally even without field descriptions.

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

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

With 0% schema description coverage, the description must carry parameter meaning, and it only explains one of the two parameters: confirmation must equal 'CONFIRM'. The large nested 'routine' payload (RoutineInput with title, exercises, sets, etc.) is left entirely to the schema, so compensation is partial at best.

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

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

The description opens with a specific verb+resource ('Create a routine'), which is unambiguous against siblings like list_routines, get_routine, and update_routine. It does not explicitly name an alternative, but the create verb is distinct enough that no sibling confusion arises.

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 states two hard usage conditions — the routine is disabled by default and confirmation='CONFIRM' is mandatory — which is real usage guidance. However, it never says when to use this versus update_routine (e.g., for an existing routine) or create_workout, so alternative selection 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 the safety profile (not read-only, open-world, non-idempotent, non-destructive), and the description adds genuinely new behavioral context: the tool is disabled by default and needs an exact confirmation token. It does not describe auth requirements or the response, but the gating disclosure is valuable 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 sentences, front-loaded with the core purpose and immediately followed by the critical gating constraint. No wasted words.

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

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

For a mutation tool with a rich nested input and existing annotations/output schema, the description covers the key operational hurdle (the confirmation gate). It omits success behavior and any distinction from create_routine, but the essential calling information is present.

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

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

With 0% schema description coverage, the description must carry param meaning. It supplies the exact expected value for the 'confirmation' parameter, which the schema leaves as a bare string, but it adds nothing for the 'workout' parameter beyond the verb. Partial compensation for the coverage 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?

States a specific verb (create) and resource (a completed workout), so the agent knows exactly what the tool does. It does not explicitly differentiate from the sibling create_routine, which is the nearest alternative, 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?

The description gives a gating prerequisite ('disabled by default, requires confirmation=CONFIRM') but never states when to choose this over create_routine or when the workout record should be created versus a routine. Usage is implied rather than articulated.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds the useful constraint that dates must be YYYY-MM-DD, but says nothing about result volume, pagination, or whether the range filter is inclusive.

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 format constraint; nothing is wasted. It is efficient, though the extreme brevity leaves gaps that a slightly longer description could have closed.

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. For a read-only history lookup with three parameters and no schema documentation, the description is minimally adequate but omits the meaning of the date range and any expectation about result size or ordering.

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

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

With 0% schema coverage, the description does carry part of the burden by specifying the required date format for start_date/end_date, which the bare 'string' schema does not convey. However, it never explains what the dates actually filter (performed sets within range) or whether they are inclusive, and exercise_template_id is only implied by context.

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

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

The description states a specific verb and resource (get performed-set history) scoped to one exercise template, which clearly separates it from siblings like list_workouts or search_exercise_templates. It does not explicitly name an alternative tool, 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?

There is no statement of when to use this versus list_workouts, get_workout, or search_exercise_templates, nor any prerequisite or exclusion. Usage is only weakly implied by 'for one exercise template'.

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

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

Annotations already provide readOnlyHint=true and openWorldHint=true, covering the safety profile. The description only adds that lookup requires an exact ID and omits auth, error, rate-limit, or return behavior, though an output schema 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?

A single front-loaded sentence with no wasted words. The size is appropriate for a simple lookup tool.

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

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

With an output schema present and annotations covering read-only/open-world behavior, the description supplies the essential invocation context: get one routine by exact ID. It could mention invalid-ID behavior or where to obtain the ID, but those are minor for this simple 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% for the single required parameter routine_id. The description partially compensates by identifying it as an exact Hevy routine ID, but gives no format, example, or source information, so meaning is added only in part.

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

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

States a specific verb ('Get'), resource ('routine'), and scope ('one') with the lookup key ('exact Hevy routine ID'). This distinguishes it from siblings like list_routines (plural) and create_routine/update_routine.

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

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

The phrase 'by exact Hevy routine ID' implies the tool is for when an exact ID is already known, but it does not name alternatives or state when not to use it. Usage is left to inference from the phrasing.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds only the 'exact ID' nuance and says nothing about behavior when the ID is unknown or about the scope of data returned, leaving little beyond the 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?

One sentence, front-loaded with the action and scope, and every word earns its place with no filler.

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

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

An output schema exists, so return values need not be explained, and the readOnly annotation covers safety. For a simple by-ID lookup this is minimally adequate, but it omits where IDs originate and what happens on a miss.

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 for the single parameter. It does tell the agent the value must be an exact Hevy workout ID, which is meaningful, but gives no format example or hint about retrieving a valid ID.

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

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

States a specific verb (Get), resource (one workout), and identity key (Hevy workout ID), which cleanly separates it from the list_workouts sibling. It does not explicitly name that sibling, but 'one' versus a list is an implicit contrast an agent can act on.

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

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

No guidance on when to call this versus list_workouts or get_exercise_history, and no statement of where the workout ID comes from. The only usable cue is the word 'exact', which implies no fuzzy or name-based lookup.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds nothing about pagination behavior or result shape; the pagination params (page, page_size) exist in the schema but the description doesn't disclose default or limit behavior.

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

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

Two short sentences, front-loaded with the primary action. No filler.

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

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

For a list operation with pagination and eight siblings, the description omits when to use it, how results are paginated, and how it differs from get_routine. An output schema exists, so return values need not be explained, but the guidance gaps remain significant.

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 two pagination parameters are only documented by their names and defaults. The description mentions neither parameter, so it neither compensates nor adds value beyond the schema.

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

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

States the verb and resource ('List routines'), which is clear enough, but it does not differentiate from get_routine, list_workouts, or other siblings beyond the noun. No scope qualifiers (all routines? user's routines?) are given.

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 ('Use get_routine before proposing an update') gives a usage hint, but it describes a workflow for update_routine rather than when to use list_routines versus get_routine or list_workouts. Implied usage only.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds pagination behavior ('capped by server policy and Hevy'), which is genuinely useful context, but omits the actual cap value, ordering, and any rate-limit behavior.

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

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

Two sentences, zero padding, and the core purpose is front-loaded ahead of the constraint detail. Every sentence earns its place.

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

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

An output schema exists, so return values need not be explained, and annotations cover the read-only safety profile. Combined with the pagination constraints, the definition is nearly complete for a simple paged list tool; only the listing scope/ordering is unstated.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning; it does add the constraint 'page must be >=1' and warns that page_size is capped. That is meaningful, but the cap value is left vague and the defaults (page=1, page_size=5) are only in the schema.

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

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

States a clear verb+resource ('List workouts'), which cleanly separates it from the singular get_workout and from list_routines on a different resource. However, it gives no scope detail (all workouts? filtered?) and never explicitly contrasts itself with the sibling get_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?

There is no when-to-use or when-not-to-use guidance. With siblings like get_workout and get_exercise_history available, the description never tells the agent when a bulk list is preferable to fetching a single workout or history.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is known. The description adds that it's scoped to the account and searches by title, but doesn't describe pagination behavior or return semantics beyond what the annotations and output schema cover.

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 search purpose is front-loaded followed by the call-order constraint.

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

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

Output schema exists, so return values need not be explained. Combined with annotations covering safety, the description is nearly sufficient, though pagination details for page/page_size are absent. For a simple search tool this is largely 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% for the three parameters (query, page, page_size). The description only implies title-based search, partially clarifying 'query' semantics but leaving page/page_size undocumented. Baseline 3 is appropriate given schema richness is minimal and description only aids one parameter.

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

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

States a specific verb+resource (search exercise templates) with scope (account, by title). Distinguishes from siblings like create_routine/update_routine since it's a read-only search, but doesn't explicitly name the alternate tools for looking up templates.

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

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

Explicitly provides when-to-use guidance: 'Call this before any routine/workout mutation.' This gives the trigger context. However, it doesn't name specific sibling alternatives (e.g., get_routine) or explain when-not to use it.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the agent knows this is a destructive write. The description adds valuable context beyond annotations: the 'fetch it first' workflow requirement and the disabled-by-default safety mechanism. It doesn't explain why fetching is needed or what happens to existing data, but it exceeds the annotation baseline.

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

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

Extremely concise—three short clauses packed with essential information. The critical safety constraint (CONFIRM) is front-loaded in the final position, and the fetch-before-replace workflow is stated first. No wasted words.

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

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

For a destructive tool with an output schema (so return values needn't be explained), the description covers the most critical unknowns: the confirmation string and the fetch-first requirement. However, it doesn't explain what 'disabled by default' means operationally or whether the replacement preserves any data. Adequate but not fully 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?

With 0% schema description coverage, the description must compensate. It clarifies the 'confirmation' parameter requires the literal value 'CONFIRM', which is critical since neither schema nor annotations specify this. It doesn't explain routine_id or routine parameters, but the confirmation detail is highly valuable for correct invocation.

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 specific verb 'Replace' and resource 'routine', distinguishing it from create_routine via the 'existing' qualifier. Clear what it does, though it doesn't explicitly name the sibling tool to use for fetching first (get_routine exists in 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 clear operational guidance: 'Fetch it first' tells the agent a prerequisite step, and 'disabled by default' hints at a usage constraint. However, it doesn't explain when to replace vs. create a new routine, and doesn't name the specific fetch tool available.

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