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?

The readOnlyHint annotation already signals a safe read operation, so the description does not need to repeat that. It adds useful behavior beyond the annotation by specifying that results are returned newest first. It does not mention limit behavior, but that is minor for this simple read 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?

A single, front-loaded sentence conveys the action, resource, and sort order with no wasted words. Every element earns its place.

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

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

The tool is low complexity: one optional parameter, read-only, and an output schema exists to describe return values. The description captures the essential retrieval semantics (list, body measurements, newest first), so nothing critical is missing for a straightforward call. Broader usage guidance and parameter semantics are missing, but those are largely covered by the simple schema and clear resource.

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

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

Schema description coverage is 0%, and the description does not explain the 'limit' parameter beyond what the schema already shows. The agent must rely on the parameter name and default value for meaning, so the description 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 names a specific verb ('List') and resource ('body measurements') and adds the ordering behavior ('newest first'). This clearly distinguishes it from write-oriented siblings such as log_body_metric without requiring schema inspection.

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 intended use is implied: call this tool when the agent needs to retrieve body measurements. However, the description does not explicitly identify alternatives or give when-not-to-use conditions, leaving the agent to infer the distinction 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?

The readOnlyHint annotation already establishes that this is a safe read operation, lowering the burden on the description. The description adds the status filtering behavior, but does not disclose details like default status handling, ordering, pagination, or what happens when no goals match.

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

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

