WorkoutX Exercise API

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the description only needs to add context: it does so with the cost signal ("one request") and the returned fields (plan, remaining quota). It omits the failure path entirely — what is returned or raised when the key is invalid, which is the primary reason to call a validation 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 outcome and finished with the cost. 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 no output schema, the description carries the return-value burden and does name the returned content. The gap is the error/invalid-key behavior, which matters for a credential check.

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

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

The tool takes zero parameters, so the baseline is 4; the description correctly implies no input is 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?

Specific verb+resource ("confirm the configured API key works") plus the returned payload (plan and remaining quota). It's not explicitly distinguished from the closest sibling, get_usage_stats, which an agent could plausibly reach for instead.

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?

"Uses one request" implicitly signals this is a cheap call, which helps an agent decide to run it freely, but there is no explicit when-to-use/when-not or named alternative such as get_usage_stats.

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=false; the description reinforces this with 'Only reads the text; never sends the request', which is the key behavioral guarantee an agent needs before pasting a request containing credentials. It also discloses a cost trait ('Uses one request'), implying quota consumption, which is not in the annotations. It stops short of describing output shape or limits on ambiguous input.

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 tight sentences, front-loaded with the action and input form, then the diagnostic coverage, then the safety and cost notes. The parenthetical failure list is long but each item adds discriminating information about what the tool can catch.

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

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

For a 3-parameter read-only tool with no output schema, the description covers input forms, diagnostic scope, safety, and cost. It implicitly describes the return value ('explains what is wrong ... and how to fix it'). Minor gaps remain around auth requirements and behavior on malformed input, but nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 67%, and the description compensates by clarifying all three inputs: the request can be a curl command, a URL, or a 'GET /v2/...' line, and status/response are optional add-ons. The schema descriptions for request and response are extended with accepted formats rather than merely repeated.

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 (diagnose) and resource (a failing WorkoutX request), and enumerates the exact failure classes it detects (wrong host, key in URL, missing header, v1 id, plan gate, rate limit, quota). This is clearly distinguishable from siblings like get_endpoint_reference or check_api_key, which do not diagnose a concrete failing call.

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 trigger is explicit: paste a failing request, optionally with status and response body. It tells the agent what input forms are accepted (curl, URL, "GET /v2/..."). It does not explicitly name when to prefer a sibling such as get_endpoint_reference or check_api_key instead, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds the calculation basis (MET value × weight × duration), which tells the agent the result is a deterministic estimate derived from the exercise record, but it does not say what happens with an unknown id or whether MET data can be missing.

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 tight sentence with zero filler, and the key qualifier (from MET value, weight, duration) is front-loaded. It reads as an incomplete fragment, 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 simple read-only calculator with three fully documented parameters and no output schema, the description is adequate but thin. It does not state the output unit (kcal) or note that an invalid or missing exercise id will fail, which an agent would need before calling it in a loop.

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

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

Schema coverage is 100% — every parameter documents its type, units, and defaults — so the schema does the heavy lifting. The description adds only the implicit mapping that the id supplies the MET value; it gives no further detail on defaults or units beyond the schema.

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

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

The description names a specific resource (calories burned) and the exact inputs of the computation (MET value, body weight, duration), which clearly distinguishes it from the search/get/generate siblings in the toolset. It is a fragment rather than an explicit verb+object statement, but the intent 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?

There is no guidance on when to call this versus alternatives such as get_exercise (which presumably returns MET data itself) or generate_workout. No exclusions, no prerequisites, no mention that the exercise id must exist in the catalog.

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

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

Goes well beyond the readOnly/openWorld annotations by disclosing pagination via offset, per-call plan caps with concrete numbers (Free 10, Starter 100, others 200), and the exemption from the distinct-exercise media limit — quota behavior an agent otherwise could not anticipate. It stops short of describing the response envelope or what happens when offset exceeds the result set.

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 tight sentences, front-loaded with the payload and purpose, then the quota exemption, then paging and limits. No filler and 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?

