AIm Workout Journal

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

Annotations already mark destructiveHint=true and idempotentHint=true. The description goes further by revealing the cascading destructive behavior ('all its entries/sets') and the boolean return value, which is not visible in annotations. This is valuable beyond the structured hints.

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 a single front-loaded sentence stating the action, its scope, and the return value. No filler words or restatement of the title.

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

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

For a one-parameter destructive tool with output schema and safety annotations, the description covers the key behavior (cascading delete) and return shape. However, it omits edge behavior (e.g., non-existent session) and there is no parameter guidance, so it is 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?

The only parameter, session_id, has no description in the schema and 0% coverage. The description does not mention session_id at all, leaving the agent to infer its meaning solely from the parameter name. This fails to compensate for 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 uses the specific verb 'Delete' with the resource 'session' and explicitly notes the cascading scope 'and all its entries/sets'. This differentiates it from sibling tools like update_session, log_session, and get_session.

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 implies its use case—deleting a session—but provides no explicit when-to-use guidance or mention of alternatives such as update_session or get_session. The agent must infer applicability from the tool name and title.

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

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

Beyond the readOnly/non-destructive annotations already present, it discloses the default window, that private activities are omitted (a real result-set constraint), and the critical interpretation caveat that an unlisted day is unknown rather than a day without the activity, plus that counts are days not times or amounts. These are exactly the traps an agent would otherwise fall into.

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 resource and its scope, then the shape of the returned activity. Dense and mostly earned, though the `goal` field breakdown partly duplicates the output schema and could be trimmed if that schema is authoritative.

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?

