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?

The annotations already disclose destructiveHint=true and idempotentHint=true, so the description does not need to restate those. It adds useful framing with 'previously declared' and real user scenarios, but it does not reveal additional behavioral traits such as what happens when no rest day exists or whether the action is reversible.

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: it states the action first, then gives usage examples, then supplies a clear inference instruction. Every sentence earns its place, and the structured 'INFER — do not ask' line is easy for an agent 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?

This is a single-optional-parameter tool with an output schema present and annotations covering mutability, destructiveness, and idempotence. The description covers what the tool does, when to use it, and how to handle the parameter, so an agent has everything needed 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?

Schema coverage is 100%, so the schema already documents the date parameter, its format, and default. The description adds meaningful semantic guidance beyond the schema by instructing the agent to infer the date from the user's reference rather than asking, which directly affects invocation behavior.

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: 'Remove a previously declared rest day.' This clearly differentiates the tool from sibling tools like log_rest_day and list_rest_days, since it targets undoing a prior declaration rather than creating or listing one.

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: when the user changes their mind or wants to undo a mistaken declaration. It does not explicitly name alternatives or state when not to use it, but the 'previously declared' qualifier and the examples make the intended context 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 cover safety (readOnlyHint=false, destructiveHint=false, idempotentHint=false), so the bar is lower. The description adds meaningful non-obvious behavior: it loads existing goals itself, reports what a standard target changed from, and refuses duplicate/stacked goals by naming an ID. It does not mention auth requirements or rate limits, and does not explain what the output contains, but the duplicate-detection and self-loading behavior is genuinely useful context beyond 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 UNIT INPUTS block is front-loaded but occupies roughly half the description with a repeated per-category list that could be condensed. The core purpose and usage statements come after, and there is some redundancy ('there is no schema-discovery or list_goals prerequisite' overlaps with the later 'do not call list_goals first'). It is information-rich but not 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?

For a 29-parameter creation tool with 100% schema coverage and an output schema, the description covers the key operational behavior (unit handling, duplicate refusal, no list prerequisite) that the schema cannot. It stops short of explaining goal_type inference rules or the full set of canonical inputs, deferring to 'the canonical Goals definitions,' but what is present is sufficient for an agent to invoke the tool correctly.

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

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

Schema description coverage is 100%, and every parameter's description already explains its purpose, unit, and when required. The description adds the UNIT INPUTS protocol, which is a real value-add: it tells the agent to pass numbers unconverted and set companion fields for kg/km/cm/oz/fl_oz. However, it omits explanation of many other parameters (goal_type, metric, weeks, etc.) and the unit block is somewhat repetitive with the schema's per-field unit notes.

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+resource: 'Create a new Wellness Project goal or standard target.' It distinguishes itself from list_goals and update_goal by saying when to call it directly and that there is no list prerequisite. However, it does not define what a 'Wellness Project goal' or 'standard target' is, and the description is cluttered with a long unit-input preamble that dilutes the core statement.

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 when to call it (user wants to establish a goal), which prerequisite tools NOT to call (no schema discovery, no list_goals), and what happens on conflict (refuses to stack and names the existing goal ID to use with update_goal). It also routes the agent to the generated inputs for formal fields. This is strong when/when-not guidance.

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

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

Annotations already declare 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 declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so safety is covered structurally. The description adds genuine behavior beyond that: it warns the call errors with candidate IDs when the selector matches multiple runs, and it requires confirmation on ambiguous intent. It does not state reversibility or what is destroyed alongside the run.

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 opens with a large UNIT INPUTS block that is irrelevant to a delete operation except for the single optional distance_mi field, and it buries the actual purpose ("Delete a run") several paragraphs down. The purpose and selector guidance are good but not front-loaded, and the boilerplate dominates the text.

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 an output schema and full annotation coverage, the description supplies the selector contract, the confirmation requirement, and the multi-match failure path. What remains unspecified is the effect on dependent data and whether deletion is recoverable.

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 per-field docs are already handled. The description still earns credit for adding rules the schema lacks: "exactly one of id or date required", the approximate 0.25 mi narrowing semantics, and the multi-match retry behavior. The long unit-conversion rules also add meaning beyond "mi, or km with input_distance_unit set".

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?

