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 description discloses key behavioral details beyond the readOnlyHint annotation: it returns a prompt to be treated as instructions, may return an intake flow if intake is incomplete, and has specific fallback behavior for the today parameter. It also explains the timezone fallback and potential mismatch with user-facing numbers.

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 well-organized with clear paragraphs and inline code, and it avoids major redundancy. It is slightly verbose with meta-commentary about common model errors and internal fallback behavior, but these asides still provide practical guidance.

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

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

The description covers the tool's purpose, usage triggers, parameter semantics, output expectations, edge cases, and alternative tools. It is sufficiently complete for an agent to call the tool correctly without needing additional context.

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

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

Although the schema has no per-parameter descriptions, the narrative fully explains all three parameters: task includes its enum, default, and the check_in typo; constraints is clearly scoped to today-only; today is explained with timezone semantics and fallback behavior. This gives complete semantic coverage.

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's purpose: to retrieve coaching instructions and fresh training context for a given task, and it instructs to call it at the start of any coaching conversation. The resource is specific and distinct from sibling tools like get_program or 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?

It explicitly says when to use the tool ('Call at the start of any coaching conversation'), explains defaults and error behavior for omitted arguments, and points to update_coach_profile as the alternative for durable facts. It also clarifies the intended scope of constraints as today-only.

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

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

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?

Beyond the readOnlyHint annotation, the description discloses the null-return behavior, the dependency on an active program, the prohibition against inventing programs, and the import_document path for edits. This is meaningful behavioral context an agent needs to act correctly.

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, all informative: the first defines the resource, the second covers the null case and the proper build workflow, and the third names the edit path. No filler or repetition.

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

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

Given the tool has no parameters and an output schema exists, the description fully covers what the tool returns, the edge case of no active program, and the correct follow-up actions. Nothing essential is missing for an agent to select and invoke 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?

The tool has zero parameters and schema description coverage is 100%, so there is nothing for the description to add about parameters. The baseline for zero-parameter tools applies, and no parameter-related ambiguity exists.

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

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

The description states a specific verb and resource: 'Get the active training program with its day templates (planned blocks/supersets and per-exercise targets).' This clearly distinguishes it from sibling getters like get_session or get_goals by naming exactly what the tool returns.

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

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

It explicitly tells the agent when the tool returns null and exactly what to do in that case: 'call get_coaching_context(task='new_program') and follow it; never invent a program from generic knowledge.' It also routes editing to import_document, giving clear 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?

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 set readOnlyHint=true and openWorldHint=false, covering the safety profile. The description adds useful behavioral context by disclosing the sort order ('newest first') and the included summary volume field, but it does not disclose pagination or behavior around the limit parameter. With annotations covering mutation risk, this is adequate 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?

Two short sentences with no filler. The core action and output characteristics are front-loaded, and the optional date-range qualifier is placed at the end. Every word adds value.

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 list operation with only optional parameters and an output schema, the description is mostly complete. It provides the ordering and key output facts, and the output schema handles return-value details. The main gap is that limit is not addressed, and the scope of 'sessions' (all vs. user-specific) is implicit rather than explicit.

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, but it only says 'Optional date range,' which mostly restates the nullable date_from/date_to parameters. The limit parameter is not described in the schema or the description, and no format or boundary semantics for the date range are given.

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

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

The description opens with a specific verb and resource ('List sessions') and adds scoping details: newest-first ordering, summary fields with total volume, and optional date range. This clearly separates it from sibling get_session, which implies retrieving a single 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 intended use case is implied — call this to get a list of workout sessions, optionally within a date range. However, there is no explicit when-to-use/when-not-to-use guidance or mention of alternatives like get_session or get_stats, so the agent must infer the choice.

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 declare readOnlyHint=true and openWorldHint=false. The description adds crucial behavioral detail: defaulting to 'volume' so empty calls succeed, exercise_id being required for progression/prs but ignored for volume, and the exact error case when calling progression/prs without it. This meaningfully extends the annotation signal and includes real usage data for why the default matters.

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 long but every sentence earns its place: scope, param naming, default behavior, requirement constraints, return summaries, and alternative tool routing. It is front-loaded with the core purpose and then proceeds logically, with no filler or repetition.

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

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