With 10 parameters, no output schema, and only 50% schema coverage, the description supplies the essential export semantics, quota behavior, and paging model an agent needs to call it correctly. Remaining gaps are the undocumented filter and language parameters, which are minor but real for a tool with this many options.

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 only 50%, yet the description only clarifies offset (paging) and format (JSON/CSV), plus loosely maps fields to the exported columns. It says nothing about the filter parameters target, bodyPart, equipment, or the lang parameter, so it does not fully compensate for the schema's gaps.

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 concrete verb and resource plus scope: exports exercise ids/names/muscles/equipment without media, as JSON or CSV, for seeding databases or fixtures. It also explicitly separates itself from media-oriented siblings by noting it does not consume the distinct-exercise media limit.

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 seeding/fixtures use case gives clear context for when to reach for this tool rather than get_exercise or search_exercises, and the mention of the media limit reinforces that. It does not name an alternative outright or state a when-not condition, so routing is still partly inferred.

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=false, so the safety profile is covered. The description adds that results are ranked by shared muscle involvement, which is real behavioral value, but it says nothing about what happens when no alternatives exist, whether results are capped by the plan (the schema hints at plan caps), or the shape of the returned list.

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 front-loaded sentences with zero filler — the core purpose first, then the optional filtering capability.

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

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

For a read-only lookup with 6 mostly-documented parameters and no output schema, the description plus schema covers what an agent needs to invoke it. The remaining gaps (return shape, empty-result behavior) are minor for this tool class.

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 83%, so nearly every parameter is already documented in the schema, including comma-separated syntax for both equipment filters. The description only restates that equipment can be required or excluded; it adds nothing on id, lang, limit, or the undocumented model 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 resource (exercise alternatives / 'swaps') and a meaningful criterion ('train the same muscles'), which is more precise than generic similarity. It never names the near-duplicate sibling find_similar_exercises, so an agent must guess which of the two 'related exercise' tools 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?

'e.g. when equipment is missing' gives a concrete triggering scenario, and 'Optionally require or exclude equipment' tells the agent how the filters are meant to be used. There is no when-not guidance and no explicit routing away from find_similar_exercises or search_exercises.

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 that this is a safe read-only, non-open-world operation. The description adds meaningful behavioral context by disclosing the similarity dimensions (pattern, muscles, equipment) and that results are ranked by score, though it does not discuss limits, plan caps, or output shape.

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 tight sentence with no filler. The core purpose and ranking behavior are front-loaded, and every clause contributes useful 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 description is adequate for a simple read-only lookup, but with no output schema and a very similar sibling tool, it leaves the agent without enough guidance on result shape or when to prefer this over find_exercise_alternatives.

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 75%, so most parameters are documented in the schema. The description only refers to the given exercise and does not clarify the roles of lang, limit, or model beyond what is already in the structured fields, so baseline 3 is appropriate.

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

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

States a specific resource and operation: exercises most similar to a given exercise, with matching criteria and ranking. It is clear what the tool returns, but it does not explicitly distinguish itself from the sibling find_exercise_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?

The usage context is implied by the similarity criteria, but there is no explicit guidance on when to use this versus find_exercise_alternatives or search_exercises. An agent must infer the choice from sibling names.

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=false, so safety is covered. The description adds real value beyond them by disclosing the plan entitlement requirement and the program structure (periodisation, deloads, volume targets), but says nothing about determinism despite a seed parameter, output size, or generation latency. With annotations carrying the safety profile, a 3 is appropriate.

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

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

Two tight sentences with the output characteristics front-loaded and the prerequisite second. Nothing is wasted; it is simply thin rather than bloated.

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 11-parameter generation tool with no output schema needs the description to explain how inputs shape the program and what comes back. Instead the description covers only the artifact's shape and a billing prerequisite, leaving an agent unable to infer much about the output structure or the role of most 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 coverage is only 55% across 11 parameters, so the description is expected to compensate, and it does not. It never mentions goal, level, weeks, daysPerWeek, equipment, avoidJoints, format or the seed parameter, leaving the most consequential inputs undocumented in 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?