The description is a single compact sentence that front-loads the resource and encodes the valid statuses. Every part earns its place, and there is no redundant phrasing.

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 an output schema and readOnly annotation, the description is nearly sufficient. It lacks explicit mention that 'active' is the default and does not compare against sibling goal tools, but these are minor gaps given the structured schema and annotations.

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 should compensate, but it largely repeats the enum values already present in the input schema. It does not explain the meaning of each status or the nuance of 'all' beyond what the enum labels already convey.

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 the resource ('the user's goals') and the status filter, making it clear this is a retrieval tool for goals. It is clear but relies on the tool name for the verb, and it does not explicitly distinguish itself from the sibling upsert_goal.

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

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

No guidance is given about when to use this tool versus alternatives such as upsert_goal or get_coaching_context. The status enum implies filtering use cases, but there is no explicit context, prerequisite, or exclusion information.

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 value by disclosing that the call returns null when no program is active and by summarizing the shape of what comes back. It does not discuss pagination or staleness, but for a no-arg read those are minor. No contradiction with the annotations.

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

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

Two sentences, zero filler. The primary behavior (retrieve the active program) is front-loaded, followed immediately by the sibling routing that prevents misuse. The parenthetical field enumeration is dense but earns its space by telling the agent what the payload contains.

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

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

With an output schema present and 100% schema coverage, the description needs only to cover scope, null behavior, and tool selection – and it does all three. Nothing an agent needs before calling this no-arg read 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline for a 0-param schema is 4. The description correctly spends no words on parameters and instead invests in return semantics.

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

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

States a specific verb+resource ('Get the active training program') and goes further by enumerating the returned content (day templates, planned blocks/supersets, per-exercise targets) and the null case. It explicitly separates itself from get_coaching_context, review_program_draft, and import_document, so an agent can pick it without opening a schema.

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

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

The second sentence routes each adjacent intent to the correct tool: planning data to get_coaching_context(task='new_program'), draft validation to review_program_draft, and saving/replacing to import_document. The null-on-no-active-program clause tells the agent what to expect as a boundary condition, leaving nothing 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 annotations already declare readOnlyHint=true, so the read-only safety profile is covered. The description adds useful scope about the payload (full nested entries, sets, cardio, wearable metrics) but gives no extra behavioral caveats such as error cases or prerequisites; this is acceptable but not rich.

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. It states the action, the object, and the scope of what is returned in a compact, easily parsed form.

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 tool with one required parameter, an output schema, and readOnlyHint annotation, the description is nearly complete. It lacks only explicit guidance on session_id provenance and when to prefer get_sessions, but these are minor given the tool's simplicity.

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

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

Schema description coverage is 0% and the description does not compensate: it never explains what session_id should contain, its format, or how to obtain it. The property name is self-evident, but the description adds no parameter-level meaning beyond that.

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 ('Get') and resource ('one session') and enumerates the contained data: nested entries, sets, cardio, and wearable metrics. This clearly differentiates get_session from the plural sibling get_sessions, which would return multiple 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?

The singular 'one session' and the detail of nested data imply when to use the tool: when a single full session object is needed. However, it does not explicitly state when not to use it or name alternatives like get_sessions for summary/list needs, so the usage guidance remains implied rather than explicit.

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, and an output schema exists, so the safety and return-format burden is light. The description still adds useful traits: newest-first ordering and the presence of total volume. Pagination behavior around the limit parameter is not disclosed.

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

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

Two sentences, front-loaded with the core behavior and no filler. The second sentence is dense with cross-reference detail but still earns its place by preventing a wrong-tool selection.

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 list semantics, ordering, date-range optionality, and the routing to get_coaching_context cover what an agent needs, and the output schema handles return values. The limit/pagination gap is the one meaningful 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?

Schema description coverage is 0% across all three parameters, so the description carries the full load. It only gestures at 'optional date range' without date format or inclusive/exclusive semantics, and the limit parameter (default 50) is never mentioned at all.

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 ordering ('newest first') and returned content ('summary fields and total volume'). It also names the sibling that covers a related but different job (get_coaching_context for training review), so an agent can place 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 clear context (session history with optional date range) and explicitly routes the training-review use case to get_coaching_context with its task argument. It does not, however, state when to reach for this versus get_session (single session) or get_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?

Well beyond the annotations, it discloses no-write guarantees ('ok=false means nothing was written'), specific refusal codes (active_program_changed, program_id_required), transactional archiving of the previous program only for 'active' imports, paused-program side effects, per-mode conflict handling, and batch retry/idempotency semantics. It also defends against prompt injection by declaring file text is data, not commands.

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?

Despite its length, it is front-loaded with the core action and then organized into clearly themed paragraphs (modes, replacement, batching, safety). Given a destructive bulk import over a deeply nested schema, each sentence carries operational weight 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 complex, destructive, 6-param tool with nested objects, it covers prerequisites, mode selection, conflict/refusal handling, transactional side effects and batch semantics; with an output schema present it does not need to restate return shape, though it usefully notes the reported counts.

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 description coverage is 0%, so the description carries the burden and does so for all six parameters: program_mode's two values and their meaning, import_batch_id's reuse/retry rule, source's role in namespacing record ids, and both expected_active_program_id/expected_revision sourcing and refusal behavior. It adds substantial meaning the bare schema lacks.

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

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

Specific verb ('Bulk-import') plus resource ('a full workout document') and an explicit enumeration of the payload (exercises, sessions, body metrics, programs). This clearly distinguishes it from single-record siblings like log_session, log_body_metric and upsert_exercise, which handle one record or one entity type.

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

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

It states the precondition ('a document the user has reviewed and confirmed') and routes program_mode with concrete alternatives ('coached' vs 'preserve', tying 'coached' to get_coaching_context(task='new_program') and both expected_* fields to get_program). What is missing is an explicit when-not (e.g. 'for a single logged session, use log_session instead'), so guidance is clear but not fully closed.

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, so the description adds value by specifying that it returns the user's own catalog with specific metadata fields and that it holds the user's existing IDs. This is useful context beyond the annotation, though it doesn't mention pagination or auth requirements.

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, front-loaded with the primary purpose and immediately useful filter details. No filler or repetition; every sentence adds meaning.

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 format isn't needed. The description covers purpose, filters, and the distinction from search_exercise_pool, which is sufficient for a simple listing tool. The only gap is deeper parameter semantics, which is minor.

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 schema has zero parameter descriptions, so the description must compensate. It lists all four filters and explains that 'query' is a substring of name or id, but it doesn't describe allowed values or formats for muscle, equipment, or movement_pattern. This is partial compensation but leaves room for ambiguity.

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

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

The description clearly states the tool lists the user's own exercise catalog with logged metadata and optional filters, and explicitly distinguishes it from search_exercise_pool for new exercises. This is a specific verb-resource pairing with clear 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?

The description implies when to use it: to retrieve the user's existing exercises, and explicitly notes that new exercises come from search_exercise_pool. It doesn't explicitly say 'use this when you need the user's catalog' but the context makes it clear, and it names the alternative.

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: it explains the upsert/merge semantics (omitted fields keep stored values, new measurements/custom_fields keys join existing ones, repeated keys are overwritten), null clearing, that no delete exists, and that the whole stored entry is returned. This makes the idempotentHint=true and destructiveHint=true annotations interpretable rather than cryptic.

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 action, then routing, then merge semantics. Dense but nearly every sentence carries information an agent needs; the 'no delete' note and the profile-bodyweight remark are worth their space. Slightly long for a single-parameter tool.

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

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

For a mutation with an output schema, the description covers the operation, its trigger, its siblings, its merge/correction semantics, and the clearing behavior. Nothing needed to call it correctly is missing.

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

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

Schema coverage reads 0% at the top level, but the nested metric object has per-field descriptions; the description still adds meaning by summarizing which metric families are accepted (weight, body-fat %, circumferences, custom fields) and by describing merge/overwrite behavior that no schema field states. It doesn't cover id/source semantics in the description, but the schema does.

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?

Names a specific verb and resource (record body weight/body-fat %/circumferences for one day) and explicitly distinguishes itself from siblings: training goes to log_session and reads go to get_body_metrics. It even clarifies that the app's weight tile and coaching context read these entries rather than the profile bodyweight field, removing the most likely confusion.

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 the trigger condition ('when the user states a current measurement') and routes the two adjacent cases to their correct tools (log_session for training, get_body_metrics for reading back). The one-entry-per-date merge rule is spelled out so the agent knows a second call for the same date is additive rather than a duplicate.

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 readOnlyHint=true and openWorldHint=false, and the description adds substantial context beyond that: it explicitly states 'Saves nothing: no profile, intake state, goal or coaching history is created or changed', and it discloses the mode-dependent severity behavior (warning vs violation) that is not visible in any structured field.

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

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

Purpose and the mode distinction are front-loaded, and every sentence conveys information (checks performed, mode semantics, return shape, no side effects). It reads as two dense paragraphs rather than a scannable structure, but there is little waste.

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

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

For a nested-document validator with an output schema, the description is complete: it covers what is validated, the two modes, the output fields (even though an output schema exists), and the absence of side effects. 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?

Top-level schema coverage is 0%, so the description carries the burden. It defines program_mode's two values in behavioral terms (coached vs preserve) and explains that `document` is the same WorkoutDocument import_document consumes, plus documents the 'unresolved' return field. This meaningfully compensates for the missing top-level parameter descriptions.

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 ('server-side checklist for an unsaved DRAFT training program') and enumerates exactly what it verifies (day references, exercise identifiability, rep ranges, equipment, injury and session-length checks). It also explicitly distinguishes itself from import_document by noting it takes the same WorkoutDocument, so an agent can tell them apart 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 the two modes: 'coached' for validation with violations, and program_mode='preserve' for a user's own file where structural errors are still refused but weight/equipment/schedule issues downgrade to warnings. It ties the mode to the one passed to import_document. It stops short of an explicit 'call this before import_document' imperative or a when-not-to-use statement.

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

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

Annotations already flag readOnlyHint=false, idempotentHint=true and destructiveHint=true; the description explains the mechanism behind that destructiveness ('an explicitly null field is CLEARED; omitted fields are untouched'). It also discloses side effects (goal_candidates from the profile) and the key intake/next_field return, adding real 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 core purpose is front-loaded, but the description is dense and runs long, particularly the intake {complete, next_field, ...} and goal_candidates clauses that return-value details an output schema could carry. It is informative but not tightly edited.

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 complex tool with a nested patch object, many optional fields and a large surface, the description covers the write/clear semantics, injury routing, and notable return behaviors. With an output schema present it need not detail every return field, so remaining gaps are minor.

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

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

Schema description coverage is 100%, so the baseline is 3; the description earns above it by clarifying null-clears-versus-omitted-untouched semantics, which the schema only partially states ('omitted fields are unchanged'). It adds genuine meaning to how the patch object should be constructed.

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 (persist) and resource (user-confirmed coach profile facts) and enumerates the fact categories it covers (goal, experience, schedule, equipment, injuries, preferences). It names sibling-adjacent concepts (upsert_goal's shape, add_injuries/resolve_injury_areas) but does not explicitly contrast itself with sibling write tools like update_session or upsert_goal.

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 context that only user-confirmed facts should be persisted and that it works mid-workout, and routes injury handling to add_injuries/resolve_injury_areas. However it never states when to prefer this tool over siblings such as upsert_goal, and offers no explicit exclusions.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, 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?

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is covered. The description adds genuinely non-redundant behavior: 'Fields omitted are left as they are, so a partial update is safe' and the identity/history inheritance from pool_slug.

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

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

Four dense but purposeful sentences, front-loaded with the core create-or-update semantics before the pool/identity nuance and the partial-update guarantee. No filler, though the middle sentence is quite long.

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

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

For a nested-object upsert with an output schema (so return values need not be described) and strong annotations, the description covers identity, visibility requirements and partial-update semantics. It is complete enough for correct invocation, with only minor gaps around the remaining optional fields.

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 description coverage is nominally 0% for the single `exercise` object, so the description must compensate — and it does, explaining id/name keying, the slug+pool_slug pairing, and which fields make a hand-written exercise visible. It adds meaning beyond the nested schema descriptions without fully enumerating every field.

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: 'Create or update an exercise in the user's catalog (keyed by its id/name).' It also distinguishes itself from the sibling search_exercise_pool by describing the pool-slug identity workflow, so an agent can tell this upsert apart from the read/import tools.

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

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

It clearly explains the two usage paths: saving a pool entry (slug as id plus pool_slug) versus writing a hand-written exercise, and it names the fields required for the latter to appear in the muscle map/app. It stops short of an explicit 'call search_exercise_pool first when…' routing statement, but the 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 flag destructive/non-idempotent, but the description adds substantial non-obvious behavior: featured=true auto-un-features other active goals, server rejects featured on frequency goals, goals are never deleted (status supersedes them), succession is two linked records, and the app never transitions goals on its own. 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?

Front-loads the create/update rule and the goal_type taxonomy before deeper domain rules; every paragraph carries information. It is dense and occasionally parenthetical-heavy, but for a deeply nested schema the length is defensible rather than padded.

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

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

Given a 1-param nested object with low schema coverage and an output schema present, the description covers the create/update mechanics, the goal_type matrix, validation constraints, succession, and featured/ratification rules. An agent has everything needed to call it correctly.

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

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

Top-level schema description coverage is ~0% (only goal_type/band have inline docs), so the description must compensate and does: it enumerates each goal_type shape with its required fields (e.g. maintenance=baseline_value+tolerance_pct, trend=exercise_id+metric no value), explains review_date, supersedes_goal_id, ratified, and the featured flag.

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 and immediately disambiguates create vs update with the `id` convention: 'Create or update a training goal (pass `id` to update)'. It then maps the full shape space of target.goal_type, letting an agent distinguish this from siblings like upsert_exercise and get_goals without opening any schema.

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

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

Gives clear contextual routing: pass `id` to update, source=new exercise ids come via upsert_exercise, list_exercises is the catalog source, and featured is rejected for frequency goals. It does not explicitly state when NOT to use this tool (e.g. use get_goals to read), so it stops short of the top band.

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