For a 3-parameter tool with a rich output schema, the description covers parameter dependencies, default behavior, error conditions, and alternatives. The only notable gap is the lack of any explanation for date_from. That said, the output schema exists and the parameter is self-describing enough that the overall completeness is high.

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 full responsibility for parameter explanation. It thoroughly explains 'kind' (all three enum values and their semantics) and 'exercise_id' (required vs ignored contexts). However, 'date_from' appears in the schema but is never mentioned in the description, leaving its meaning entirely implicit.

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

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

The description opens with a precise scope: 'Statistics for ONE exercise, or for training as a whole.' It clearly defines the resource and distinguishes the tool from get_coaching_context, which is the main sibling overlap. The verb is implied by the title, and the description adds specificity about the three kinds of statistics.

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 guidance is provided throughout: 'For coaching decisions ... start from get_coaching_context instead' names the alternative and the condition for using it. It also tells the agent when to pick an exercise_id from list_exercises first, and when to default to kind='volume'. This is far beyond a vague hint.

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 destructiveHint=true, readOnlyHint=false, idempotentHint=false, and the description adds substantial context on top: ok=false means nothing written, the previous program is archived only when the incoming one is 'active', retrying a batch writes nothing, and the file-is-data warning. It even discloses the refusal code 'active_program_changed'. No contradiction with 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?

Long, but every sentence carries genuinely non-obvious behavioral weight for a destructive tool — no filler or restatement of the schema. The critical safety precondition ('Import ONLY after the user has seen what you parsed and said yes') is front-loaded. Slightly dense for an opening line but justified by the tool's complexity.

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, deeply nested, destructive import tool with an output schema present, the description covers every critical surface: safety confirmation, mode semantics, replace-existing flow, batching idempotency, error reporting ('quote those numbers'), and the prompt-injection guard. Nothing an agent needs to invoke 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?

Schema description coverage is 0%, but the description adds real meaning to program_mode (the coached vs preserve semantics), import_batch_id (stable per-batch id, reused only for retry), source (namespaces record ids), and the expected_* revision pair. The giant `document` param is not covered in the description, but its nested schema is richly self-documented (date, rir, weight_kg, etc.), so the burden is adequately met overall.

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

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

The description opens with a specific verb and resource: 'Bulk-import a full workout document (exercises, sessions, body metrics, programs)'. It clearly differentiates from siblings like log_session (single-session logging) and the various get_* readers by the bulk scope. An agent can immediately tell this is the high-volume ingestion 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?

Exceptionally explicit. It states the precondition ('Import ONLY after the user has seen what you parsed and said yes'), routes program_mode via get_coaching_context(task='new_program') for 'coached' versus a user's own file for 'preserve', tells when to read get_program for expected_active_program_id/expected_revision, and explains batching with import_batch_id/source. Every decision point names its alternative tool.

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, covering the safety profile. The description adds useful behavioral context by clarifying that this lists only the user's own trained exercises (not the global pool) and that filters narrow that catalog. This goes beyond what the annotations alone convey.

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

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

Two tightly written sentences front-load the core purpose and scope, then list the filters, then give the routing guidance to the sibling tool. There is no filler or repetition of schema details.

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

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