The description names the produced artifact concretely (a multi-week program with periodisation, deloads and weekly volume targets), which implicitly separates it from the single-session sibling generate_workout. It stops short of an explicit verb or an explicit contrast with that sibling, so it is clear but not maximally differentiating.

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 only usage guidance is an entitlement prerequisite ('Needs the Scale plan'), which is useful but is a gating fact rather than a when-to-use rule. Nothing says when to pick this over generate_workout, or what happens if the plan requirement is unmet.

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=false, so safety is covered; the description adds that output is derived from the OpenAPI spec and costs one request. It does not say how the generated code is returned (single blob vs per-model strings), which matters since there is no output schema.

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 deliverable front-loaded and the cost note second. Nothing is padded, though 'Uses one request' is slightly clipped for an agent unfamiliar with quota semantics.

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

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

For a two-parameter generator with no output schema, the description conveys the languages, the source (OpenAPI spec), and the 'ready-to-paste' output nature. The main gap is the shape of the returned code payload, but the essentials for a correct call are 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?

Schema coverage is 50%: the `models` parameter is well documented in-schema (defaults and alternatives), while `language` relies on its enum. The description merely restates the four enum values and adds no new semantics such as default model set behavior or the 20-item cap.

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 TypeScript/Swift/Kotlin/Dart model types from the OpenAPI spec, scoped to v2 responses. The closest sibling, get_code_example, is not named or contrasted, so differentiation is left to inference.

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?

'For v2 responses' implies a context of use, and 'Uses one request' hints at cost. But there is no explicit when-to-use/when-not or mention of get_code_example as the alternative for example snippets rather than model types.

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=false, so the safety profile is covered. The description adds two genuinely useful facts beyond that: the output composition and the 'Growth plan or higher' entitlement requirement. It does not address determinism, defaults handling, or selection behavior when constraints conflict, which matters for a 12-parameter generator.

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 output content front-loaded and the plan requirement trailing as a constraint. No filler, though the entitlement sentence could carry more weight if paired with usage guidance.

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 12 optional parameters, no output schema, and only sparse descriptions, the definition is under-specified for correct invocation. The description covers what comes back and the plan gate but leaves parameter interaction, defaults beyond those in the schema, and alternative-tool routing 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 67% and the description supplies no parameter-level meaning at all: nothing about how goal, split, format, duration, equipment, bodyFocus or avoidJoints interact, nor how conflicts (e.g., avoidJoints vs bodyFocus) are resolved. 'Built from movement patterns' is the only hint and it does not map to any 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 what is produced (a complete single session: warm-up, main work with sets/reps/rest, cool-down, plus swap suggestions) and the underlying approach (movement patterns). It implicitly distinguishes itself from generate_program via 'one complete session', but never names that sibling or states the verb 'generate' 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?

There is no guidance on when to call this versus generate_program or search_exercises, and no stated prerequisites beyond a plan tier. The agent must infer that this builds one session while generate_program builds a multi-week 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 readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds a genuine behavioral signal beyond that: "Uses one request," which tells the agent the call cost is a single API round-trip — useful for budgeting. It stops short of stating auth requirements or whether snippets are compilable/complete.

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 deliverable, with the enum expansion packed into a single clause. The middle list is long but each item adds meaning to a topic value, so it earns its space; the fragment-style opening sentence is slightly rough but not wasteful.

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 no output schema, the description still communicates what comes back — a working snippet in the requested platform's language for the requested task — and that the call is a single request. It leaves open details like snippet length, snippet completeness, or error behavior, but nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 0%, so the description carries the burden — and it does, translating opaque enum values into meaning: play-video is "playing the looping MP4 and refreshing its signed link," handle-errors is "error and rate-limit handling," backend-proxy is "keeps your key off the device." That is real semantic value beyond the raw enum tokens, though the platform enum is left entirely to the schema.

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

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