"Delete a run" names a specific verb+resource, and "Use when the user wants to remove a run entry" disambiguates it from the many sibling deleters (delete_workout, delete_cycle, delete_meal). An agent can pick it out immediately from the list.

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

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

It gives clear trigger conditions ("remove a run entry") and an explicit caution to ask for confirmation on ambiguous intent. However, it never explicitly routes the agent away from the nearest alternative (e.g. delete_workout, or update for corrections), so the alternative-selection guidance is 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?

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?

Beyond the destructiveHint/idempotentHint annotations, it discloses irreversibility, the exact scope of destruction (session, supersets, sets), and critically the failure semantics: a non-singleton match errors with nothing deleted, with retry guidance. This is behavioral context the annotations cannot convey.

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

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

Front-loaded with the action and consequence, then organized under FIND THE SESSION and SAVED WORKOUTS headers. Multi-sentence length is justified because every sentence carries disambiguation or safety 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?

An output schema exists, so return values need not be described, and the definition covers selection logic, scope of deletion, failure behavior, and the alternate entity path. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: name is a case-insensitive substring used only for disambiguation when more than one session exists that day, session_date defaults to today, and saved_workout_id targets a different entity class. It goes beyond restating 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?

States a specific verb and resource ("Permanently delete a workout session and all its exercises and sets") and clearly separates the two deletable entities: completed workout session vs. reusable Saved Workout. It is trivially distinguishable from sibling update_workout and the other delete_* tools, which target different resources.

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

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

