Wellness Project

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

Beyond the annotations, the description discloses that writes happen immediately with no separate approval step, that free accounts are capped at 3 memories and Pro at 50, that updates by id are allowed even at the cap, and that there is no delete/bulk capability. This meaningfully extends what the annotations alone communicate.

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 longer than typical, but each paragraph earns its place: purpose, do-not-duplicate workflow, exclusions for structured health data, and write/cap behavior. The core action is front-loaded before broader guardrails.

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 3-parameter tool with full schema coverage, an output schema, and meaningful annotations, the description closes the important gaps: when to update vs add, what content belongs, what caps apply, and why duplicate structured records should be avoided. No critical dimension appears 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 schema already covers all three parameters at 100%, but the description adds real semantics: it clarifies that content must be a compact durable fact/preference, illustrates valid content with examples, and explains the relationship between memory_id and operation update in the list-first workflow.

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: 'Add a new Personal Context memory, or update an existing one by id.' It also distinguishes itself from nearby tools in the sibling list by explaining that memories are durable circumstances/preferences and that structured health data belongs in other dedicated 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 gives explicit, actionable guidance: use list_personal_context first, pass the existing id with operation update instead of duplicating, and avoid storing metrics/trackable health data here because dedicated tools exist for those. This is strong when-versus-alternative guidance.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the agent knows this mutates state and is safe to retry. The description adds only that the target is a 'previously declared' status of one of three types; it says nothing about permissions, error behavior on a non-existent day, or reversibility beyond what annotations already cover.

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

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

Two short sentences with the mutation front-loaded and the inference rule clearly separated; no filler. Slightly verbose in enumerating the three status types, but nothing wasted.

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

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

An output schema exists so return values need no prose, the single parameter is fully documented in the schema, and annotations cover the destructive/idempotent profile. For a one-parameter undo tool, this is nearly complete; only edge behavior on missing entries is unaddressed.

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

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

Schema coverage is 100% and the single parameter's description already includes 'Format: YYYY-MM-DD. Default: today.' The description's 'default to today' and inference instruction duplicate rather than extend the schema, so baseline 3 applies.

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

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

States a specific verb (Remove/cancel) and a precise resource (previously declared Rest Day, Sick Day, or Travel Day status), which is clearer than the tool name alone and distinguishes it from log_rest_day/list_rest_days. It does not, however, explicitly name the sibling it complements.

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

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

The phrase 'previously declared' implies this is for undoing an existing marking, and the INFER block gives concrete invocation guidance for the date. There is no explicit when-not-to-use or named alternative (e.g., log_rest_day to re-mark), so the guidance remains implied rather than stated.

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 idempotentHint=true, so the destructive nature is covered. The description adds valuable behavioral detail: exactly one of id or date is required, date resolution matches only the period start date or any date within it, and an ambiguous match causes an error that returns candidate IDs to retry with. This goes beyond the structured 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 compact and front-loaded with the core purpose, followed by usage constraints and selector details. Every sentence earns its place, with 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 2-parameter destructive tool with annotations and an output schema, the description is complete. It covers what the tool does, when to use it, when not to use it, how to select the target, and how ambiguity is handled. 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 coverage is 100%, so the schema already documents both parameters. However, the description adds important semantics: 'Exactly one required' clarifies the optional-looking schema, and it explains how date resolves and what happens on ambiguous matches. This meaningfully aids correct invocation beyond the schema alone.

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

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

The description states a specific verb and resource: delete a period record. It explicitly distinguishes itself from update_cycle, telling the agent it must not use this tool to 'fix' a record. This makes it easy to tell apart from the sibling update_cycle 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?

Provides explicit when-to-use guidance: only when the user explicitly asks to remove a specific record. It also gives a clear exclusion and alternative: do not delete to fix a record; use update_cycle instead. The selector instructions further clarify how to invoke it correctly.

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 mark this destructive, but the description adds meaningful behavioral context: deletion is permanent, severity history is also removed, and ambiguous injury matches cause an error returning candidate IDs. This goes well beyond the structured hints and clearly sets expectations for side effects.

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 compact and front-loaded: effect first, side effect second, then selector rules. Each sentence earns its place and no information is repeated from the schema or annotations. The use of an em-dash separator and explicit rule statements makes it easy to parse.

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 output schema exists and annotations cover safety, the description supplies everything else needed: selection strategy, disambiguation behavior, requiredness despite no schema-required params, and destructive consequences. The tool is fully usable based on this description alone.

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

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

Schema coverage is 100%, so the baseline is met. The description adds value by explaining the mutual exclusivity between id and injury, the exact-one-required contract, the role of date as a narrowing filter, and the error behavior on ambiguous matches — all beyond the schema's individual property 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 and resource: 'Permanently delete an injury entry.' The scope is precise, and naming the cascading removal of severity history distinguishes this from update_injury and log_injury. An agent can tell exactly what this tool does and what side effects come with it.

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

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

Provides clear operational guidance: how to choose between id and injury, when to use date to narrow, and that exactly one selector is required. It does not explicitly discuss alternatives like update_injury for non-destructive changes, but the selector guidance is detailed enough for practical use.

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 mark destructiveHint=true and idempotentHint=true, but the description adds crucial behavioral context: deletion is irreversible, date-scoped deletes can remove many rows, and ambiguous dates are rejected with nothing deleted and candidate IDs returned. This fully discloses what gets destroyed and how failures behave.

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 block earns its place given the destructive and ambiguous nature of the operation. The core action and use condition are front-loaded, selector rules are organized, and the AMBIGUITY section handles the trickiest behavior clearly. No filler or repetition beyond what improves safe usage.

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

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

For a destructive tool with five optional parameters and complex selector semantics, the description covers the key decision space: which selector to use, how ambiguity is resolved, what is irreversible, and when to confirm with the user. The output schema exists, so return-value details do not need to be repeated here. Nothing critical is missing for correct invocation.

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

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

Schema coverage is 100%, yet the description adds substantial meaning beyond the schema: pass exactly one selector, marker matching is a case-insensitive substring, draw_id deletes all rows sharing that label, and panel_name narrows date selectors. It also explains resolution and rejection behavior that the schema alone cannot 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 opens with a specific verb and resource: 'Permanently delete one or more lab results.' It clearly distinguishes this destructive action from the sibling update_lab_result and the many list/log tools, and even states the triggering user intent. The selector breakdown reinforces exactly what the tool operates on.

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

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

It explicitly says when to use the tool: when the user asks to remove or delete a logged lab result. It also provides strong exclusions and guardrails: 'Never guess a selector,' warns about ambiguity, and instructs confirming with the user before date-scoped deletes. This goes well beyond implied usage and actively prevents misuse.

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 flag the operation as destructive, but the description adds meaningful behavioral detail: the action is irreversible, ambiguous matches return an error with nothing deleted, retries should use id or a narrower name, and linked hydration/caffeine events are removed automatically. This goes well beyond the annotation metadata and directly shapes safe invocation.

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 longer than average, but every section earns its place. The intent is front-loaded in the first sentence, and the FIND THE MEAL / HYDRATION / CAFFEINE sections are clearly labeled and logically separated, making the content easy for an agent to parse and apply.

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

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

For a destructive, ambiguity-prone delete operation, this description covers the entire invocation context: how to identify the target, what happens on failure, retry guidance, and automatic cascade behavior for linked records. An output schema exists to cover return values, so 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?

Although the schema already has a strong 100% coverage with per-parameter descriptions, the tool description enriches those semantics with the decision tree: id takes priority, date defaults to today, and name is only a disambiguator used when multiple meals were logged that day. It even warns that an ambiguous match will error and the agent should never guess, which is genuinely useful parameter-level guidance.

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 'Permanently delete a meal entry,' naming the exact verb and resource. It also states the precise user-intent trigger ('when the user explicitly asks to remove or delete a logged meal'), which clearly differentiates it from update_meal and the other meal-related 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?