Since an output schema exists, the description is not obliged to document return values, and it still covers privacy filtering, default range, and count semantics. The remaining gap is the ambiguity around the two date parameters, which leaves an agent guessing at boundary behavior.

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% — the two date params carry only format and null defaults, no descriptions. The description compensates partially by stating the default range (last 28 days), but never explains the semantics of a null date_from vs date_to or whether they're inclusive, leaving half the burden unmet.

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 (the user's own activities) and immediately scopes it against the obvious confusable: 'besides workouts (e.g. football, swimming, a drink)'. An agent can distinguish this from get_sessions/get_stats without opening a schema.

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

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

Gives clear context for use: activities rather than workouts, an explicit default range of the last 28 days, and the note that the user creates activities and goals in the AIm app. It stops short of naming an alternative tool or an explicit 'use X instead of get_goals' routing rule, so it's clear but not fully directive.

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's one added behavioral fact is sort order ("newest first"), but it says nothing about truncation via the default limit, pagination, or what happens when more than 100 records exist.

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 short sentence with no filler and the ordering fact front-loaded. It is efficient, though the brevity borders on under-specification given the unaddressed limit parameter.

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

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

An output schema exists, so return-shape explanation is not required, and annotations cover the safety profile. However, for a list tool the description should still address result cardinality and the default limit, which it does not, leaving a meaningful 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% for the single `limit` parameter; it has a type and default of 100 but no textual meaning. The description never mentions the parameter, so an agent cannot tell whether the list is silently truncated at 100 rather than returning everything.

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 ("List body measurements") plus the ordering ("newest first"). It does not distinguish itself from the sibling log_body_metric, so an agent must infer that this is the read counterpart to a write 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?

No when-to-use or when-not-to-use guidance. The presence of log_body_metric as a sibling makes an explicit "use this to read, use log_body_metric to write" statement the obvious missing piece.

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

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

Beyond readOnly and non-destructive annotations, the description discloses important behavior: intake fallback for next_workout/new_program, intake_required semantics, safety screening caveats, heuristic injury mapping, residual load limitations, private activity exclusion, and timezone-dependent date handling. This is unusually rich behavioral context for an agent.

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 front-loaded and organized with bullets, but it is very long and describes many return fields in detail even though an output schema exists. Much of that detail adds nuance, but the definition is over-sized and could be tighter.

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

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

Given the tool's complexity, zero schema parameter descriptions, and the many modes it supports, the description is complete enough for an agent to select a task, pass constraints and today correctly, and understand key return semantics. The output schema exists, but the extra behavioral nuance is not harmful to completeness.

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: it explains every task enum value, the default, the check_in alias, constraints as today-only and non-persistent, and the today date format/default timezone behavior. This fully compensates 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 states a specific resource, the user's training data, and enumerates the coaching tasks it supports (next_workout, new_program, weekly_review, deload_check, checkin, intake). It clearly distinguishes this aggregate coaching-context tool from granular CRUD siblings, though it does not explicitly name alternatives like get_stats or get_sessions.

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 contexts through the task list and explains that constraints are for today-only circumstances, with durable facts redirected to update_coach_profile. It does not provide explicit when-not-to-use guidance or name most sibling alternatives, but the intended use 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?

The annotations already establish that this is a read-only, non-destructive, non-open-world operation. The description adds scope context about status filtering and where activity goals live, but it does not add much beyond that; output behavior is covered by the 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?

The description is two compact sentences with no wasted language. The primary resource is stated first, followed by useful routing 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 one-parameter read tool with annotations and an output schema, the description is largely complete. It covers the resource, the status filter, and the key sibling relationship, though it could slightly improve parameter guidance around the default.

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 lists the accepted status values and implies that 'all' covers all statuses, but it does not explain the default behavior or distinguish the statuses 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 identifies the resource as the user's goals and clarifies the status scope, though it does not explicitly use a retrieval verb. It usefully distinguishes this tool from activity-related goal data found in get_coaching_context.activities and get_activities.

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 routing guidance by stating that goals on the user's own activities belong in get_coaching_context.activities and get_activities. It does not explicitly discuss when to use status 'all' versus specific statuses, but the main alternative path 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, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds genuine behavioral context beyond that: the conditional result shape when there is no active program, and the null semantics for pending_draft when no draft waits.

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

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

Purpose is front-loaded in the first clause, and the sibling-routing sentence is a clean closer. The middle is dense with nested parentheticals and backticked field names, and partly restates what the output schema already declares, so it could be tightened.

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?

Coverage is strong for a read-only, zero-param tool: it explains both the populated case and the degenerate no-program/no-draft cases, and points to the right siblings. Because an output schema exists, the detailed field enumeration is largely redundant, leaving only that minor inefficiency rather than a substantive 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?

The tool takes zero parameters (schema coverage 100%), so there is nothing parameter-level to explain and the baseline of 4 applies. The description correctly implies a no-argument 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 (get the active training program) and enumerates the payload: day templates with planned blocks/supersets and per-exercise targets, plus pending_draft. It is clearly distinguishable from siblings like get_coaching_context, review_program_draft and import_document, which it explicitly names.

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

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

It routes the agent away from this tool for adjacent jobs: program-planning data lives in get_coaching_context(task='new_program'), draft validation in review_program_draft, saving/replacing in import_document. What it doesn't spell out is the positive trigger (e.g. 'use when the user asks about their current program'), so it stops just short of full when/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 declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds useful signal that the payload is deep (nested entries, sets, cardio, wearable metrics), which hints at a heavier response than a list call, but says nothing about not-found behavior or payload size 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?

A single front-loaded sentence with no filler; every clause names a component of the returned payload.

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 spell out return values, and for a one-parameter read getter this is close to sufficient. The only gap is routing guidance versus the list and activity siblings.

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

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

Only one parameter exists and the schema provides zero description coverage for session_id. The description never mentions the identifier at all, though the name is largely self-explanatory, leaving the agent to infer it must be an existing session's 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) and resource (one session) and enumerates the nested payload (entries, sets, cardio, wearable metrics). 'One session' implicitly distinguishes it from the plural get_sessions sibling, though the sibling is never 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 singular scope implies this is the detail-fetch tool rather than the list tool, but the description never states when to use it over get_sessions or get_activities, nor any prerequisites. Usage is only inferable from the wording.

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 real behavioral facts -- results ordered newest first and returned as summary fields with total volume -- but says nothing about pagination behavior or the 50-item default beyond the 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?

Front-loaded with the ordering and payload facts an agent needs first, then the optional filter, then the sibling pointer -- a sensible priority order. Only mild redundancy in repeating 'sessions' and the trailing parenthetical is slightly dense.

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 spelled out, and annotations cover the safety profile. What's missing is enough to call it correctly: the unexplained limit and the ambiguity of whether 'total volume' is per-session or an aggregate figure leave the agent 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%, so the description must carry the parameter burden and it only partly does: 'Optional date range' covers date_from/date_to but gives no format or inclusivity semantics. The `limit` parameter is never mentioned, leaving its default and any maximum 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 plus two distinguishing traits: newest-first ordering and summary fields with total volume. It implicitly separates itself from the singular get_session by saying 'List sessions', and explicitly redirects review-oriented needs to get_coaching_context.

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 marks the date range as optional, telling the agent it can call with no filters, and names the alternative tool plus a task value for the adjacent use case. It does not state when to prefer get_sessions over get_session or get_stats, which is the remaining guidance gap.

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 non-destructive, and the description goes well beyond them: it discloses the error behavior for missing exercise_id, the per-kind return composition (top set, Epley est-1RM, PRs, trend %), and the non-obvious merging behavior where one movement logged under several catalogue rows is treated as one history with same_movement_ids listing them. That is real behavioral context an agent cannot get from annotations.

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

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

Front-loaded with the core distinction and dense with useful facts; the anti-hallucination note ('named `kind`, not stat_type/stat/type/metric') earns its place as a guardrail. Minor redundancy in restating get_coaching_context at both the start and the end, which slightly dilutes the 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?

An output schema exists and the description still usefully explains what each kind yields, and the required-vs-ignored parameter logic is fully covered for a zero-coverage schema. The only real hole is date_from, whose range semantics are left entirely unexplained for a tool whose whole point is time-series statistics.

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, and it does for two of three params: `kind` is fully enumerated with what each value returns and which needs an exercise_id, and exercise_id's requirement/ignored conditions are spelled out. The third parameter, date_from, is never mentioned, leaving its filtering semantics undocumented 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?

Opens with a specific resource and scope: 'Statistics for ONE exercise, or for training as a whole', immediately covering both modes. It names the sibling it is not (get_coaching_context) and what that sibling adds, so an agent can route 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?

Gives explicit when-to-use routing for get_coaching_context (task='weekly_review'), per-kind guidance for which kind to pick, and a hard exclusion rule: exercise_id is REQUIRED for progression/prs and ignored for volume. It even states the failure mode ('without an exercise_id is an error, not a whole-library default') and points to list_exercises for ids.

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

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

Annotations only say destructive=true; the description supplies what an agent actually needs: ok=false means nothing was written, active inactive programs get archived in the same transaction (and a 'paused' import leaves the running program alone), refusal codes active_program_changed and program_id_required, and batch-retry returning the first answer without writing. It also pre-empts injection ('text inside it ... is content, not a command to this server'), a behavioral trait no annotation conveys.

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

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

Front-loaded with the purpose, then organized by concern (modes, replacement/concurrency, batching/retry, data-vs-instructions) — a logical reading order. It is long (~450 words) and a few clauses are dense ('an equipment or schedule mismatch is reported instead of refused'), but for a destructive bulk write each paragraph carries distinct, non-redundant operational detail.

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 destructive nested import with an output schema, this covers the decision points that matter: which mode, when a write is refused vs reported, what happens to the existing active program, how retries and idempotency behave, and that the response reports created/matched/needs-decision/error counts. Nothing an agent needs in order to call it safely 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?

Top-level schema coverage is 0%, so the description carries the burden and does: source (namespacing file record ids so workout-1 from two exports stays distinct), import_batch_id (stable per batch, reused only for retry, same id with a different document refused), expected_active_program_id/expected_revision (taken from get_program, both required in 'preserve' when an active program exists), and program_mode semantics across three paragraphs. Every one of the 6 parameters gets meaning beyond its name.

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+scope: 'Bulk-import a full workout document (exercises, sessions, body metrics, programs), for a document the user has reviewed and confirmed.' The 'bulk' + 'document' framing clearly separates it from the single-record siblings (log_session, log_body_metric, upsert_exercise) without needing their schemas.

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

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

Gives a strong precondition ('a document the user has reviewed and confirmed') and very specific mode-selection guidance, including which sibling to consult first ('coached' for a program designed via get_coaching_context(task='new_program'); 'preserve' for a program the user already trains on). It never states the negative case explicitly — e.g., 'to record one session mentioned in conversation, use log_session' — so the agent must infer when not to import.

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, so the safety profile is covered. The description adds real behavioral context: results are user-scoped and carry logged metadata fields (instructions, video_url, image_url, pool_slug). It stops short of mentioning ordering or pagination.

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, scope and output content first, filter list second, sibling routing last — well front-loaded. The line 'It holds the ids the user already has' is a slightly cryptic restatement that costs a few words without adding 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 not explaining return values is correct; the description instead clarifies scope and the metadata carried through. The remaining gap is filter value semantics, which matters for a zero-coverage 4-param schema but is at least partially implied by the natural-language filter names.

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 the parameters, and it does list all four names plus one real semantic detail (`query` is a substring of name or id). However, it never says what value format `muscle`, `equipment`, or `movement_pattern` accept (slug vs. display name) or whether filters are ANDed, leaving the most error-prone part 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 (list) and a precisely scoped resource: THIS USER's own exercise catalog, not the global pool. It also flags the sibling boundary ('new exercises come from search_exercise_pool'), so an agent can pick it 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 a clear when-to-use condition (things the user already has/logged) and an explicit alternative for the opposite case (adding new exercises → search_exercise_pool). No statement of when it is the wrong choice beyond that, so it stops short of the full 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 declare write/destructive/idempotent, and the description goes well past them: it explains the upsert merge rules (omitted fields keep stored values, new keys join, repeated keys overwrite), that null clears a field, that there is no delete, and that the whole stored entry is returned. This is exactly the extra context annotations cannot carry.

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 purpose, then routing, then merge semantics. Every clause carries operational meaning (one entry per date, overwrite-as-correction, no delete) 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?

For a nested-object write tool with an output schema present, the definition covers trigger, alternatives, merge/overwrite behavior, null-clearing and the absence of delete. Nothing an agent needs to call it safely is missing; return shape is delegated to the output schema.

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

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

The nested `metric` schema has rich per-field descriptions, and the description still adds merge semantics that the schema only hints at (omitted fields retained, new measurements/custom_fields keys join, null clears, repeated key overwrites). It doesn't restate units or ranges, which the schema already covers, so it stops short of a 5.

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 set ('Record the user's body weight, body-fat % or circumferences for one day') and immediately contrasts with the siblings log_session (training) and get_body_metrics (read-back). An agent can distinguish it from every other logging tool without opening a schema.

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

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

Gives an explicit trigger condition ('when the user states a current measurement'), names the alternatives for adjacent intents (log_session, get_body_metrics), and adds a routing caveat: the app's weight tile, charts and coaching context read these entries, not the profile's bodyweight field.

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, non-idempotent, non-destructive append; the description reinforces this with 'Each call adds a new entry' and adds traits annotations cannot express — that the history is kept with the user's data export, that no tool reads it back, and that it does not replace facts stored via update_coach_profile or upsert_goal. That is real behavioral context 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?

Front-loads the core action and constraints, then adds the important caveat about read-back. The middle enumeration of milestone types is somewhat list-like, but each sentence carries distinct information and none is 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 elaboration; the description still notes 'Returns the stored event.' Combined with the append-only semantics, sibling disambiguation and exclusion list, an agent has everything needed to call this correctly.

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

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

Schema description coverage is 100% and the enum plus payload examples are already documented in the schema; the description's 'for example type=checkin' and payload gist largely restate that. Baseline 3 is appropriate since the schema carries the parameter 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?

Opens with a specific verb+resource ('Append a dated milestone to the user's coaching history') and then enumerates the milestone kinds the type enum covers, so an agent knows exactly what this tool records. It explicitly differentiates itself from log_session and upsert_goal, which are the most confusable 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 explicit when-to-use cases (check-in held, goal reviewed/achieved, deload advised, red flag raised, intake started/finished, profile changed) and explicit when-not-to-use cases ('Not for ordinary chat, logged workouts (log_session) or goal edits themselves (upsert_goal)'), naming the alternative tools by name.

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=false, destructive=true, idempotent=false. The description goes beyond them by disclosing that the response returns the stored session plus any auto-created exercise catalog entries, and by describing the conditional, rate-limited `coaching_setup` injection (at most once a week, only for users without a completed intake or active program). It does not address the destructiveHint=true or the non-idempotency (duplicate-log risk), which are the remaining behavioral gaps.

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

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

Purpose is front-loaded in the first sentence and every paragraph carries information (return shape, coaching_setup injection, sibling routing, duration_sec display). It is somewhat long, and the coaching_setup aside is verbose for a behavior that affects at most one response per week, but 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?

An output schema exists, yet the description still usefully explains the dynamic `coaching_setup` block and the auto-created catalog entries, which structured fields alone would not convey. Given the highly nested schema this is close to complete, but it never warns that the call is non-idempotent (repeated logging can create duplicates), which an agent writing a mutation needs to know.

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?

Top-level schema coverage is 0% for the single `session` parameter, so the description must compensate. It does sketch the payload structure (exercises → sets, cardio, wearable metrics) and explains the user-visible effect of `duration_sec` (blank duration in history and session views). However, the deep nested schema carries its own rich field descriptions, so the description adds only moderate value at the top level.

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 ('Log a completed workout session') and enumerates the payload shape (exercises → sets, cardio, wearable metrics). It also explicitly distinguishes itself from siblings by name (get_coaching_context for planning, get_sessions/get_session for reading, update_session/update_set for changing), so an agent can place it without opening a schema.

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

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

Explicit when-not guidance: a workout run in the AIm app is already stored by the app, so it is read via get_sessions/get_session and changed via update_session/update_set — not logged here. It also routes planning data to get_coaching_context and states this tool stores completed workouts. This is textbook when/when-not/alternatives.

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

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

Annotations already declare the mutation/idempotent/destructive profile, but the description adds real behavioral context: the toggle semantics of mark vs unmark, the unknown-name error behavior (returns the user's activity names), and the future-day refusal. That is genuine added value beyond structured fields, though return format is left to the 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?

The core verb and example are front-loaded, and the sentence carries dense, useful information. Slightly verbose with the parenthetical asides, but 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?

An output schema exists, so return values needn't be covered, and annotations handle the safety profile. The description rounds this out with error handling and the activity-must-exist prerequisite, making it complete for calling the tool correctly.

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

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

Schema coverage is 100%, so all four parameters (date, done, today, activity) are already documented in the schema. The description reinforces timezone and day-restriction semantics but adds little syntax beyond what the schema states, so the 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 pair (mark/unmark) and resource (an activity day), reinforced by a concrete example ('I played football yesterday'). It explicitly distinguishes itself from the sibling log_session by stating marks are not 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?

Names the alternative (log_session) and the condition that routes to it, plus the constraint 'one day per call; past days and today only'. It also explains what to do when the activity doesn't exist, leaving little 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?

The description goes well beyond annotations by explaining the validation checks, mode-dependent acceptance, kept versus pending-draft outcomes, replacement of an earlier pending draft, non-change to the active program in most cases, and that no profile, intake, goal, or coaching history is modified.

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 then adds mode, return-shape, and persistence semantics in a logical order. It is dense and appropriately detailed for a complex draft-review tool, though some sentences could be tightened.

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

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

Given the complex nested input, destructive/idempotent annotations, and output schema, the description is complete enough for an agent to understand validation behavior, mode differences, return fields, and side effects. No critical behavioral or usage gap remains.

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?

It adds important meaning for program_mode, including coached versus preserve behavior and how mismatches are downgraded to warnings in preserve mode. For document it explains that it is the same WorkoutDocument import_document accepts and what is checked, though it does not independently document the full nested document structure.

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: a server-side checklist/review for a DRAFT training program. It identifies the exact validations performed and distinguishes itself from import_document by framing this as review-and-keep rather than import.

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 clearly explains the two modes, especially when program_mode='preserve' is intended for the user's own program brought in from a file. It references import_document as the sibling that takes the same document and mode, but does not explicitly spell out a full when-to-use-this-vs-import_document decision rule.

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

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

Annotations only cover the safety profile (readOnly, non-destructive, closed-world); the description adds substantial behavior beyond that: a hard 25-entries-per-call cap with guidance to narrow filters, the ranked partial-word fallback for `query`, the body-region word matching rule, and the equipment-matching rule where body weight always counts and [] means no equipment. It also flags `safety` as something to respect when prescribing, which is real operational 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?

Front-loaded with the core purpose, then the filters, then the return shape – a sensible order with little waste. It is dense and long, and the field-by-field enumeration of return values partially duplicates what the output schema already provides, but with 0% parameter documentation the length is largely earned.

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 7-parameter, all-optional search tool with an output schema, the description covers the search semantics and result shape well enough to call it correctly, and the output schema handles return typing. Minor incompleteness remains around `limit` bounds and how `locale` interacts with `query` matching.

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 carries the full burden, and it does well: `muscle` gets concrete values, `equipment` gets a precise matching rule and an explicit meaning for the empty list, `query` gets multilingual and ranking semantics, and `movement_pattern`/`category` are named as filters. The gaps are `limit` (only implied by the 25 cap) and `locale` (only implied by 'localized name'), neither of which is defined.

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 ('Search the curated global exercise pool') and immediately scopes it as the catalog programs/workouts are built from, which separates it from user-catalog tools. The added detail that `in_user_catalog` merely marks prior training reinforces that this searches the global pool, not the user's own list.

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 implied rather than stated: it is clearly for finding exercises by attribute, and the closing line 'a narrower filter finds the rest' is a genuine usage tip for the 25-result cap. However, it never says when to prefer this over list_exercises or show_exercise, nor when not to use it, so the agent must infer routing.

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 covered. The description adds valuable behavioral context beyond annotations: it specifies what is returned (summary, cues, safety, progressions), notes that display depends on client capabilities, and describes the fallback when a name matches no single exercise (found=false, up to five candidates with slugs, shows nothing).

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 remains reasonably concise. The three sentences are structured logically: primary action, return details, and fallback behavior. The first sentence is somewhat list-heavy but each component earns its place.

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

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

For a read-only tool with no output schema, the description adequately explains what is returned and the fallback behavior. Annotations cover safety, and the two parameters are fully described in the schema. The only minor gap is the absence of explicit sibling differentiation, but overall the definition is complete enough for an agent to call it correctly.

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

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

Schema coverage is 100%, so both parameters (locale and exercise) are fully documented in the schema. The description reinforces the exercise parameter's accepted forms (slug, id, or name) and explains the fallback for ambiguous matches, but it adds no new semantics for the locale parameter. Baseline 3 is appropriate when the schema already carries the parameter 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 uses a specific verb and resource: 'Shows the user one exercise from AIm's catalog' and enumerates the content returned (picture/animation, technique, summary, cues, safety, progressions). It is clear what the tool does, but it does not explicitly differentiate itself from siblings like list_exercises or search_exercise_pool.

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 implied by 'Shows the user one exercise' and the fallback behavior for ambiguous names, but there is no explicit guidance on when to use this tool versus list_exercises or search_exercise_pool. The description lacks exclusion or alternative-selection criteria.

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

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

Beyond the annotations, the description discloses important write semantics: explicitly null clears a field while omitted fields are untouched. It also describes the return shape, including changed fields, ui_impact, intake progress, and conditionally computed goal_candidates, which gives the agent substantial behavioral context for a destructive/idempotent mutation.

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 main purpose is front-loaded, and every part of the description relates to correct invocation or interpretation. Some return-value details are dense and arguably unnecessary because an output schema exists, but the wording is generally efficient rather than padded.

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

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

Given the tool's complexity, nested patch object, annotations, and output schema, the description is complete enough to call it correctly. It covers write semantics, injury handling, return structure, intake state, and goal_candidates behavior without leaving obvious gaps for an agent.

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

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

Schema coverage is 100%, so the schema already documents the patch fields and their allowed values. The description adds meaningful semantics beyond the schema by explaining the null-versus-omitted distinction and how add_injuries and resolve_injury_areas are used.

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 action and scope: persisting user-confirmed coaching profile facts, with examples (goal, experience, schedule, equipment, injuries, preferences), and notes that it works mid-workout. It is clearly distinguishable from session/logging tools, though it does not broadly differentiate itself from siblings such as upsert_goal or log_coach_event.

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 condition — persist facts the user confirmed — and clarifies that one fact or several can be sent per call. It also routes injury creation and closure to the correct fields, but it does not explicitly state when not to use this tool or name most alternative siblings for other profile-adjacent tasks.

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 mutation nature is covered. The description adds the list of allowed keys, which is useful context for what gets modified, but it does not disclose whether the operation is a partial merge or a full replacement, nor any permission or reversibility details. It does not contradict 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 a single, tight sentence with a clear verb and a scannable list of allowed keys. No filler or repetition; it front-loads the core purpose before listing details. This is appropriately concise.

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 value details are not needed. The tool is a simple patch operation with two parameters, and the description provides the essential field list. It could explicitly mention that it is a partial update (patch) rather than a full replacement, and could note prerequisites like session existence, but the current description is sufficient for an agent to invoke it correctly in most cases.

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 lists the allowed keys for the patch object (date, day_label, duration_sec, etc.), which is critical since the schema only says 'additionalProperties: true' with no field documentation. This adds substantial meaning beyond the schema, though it does not explain types or constraints for each key.

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 ('Fix') and a clear resource ('session-level fields'), and lists the allowed keys. This distinguishes it from siblings like log_session (create) and delete_session (remove). The purpose 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 description implies use for editing existing sessions via 'Fix session-level fields', but it does not explicitly state when to use it versus alternatives like log_session for creating, or update_set for set-level changes. No exclusions or alternative routing are given, leaving the agent to infer the context.

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

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

Beyond annotations (readOnlyHint=false, destructiveHint=true, idempotentHint=true), the description adds useful behavioral details: the `occurrence` parameter's 1-based selection logic, the constraint on allowed patch keys, and the return value ('updated set, or null if none'). It does not contradict 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 two sentences with no fluff. The first sentence front-loads the primary purpose and locators; the second packs necessary details (patch keys, occurrence behavior, return value) efficiently. Every word earns its place.

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

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

For a tool with 5 parameters and a nested object, the description covers the essential operational semantics: how to identify the set, what can be patched, how to disambiguate repeated exercises, and the return contract. Minor omissions like whether patch merges or replaces existing fields are implied by the update semantics and the presence of an output schema.

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

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

With 0% schema description coverage, the description carries the burden of explaining parameters. It maps session_id, exercise_id, and set_number as locators, explicitly defines `occurrence`, and lists the allowed keys for the `patch` object. This adds meaning that the raw schema does not provide.

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 clear verb ('Fix'), a specific resource ('a single set'), and the locators ('session + exercise + set_number'). It also enumerates the exact patchable fields, making it unambiguous what the tool does and how it differs from siblings like update_session.

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 implies its usage context (correcting a set's metrics) and explains how to locate the set, but it does not explicitly mention when to prefer this tool over alternatives or call out exclusions. There is no direct guidance like 'for session-level changes, use update_session'.

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 annotations by disclosing that omitted fields are preserved (safe partial update), that pool-linked entries inherit muscles/equipment/technique cues, and that hand-written exercises are invisible in the muscle map until required fields are set. It does not spell out whether passing explicit null clears a field versus omitting it — a meaningful gap for a tool flagged destructiveHint=true.

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 create/update action and the identity key, then the pool path, then the hand-written requirements, then the partial-update guarantee. Dense but every sentence carries a rule; slightly heavy paragraph form rather than a short list.

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 deep nested object with an output schema present, the description covers the identity model, inheritance behavior, visibility prerequisites and update semantics — the parts that are not obvious from field names. Coverage of null-vs-omit semantics is the main omission.

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?

Top-level schema coverage registers as 0%, but the description supplies real semantics for the ambiguous parts: id-vs-name keying, the pool_slug linking rule, what instructions should contain (2-3 short technique cues, user's language), and which fields are required for display. The many remaining fields (dose_unit, long_length, movement_pattern) are documented inside the schema 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?

States a specific verb pair and resource: 'Create or update an exercise in the user's catalog (keyed by its id/name)'. It also clarifies the upsert key, which distinguishes it from list_exercises and search_exercise_pool, and names search_exercise_pool as the source of pool-backed entries.

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 guidance on the two paths: an exercise saved with the pool `slug` as `id` plus `pool_slug` inherits pool data and keeps one identity, whereas a hand-written exercise needs instructions, primary_muscles, category and equipment to surface anywhere. It does not explicitly say when to prefer this over search_exercise_pool or show_exercise, but the workflow is clear enough to act on.

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?

Well beyond the annotations, it discloses consequential side effects: featured=true 'automatically un-features any other active goal', a sessions_per_week goal and training_days_per_week 'are one number: writing either sets both', and unknown exercise ids are rejected. It also clarifies that despite destructiveHint=true nothing is hard-deleted ('Goals are not deleted: status=revised/abandoned/achieved supersedes them'). The one missing piece is whether an update with an existing `id` is a full replace or a merge of the nested goal object — important for a non-idempotent upsert and 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-loads the create-vs-update branch and the goal_type taxonomy before the edge rules, which is the right ordering. It is long (~200 words) and the parenthetical example quotes are chatty, but nearly every sentence carries a rule that cannot be inferred from annotations or schema; the trailing paragraphs on user-set goals, app-only activity goals, and ratified are the only parts that could be trimmed.

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 hard parts of a 20-field nested object: goal_type shapes, succession via supersedes_goal_id plus status=achieved, the featured exclusivity rule, and the profile coupling. Gaps remain on the required `kind` field, allowed status transitions, and update-merge semantics, which matter for a mutation tool with destructiveHint=true.

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 reported at 0%, so the description carries the burden, and it does map most of the consequential nested fields: which target keys each goal_type requires (exercise_id/value/baseline_value/tolerance_pct/muscle/band/metric), review_date, featured, ratified, supersedes_goal_id, source=user. It leaves unexplained the required `kind` enum (outcome/process/performance) and fields such as status, unit, direction, deadline, notes, and custom_fields, so it does not fully compensate 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?

Opens with a specific verb+resource ('Create or update a training goal') and immediately disambiguates the two modes ('pass `id` to update'), which is the key branch an agent needs. The rest of the first sentence narrows 'goal' to five concrete shapes via goal_type, so an agent can tell this apart from get_goals or update_coach_profile 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?

It gives explicit selection rules per goal_type ('milestone (point target — exercise_id+value, or bodyweight+baseline_value)', weekly_volume, trend, maintenance, plain process metric=sessions_per_week) plus the default when goal_type is omitted. It also states real exclusions and routes elsewhere: activity goals are 'set in the app only and read in get_coaching_context.activities', exercise ids must come from list_exercises/upsert_exercise, and featured is rejected on frequency goals.

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