Gives explicit when-to-use ("Use when the user wants to remove a logged workout entirely") and a full decision procedure: pass session_id if known, else session_date + optional name, and only the name when multiple sessions share a date. It routes to saved_workout_id for the other deletion target and tells the agent never to guess.

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 read-only and idempotent safety, and the description adds behavioral context annotations cannot express: the closed-book grounding requirement ('answer them from this tool's result, never from memory'), the verbatim-reproduction rule for pricing messages, and the prohibition on typing out buttons, chips, or link markup. The note that the app attaches its own upgrade button also informs expected output handling.

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

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

The core purpose is front-loaded in the first sentence and the text is organized into distinct sections (purpose, grounding rule, tool routing, sibling routing, pricing behavior) with no fluff. It is long, and the wearables/metrics/sync_details/troubleshooting routing prose partly duplicates the schema's enum descriptions, so it is not maximally concise — but every paragraph earns its place given the routing complexity.

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

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

For a single-parameter lookup tool with an output schema, full enum documentation, and safety annotations, the description is complete: it covers purpose, when to use internal topics vs sibling tools, grounding behavior, and the special pricing output format. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100% with detailed per-enum descriptions, so the schema carries the semantic weight. The description adds modest value by mapping cost/price/Free-vs-Pro/Founding-Member/3-analysis-limit queries to topic=pricing — details beyond the schema's terse 'approved pricing copy' — but otherwise reinforces rather than extends the schema's enum meanings.

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 — 'Look up customer-facing Wellness Project product knowledge' — and enumerates concrete use cases (app navigation, visible features, integrations, metric meanings, logging methods, permissions/sync, troubleshooting). It differentiates from siblings by expressly naming list_exercises for exercise-name lookups and pricing for cost questions, so an agent can distinguish it without inspecting schemas.

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

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

Routing guidance is explicit and actionable: within the tool it tells which topic to use for which need (wearables vs metrics vs sync_details vs troubleshooting), and outside it names list_exercises as the alternative for exercise names. It even states a positive selection rule ('Use troubleshooting only when the user reports unexpected behavior') and a negative one ('never from memory').

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 signal read-only and idempotent behavior, and the description goes far beyond them by disclosing a non-obvious accuracy quirk: a wrong or missing equipment tag on a dumbbell exercise 'silently halves or doubles its NSI score.' It also explains when equipment is shown per exercise vs per set and what 'missing' means, which is highly useful behavioral detail not present in 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 densely informative, with clear section headers (NSI, EQUIPMENT, REQUIRED WORKFLOW, SAVED WORKOUTS) that make scanning easy. Every sentence adds operational knowledge; there is no filler or repetition of schema definitions.

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?

Despite having an output schema, the tool has complex behavior (nested NSI scoring at session/exercise/set grains, equipment-tag sensitivity, two distinct input modes). The description covers all of these, plus the required lookup workflow and a correctness caveat. Together with the annotations and schema, an agent has everything needed to invoke the tool correctly and interpret its unusual scoring behavior.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value beyond the schema: it explains that session_id comes from list_workouts and is required, clarifies saved_workout_id returns a 'reusable prescription instead of a completed workout session,' and warns against combining saved_workout_id with session_id/session_date. These semantic clarifications exceed the schema's basic field 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: 'Retrieve full detail of a workout session' and enumerates the exact contents (exercises, sets, reps, weights, superset groupings, heart points, notes, NSI scoring). It clearly differentiates from siblings like list_workouts (list vs full detail) and show_workout (which may focus on summary/display), and also explains the separate saved_workout_id mode.

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 states when to use: 'Use for detailed questions about a past workout, reviewing training before recommendations, confirming what was logged, or comparing a session to population strength standards.' It also mandates the preceding workflow step ('call list_workouts first to find the session ID — never guess it') and gives a clear exclusion/alternative for saved workouts ('Do not combine it with session_id/session_date').

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, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds meaningful context by revealing the grouping behavior and explaining that canonical names support exercise tracking and NSI score calculation, which goes 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?

Three concise sentences with no filler: output definition, when to call it, and why it matters. The most actionable guidance is front-loaded, and 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?

For a zero-parameter read-only listing tool with an output schema present, the description is complete. It explains the return content, the grouping, the practical invocation timing, and the downstream benefit, leaving no obvious gap 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?

The tool has zero parameters, so there is no parameter semantics burden on the description. The baseline is 4, and the description appropriately focuses on the return value and usage context rather than inventing parameter details.

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 precise resource ('all canonical exercise names from the exercise library'), and an organizing detail ('grouped by muscle group'). It clearly distinguishes this tool from sibling list_* tools by focusing on the canonical exercise library rather than logs, meals, 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 to call this before log_workout or update_workout to match user-described exercise names to canonical ones. This provides clear contextual guidance, though it does not explicitly discuss when not to use it or name alternatives as exclusions.

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

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

Annotations already declare 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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context beyond those annotations: the tool returns IDs, defaults start_date to 365 days ago, end_date to today, and clarifies that update/delete can resolve results independently. It does not describe every output detail, but an output schema exists, so this is not a major gap.

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. Each subsequent sentence adds distinct value: sibling relationship, use cases, filtering, and inference defaults. There is no filler or repetition of schema fields, and the formatting makes the INFER instructions 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 tool's low complexity (0 required parameters, 4 optional well-documented parameters, no nested objects, and an output schema), the description covers all important context. It explains when the tool is needed, when it is not needed, what IDs are for, and how defaults should be inferred. Nothing essential is missing for correct selection and invocation.

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

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

Schema description coverage is 100%, with each parameter already documented with format, defaults, and optionality. The description adds value by instructing the agent to 'INFER — do not ask' the defaults and by explaining why start_date defaults to 365 days ago ('labs are infrequent'). This goes beyond the schema and gives practical guidance for parameter selection.

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 lab/biomarker results within a date range, including each result's ID.' It clearly distinguishes itself from related siblings like list_lab_markers, update_lab_result, and delete_lab_result by focusing on historical review and ID retrieval. No ambiguity remains about what the tool does.

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: to review lab history, answer trend questions, or get an ID after ambiguous update/delete matches. It also explicitly says this tool is 'no longer required' before update_lab_result or delete_lab_result, giving clear exclusion criteria. The INFER defaults further guide autonomous invocation without asking the user.

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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context by stating the INFER rule: default start_date to 30 days ago and end_date to today without asking 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: purpose first, then usage conditions, then inference rules. No filler or redundant phrasing; every sentence contributes.

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, fully documented parameters, an output schema, and annotations covering safety, the description provides everything an agent needs: purpose, when to use, inference behavior, and range semantics. Nothing critical is missing.

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

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

Schema description coverage is 100%, so the schema already documents both parameters and their defaults. The description adds meaningful guidance beyond the schema by instructing the agent to infer defaults rather than ask, which changes invocation behavior.

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

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

The description states a specific verb ('List') and resource ('dates a user has marked as rest days within a range'), clearly distinguishing it from sibling tools like log_rest_day and cancel_rest_day. The accompanying examples reinforce the exact 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?

Explicitly says 'Use when the user asks about their rest pattern' and gives two concrete example queries. It doesn't name alternatives or state exclusions, but the context is clear enough for an agent to route to this tool 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 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?

Beyond the readOnlyHint and idempotentHint annotations, the description reveals important runtime behaviors: default date range, 90-day maximum range, the need to chain calls for older periods, and the effect of the saved_workouts flag. This adds meaningful context that annotations alone do not 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 slightly long but well-organized with labeled sections (SAVED WORKOUTS, INFER) and each sentence adds value. It front-loads the core function and usage examples before diving into edge cases, though a bit of trimming could improve conciseness.

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 three optional parameters and the tool's role in a broad ecosystem, the description covers all necessary aspects: default dates, range limitations, chaining strategy, saved workout mode, and the output fields. Users have enough context to call it correctly without referencing external docs.

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 descriptions cover all three parameters, but the tool description enriches them further by specifying defaults (start_date = 7 days ago, end_date = today), the meaning of saved_workouts, and instructions to widen the range up to 90 days. This goes well beyond the schema's basic 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 clearly states the tool's function: listing workout sessions with specific attributes (ID, date, focus, location, NSI rating). It also gives concrete usage examples and distinguishes between completed workouts and saved workouts, making its 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?

It provides explicit guidance on when to use it: before get_workout to find a session ID, for answering trend questions, and how to handle older data via chaining. It also clarifies the saved_workouts flag to switch modes, which helps select the right tool among siblings.

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 contains rich behavioral disclosure: unit conversion companion fields, derived lean/fat mass calculation, optional fields, proactive data collection, and upsert behavior. However, annotations declare idempotentHint false, while the description explicitly says 'Calling this tool twice on the same date updates the existing entry (upsert)' — an idempotent upsert behavior that contradicts the annotation. Per the rubric, description contradicting annotations must score 1.

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 very well structured: UNIT INPUTS, PROACTIVE DATA COLLECTION, INFER, and exclusion rules are all labeled and front-loaded. Vital unit-handling rules appear first because getting them wrong corrupts stored data. Every block earns its place, and the layout makes the dense content scannable.

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 23-parameter tool with unit pitfalls, derivation logic, and upsert semantics, the description is nearly exhaustive. It covers when to use the tool, how to infer dates, how to handle all supported unit cases, which fields to derive, which fields are optional, how duplicate calls behave, and what not to log. The output schema exists, so omitting return-value explanation is acceptable.

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, and the description adds a great deal of added meaning: exact rules for passing numbers unconverted and setting companion unit fields, formulas for lean_mass_lb and fat_mass_lb, the distinction between muscle_mass_lb and lean_mass_lb, and the clarification that *_in fields are manual tape measurements while *_pct fields are percentages. This is substantive semantic guidance 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 states a specific action on a specific resource: 'Log or update body composition metrics for a given date.' It names the exact trigger condition with concrete examples like weight, body fat percentage, typed manual input, copy-pasted scale output, or scale-display photos. This makes it clearly distinguishable from sibling read tools like list_body_metrics and show_body_composition.

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 clearly says when to use the tool: whenever the user shares body composition data. It also gives exclusions such as 'BMI is not a field here... never ask the user for BMI, and never try to log it' and gives proactive collection guidance. It does not explicitly name alternative sibling tools or explicit when-not conditions relative to list_body_metrics/show_body_composition, so it falls just short of a 5.

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

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

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 already indicate readOnlyHint=false, destructiveHint=false, idempotentHint=false, so the mutation profile is known. The description adds valuable behavioral context: it mandates a required workflow (list_lab_markers first), specifies inference rules (date, panel_name, flag, ref_range, lab_name), and clarifies fasting_status handling with explicit never-infer rules. It also states that all markers from a single visit should be submitted in one call. This goes well 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 long but every section earns its place: purpose, glucose routing, required workflow, prompting, inference rules, fasting rules, and batching instruction. It is well-structured with clear section headers (GLUCOSE ROUTING, REQUIRED WORKFLOW, INFER, FASTING) and front-loads the core purpose. It could be slightly tighter, but the density of actionable guidance justifies the length.

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 one array parameter and a rich nested schema, the description covers all the operational context an agent needs: when to use it, how to prepare canonical names, what to infer, what to ask, and how to batch. The output schema exists, so return values don't need explanation. The only minor gap is that it doesn't describe what the response looks like, but the output schema covers that. This is complete for the tool's complexity.

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 significant meaning beyond the schema: it explains the canonical marker_name/loinc_code workflow, defines when to omit loinc_code, clarifies fasting_status semantics (only 'fasting'/'non_fasting' when explicitly stated, omit otherwise), and explains draw_id usage. It also clarifies that report_date and draw_id are optional and when to include them. This is meaningful added value over 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 opens with a specific verb and resource: 'Log one or more blood test or biomarker results.' It then immediately distinguishes itself from log_wearable by routing finger-stick/CGM/home meter glucose to that sibling. This is a clear, specific purpose statement that differentiates the tool from its closest alternative.

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 when-to-use guidance: use for lab/blood-draw results, and explicitly excludes finger-stick, CGM, home meter, wearable, Apple Health, and Health Connect glucose, directing those to log_wearable. It also specifies the required workflow (call list_lab_markers first) and the prompt to use when the user hasn't shared results yet. This is exemplary 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?

Annotations declare it is a non-idempotent write (readOnlyHint=false, idempotentHint=false), but the description goes far beyond: duplicate detection and force=true retry semantics, the rule never to replace stored macros, recipe non-mutation, fasting-day collapse to a zero-macro "Fast day" Snack, and hydration/caffeine persistence behavior. This is unusually rich 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?

Front-loaded with purpose and trigger, then organized into clear headed sections, so structure is strong. It is long, and the DRINKS/HYDRATION and CAFFEINE/DRINKS sections partially restate each other (both repeat "single write path"), which is mild redundancy for an otherwise complex tool that justifies most of its length.

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 explained, and the description covers all the decision logic an agent needs for a 15-parameter write tool: inference, macro sourcing, optional fields, duplicates, fasting, drinks/caffeine, and recipe saving. 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 baseline is 3, but the description adds real meaning beyond the schema: INFER rules for date and meal_type (with time-band mapping and context overrides), the macro-source priority (repeats > saved recipes > brands > estimate), saturated_fat_g/fiber_g evidence rules, and fluids/caffeine/alcohol semantics. Schema fields even defer back to these sections ("See MACROS above"), so the description carries essential semantics.

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

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

States a specific verb+resource ("Log a meal to the user's food diary") and immediately scopes the trigger condition. It also distinguishes itself from siblings by naming list_meals, update_meal, and the never-use separate hydration/caffeine write tools. An agent can identify this as the single write path for meal food.

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

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

Explicit when-to-use ("user mentions eating, describes a meal, or asks to log food") plus when to route elsewhere: list_meals first for repeats, update_meal for adjusts, and explicit prohibition of separate hydration/caffeine tools. Covers when-not and alternatives, which is the top bar.

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 declare idempotentHint=true, but the description adds meaningful behavioral context beyond that: it explains that repeated calls are a no-op returning the same confirmation, and that the tool suppresses workout-prompt nudges and treats the day as planned rather than skipped. This is useful behavioral disclosure, though the idempotence itself is already annotated.

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

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

The description is well-organized into three purpose-driven chunks: what the tool does, how to interpret the date parameter, and idempotency behavior. Every sentence contributes actionable guidance, and the most important scoping information 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 a one-optional-parameter tool with an output schema and strong annotations, this description is complete. It covers purpose, usage triggers, date inference, idempotency, behavioral effect, and how to undo the action. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100% for the single date parameter, including format and default. The description goes further by providing explicit natural-language inference rules and examples ('today' = today, 'yesterday' = today minus 1, 'last Monday' = most recent Monday before today) and instructing the agent to infer rather than ask. This adds real value 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 opens with a specific verb and resource: 'Mark a date as an intentional rest day.' It immediately distinguishes this tool from its siblings by explaining the effect (suppresses workout nudges, treats the day as planned rather than skipped) and contrasts it with cancel_rest_day.

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 conditions with concrete examples: 'today is a rest day', 'I rested yesterday', and marking a past day after the fact. It also names the alternative, cancel_rest_day, for removal, so an agent can route correctly without 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 only declare the generic mutation profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false). The description adds genuine behavior: the write returns 'a card marker for in-app editing,' the log/plan intent controls whether history is mutated, and 'Never invent sensor data or splits' constrains hallucination. It does not discuss permissions or overwrite semantics, so it falls short of a 5.

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

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