The description names the deliverable ("a working snippet") and scopes it by platform and task, which is a specific verb+resource pairing an agent can distinguish from reference-oriented siblings like get_endpoint_reference. It does not explicitly contrast itself with siblings such as diagnose_request or generate_types, so it falls short of full differentiation.

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?

Usage is only implied through the enumeration of tasks ("listing and paging exercises, playing the looping MP4...") which mirrors the topic enum. There is no explicit when-to-use versus when-to-use-an-alternative guidance, nor prerequisites such as needing an API key first.

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=false, so the safety profile is covered. The description still adds real value by noting the source of truth ('straight from the OpenAPI spec') and the cost profile ('Uses one request'), which tells the agent this is a cheap, non-destructive lookup.

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, zero filler: what it returns, the no-argument mode, and the cost. The payload enumeration is front-loaded and each sentence earns its place.

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

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

With no output schema, the description carries the burden of describing return contents and does so explicitly (parameters, response shape, errors, curl example). For a single optional-parameter read tool with strong annotations, this is nearly complete, missing only any note on response size or formatting.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds genuine semantics by stating that omitting the endpoint lists all endpoints, which the schema alone conveys only implicitly via zero required fields. It also adds 'any v2 endpoint', clarifying the accepted scope beyond the schema's example formats.

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

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

The description names a concrete resource (v2 endpoints) and enumerates exactly what comes back: parameters, response shape, errors, and a curl example, sourced from the OpenAPI spec. An agent can tell this is a spec-lookup tool, though the 'curl example' payload slightly overlaps with the sibling get_code_example without an explicit disambiguation.

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?

'Call with no endpoint to list them all' is a concrete usage instruction covering the zero-argument case. It gives clear context for when to reach for this tool but names no exclusions or alternatives among siblings like diagnose_request or get_code_example.

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=false, so the safety profile is covered. The description adds useful return-content context, including signed media links, but does not cover not-found behavior, auth/signing requirements, or rate limits.

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

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

It is a single compact line, front-loaded with the singular lookup scope and followed by the relevant return fields. There is 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?

With no output schema, the description usefully enumerates the returned content, and the input schema fully documents both parameters. It is nearly complete for a simple read-only lookup, though failure behavior for an invalid id is not described.

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

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

Schema coverage is 100%, so both parameters are already documented. The description reinforces that the id is a v2 id but adds no extra semantics for the lang parameter beyond what the schema provides.

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 a single-exercise lookup by v2 id and enumerates the returned data. This singular, id-based scope separates it from the search/list siblings, though no sibling is explicitly named.

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 v2 id' implies the tool is used once an exercise id is already known, but it gives no explicit when-to-use guidance or alternatives such as search_exercises or map_v1_exercise.

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

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

Annotations already declare readOnlyHint and openWorldHint=false, but the description adds non-obvious behavior: links are signed, they expire, and results should not be cached. That expiry/re-fetch contract is exactly the kind of context annotations cannot convey.

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

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

One sentence, front-loaded with the return value, with the expiry caveat parenthetically attached. 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?

No output schema exists, and the description names what comes back (MP4 + thumbnail links), which covers the main gap. Minor omissions like behavior for exercises with no media or error/auth conditions keep it from a 5.

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

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

Schema coverage is 100% and the single id parameter is documented in-schema with a format example. The description only says 'one exercise' without adding ID format or id-resolution details, so the schema does the heavy lifting – baseline 3.

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 signed MP4 and thumbnail links for one exercise. It's clearly distinct from get_exercise (metadata) by naming the exact artifacts returned, though it doesn't name any 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?

Gives clear usage context: use it to get fresh links, and the parenthetical instructs the agent not to store them but to call again. It lacks an explicit 'use get_exercise for metadata instead' routing, which keeps it from 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?

The annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds meaningful context beyond that: it requires the Scale plan and indicates the response includes dosages and timing, though it does not mention rate limits or caching.

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 short sentences with no wasted wording. The core purpose and the plan requirement are both front-loaded.

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 description covers the main purpose, plan gating, and rough return content (dosages and timing). But with no output schema and 0% schema description coverage, it should explain what 'level' means and give more semantics for the 'goal' enum values; those gaps leave the agent with an incomplete picture 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 the burden of explaining parameters. It only hints that 'goal' is required ('for a goal') and does not mention the 'level' parameter at all, leaving both enum meanings largely unexplained beyond their 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?

The description states a specific resource and scope: a recommended supplement stack for a goal, including dosages and timing. It is clear what the tool returns, but it does not distinguish itself from the sibling tool search_supplements.

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 adds a useful prerequisite ('Needs the Scale plan'), which tells the agent when the tool is available. However, it gives no guidance on when to choose this tool over search_supplements or other siblings, and no exclusions or alternatives.

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

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

Annotations already establish read-only and closed-world behavior. The description adds meaningful traits: a 30-day aggregation window, an anonymization threshold of at least 3 accounts, filters reported as shares, and single-request usage. It does not detail response shape or rate limits, but it adds substantial behavioral context 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?

The description is front-loaded with purpose and scope, then adds anonymization, use case, and cost in four compact sentences. Every sentence contributes useful information without 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?

With no output schema, the description carries more burden for explaining returns and does describe exercises/filters, anonymization, and shares. However, it does not specify the exact response structure or how limit and plan caps affect results, leaving a minor gap for an agent calling the tool.

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

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

Schema coverage is 100%, so lang and limit are already fully documented by the schema. The description mentions filter categories and shares, but adds no syntax or meaning for the actual parameters beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description names a specific resource and scope: exercises and filters requested most across WorkoutX apps in the last 30 days. It clearly separates this trending/aggregated view from generic exercise search, but it does not explicitly name sibling alternatives, so it falls short of 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?

It gives a concrete use case — deciding what to feature in an app — and notes the one-request cost. It lacks explicit exclusions or routing guidance versus search_exercises or list_exercise_filters, but the context is clear.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds that it 'Uses one request', which is useful cost context for budget-sensitive agents, and lists what data is returned, though it doesn't mention auth requirements or freshness of 'live quota'.

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 dense sentence front-loads the resource and metric list, followed by example questions and a cost note. Every clause carries information an agent needs; there is 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?

With no output schema, the description fully enumerates the returned metrics, including errors by status code and rate-limit usage. The single optional parameter is covered by schema, and the 'one request' note rounds out the operational 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 coverage is 100%, and the 'days' parameter is already fully documented in the schema with its default and maximum. The description adds no additional meaning about the window parameter, so baseline 3 is appropriate.

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

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