The description is complete for a read-only filterable list tool: it states the resource, the returned metadata categories, all optional filters, and the decision boundary versus search_exercise_pool. An output schema exists, so return-value details are not required here.

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 meaning. It names all four parameters and explains the query parameter specifically as a substring of name or id. It does not elaborate on accepted values for muscle, equipment, or movement_pattern, but it clearly marks them as optional filters.

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 ('List') with a clear resource ('THIS USER's own exercise catalog') and explicitly distinguishes it from search_exercise_pool. It also enumerates what is returned (logged metadata such as instructions, video_url, image_url, pool_slug), making the tool's scope 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 gives explicit guidance: use this tool to reuse an id the user already has, and use search_exercise_pool to choose a NEW exercise. This directly addresses when to choose this tool over the most relevant sibling.

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

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

Goes well beyond the idempotentHint and destructiveHint annotations by explaining one-entry-per-date merging, overwrite-on-repeat, null-to-clear behavior, no-delete policy, and the full-entry return value. This gives the agent a precise model of the mutation semantics.

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 dense but every sentence earns its place, front-loading the core purpose and then systematically covering usage, merge behavior, correction, clearing, and return value. No filler or repetition of schema details.

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 a nested parameter object and subtle update semantics, the description covers when to use it, how it differs from siblings, what the merge/overwrite/null behaviors are, how IDs relate to import_document, and what the response is. 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?

Adds critical merge semantics that the schema alone does not convey: omitted fields keep their stored values, new keys join existing ones, repeated keys overwrite, and null clears a field. It also tells the agent to send only what the user just stated, which is essential for correct partial updates.

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: 'Record the user's body weight, body-fat % or circumferences for one day.' It also names the sibling alternatives (log_session, get_body_metrics) to prevent 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?

Explicitly instructs when to use it ('whenever the user states a current measurement') and where other operations belong ('training goes to log_session, reading measurements back is get_body_metrics'). Also clarifies that these entries feed the app's weight tile and coaching context, not the profile 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 already flag readOnlyHint=false and idempotentHint=false, but the description adds crucial context: each call is a new entry (non-idempotent), the history is write-only ('no tool reads it back'), and it does not replace persistent storage via other tools. It also clarifies that the history rides along with the user's data export, which is not obvious 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?

The description is dense but every sentence earns its place: purpose, exclusions, idempotency warning, persistence note, return value. It front-loads the core action and then systematically addresses edge cases. 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 write-only event logger with an output schema and clear annotations, this description covers all decision points: when to call, what types exist, how to format payload, when to omit, repetition risk, and persistence semantics. An agent has everything needed to call it correctly without external lookup.

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 parameters are documented, but the description adds real value: it explains the payload's purpose with concrete examples per event type and says when to omit it. It also ties the type enum to the coaching-prompt step, which is more than the schema's generic 'Which milestone happened.' This goes beyond the baseline.

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

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

The description opens with a specific verb+resource ('Append a dated milestone to the user's coaching history') and immediately enumerates the exact event types it records. It explicitly names sibling tools (log_session, upsert_goal) to disambiguate, leaving no doubt about what this tool is for.

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 timing ('at the end of the step the coaching prompt names'), explicit exclusions ('not for ordinary chat, logged workouts (log_session) or goal edits themselves (upsert_goal)'), and a caution about non-idempotency ('Each call adds a new entry, so do not repeat one'). This is textbook when-to-use 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?

Beyond annotations (readOnly=false, destructive/idempotent hints), the description reveals return behavior including auto-created exercise catalog entries, a coach_hint server note, and the UI consequence of omitting duration_sec. It warns against duplicate logging, which is particularly relevant given destructiveHint=true and idempotentHint=false.

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?

Every sentence earns its place: overview, return behavior, coach_hint, planning alternative, AIm-app exclusion, and duration guidance. It is long because the tool is complex, but it is front-loaded and structured logically.

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 nested-parameter creation tool, the description covers the primary use, key exclusions, side effects/returns, and a critical parameter guidance. With a rich output schema and nested parameter documentation, nothing essential for selecting and invoking the tool 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?

There is only one top-level parameter and the schema has no description on it, but nested properties carry extensive detail. The description compensates by explaining duration_sec must be set and by clarifying what the response contains; it does not need to re-explain the already-detailed nested schema.

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

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

The description states a specific action and resource: 'Log a completed workout session (exercises → sets, cardio, wearable metrics) at once.' It also differentiates from siblings by explicitly saying not to log sessions already recorded by the AIm app and to use get_sessions/get_session instead.

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

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

It gives explicit when-to-use and when-not-to-use guidance: call get_coaching_context first for planning, and do NOT re-log workouts already stored by the AIm app but read/correct via get_session/update_session. It also tells the agent to ask for duration instead of guessing.

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 readOnlyHint=true, and the description reinforces and extends this: 'Saves nothing, and creates nothing: reviewing somebody's file is not the start of a coaching relationship.' It goes beyond the annotations by disclosing the exact return contract ({ok, mode, violations, warnings, unresolved, notes}) and the meaning of `unresolved` ('lists fields the file never stated — ask about those; never fill them in'). This is rich behavioral context that the readOnlyHint alone would not convey.

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

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

Three dense paragraphs with the purpose and timing front-loaded, followed by the mode differentiation and the return contract. Every sentence carries information — the mode explanation is lengthy but necessary given the two divergent behaviors. Minor redundancy: 'Saves nothing, and creates nothing' restates readOnlyHint, but the coaching-relationship framing adds value. No wasted words for a tool of this complexity.

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

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

The description covers the full decision surface: when to call, what it validates (day references, exercise identifiability, rep ranges, weight/equipment/schedule in coached mode), the mode-specific behavior, the return contract, and the semantic of `unresolved`. With a rich input schema and an output contract disclosed inline, nothing an agent needs to call it correctly is missing. Only the document's internal structure is left to the schema, which is appropriate.

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

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

Schema description coverage is 0%, so the description must compensate — and it does substantially for program_mode, explaining both enum values' behavioral consequences (coached enforces starting weight/equipment/schedule; preserve downgrades mismatches to warnings). The document parameter is handled by reference ('the same WorkoutDocument you intend to import'), tying it to import_document's input. It doesn't enumerate the document structure, but the schema already carries that detail, so the pointer is sufficient.

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

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

The description opens with a specific verb+resource: 'Server-side checklist for a DRAFT training program' — a validation/verification tool, clearly distinct from its siblings. It explicitly differentiates itself from import_document ('Use the same mode you will pass to import_document'), so an agent can tell them apart without opening the schema. The name, title, and description are mutually consistent.

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 guidance: 'Call it with the same WorkoutDocument you intend to import BEFORE presenting the draft to the user' — this sets the sequencing against import_document. It further explains the two modes ('coached' default vs 'preserve' for user's own file), telling the agent exactly when each applies and to mirror the mode passed to import_document. Nothing is left to inference.

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

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

Annotations already carry readOnlyHint=true and openWorldHint=false, and the description adds substantial behavior beyond those: equipment filtering semantics ('only exercises fully covered by it are returned'), the instruction to reuse the canonical slug verbatim as exercise_id, the meaning of in_user_catalog, and the returned data shape (localized names, technique cues, muscle tiers, rep/rest defaults). Nothing here contradicts the annotations; the open-world hint is consistent with 'curated global exercise pool.'

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

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

Four sentences, each earning its place: core purpose and when to use it, filter semantics, return-content and slug contract, and the fallback boundary. The most decision-relevant information is front-loaded in the first sentence, 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 7-parameter, all-optional, no-enum search tool, the description covers the important semantics and an output schema exists to document return values. Remaining gaps are the conjunction behavior of multiple filters (AND vs OR), the effect of `limit`, and the role of `locale` — minor but nonzero for fully correct invocation.

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

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

With 0% schema description coverage, the description carries the burden and compensates well: `muscle` gets concrete examples ('lats', 'side_delts'), `equipment` gets coverage semantics, and `query` gets 'a name in any supported language.' However, `limit` and `locale` are left undocumented in both the schema and the description, so the compensation is strong but incomplete.

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

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

The description opens with a specific verb+resource — 'Search the curated global exercise pool' — and frames it as 'THE place to pick exercises from when building a program or a workout,' which sets it apart from sibling list/upsert tools. The scope ('curated global') and the distinction between the pool and user-catalog entries ('in_user_catalog marks the ones this user has trained before') make its role unmistakable.

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 when-to-use context ('when building a program or a workout') and a when-not boundary ('Invent your own exercise only when nothing here fits'), which effectively routes the agent to a creation path when search fails. However, no sibling tool is explicitly named as an alternative, and the closely related `list_exercises` sibling is never addressed, leaving some routing to inference.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, and idempotentHint=true. The description adds meaningful behavioral context beyond those: null fields are CLEARED while omitted fields are untouched, partial PAR-Q answers merge into previously stored flags, and the return value includes changed fields and ui_impact. It also explains that bone_joint_problem is deliberately excluded from clearance gating. This is substantial added context, though it doesn't cover every edge case.

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 dense but every sentence earns its place: it states the action, the timing, the null semantics, the injury routing, and the return-value usage. It is front-loaded with the core purpose and the most important usage rule. No filler or repetition of schema content.

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 nested objects, an output schema, and 1 parameter, the description covers the critical operational details: when to call, how to handle nulls, how to handle injuries, and what to do with the response. The output schema exists, so the description needn't explain return values in detail, but it still tells the agent to confirm to the user that the answer was saved. Nothing essential is missing.

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

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

Schema description coverage is 100%, so the schema already documents the patch object and its fields. The description adds value by explaining the semantics of null vs omitted fields, the one-fact-per-call convention, and the special handling of injuries and PAR-Q flags. It doesn't enumerate every field, but the schema already does that, so the description's semantic additions are appropriate.

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

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

The description states a specific verb ('Persist facts the user confirmed') and a clear resource (the coaching profile), and enumerates the fact categories (goal, experience, schedule, equipment, injuries, preferences). It also distinguishes injury handling from the main tool by routing to add_injuries and resolve_injury_areas, which separates it from 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?

The description gives explicit when-to-call guidance: 'Call as soon as a fact is confirmed — one fact per call is fine, don't batch or wait for the end of the conversation; works mid-workout too.' It also names alternatives for injuries (add_injuries, resolve_injury_areas), which is clear routing versus sibling tools.

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

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

Annotations already declare 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?

Discloses merge semantics beyond what annotations provide: 'Fields you omit are left as they are, so a partial update is safe' — this is exactly the behavioral trait an agent needs for an upsert. The description also adds identity/history preservation context and the consequence of missing fields (blank muscle map/UI). consistent with readOnlyHint=false, destructiveHint=true, and idempotentHint=true; no contradiction.

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?

Roughly 110 words with no filler. The core action is front-loaded, followed by the preferred route, the fallback route with conditional requirements, and the merge safety note. Each sentence earns its place and the structure mirrors the agent's decision flow.

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?

Complete for a write tool of this complexity: it covers the primary decision (pool vs hand-written), the merge behavior, and the fields that must be set in the fallback case. The output schema exists so return-value explanation isn't needed, and the input schema carries detailed field semantics. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 0%, so the description must compensate, and it does for the critical parameters: id (pass pool slug as it), pool_slug, instructions, primary_muscles, category, and equipment. It adds meaning beyond the schema by explaining the conditional requirement ('the muscle map and the app UI are blank without them') and the id/slug relationship. It doesn't cover every field, but the schema's own rich per-property descriptions carry the rest.

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 an exercise in the user's catalog (keyed by its id/name)'. It clearly distinguishes itself from siblings by naming search_exercise_pool as the lookup step and explaining the relationship, so an agent can tell exactly what this tool does versus list_exercises or 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?

Gives explicit when/when-not guidance: 'Prefer a pool exercise: call search_exercise_pool first...' and 'Only hand-write an exercise when the pool genuinely has nothing for it'. It names the alternative tool directly and specifies the exact call pattern (pass slug as id plus pool_slug), 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?

Beyond the annotations (destructiveHint=true, readOnlyHint=false), the description reveals that setting featured=true automatically un-features other active goals, that the server rejects featured on frequency goals, that unknown exercise_ids are rejected, that coach-proposed goals start with ratified=false, and that goals are never deleted but superseded. This is rich behavioral context the annotations alone cannot provide.

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 long but proportionately so for a tool with a deeply nested goal object and multiple workflow rules. It is front-loaded with the core operation, then systematically covers each goal type, validation constraints, featured behavior, and lifecycle transitions. Each paragraph earns its place with non-redundant, actionable guidance.

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

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

The description covers nearly every meaningful field and behavior, and the output schema exempts it from explaining return values. However, the required 'kind' enum (outcome/process/performance) is never explained and has no schema description (coverage 0%). While goal_type is thoroughly handled, the distinct concept of 'kind' remains underdocumented, leaving a gap for agents that must populate this required field 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?

With schema description coverage at 0%, the description fully compensates by explaining the semantic meaning of goal_type values (milestone, weekly_volume, trend, maintenance, plain process), their required nested fields (e.g., muscle+band for weekly_volume, baseline_value+tolerance_pct for maintenance), and the roles of id, featured, status, ratified, review_date, and supersedes_goal_id. The raw schema only lists enums and null types, so the description adds decisive value.

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 opening sentence 'Create or update a training goal (pass `id` to update)' names a specific verb, resource, and the key update selector. It also enumerates all goal_type variants and their field requirements, making the tool's purpose unmistakable and clearly distinct from sibling tools like upsert_exercise and get_goals.

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

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

The description gives explicit operational guidance: when to update (`pass id`), when to check list_exercises and use upsert_exercise for new exercises, when to avoid featured (frequency goals), and the required two-call workflow for achieved milestones. It also states the hard rule 'Never delete goals — supersede with status=revised/abandoned/achieved', leaving no ambiguity about appropriate use.

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