The bulk of the opening is a unit-convention block, much of it enumerating companion fields that this tool's schema doesn't have, so the actual purpose ('Create an editable running card') is buried. Every remaining sentence is useful, but the front-loading is misprioritized and the reused template block is wasted text.

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 the mutation intent, run-type classification, unit handling, and data-fidelity rules, which is everything an agent needs to call this 19-parameter tool correctly. No material gaps remain.

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% (baseline 3), but the description adds real meaning beyond the schema: the schema fields merely point to 'See UNIT INPUTS,' and the description is where the actual rule lives (pass numbers unconverted, set the companion unit field, omit when canonical). It also explains run_type classification and detail-preservation constraints. It loses a point for listing unit families (_lb, _in, _stated_g, _stated_ml) that do not exist in this 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?

States a specific verb+resource ('Create an editable running card') and explicitly scopes it ('completed run OR a future run plan'). It also differentiates itself from the sibling log_workout by excluding non-running sessions, so an agent can route between them without opening either schema.

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

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

Explicit when-to-use and when-not-to-use: 'use log_run only for running on foot... A bike/cycling ride, walk, or rowing session is not a run... For those, use log_workout.' It also disambiguates intent (log vs plan) with the rule 'Never put a future run in completed history.'

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 surfaces behaviors not visible from annotations: repeated calls on the same date upsert rather than duplicate, entries are always tagged manual, and wearable-provider sources are reserved for auto-sync. It also discloses the proactive questioning behavior. These details match the write-oriented annotations and add real operational 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 organized into labeled sections, each earning its place: core purpose, proactive collection, inference rule, subset/upsert behavior, and manual tagging. There is no redundant or filler content, and critical scoping information 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 a 9-parameter write tool with many optional fields, the description answers the key operational questions: when to call it, what to ask if data is missing, how to compute date, whether partial data is allowed, what happens on duplicate calls, and how entries are tagged. An output schema also 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 100%, so the schema already defines each parameter. The description adds valuable semantics by clarifying that date refers to the wake date (night ending on that date), defaults to today, allows any subset of fields, and that a second call on the same date updates the existing row. This goes beyond the schema's per-field 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-resource pair, 'Log a sleep entry', and lists the exact data types accepted (duration, score, stage breakdown, bedtime, wake time) and the sources (Fitbit, Oura, Whoop, Apple Health, manual recall). It clearly distinguishes this write tool from read siblings like list_sleep and show_sleep_detail, and separates manual entry from wearable auto-sync behavior.

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?