States a specific verb and resource ('Your account's API usage') and enumerates the exact metrics returned: requests, success rate, response times, errors, endpoints, quotas, and limits. This clearly separates it from siblings like diagnose_request, which handles individual request troubleshooting.

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 example questions it answers ('why am I getting 429s?', 'when will my quota run out?'), which tells the agent when to reach for it. It does not name alternatives or state exclusions, but the usage context is unambiguous.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds real behavioral context by disclosing that values come with counts, which hints at the shape of the response. It stops short of describing the full return structure, but with no output schema that gap is minor for a static enumeration 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 sentences, zero filler, with the resource enumeration first and the routing instruction 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?

For a single-optional-parameter read-only tool this covers purpose, routing, and the presence of counts in the response. Since no output schema exists, a brief note on the response shape would have made it fully self-sufficient, but the essentials are 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?

There is only one parameter (lang) and schema description coverage is 100%, with the enum listing every allowed value, so the schema fully carries parameter meaning. The description mentions nothing about language selection, providing no added semantics beyond the schema. Baseline 3 applies.

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

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

States a concrete resource set (body parts, target muscles, equipment, categories, muscles) and that each value comes with counts, which tells an agent exactly what the payload is. It is clearly not a search tool, and its enumeration role is distinct from search_exercises and get_endpoint_reference.

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 alternative (search_exercises) and the condition that should route to this tool instead: 'Call this before search_exercises when unsure of a value.' That is a direct when-to-use rule with the sibling named.

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=false, so the safety profile is covered. The description adds genuine value by disclosing the match-quality taxonomy (exact, equivalent, alternative, closest, none), which tells the agent results may be approximate rather than guaranteed. No rate-limit or auth notes, but none needed for a local read.

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 sentence with zero waste, front-loading the action and resource before the return-value detail. 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?

For a simple two-parameter read with full schema coverage and clear annotations and no output schema, the description covers purpose and the meaning of the result values. Only a note on how to interpret 'none' or 'closest' outcomes is missing.

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

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

Schema coverage is 100%, so both parameters are fully documented in the schema, including the enum for lang. The description's '0025' example duplicates the schema's own example and it never mentions the lang parameter. Baseline 3 is correct when the schema carries the burden.

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 ('Find the v2 exercise') and resource (old v1 id) plus the return shape (match quality tiers). It is clearly distinguishable from siblings like get_exercise or find_exercise_alternatives, which operate on v2 ids rather than mapping legacy ones.

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 'for an old v1 id' establishes the triggering context clearly: this is the tool for legacy-id lookups. It does not name exclusions or point to an alternative for v2-native ids, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint and openWorldHint=false, but the description adds genuinely new behavior: a plan-gated restriction on multi-filter queries and signed media links in results. It stops short of describing pagination behavior, error behavior when a plan cap is hit, or how limit interacts with plan caps.

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

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

Three dense sentences, front-loaded with the resource and corpus size, then constraints, then return shape. With no output schema present, the sentence describing returned fields earns its place rather than duplicating structured data.

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 15-parameter tool with no output schema, the description covers purpose, plan constraint, and a return-value summary, which is most of what an agent needs. Gaps remain around pagination via offset/limit and what happens when a plan cap is exceeded.

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 67%, and the description compensates by stating cross-cutting filter semantics the schema does not: filters are optional, matching is case-insensitive, and combining filters is plan-gated. It adds no per-parameter detail for the undocumented enums (force, category, mechanic, difficulty) or for offset/includeMedia, so it is not fully complete.

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

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

Opens with a specific verb+resource and a concrete corpus size ("Search 1,900+ exercises"), which clearly separates it from single-record siblings like get_exercise and get_exercise_media. It does not explicitly distinguish itself from find_similar_exercises or find_exercise_alternatives, so it falls short of full sibling differentiation.

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?

States that filters are optional and that combining two or more requires the Starter plan, which is real usage guidance an agent must know before composing a query. However, it never says when to prefer this over list_exercise_filters or find_similar_exercises, leaving alternative selection 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 establish readOnlyHint=true and openWorldHint=false, so the safety profile is clear. The description adds important non-schema context: access requires the Growth plan or higher. It does not discuss pagination behavior beyond what the schema provides, so it stops short of a 5.

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

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

The description is short and front-loads the resource and its key attributes, followed by filters and the plan requirement. Every sentence contributes useful information. The first sentence is a fragment rather than an explicit action statement, which slightly weakens structure.

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

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

Given seven optional parameters, partial schema descriptions, and no output schema, the description does a reasonable job of stating what is returned and what can be filtered. The plan requirement is important context. It could be more complete by explaining pagination or contrasting with the supplement stack sibling, but it is sufficient to invoke the tool.

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

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

Schema description coverage is 57%, and the description lists most filter dimensions: category, goal, timing, evidence, and free text. It does not mention limit or offset, and it adds little detail beyond the schema for the documented parameters. This is adequate but leaves the pagination parameters to the schema alone.

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

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

The description clearly identifies the resource as supplements and notes the returned attributes: evidence ratings, dosage, and timing. It also lists the supported filters, so the agent can distinguish this as a filtered supplement search rather than a stack lookup. It does not explicitly contrast with the sibling get_supplement_stack, which keeps it from 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 practical usage context by listing the filter dimensions and the plan prerequisite, implying it is used to search/filter supplements. However, it does not say when to use this instead of get_supplement_stack or other siblings, and there are no explicit exclusions.

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