The description gives an explicit when-to-use condition and then expands into a structured disambiguation protocol: use id if known, otherwise date, and add name only when multiple meals exist on that date. It also provides strong exclusions, telling the agent not to issue separate hydration or caffeine delete calls because the database handles those cascades.

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 signal destructiveness and idempotency, and the description adds irreversibility, ambiguity-handling guidance, and the error behavior with candidate IDs. The description and annotations align, and the additional context meaningfully exceeds what annotations alone 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 front-loaded with the most important facts (permanence, irreversibility, ambiguity handling) followed by a compact selector block. Every sentence adds operational value and there is no filler or redundancy.

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

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

Given the tool's destructive nature and the non-obvious selector logic, the description fully equips an agent to call it correctly: it covers user clarification, parameter selection, ambiguity resolution, and error recovery. The output schema and annotations cover remaining details, so nothing material is missing.

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

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

Schema coverage is 100%, but the description adds crucial cross-parameter semantics: the selector relationship between id and session_date, the optional narrowing role of session_category, that session_category is ignored when id is given, and the exactly-one-required constraint. This goes well beyond the baseline schema 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?

The description states a specific verb ('Permanently delete') and a specific resource ('a recovery session log entry'), clearly distinguishing it from sibling delete/update/log tools. The title annotation adds a parallel label, and the resource is unambiguous against the large set of sibling 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?

Explicitly instructs the agent on when to ask the user for clarification, how to resolve the target session using either id or session_date, and what to do if multiple sessions match. It also clearly states that exactly one of id or session_date is required, which is not reflected in the schema's required parameters.

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 supply destructiveHint and readOnlyHint; the description adds deletion-safety behavior such as the id-or-date selector, approximate 0.25 mi matching, an error-with-candidate-IDs failure mode, and a confirmation rule. This is valuable context beyond the annotations and does not contradict them.

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 useful selector guidance is buried after four lines of UNIT INPUTS instructions for parameters that do not exist on delete_run. This is not front-loaded and wastes tokens; the whole message could be reduced to two focused sentences.

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 output schema and annotations, the description covers the full calling flow: selector, one-of requirement, confirmation when ambiguous, and behavior on multiple matches. The irrelevant unit preamble subtracts from comprehensibility, but no critical deletion-handling detail 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?

With 100% schema coverage the baseline is 3; the description adds the essential one-of constraint ('Exactly one of id or date required') and explains id-first selection and distance narrowing. The unrelated UNIT INPUTS block is confusing noise, but the selector paragraph genuinely augments the schema.

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

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

Core statement 'Delete a run' and 'Use when the user wants to remove a run entry' name a clear verb and resource, distinguishing delete_run from sibling delete_* tools by target. But the opening UNIT INPUTS block references parameters like value/alternate_unit/canonical_unit/precedence that are not in the schema, which muddies the first impression.

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 says to use it when the user wants to remove a run entry and tells the agent to ASK for confirmation if intent is ambiguous. It does not name specific alternative tools or exclusion cases, but the run-targeted scope is enough to route the agent correctly.

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 reinforces the destructive nature ('Permanently delete') and adds transparency about the idempotent behavior (error with candidate IDs on ambiguous date). It goes beyond the annotations by detailing the exact failure mode and retry guidance.

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 compact yet complete, comprising two sentences and a selector note. Every word contributes to usage clarity, with no redundant or vague statements.

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 delete operation, the description covers all necessary context: target, selector, exclusivity, and error handling. The lack of output schema details is acceptable since a delete confirmation is standard and does not hinder usage.

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?