'Use when the user shares sleep data...' gives an explicit triggering condition. Proactive data collection instructions specify what to ask when the user wants to log but has no numbers, and the 'INFER — do not ask' section prevents unnecessary clarification. It does not explicitly name sibling alternatives for when to use something else, but the manual-vs-auto-sync note provides a meaningful exclusion rule.

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

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

Annotations 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.

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

The description is highly transparent (additive step semantics, replacement behavior, no-op success), but it explicitly claims 'IDEMPOTENT' while the annotation idempotentHint is false. This is a direct annotation contradiction, so per rubric the score must be 1 despite the otherwise rich detail.

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 front-loaded purpose and uppercase section headers (VITALS, STEPS, ALL OTHER FIELDS, INFER, IDEMPOTENT). Some enumeration of vitals duplicates the schema, creating mild redundancy, but the operational rules justify most of the length.

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 17-parameter tool with an output schema and 100% schema coverage, the description covers all critical behaviors: defaulting to today, step additive semantics, replacement scope, no-op idempotent success, and lab-result routing. Only minor gaps exist, such as explicit behavior for omitting all fields, but nothing required for correct invocation 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 substantial extra meaning: step_count is additive and requires explicit confirmation, vitals replace existing manual values, systolic requires diastolic to accompany, and glucose routing depends on source. These are the exact semantic constraints the schema does not fully capture.

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

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