Both parameters (id and date) are fully described in the schema and the description, including the semantics of date ('any day within the entry's period') and the exclusivity requirement. High schema coverage combined with clear prose makes parameter usage unambiguous.

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 action ('Permanently delete') and the target ('a wellbeing entry'), with no ambiguity. It effectively distinguishes this from sibling tools like update or log by specifying deletion and the selector mechanism.

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 explains when to use the tool by providing a selector rule: pass id or date, exactly one required. It also describes the error condition when the date matches multiple entries, giving clear guidance for resolution.

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 mark destructiveHint=true and idempotentHint=true, but the description goes well beyond: it states the action is irreversible, removes the session, all supersets, and all sets, and explains that a non-exact match returns an error with nothing deleted. It also clarifies that saved_workout_id does not touch completed workout history, providing full behavioral disclosure.

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-structured with clear sections: the core purpose, 'FIND THE SESSION' instructions, and 'SAVED WORKOUTS' alternative. It front-loads the primary use case, then provides necessary lookup steps, and every sentence adds value without redundancy.

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

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

For a destructive tool with multiple targeting methods, the description covers irreversibility, error behavior, parameter interactions, and the alternative mode for saved workouts. An output schema exists, so return values are presumably documented elsewhere. No critical information is missing for an agent to call it correctly.

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

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

Schema coverage is 100%, so each parameter already has a description. The tool description adds crucial usage logic: session_id is preferred and never to be guessed, session_date defaults to today, name is a case-insensitive substring for disambiguation, and saved_workout_id switches the operation to delete a reusable prescription. This clarifies parameter interactions beyond the schema.

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

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

The description clearly states the tool permanently deletes a workout session and all its exercises and sets, which is a specific verb+resource. It also distinguishes between deleting a logged session and a reusable Saved Workout, making it distinct from sibling delete_* tools like delete_cycle or delete_meal.

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 'Use when the user wants to remove a logged workout entirely' and provides a detailed decision path: pass session_id if known, otherwise session_date and name for disambiguation, and saved_workout_id for the reusable prescription. It also warns against guessing and directs retries with a narrower name or session_id.

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/idempotent/non-destructive/no-open-world, and the description adds substantial behavior beyond them: the result carries its own grounding rules, published video links may be included, pricing answers must be reproduced verbatim with exactly one message and the supplied link, and the app attaches its own upgrade button so the agent must never emit its own CTA markup. That is unusually rich operational context.

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

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

Four paragraphs, but each is front-loaded on its rule (purpose, closed-book, exercise routing, pricing) and every sentence carries a distinct constraint. Dense rather than padded, though the length is at the upper edge of what an agent can absorb at selection time.

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

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

An output schema exists so return values need no explanation here, and the description covers the remaining gaps: which topics to pick, how to handle pricing output, the grounding requirement, and the sibling alternatives. Nothing needed to invoke or interpret this tool 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% and the enum already defines every topic value in detail, so the baseline is 3. The description adds the routing principle ('select the relevant feature topic', 'narrowest relevant area') and the pricing-topic constraint, but mostly reinforces what the schema already documents.

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: 'Look up customer-facing Wellness Project product knowledge,' and immediately enumerates the domains it covers (navigation, features, integrations, metrics, logging, permissions/sync, troubleshooting). It also explicitly separates itself from a sibling by naming list_exercises as the tool for exercise-library questions.

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 routing rules: use list_exercises for exercise names/library membership, use topic=pricing for all cost/upgrade/limit questions, and select the relevant feature topic for how-to questions. It also states the closed-book constraint (answer from this result, never from memory), which is exactly the kind of when/when-not guidance an agent needs.

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

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

Annotations already establish readOnly, idempotent, non-destructive, closed-world. The description adds genuine behavioral detail beyond them: that the PR is always all-time regardless of since_date, that banded and unbanded PRs appear side-by-side, rep-range bests, and that since_date narrows only the Recent block. Some return-content detail overlaps the output schema, keeping this just short of a 5.

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

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

Strongly front-loaded and organized under USE FOR / NOT for / INFER headers, with the scoping constraint stated first. Slightly long overall, but no sentence is clearly disposable, so a 4 rather than a perfect score.

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 tool with rich annotations, a full output schema, and three fully documented parameters, nothing an agent needs to invoke it correctly is missing — selection criteria, argument inference, and the since_date/PR interaction are all covered.

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

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

Schema coverage is 100%, so the baseline is 3, but the description earns extra: it clarifies exercise_name resolution (free-text resolved to canonical, or reports if never logged) and reinforces that since_date affects only the Recent block while the PR stays all-time. This adds meaning the schema states only in passing.

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 states a precise verb and resource — look up everything for ONE exercise, all-time PR plus recent performance across sessions. It explicitly contrasts against the two most confusable siblings (get_workout for a full session, list_workouts for a date-window list regardless of exercise), so an agent can route to 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 USE FOR block enumerates three distinct intents with example user phrasings (PR lookups, recent-activity, trend), and the NOT-for section names the exact alternative tools and the condition that selects them. The INFER block further tells the agent which arguments to derive rather than ask for.

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

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

Annotations already declare the safe read-only/idempotent profile, and the description adds substantial behavior beyond them: default resolution rules, the compact-vs-verbose output contract, coverage semantics ('based on foods with X data'), and the non-obvious rule that an active daily supplement counts on every day unless marked not taken. These are exactly the traits an agent cannot infer from 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 purpose and is clearly sectioned (INFER / FORMAT / DATA COMPLETENESS), so scanning is easy. It is on the long side and the FORMAT block partially restates the schema's format field, but the detail is load-bearing rather than 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 shape need not be re-explained, and the description nonetheless covers defaults, alias handling, output-format tradeoffs, and the statistical caveats (coverage, not a lab result, supplement-vs-food split). Nothing an agent needs to invoke this correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning: nutrient accepts common aliases (b12, carbs, fibre), format semantics explain how output changes per value, and default/omission behavior for date, days, and limit is spelled out. This exceeds what the schema alone conveys.

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+scope: top logged foods/supplements contributing to ONE nutrient over a day or range, ordered highest first. This clearly differentiates it from aggregation siblings like get_nutrient_summary and get_nutrient_history, and the example phrasings ('what gave me most of my sodium today') remove any ambiguity about what it 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?

Gives concrete usage triggers via quoted example questions, and the defaults section tells the agent how to proceed without asking. However it never explicitly names alternatives (get_nutrient_summary, get_nutrient_history) or states when NOT to use this tool, so the routing guidance is context-only 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 cover the safety profile (readOnly, idempotent, non-destructive), and the description adds substantial behavior beyond them: only dates with logged data are returned, the compact/verbose output distinction, and the non-obvious supplement rule (a daily supplement counts on every active day unless explicitly marked not taken). It also warns against misinterpreting intake as a lab result or a deficiency, which materially affects how the agent should report results.

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 purpose is front-loaded in the first sentence, and the INFER/FORMAT/DATA COMPLETENESS sections are clearly delimited. It is long, but the length is largely justified by the tool's complexity (two output modes, alias handling, supplement counting); some of the FORMAT prose could be tightened.

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

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

For a tool with an output schema, four parameters, and non-obvious data semantics, the description covers everything an agent needs: what is returned, which dates are included, default inference, alias support, and the caveats required to report intake honestly. Nothing material is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it confirms nutrient accepts common aliases ('b12', 'carbs', 'fibre'), restates the days/end_date defaults in user-facing terms, and explains what 'format' actually changes in the payload. This goes beyond the schema's field-level 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 and resource with scope: 'Day-by-day history for ONE nutrient over a range, with its target, how many days met it, and how many days went over the upper limit.' It also implicitly distinguishes itself from the aggregate sibling get_nutrient_summary (which it references for the nutrient dictionary) and from get_nutrient_contributors. An agent can tell exactly what this returns 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 concrete usage examples ('show my vitamin D over the last month', 'am I usually over on sodium') and explicit inference rules for days/end_date defaults, which is strong context. It does not, however, explicitly state when to prefer get_nutrient_summary or get_nutrient_contributors over this tool, so the routing is only implied.

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/idempotent/non-destructive, yet the description adds substantial extra behavior: coverage semantics ('totals are sums over items that carry a value'), the instruction never to call low intake a deficiency, food-vs-supplement split reporting, and the subtle default that an active supplement counts on every day unless explicitly marked not taken. These are genuine behavioral facts not derivable 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?

Well front-loaded (purpose first, then INFER/FORMAT/DICTIONARY/DATA sections) and everything is labeled, but the 44-entry ID dictionary dominates the length and is payload reference data that inflates the definition. Defensible because compact output is unreadable without it, but it is a lot of text for a tool definition.

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

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

An output schema exists, so return values need not be explained, yet the description still documents the two format modes and what each returns. Combined with the completeness caveats and default rules, an agent has everything needed to call this correctly and interpret the results.

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% (baseline 3), and the description goes further by spelling out resolution rules: timezone-local 'today', 'this week' -> days=7, alias handling ('b12', 'carbs', 'fibre'), and that days>1 returns a range average. Much of the date/days/format meaning still overlaps the schema text, so it is strong rather than exhaustive.

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 with scope: 'Summarize logged micronutrient (and macro) intake for one day or a short range, with each nutrient's target and coverage.' It also distinguishes itself from the related history/contributor tools by referencing them in the ID dictionary context, so an agent can tell what this tool uniquely returns (a period summary with targets) versus a history or contributor breakdown.

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

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

Gives concrete triggering phrases ('how's my vitamin D / sodium / iron this week', 'how are my micronutrients looking') and resolves the common inference cases (date=today, days=1, nutrients=all-but-amino-acids) with explicit 'do not ask' instructions. It does not, however, explicitly route against the sibling get_nutrient_history/get_nutrient_contributors for when a summary is preferable to a trend or breakdown, leaving one routing decision to inference.

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

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

Annotations already declare the operation read-only, idempotent, and non-destructive. The description goes well beyond this by explaining NSI scoring behavior at session, exercise, and set grains, disclosing that missing/wrong equipment tags can silently alter NSI scores, and explaining how saved workout prescriptions differ from completed sessions. This is rich, honest behavioral context that an agent would otherwise have no way to infer.

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 longer than average but well structured with labeled sections (NSI, EQUIPMENT, SAVED WORKOUTS) and front-loads the core purpose in the first sentence. Some detail, such as the equipment tag consequence, could arguably live in update_workout, but it is relevant here because it explains how to interpret the retrieved data. It is organized enough to remain navigable.

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 two parameters, rich output schema, and clear annotations, the description covers everything an agent needs: how to retrieve session details, how to interpret NSI and equipment fields, how to handle saved workouts, and how to recover from unknown IDs. There are no obvious gaps that would prevent correct invocation or interpretation.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful guidance beyond the schema: session IDs should be reused from workout tool results, unknown IDs should be resolved via list_workouts, saved_workout_id returns a prescription rather than a logged session, and the two IDs should not be combined. This materially helps an agent choose and populate the parameters correctly.

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 clear, specific verb and resource: 'Retrieve full detail of a workout session,' and enumerates the included data fields. It differentiates itself from list_workouts and update_workout by naming them, though it does not explicitly distinguish itself from the sibling show_workout, leaving some ambiguity about how the two compare.

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 explicitly states when to use the tool: for detailed questions about a past workout, reviewing training, confirming logs, or comparing to population standards. It also gives clear routing guidance for unknown session IDs ('list_workouts. Never guess') and for saved workouts, including a warning not to combine saved_workout_id with session_id. It does not mention show_workout as an alternative, but the provided context is strong.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior. The description adds valuable behavioral context beyond that: it is a search over public content, returns specific fields, and prescribes how results should be linked inline. This is more than the annotations alone provide, though it does not cover edge cases like empty results or error behavior.

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

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

The description is compact and well organized: purpose first, usage constraint second, return format and link handling last. Every sentence adds useful information, with no redundancy or 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?

This is a simple, optional-parameter read tool with a rich schema, output schema, and full annotations. The description covers when to use it, what it returns, and how to format links, so an agent has everything needed 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?

Schema description coverage is 100%, so all three parameters are already documented with types and descriptions. The tool description adds no new parameter semantics beyond the general search framing, which matches the baseline for fully covered schemas.

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: searching the public Crew Blog at /blog for advisor-authored posts. It clearly identifies what the tool returns and the /blog/<slug> link format, making its purpose unambiguous and distinguishable from the many list/show 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-use guidance: only when the user explicitly asks about the blog or what an advisor has written. It also provides a clear when-not-to-use instruction: don't volunteer posts in normal conversation. No sibling tool covers this same domain, so naming an alternative is unnecessary.

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 (readOnlyHint, idempotentHint, destructiveHint false), the description adds behavioral context: it states BMI in the output is derived from the user's canonical height and that day's resolved weight, and instructs the agent not to recompute it. It also explains default parameter behavior (infer 30 days ago to today). These details help the agent understand side effects and derived data, exceeding annotation-only transparency.

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 concise and well-structured. It covers purpose, usage conditions, range constraints, and behavioral notes without unnecessary verbosity. Each sentence serves a distinct purpose: identifying the resource, stating when to use, noting the 31-day limit, and explaining parameter inference. No fluff or redundant information.

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

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

Given an output schema exists, the description need not explain return values. It fully covers input parameters, defaults, usage context, range limits, and derived data behavior. The description provides all necessary information for an agent to invoke the tool correctly in various scenarios, making it contextually 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 schema descriptions for start_date and end_date specify format (YYYY-MM-DD) and defaults ('30 days ago', 'today'). The description reinforces these defaults and adds the 'INFER — do not ask' guidance, making the parameter semantics fully clear. Schema coverage is 100%, and no enums exist, so the description effectively complements the schema.

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

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

The description clearly states the tool lists body composition entries within a date range. It specifies the resource ('body composition entries') and scope ('date range'), and the context signals show sibling tools include similar list tools, enabling an agent to distinguish this from list_workouts, list_meals, etc. The verb 'list' and explicit resource make the purpose 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 explicitly states when to use the tool ('when the user asks about their weight history, body fat trend, or any body metrics over time'). It also provides guidance for handling longer periods by making multiple calls with sequential date ranges, and instructs the agent to infer default parameters rather than asking the user. This gives clear, actionable usage instructions.

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

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

Beyond the readOnly/idempotent annotations, the description discloses important behavioral details: the 366-day limit, daily totals covering all doses, the dose list capping at 200 most recent, and that omitted doses are reported. It also explains default date behavior via the INFER note.

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 compact, front-loaded with the core purpose, and uses a clear INFER section for defaults. No sentence is wasted; the behavioral limits and use cases are presented efficiently.

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 presence of an output schema and comprehensive annotations, the description covers all necessary operational context: purpose, defaults, limits, and truncation behavior. An agent has enough information to invoke the tool correctly without further inference.

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

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

Schema coverage is 100% and each parameter already has a clear description. The tool description adds value by explaining the default range behavior ('from/to default to the last 14 local calendar days through today') and by framing parameters in terms of local calendar dates.

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: 'List caffeine doses by local date with daily totals.' It also clarifies its intended use cases ('caffeine history or today's total'), making it distinct from other list tools like list_sleep or list_meals.

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 explicitly says 'Use for caffeine history or today's total,' which gives clear usage context. It does not mention alternatives or when not to use it, but the use cases are specific enough for an agent to select it correctly.

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, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds useful behavioral context beyond annotations: it clarifies date-range scoping, explains the relationship to update/delete operations, and instructs the agent to infer defaults rather than ask the user.

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 compact and front-loaded with the core purpose. The sibling differentiation, usage condition, and default-inference instruction each earn their place without redundant filler. It is structured for quick scanning by an agent.

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 list tool with two optional parameters, full schema coverage, a safe read-only annotation profile, and an output schema, the description provides everything needed to invoke it correctly. It also covers the relevant edge case of ambiguous update/delete matches, making it contextually complete.

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

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

Schema description coverage is 100%, with both start_date and end_date already documented including format and defaults. The description mostly repeats these defaults in the INFER block. It adds the 'do not ask' operational instruction, but that is not new parameter semantic meaning beyond what the schema already provides.

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

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

The description states a specific verb and resource: 'List the user's logged period records within a date range.' It also explicitly differentiates this tool from update_cycle and delete_cycle, so an agent can tell exactly what list_cycle is for relative to its 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-use guidance: use it when the user asks about cycle history, or to get an id after an ambiguous update/delete match. It also explicitly says the tool is no longer required before update_cycle/delete_cycle because those resolve records by date, which prevents unnecessary calls.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the grouping behavior and the downstream consequence ('Canonical names ensure proper exercise tracking and NSI score calculation'), which is useful context. It does not describe pagination or ordering, but for a zero-parameter catalog read this is a reasonable level of disclosure.

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 and front-loaded with the core behavior. The second sentence is a compact usage rule, and the third explains the rationale. Minor redundancy exists between 'canonical exercise names' and the final sentence, but nothing is wasted.

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

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

For a zero-parameter, read-only, idempotent catalog tool with an output schema, the description covers the essential decision points: what it returns, when to call it, and when not to. It does not detail the output schema structure, but the output schema itself carries that burden. The only minor gap is not naming a specific sibling alternative, though the usage rule makes the boundary clear.

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, so the schema provides no parameter semantics to rely on. The description compensates by clarifying what the returned data represents (canonical exercise names grouped by muscle group) and why that matters. There is no parameter ambiguity to resolve.

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 ('Returns'), a specific resource ('canonical exercise names from the exercise library'), and a grouping dimension ('by muscle group'). It clearly distinguishes this from the many list_* siblings by focusing on the exercise catalog rather than user logs or metrics.

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 explicitly says when to use it: 'before logging, adding or renaming exercises when canonical names are not already known.' It also gives an exclusion: 'Metadata/set-value edits: no catalog lookup.' This is strong routing guidance relative to the large sibling set.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, covering the safety profile. The description adds meaningful behavioral context beyond that: it explains that include_capabilities=true appends a 'full catalog' that is 'large', informing the agent of an output-size tradeoff. It also clarifies that write tools resolve current goals themselves, preventing unnecessary calls. Minor gaps remain (e.g., pagination or exact response shape), but the output schema exists to cover structure.

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 three sentences, each earning its place: the first states purpose and output, the second gives usage triggers, and the third covers negative usage and the parameter caveat. It is front-loaded with the core purpose and contains 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 single-optional-parameter read-only tool with a full output schema and comprehensive annotations, the description covers everything an agent needs: when to use, what it returns, when to pass the parameter, and when not to use it. No critical context 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 baseline is 3. The description adds value beyond the schema by tying include_capabilities to a specific user intent ('what kinds of goals Wellness Project supports') and explicitly warning that the appended catalog is 'large'. This helps the agent decide when to set the flag, which is more actionable than the schema's generic phrasing.

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 ('Analyze or show the user's current and past goals'), names the resource ('user's goals'), and enumerates the exact return categories: active/paused formal goals, completed/historical formal goals, and current standard targets. It also implicitly distinguishes itself from sibling write tools by noting it should not be used to fetch an ID for create_goal or update_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?

Explicit usage conditions are provided: use when the user asks about their goals or wants a review/analysis. The description also gives a clear when-not-to-use rule ('Do not call this tool merely to obtain an ID before create_goal or update_goal') and a precise condition for setting include_capabilities. This fully routes an agent to the correct tool and parameter 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 already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description only needs to add extra context. It adds meaningful behavioral details: maximum range of 31 days, defaulting to the last 7 days, and the Settings prerequisite. This goes beyond the annotations without contradicting them.

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

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

Three short sentences cover purpose, usage trigger, prerequisite, range, and defaults with no filler. The most important scoping information is front-loaded in the first sentence.

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 two-parameter list tool with an output schema, the description is complete: it states what is returned, when to use it, the prerequisite, the allowed range, and the default behavior. Nothing needed for correct invocation or selection is missing.

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

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

Schema coverage is 100%, so the schema already describes both parameters and their defaults. The description adds value by stating the maximum range (31 days) and the default window (last 7 days), which helps an agent validate input without opening the schema.

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

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

The description uses a specific verb ('Review') with a clear resource ('hydration events and stored effective hydration totals'), and the hydration domain distinguishes it from the many list_* siblings. It states exactly what the tool returns without relying on the title.

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 explicitly says 'Use when the user explicitly asks about hydration history or fluid intake' and adds a prerequisite ('Hydration tracking must already be enabled in Settings'). It does not name an alternative tool, but no direct hydration-list sibling exists, so the guidance is clear enough.

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, idempotentHint=true, and destructiveHint=false, so the description does not need to restate safety. It adds valuable behavioral context beyond the schema: the default filter combines Active and Monitoring, the meaning of 'all' versus 'Resolved', and an explicit instruction to infer rather than ask.

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-structured with a clear usage section and a compact INFER block. The only minor flaw is slight redundancy between the sentence 'Defaults to active and monitoring injuries' and the INFER line restating the same default, but the overall size is appropriate and front-loaded.

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

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

For a simple read-only list tool with one optional parameter, an existing output schema, and strong annotations, the description covers everything an agent needs: what it returns, when to use it, how to handle the status filter, and how it relates to sibling mutation tools. No important operational gap remains.

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

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

Schema coverage is 100% and the schema already documents the status filter, so the baseline is 3. The description adds extra semantic value by specifying the default behavior, the exact meaning of each enum option, and an INFER directive that helps the agent invoke the tool without unnecessary clarification.

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

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

The description uses a specific verb and resource ('List injuries from the injury log') and clearly distinguishes the tool's purpose from update_injury and delete_injury by explaining that those can resolve injuries without a prior lookup. It also enumerates concrete use cases: reviewing the log, answering history/rehab questions, and retrieving an id after ambiguous matches.

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 explicitly says when to use this tool (review, answer history/rehab questions, get an id after ambiguous matches) and when it is not required (before update_injury/delete_injury). It also gives direct guidance on the status filter values, making the decision boundary clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered structurally. The description adds useful behavioral context: it returns canonical library data, includes aliases for matching, and supports canonicalization. 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?

Three sentences with no filler. The primary return value is front-loaded, the output fields are enumerated compactly, and the usage directive follows naturally. Every sentence earns its place.

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

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

The tool has no parameters, has an output schema, and is fully annotated as read-only and idempotent. The description adds the only missing context: what the data represents, what fields are returned, and how it should be used in the logging workflow. Nothing essential is left out.

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 are zero parameters, so there is no parameter burden for the description to carry. The description instead clarifies the semantic meaning of the returned canonical marker set, which is more valuable here. Baseline 4 is appropriate for a no-parameter tool.

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 ('Returns'), a specific resource ('LOINC-coded markers in the reference library'), and enumerates the returned fields. It clearly distinguishes itself from list_lab_results, which is about logged lab results rather than the reference marker library.

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 explicitly tells the agent to call this BEFORE log_lab_results, gives the matching purpose, references the analogous list_exercises pattern, and explains why it matters ('prevents name drift and ensures trending works'). This is strong when-to-use guidance with a concrete alternative pattern.

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, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds genuine behavior beyond that: results include their ID, and update/delete can resolve results independently so this isn't a mandatory prerequisite. It doesn't describe volume/pagination behavior, but the output schema covers the return shape.

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

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

Front-loads purpose, then the prerequisite-relaxation note, then use cases, then an INFER block for defaults. Dense but each clause carries routing or default guidance; the em-dash aside about update/delete is slightly long but earns its place by preventing unnecessary calls.

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

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

An output schema exists, so return values need no explanation. The description covers purpose, when-to-use, when-not-to-use, alternatives, and the default-date inference policy — everything an agent needs to invoke it correctly without asking the user.

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

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

Schema coverage is 100%, so all four parameters (start_date, end_date, panel_name, marker_name) are already documented with formats and defaults. The description reinforces the date defaults via the INFER block but adds no syntax or matching semantics beyond what the schema already states, so baseline 3 is appropriate.

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

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

States a specific verb (List) and resource (lab/biomarker results) plus scope (within a date range) and even what each record carries (the ID). It distinguishes itself from siblings like update_lab_result/delete_lab_result and list_lab_markers, 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?

Explicitly names the alternatives (update_lab_result/delete_lab_result can resolve a result on their own) and states when this tool is NOT required before them. It then enumerates positive use cases: reviewing lab history, answering trend/marker questions, and disambiguating an id after an ambiguous match.

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/idempotentHint/destructiveHint, so 'Read-only' is partly redundant. However, the description adds genuine behavioral context the annotations cannot convey: how to interpret the returned equipment list (known-available vs. exhaustively complete), that load ceilings and explicit user limits must be respected, and that user-stated location/equipment overrides assumptions.

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 purpose, then usage, then the planning rule, then the sibling handoff. Dense but every clause carries information; the long middle sentence on availability semantics is the one place a reader must slow down, keeping it just shy of a 5.

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 documentation is not required, yet the description still flags that location ids are emitted for manage_location. Together with the usage triggers and the availability-interpretation rule, nothing an agent needs to call this 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?

The tool takes zero parameters, so the baseline is 4. The description correctly adds no parameter detail and instead spends its words on output interpretation, which is the right allocation for a no-arg list tool.

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?

Starts with a specific verb+resource ('List the user's saved training locations') and immediately enumerates the content shape (equipment per location, heaviest dumbbell and barbell load). This distinguishes it from the many other list_* siblings (list_workouts, list_meals, etc.) without requiring the schema to be opened.

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

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

Explicitly names three trigger conditions ('when the user asks where or with what they can train, before editing a location, or when planning needs equipment availability') and points to the sibling that consumes its output ('Returns each location id for manage_location'). It also states an interpretation rule: listed equipment is known-available, not proof that unlisted incidental supports are absent.

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 cover readOnly, idempotent, and non-destructive. The description adds meaningful behavioral constraints beyond annotations: the 31-day maximum range per call and the parameter inference rules (default today, end_date logic for week/range queries). This goes beyond what annotations 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 well-structured with clear sections and bullets, but it contains some redundancy (e.g., the note about update_meal/delete_meal resolving appears twice in slightly different forms). It is still efficient overall and not bloated.

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

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

Given the output schema exists, the description doesn't need to enumerate all return fields, but it still mentions key outputs (meal ID, date, type, food description, macros). It covers purpose, parameters, usage, routing, and constraints, providing everything an agent needs to 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?

Both parameters (date and end_date) are fully described with format (YYYY-MM-DD), optionality, and specific semantics (start vs. single date, end of range). The description also explains default behavior and inference rules, making both parameters unambiguous.

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 meals logged for a date or range, with a specific verb ('List'), resource ('meals'), and scope (date/range). It also distinguishes it from siblings like show_meal_diary and show_week_macros via the ROUTING section.

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

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

Provides explicit when-to-use guidance: answering 'what did I eat today/this week/yesterday?', reviewing logged meals, and retrieving an ID after an ambiguous update/delete match. It also explains when it is not required (update_meal/delete_meal can resolve on their own) and how to handle longer periods with multiple calls.

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, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds useful behavioral context by specifying that only 'active' memories are returned and by describing the type of content stored, which helps the agent set expectations beyond the structured 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 concise and front-loaded: it states the core action and resource first, gives illustrative examples, then provides usage context. Every sentence adds value and there is no redundancy beyond the harmless 'Read-only' confirmation.

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 parameterless read-only tool with an output schema and annotations covering safety, the description fully covers purpose, scope, content type, and when to invoke it. Nothing essential is missing for an agent to select and call this tool correctly.

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

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

The tool has zero parameters and the schema is trivially complete at 100% coverage. With no parameters to document, the description's focus on the returned content and usage context is appropriate. The baseline for zero-parameter tools is 4, and the description earns it.

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'), a specific resource ('the user's active Personal Context memories'), and includes concrete examples. It clearly distinguishes this tool from the sibling add_or_update_personal_context and from other list tools by focusing on durable remembered preferences and circumstances.

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 states when to use: when the user asks what has been remembered about them, or before proposing a new memory to check for existing coverage. This gives clear practical guidance and implicitly routes the agent to add_or_update_personal_context when no existing memory covers the subject.

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, destructiveHint, and idempotentHint, and the description does not contradict them. It adds meaningful behavioral context such as the 90-day maximum range, the need for sequential calls to cover longer periods, and the 'INFER — do not ask' directive, which helps the agent behave correctly. It does not explicitly mention output format or error behavior, but with an output schema present that is less critical.

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 lengthy but well-organized: it starts with the primary purpose, then contrasts with a sibling, and finally gives usage and inference rules. While it could be trimmed, the added detail on multi-call traversal and inference rules is necessary for correct usage, so the structure is appropriate.

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

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

Given the tool's complexity (multiple optional parameters, inference rules, range limitations, and a sibling that is easily confused), the description covers all necessary context: it identifies when to use it, how to handle date ranges, how to distinguish from list_recovery_strategies, and how to handle long histories. No critical information is missing for an agent to use 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 input schema provides descriptions for all four parameters, and the description enriches them further: it explains default values for start_date/end_date, that omitting category returns all categories, and the limit's default/maximum. This goes beyond the schema and gives the agent full understanding of each parameter's meaning and usage.

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 verb 'List', the resource 'logged recovery sessions', and the scope 'within a date range, each with its ID'. It also explicitly contrasts with the sibling tool list_recovery_strategies to remove ambiguity, so an agent immediately knows what this tool does and how it differs.

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 provides explicit usage scenarios ('answer what recovery sessions have I logged', audit/spot-check, get an id after ambiguous match) and gives concrete inference rules for parameters (default date range, category omission). It also tells the agent when to make multiple calls for longer histories, making the usage guidance highly actionable.

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

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

Annotations already establish readOnly/idempotent/non-destructive behavior. The description builds on that by explaining the INFER behavior ('do not ask'), the default filter, and what fields are returned. This adds useful operational context beyond the annotations.

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

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

The description is compact and front-loaded: purpose first, use cases second, then a clearly marked INFER block with parameter guidance, and finally a one-line return convention. Every sentence carries information.

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

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

For a single-parameter, read-only list tool with annotations and an output schema, the description covers usage, filter semantics, inference behavior, and return fields. 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?

Although schema coverage is 100%, the description adds meaning not present in the schema: 'use 'all' for history; use 'historical' for ended strategies only.' This disambiguates the enum values and gives the agent a rule for inferring the parameter without asking.

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?

Description begins with a specific verb and resource: 'List the user's recovery and mindfulness strategies.' It also gives concrete use cases ('user asks about recovery practices, mindfulness routines, or you need strategy IDs before logging a session'), which distinguishes it from related siblings like manage_recovery_strategy or list_recovery_sessions.

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

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

It explicitly states when to use the tool: when the user asks about recovery practices, mindfulness routines, or needs strategy IDs before logging a session. It does not explicitly name alternatives or say when not to use it, so it earns a 4 rather than a 5.

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

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

Annotations already declare readOnly, idempotent, non-destructive, so the safety profile is covered. The description adds genuine behavioral context beyond that: Travel Day is context-only and can coexist with training, meaning a rest-day entry does not imply absence of training, and it explicitly instructs the agent to infer default dates rather than prompt the user.

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, followed by usage rationale and then a short inference directive. Every sentence carries information, though the INFER block restates defaults that the schema already declares, which is mildly redundant.

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

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

An output schema exists, so return values do not need explaining, and annotations plus the output schema cover the safety and shape of results. The description supplies the interpretive context an agent needs (what a rest-day entry means, how it interacts with training data). It could be slightly stronger by noting the distinction from log_rest_day/cancel_rest_day, but it is complete enough to call 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%, so both parameters (start_date, end_date) are already fully documented with format and defaults. The description's 'default to 30 days ago / today' merely duplicates the schema defaults, and the INFER instruction is a call-behavior hint rather than added parameter semantics. Baseline 3 is appropriate.

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

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

States a specific verb (List) and a precise resource (user-selected Rest Day, Sick Day, and Travel Day context) with an explicit scope (within a date range). The semantic content — 'context-only, can coexist with training' — lets an agent distinguish it from data-bearing siblings like list_wellbeing or list_recovery_sessions 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?

It clearly states when to reach for this tool: to explain a date with no workout or anomalous recovery/sleep/nutrition data. That is a real usage signal rather than restated purpose. It stops short of naming an alternative or a when-not condition (e.g., use list_personal_context for other context types, or log_rest_day to add one).

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

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

Annotations already declare the operation read-only, idempotent, and non-destructive, so the description is free to add behavioral value. It does: range reads 'stay compact and return a Runner State summary first,' run_id reads return 'stored splits and structured segments plus detailed metrics,' and the 92-day maximum with multi-call guidance is a meaningful constraint beyond the schema.

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

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

Two short paragraphs front-load the primary distinction and then add behavioral and constraint details. Every sentence earns its place: the mode split, the output differences, the defaults, and the multiple-call instruction. 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?

With three optional parameters, 100% schema coverage, an output schema, and full annotation coverage, the description fills the remaining gaps: output shape per mode, maximum range, defaults, and how to handle spans longer than 92 days. Nothing an agent needs to invoke this 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?

The schema already documents all three parameters with formats and defaults, so baseline is 3. The description adds the 92-day maximum range and clarifies the distinction between compact range output and detailed run_id output, reinforcing parameter behavior beyond the schema without repeating it.

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 runs within a date range, or return full saved detail for one run when run_id is provided.' This clearly distinguishes the two modes of operation and their triggers, so an agent knows exactly what the tool does and when each mode applies.

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 clear usage context: date-range reads return a compact summary, run_id reads return split and segment detail, and long spans require multiple calls covering consecutive windows. It does not explicitly name alternatives like show_runs, so sibling differentiation is left to inference, but the usage conditions themselves are concrete and actionable.

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 provide readOnlyHint and destructiveHint, and the description adds transparency about the returned data fields (duration, score, stage breakdown) and the nature of the entries. There is no contradiction; the description supplements the annotation adequately.

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 concise yet information-dense, covering purpose, scope, parameters, defaults, limits, and exclusions in a clear, structured format without superfluous wording.

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?

All necessary details for correct usage are present: the data returned, the date range constraints, the default behavior, and the exclusion of naps. Given the tool's simplicity, the description is fully complete and leaves no ambiguity.

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?

Both parameters are explained with format and default values in the description, adding guidance on the 31-day limit and the inference of defaults, which goes beyond the schema's basic descriptions. This is particularly valuable given the schema only lists field names and 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?

The verb 'List' clearly specifies the action, the resource 'sleep log entries' is unambiguous, and the scope (date range) is defined. It also implicitly differentiates from logging a new sleep entry via the sibling tool 'log_sleep'.

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 explicitly states the maximum range of 31 days and instructs to make multiple calls for longer periods. It also clarifies the default values for start_date and end_date, and notes that daytime naps are excluded, providing clear 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered by structured data. The description adds useful behavioral context: default filtering behavior, how to request history, and the full list of returned fields. This goes beyond annotations without contradicting them.

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-structured and front-loaded with the core purpose, followed by concise parameter inference guidance and a clear list of return fields. Every sentence adds value, and the use of labeled sections ('INFER — do not ask') makes it easy for an agent to parse. Nothing feels redundant or wasted.

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

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

For a read-only list tool with two optional enum parameters and an output schema, the description is complete. It covers when to use the tool, what each parameter means, how to handle ambiguous matches, and what fields are returned. There is no missing information an agent would need to invoke this tool correctly.

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

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

Although the input schema covers both parameters 100%, the description adds significant extra meaning. It defines the inference rules, explains the default 'active' filter, clarifies when to use 'all' vs 'historical', and specifies that omitting category returns both types. This is exactly the kind of parameter guidance that helps an agent choose values correctly without asking the user.

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 the user's medications and supplements.' It clearly distinguishes itself from the sibling manage_supplement by explaining that list_supplements is for reviewing what the user takes, not for managing individual items. This lets an agent immediately know what the tool does and how it differs from related 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?

The description explicitly states when to use the tool: when the user asks what medications/supplements they're taking, asks to review their stack, or needs an id after an ambiguous manage_supplement match. It also explains that manage_supplement can resolve items on its own, so list_supplements is not a required prerequisite. This is strong, actionable routing guidance.

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

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

Annotations already mark it read-only and idempotent, and the description adds meaningful behavioral context: the 31-day maximum, sequential date-range calls, Zone Minutes scoring details, and the explicit rule that derived resting calories are 'labelled an estimate, never shown as measured.' It also explains how TDEE method or missing profile fields are surfaced. 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?

The description is long but tightly structured: opening scope, expansion of ambiguous metric semantics, operational limit, inference defaults, and routing rules. Each section adds information an agent needs, and the key verb/resource is front-loaded.

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

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

Given the output schema exists and annotations cover safety, the description covers everything needed to call correctly: metric coverage, date-range limits, batching, estimation caveats, default inference, and sibling routing. No critical behavioral or usage element 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?

Although the schema already documents both parameters with defaults and formats, the description adds the actionable instruction 'INFER — do not ask', the default values, and the operational constraint that maximum range is 31 days per call with sequential calls for longer periods. This goes beyond the schema's structured parameter documentation.

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

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

The description opens with a specific verb and resource: 'List daily wearable data' within a date range, and enumerates the exact metrics covered. The ROUTING section further distinguishes it from show_health_overview, show_recovery, and show_week_steps, so an agent can tell siblings apart.

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

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

It provides explicit routing ('Exact daily values: list_wearable_data. Broad visual: show_health_overview. RHR/HRV: show_recovery. Steps: show_week_steps') and a 31-day call batching rule. However, the earlier 'Use when the user asks about ... HRV trends' is not fully reconciled with the ROUTING line that sends RHR/HRV to show_recovery, creating a minor ambiguity for that query type.

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 mark it as read-only, idempotent, and non-destructive; the description adds further transparency by explaining that the tool is not a prerequisite for update/delete operations and that it returns ids useful for resolving ambiguous matches. No contradictions 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?

Every sentence contributes: the main purpose, the relationship to update/delete, the 31-day limit, and the parameter defaults. No redundant or filler content; the structure flows logically from what the tool does to how to use it.

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 two optional parameters and the presence of an output schema (mentioned in context), the description provides sufficient context for an agent to call the tool correctly. It covers parameter defaults, usage scenarios, and operational limits, so no missing information would cause incorrect 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?

The input schema fully describes both parameters with types and defaults, and the description reinforces their behavior ('INFER — do not ask' with default values), clarifying that the agent should infer these rather than prompt the user. This adds semantic value beyond the schema's basic metadata.

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?

Clearly states the action ('List wellbeing log entries') and the resource, with explicit scope ('within a date range'). It distinguishes itself from sibling tools by noting that update_wellbeing and delete_wellbeing can resolve entries on their own, making list_wellbeing specific to trend queries and id retrieval after ambiguous matches.

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

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

Provides explicit when-to-use guidance: for trends over time or getting an id after an ambiguous match, and explicitly states it is not required before update/delete. Also gives operational constraints (maximum 31 days per call) and default parameter values, leaving no ambiguity.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior, and the description adds substantial operational context beyond them. It discloses internal 90-day slicing, a 3660-day cap, output bound of 250 rows, what happens when results are omitted, and how all_history handles older stored start dates. These details are exactly the kind of behavioral context an agent needs to invoke the tool 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?

The description is long but well-structured with capitalized section headers that front-load the core purpose and then handle date ranges, all-history behavior, output bounds, filters, inference, and saved workouts. Most sentences earn their place by preventing incorrect invocations, though some return-field detail overlaps with the existing output schema. It is appropriately sized for a complex, multi-mode listing tool, but not maximally tight.

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 six optional parameters, a rich schema, an output schema, and many siblings, the description is complete enough for correct invocation. It covers filtering, defaults, pagination-like bounds, all-history edge cases, saved workouts, and sibling routing. Nothing critical to selecting or calling the tool 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?

Although schema coverage is 100%, the description adds meaningful parameter semantics beyond the schema. It explains when to set all_history, how activity_type and exercise_name differ in practice, that both filters may be combined, and that saved_workouts switches to a separate Saved Workouts library with distinct IDs. It also gives date-inference rules and treats user-specified dates as authoritative.

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: list workout sessions in a date range, plus Rest Day/Sick Day/Travel Day context. It clearly distinguishes the tool from siblings by explaining that it returns session IDs for use before get_workout and that it handles training-history questions. The added warning that context labels are not workouts further sharpens the tool's purpose.

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-use guidance: before get_workout to find a session ID, for training-history questions, for all-history queries, and for saved-workout library listing. It also provides when-not guidance by saying not to make sequential list_workouts calls to cover one range and by distinguishing activity_type from exercise_name filter use cases. Alternative sibling tools are not exhaustively named, but the key routing decisions are covered.

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

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

Beyond the annotations, the description discloses meaningful behavior: it can reopen a period that was marked ended, it infers started_on and ended_on instead of asking, and it requires a consent/tracking check before logging. No statement contradicts the provided 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 well-structured with a clear top-line definition, a bulleted list of cases, a prerequisite warning, and an inference section. Every sentence carries information an agent needs; nothing is filler or redundant.

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

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

The description covers edge cases, prerequisites, inference rules, and forbidden usage. An output schema exists, so the description does not need to explain return values. For a tool that logs cycle data with inference and consent requirements, this is 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?

While the schema already documents both parameters at 100% coverage, the description adds crucial semantics: started_on defaults to today for current-period statements, ended_on should be omitted unless explicitly stated, and both dates can be inferred from context. This goes well beyond the schema's basic format 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?

The description opens with a specific verb and resource, 'Log a period to the user's cycle log', and then enumerates the distinct real-world utterances it handles. This makes the tool's scope unmistakable and clearly separates it from siblings like list_cycle, update_cycle, and delete_cycle.

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 applicability through concrete examples, a prerequisite check for cycle tracking, and an explicit exclusion: 'Do NOT use this tool to log future dates.' It does not explicitly route users to update_cycle for modifications, but for a logging action the guidance is strong and actionable.

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 adds substantial behavioral context beyond the annotations: injuries are date ranges that stay open until end_date is set, many fields should be inferred rather than asked, and only body_part warrants a clarifying question. The annotations correctly indicate a write operation with readOnlyHint=false, so there is 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?

The description is well-structured and front-loaded: purpose, trigger conditions, domain model, then a scannable INFER list. Every sentence earns its place, and there is no redundancy with the schema descriptions.

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 9-parameter create tool, the description covers when to call, what to infer, what to ask, and the date-range semantics. Since an output schema exists and schema coverage is 100%, no critical information is missing for an agent to invoke this tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful extra value with numeric severity anchors (minor twinge=2-3, moderate pain=5-6, severe/acute=8-9), an example for affected_movements, and a clear policy to ask only when body_part is unclear. This is above baseline but not maximal because the schema already carries much of the parameter information.

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: 'Log a new injury or aggravation.' It also lists concrete user signals like 'getting hurt, feeling pain, straining something' that trigger this tool. The word 'new' distinguishes it from sibling tools like update_injury and delete_injury.

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: when the user mentions getting hurt, feeling pain, straining, or describes an injury. It doesn't explicitly state when not to use it, such as 'if the injury already exists, use update_injury instead,' but the context is clear enough.

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 state flags (readOnlyHint=false, etc.). The description adds substantial behavioral rules: required workflow order, handling unknown markers (use name as stated, omit LOINC), never inferring fasting status, never substituting report_date for collection_date, and batching all markers in one call. It also explicitly states what is *not* allowed, which goes well beyond the structured 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 long but tightly organized with clear headings (GLUCOSE ROUTING, REQUIRED WORKFLOW, FASTING) and every sentence earns its place. Some minor repetition of 'omit otherwise' and the explicit prompt text add length, but overall it is efficiently structured and front-loaded with the core purpose.

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 highly complex with many conditional fields and routing rules. The description covers the required pre-step, handling of missing data, field-specific semantics, and batching, and an output schema exists to explain return values. Nothing an agent needs to invoke this correctly is left out.

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%, but the description enriches every parameter. It clarifies that fasting_status must be omitted unless explicitly stated, explains when draw_id applies, specifies that loinc_code must come from list_lab_markers, and gives rules for panel_name inference. This adds meaning far beyond the bare schema 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?

The description opens with a specific verb and resource: 'Log one or more blood test or biomarker results.' It immediately contrasts with review/interpretation ('Review/interpretation alone: no write') and explicitly routes glucose readings to log_wearable, distinguishing it from the main sibling. An agent can tell exactly what this tool does 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?

Provides explicit when-to-use ('requested logging/import of lab values or a concrete result to record') and when-not-to-use ('Review/interpretation alone'). It also names the sibling alternative for glucose (log_wearable), mandates a pre-step with list_lab_markers, and gives a ready-made prompt for incomplete user input. This is textbook usage 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 the annotations, it details real behavior: infer date/category/strategy_name instead of asking, omit duration_minutes for skipped sessions, include quality only when the user rates it, and map 'skipped/missed/didn't do' to skipped=true. These rules tell the agent exactly how the tool expects the call to be constructed.

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 organized into a two-sentence purpose, a compact INFER bullet list, and a short workflow callout. There is no filler, and the highest-value guidance is front-loaded.

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

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

For an 8-parameter write operation, it covers all major decision points: defaults, inference rules, skipped handling, strategy linking, and the standalone fallback. Optional fields like notes are already documented in the schema, and an output schema exists, so the description does not need to explain return values.

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 already 100%, but the description adds inference semantics that the schema cannot express: category comes from the practice name, strategy_name comes from the linked strategy or user phrasing, and duration is omitted when skipped. This materially improves an agent's ability to fill the parameters correctly.

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 concrete action and resource: 'Log a completed or skipped recovery/mindfulness session,' and lists representative practices. It also carves out 'one-off standalone sessions not linked to a recurring strategy,' which separates this tool from strategy-management siblings and gives the agent a clear scope.

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

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

The trigger is explicit ('Use when the user says they did or skipped...') and the preferred workflow names list_recovery_strategies and a standalone fallback, so the agent knows when to invoke it. It never states a when-not or names a sibling tool as the alternative, leaving some exclusion logic implicit.

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 cover safety (idempotentHint=true, destructiveHint=false, readOnlyHint=false), and the description reinforces idempotency by stating a repeat call updates status in place. It adds non-obvious behavior: visibility to the AI team and workout-history reads, and that Travel is context-only and can coexist with a workout. Strong given the annotations already carry the safety profile.

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

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

Front-loaded with the core purpose before branching into day_type semantics, with a clear INFER block and a closing note on idempotency/removal. Every sentence carries information, though it is slightly verbose for a two-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?

With an output schema present, return values need not be described. The description covers date interpretation, all enum semantics, idempotent re-call behavior, cross-system visibility, and the removal path via cancel_rest_day, leaving no gap for correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3, but the description earns more by explaining how to derive each parameter: parse the user's date reference defaulting to today, and infer day_type from wording defaulting to rest. This adds interpretation guidance the 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?

States a specific verb (Mark) and resource (a date with day context), and enumerates the three day types. It distinguishes itself from the sibling cancel_rest_day and is trivially separable from log_wellbeing/log_sleep. An agent knows exactly what this tool produces.

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 maps each day_type to the user condition that selects it (takes day off, sick/recovering, traveling), and names cancel_rest_day for the removal case. It even prescribes inference over asking, which removes ambiguity about behavior at call time.

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=false, idempotentHint=false, so the description doesn't need to restate that this is a write operation. It adds behavioral context by explaining what the tool does with the value field (converts once before storage), how intent affects the outcome (writes completed run vs creates planned card), and explicitly says never to invent sensor data or splits. The description goes beyond the annotations by disclosing the conversion convention and the no-invention rule.

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 compact relative to the 19-parameter schema. It front-loads the critical UNIT INPUTS and RUNNING ONLY rules, then intent, then run_type, then detail. Every sentence earns its place – the RUNNING ONLY and UNIT INPUTS sections are high-value disambiguation that prevents wrong tool selection and wrong unit handling. The format uses clear section headers to break up the different concerns.

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 19-parameter tool with an output schema and high schema coverage, the description covers the key ambiguities: when to use this tool vs log_workout, how intent changes the call, how units are handled, and what not to invent. It could add a note about the output schema/returned card marker, but the output schema exists and the intent section already mentions it returns a card marker for in-app editing.

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 89%, which is high, so the baseline is 3. The description adds additional meaning by clarifying the UNIT INPUTS convention (pass value unconverted; tool converts once before storage), explaining the intent parameter semantics in detail (log vs plan, required fields for log), and specifying that run_type should only be set when the runner or workout structure supports it. It also adds the rule that sensor data and splits must never be invented, which adds semantic guidance beyond the schema's 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?

The description names a specific verb ('log') and resource ('run card'), states that it is for running on foot only, explicitly excludes cycling/walking/rowing sessions, and distinguishes between completed runs (log) and future run plans (plan). It differentiates itself from the sibling log_workout by naming the alternative and the conditions that select it.

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 explicitly says 'RUNNING ONLY: use log_run only for running on foot,' names log_workout as the alternative for cycling/walking/rowing with the specific focus_type values, and gives clear guidance on intent (log vs plan). It also states when run_type should be classified and warns against labeling unspecified wearable runs as 'easy'.

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 critical behavioral traits beyond the annotations: one row per day, calling twice on the same date is an upsert/update, manual tagging, and the exclusion of wearable-provider sources. These details are not present in the input schema or annotations and materially affect how an agent uses the 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?

The description is longer than average but well-structured with clear sections and front-loaded purpose. Every section adds necessary operational detail—proactive data collection, inference rules, upsert behavior, and manual tagging—so the length is justified.

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 9-parameter, mutation-prone tool with an output schema. It covers when to call, what to ask, how to infer the required date, update semantics, and provenance constraints. With the output schema present and annotations provided, 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 coverage is 100%, so the schema already documents each parameter. The description adds useful semantic guidance not in the schema, such as inferring the date from the wake date rather than asking, defaulting to today, and allowing any subset of fields to be logged.

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 begins with a specific verb and resource, 'Log a sleep entry', and immediately clarifies what qualifies as a loggable event ('logging request or concrete sleep event') and what does not ('Question/habit/hypothetical alone: no write'). It also distinguishes itself from wearable-provider auto-sync sources by noting entries are always tagged as manual.

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 clear guidance on when to use the tool: when a user requests logging or provides a concrete sleep event, including proactive follow-up when numbers are missing. It provides negative guidance for hypotheticals alone and implies that wearable auto-sync pipelines should not use this tool, though it does not name a specific sibling alternative such as log_wearable.

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 signal mutation (readOnlyHint=false). The description adds meaningful behavior beyond that: it documents inference defaults (date=today, taken=true), the requirement that exactly one selector be provided, and the error behavior when supplement_name matches multiple items. This is valuable context for invocation.

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 compact and well-organized. Purpose, usage condition, inference rules, and selector requirements are each given their own section with no redundant or filler content. Every sentence adds operational 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?

Given the moderate complexity, the 100% schema coverage, the presence of an output schema, and annotations covering mutation safety, the description is complete. It covers prerequisites, defaults, selector resolution, and failure behavior, so an agent can invoke it correctly without guessing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds important semantics beyond the schema: the exact-one-required relationship between supplement_id and supplement_name, the inference rules, and the multiple-match error behavior. This compensates well for the schema's lack of required-parameter enforcement.

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: 'Mark a medication or supplement as taken or not taken for a specific date.' This clearly distinguishes it from sibling tools like list_supplements or manage_supplement, and the action 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?

It explicitly says when to use the tool: 'Use when the user says they took (or missed) a medication or supplement on a particular day.' It also notes the daily tracking mode prerequisite. It does not explicitly name alternatives or state when not to use it, but the guidance is clear enough for selection.

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