The description clearly identifies a specific verb and resource: logging daily wearable/manual health metrics across many vitals. It explicitly distinguishes where lab glucose values belong (log_lab_results instead), which separates it from that sibling without opening schemas.

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

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

Provides explicit when-to-use and when-not-to-use guidance: manual step_count only for device-missed steps, never for sync issues; lab-derived glucose belongs in log_lab_results; all other fields replace existing manual values. This is model-level 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?

Beyond annotations, it discloses the overlap conflict behavior: returns a warning with conflicting entry IDs and requires the user to update or delete existing entries first. It also explains date-range inference defaults and rating estimation. This adds meaningful behavioral context not present in 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 front-loaded with the core purpose, then organized into support scope, conflict handling, and inference bullets. Every section adds operational value, with no filler or redundant restatement of the schema.

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

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

For a 7-parameter tool with all optional fields and an output schema, it covers when to use it, how to derive period and ratings, and what happens on conflicts. The output schema handles return-value details, 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 schema coverage is 100%, the description adds substantive meaning: natural-language inference rules for period_start and period_end ('this week' = Monday–Sunday, 'this month' = first–last day) and example rating mappings ('exhausted'=2, 'great energy'=8). It also clarifies that any subset of rating fields may be logged, which is operationally useful.

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 subjective wellbeing ratings for a day, week, month, or custom date range.' It names the rating dimensions (energy, mood, stress, soreness), which clearly distinguishes it from sibling log_* tools such as log_sleep, log_body_metrics, and log_workout.

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: 'Use when the user describes how they feel — energy level, mood, stress, or muscle soreness.' It also defines date-inference behavior and overlap handling, but it does not explicitly name alternative tools or give when-not-to-use exclusions.

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