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

Annotations only state readOnly=false, openWorld=true, idempotent=false, and destructive=false, so the description carries the behavioral burden. It adds meaningful detail: validation happens before synchronization, rejected inputs are called out, results include a confirmed status, and returned itemIds are persisted and ready for later meal-item mutations. No contradiction with annotations exists.

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 action and then gives usage priorities, rejection behavior, and the result shape. It is longer than minimal but each sentence earns its place, except for the vague 'id field selects the variant' sentence, which adds little clarity.

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-way variant complexityholo, the description is complete: it explains how to choose among product, recipe, and custom variants, what identifiers to provide, what validation risks exist, and what the caller can expect in the response. Combined with the fully documented schema, an agent has enough 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%, so the schema already documents each parameter. The description still adds value beyond the schema by explaining preference ordering, specifying raw recipeId, and noting that custom items should only be used when no catalog match exists. The phrase 'The id field selects the variant' is slightly vague and does not map cleanly to a named schema property, which keeps this from a perfect score.

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-plus-resource statement: it validates, submits, and confirms products, recipes, or custom items in a Fitatu meal. It clearly distinguishes the three item variants and differentiates this tool from the surrounding meal-mutation siblings by emphasizing that it adds new items rather than updating, replacing, or removing them.

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 usage direction: search_food or search_recipes should be used first, catalog products or recipes are preferred, and custom items are a fallback only when no suitable match exists. It also explains preconditions such as using raw recipeId and measureId and warns that deleted recipes and mismatched measures are rejected.

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

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

Annotations already declare readOnlyHint=false and idempotentHint=false, and the description amplifies these by explicitly stating 'repeating the same request creates another recipe'. It also discloses the privacy default ('private unless shared=true') and the return contract (status, recipeId, details, warnings) with a pointer to add_meal_items. This is rich behavioral context 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 seven sentences, which is on the longer side, but every sentence earns its place: purpose, required fields, step formatting, numeric validation, tag guidance, privacy default, and return behavior. The main purpose is front-loaded, and there is no filler or repetition.

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

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

For a 9-parameter creation tool, the description is remarkably complete. It covers prerequisites, validation rules, preparation steps semantics, tag handling, visibility default, return structure, downstream compatibility, and non-idempotency. The output schema exists, so the return-value details do not need full enumeration, but the description still provides the critical integration points.

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 value by explaining the 'why' behind step arrays ('one step per array item so Fitatu displays separate step fields'), reinforcing numeric constraints ('positive finite numbers'), and directing custom tags to RECIPE_TAG_USERS_TYPE. These clarifications exceed what the schema alone 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 uses a specific verb-resource pair ('Creates and confirms a Fitatu recipe') and immediately names the source of validated products ('selected with search_food'). This distinguishes it from siblings like update_recipe, get_recipe, and delete_recipe without needing to open their schemas.

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

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

The description states clear prerequisites: products must be validated via search_food, required fields (name, ingredients, servings), and downstream integration ('measureId values accepted by add_meal_items'). It does not explicitly say 'use update_recipe to modify an existing recipe', but the creation context and non-idempotency warning make the intended use unambiguous.

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

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

Beyond the annotations' destructiveHint, the description adds crucial behavioral nuance: the deletion is soft, the recipe disappears from searches, existing day-plan entries remain as historical snapshots, and the operation requires exact-name confirmation. It also states the return shape. This exceeds what annotations alone convey.

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

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

The description is dense and information-rich without filler. Each sentence covers a distinct need: what is deleted, what persists, how to remove the remaining artifacts, and what the response contains.

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

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

Given the tool's destructiveness and confirmation requirement, the description fully covers behavior, parameter sourcing, side effects, and return value. The output schema and sibling context complement it, so an agent has everything needed to invoke it safely and 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 the baseline is 3. The description adds meaningful context beyond the schema: recipeId must be a raw id from a recipe-aware MCP tool, and expectedName is an untrimmed, case-sensitive confirmation value obtained from get_recipe. This reinforces and extends the schema documentation.

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

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

The description uses a specific verb ('soft-deletes') and a precise resource ('owned active recipe definition identified by a raw recipeId after exact-name confirmation'). It clearly distinguishes this deletion from removing meal-plan entries, which is handled by remove_meal_items.

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 states when the tool applies (owned active recipes with exact-name confirmation) and explicitly tells the agent that day-plan entries are not removed and must be handled separately via remove_meal_items. This prevents a common misuse 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 already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context beyond annotations by explaining the date-omission fallback and the scope across weight, circumference, and body-fat history.

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

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

Two sentences with no filler. The primary operation and resource are front-loaded, and the second sentence clarifies the optional-date behavior. Every word earns its place.

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

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

The tool has one optional parameter, a complete schema, rich annotations, and an output schema. The description covers the only meaningful behavioral nuance (default date selection). 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 description coverage is 100% and the only parameter, date, is already described with format and optionality. The description adds the defaulting behavior ('defaults to the latest available entry') but does not need to explain the parameter further, so the baseline of 3 is appropriate.

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

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

The description clearly states the action ('Gets'), the resource ('the authenticated Fitatu user's body measurement'), and the optional date scope. It avoids tautology by adding the default behavior, and the read/write distinction from save_body_measurement is evident from the verb.

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 context for when to call the tool: retrieving a body measurement for an optional date, with the latest measurement returned when date is omitted. It does not explicitly name sibling alternatives or state when not to use it, but the read-only verb and the write-focused sibling save_body_measurement make the intended use reasonably 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, openWorldHint, and idempotentHint, covering safety and side-effect behavior. The description adds the 'authenticated' qualifier, which clarifies that the tool operates on the user in the current session – a meaningful contextual detail. However, it does not disclose error behavior (e.g., if no user is authenticated) or any rate-limit considerations, but given the annotation coverage, a 3 is justified.

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

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

The description is a single, compact sentence with no redundant words. It front-loads the verb and resource immediately, conveying the core action without fluff. Every word contributes to the meaning.

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

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

Given the tool's simplicity, the description, combined with the output schema (which is present) and annotations (readOnly, idempotent, openWorld), fully covers what an agent needs to know to invoke it correctly. There is no missing information about parameters, return values (handled by output schema), or side effects (handled by annotations).

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

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

The tool has zero parameters, so the schema provides no parameter details. According to the rubric, a baseline of 4 is appropriate for 0-parameter tools. The description adds nothing about parameters because none exist, and no further semantics are required.

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 ('fetches'), a clear resource ('currently authenticated Fitatu user'), and a result ('profile'). It distinguishes from all sibling tools, which handle meal items, recipes, body measurements, and settings – none of which are about retrieving the current user. This leaves no ambiguity 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 implicitly indicates the tool is for retrieving the current user's profile, which is distinct from other tools like get_user_settings or get_diet_summary. It does not explicitly name alternatives or state when not to use it, but the purpose is so unambiguous that an agent would naturally select it for that action. A slight deduction for not explicitly mentioning exclusions, but the context is clear.

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

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

Annotations already cover readOnlyHint, idempotentHint, and openWorldHint, lowering the bar. The description still adds value beyond annotations by revealing the default local-date behavior and by clarifying how returned identifiers map to fixable/removable entries versus food definitions. 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, each earning its place: the first defines purpose, the second gives actionable ID-handling guidance for sibling tools, and the third states the default date. 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 simple, read-only, optional-parameter fetch with a rich output schema, this definition is highly complete. Annotations cover safety and open-world behavior, the schema documents both parameters, and the description supplies the critical cross-tool usage guidance. Nothing essential is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description only repeats the date default already stated in the schema and adds nothing about withRating. It doesn't harm, but it doesn't enhance parameter understanding 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: "Fetches Fitatu meals and concrete day-plan entries." It clearly differentiates this retrieval tool from the mutation siblings (add_meal_items, update_meal_item, remove_meal_items, etc.) by explaining what the returned IDs mean and which ones should be passed to those mutation 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 clear downstream context: it tells the agent to copy mealKey with itemId into update/move/remove tools and warns that productId/raw recipeId are not removable entries. It also explains the default-date behavior. It does not explicitly state when not to use this tool or name alternative fetch tools, so it misses the top tier.

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, idempotent, and open-world behavior. The description adds the authenticated-user scope and clarifies that the date range is inclusive, which is useful context. It does not add auth requirements, rate limits, or other behavioral details, but the annotation coverage lowers the burden.

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

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

A single 15-word sentence that front-loads the verb and resource and includes the key scope (authenticated user, inclusive date range). There is no fluff, repetition of the title, or filler 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 read-only, two-parameter fetch with an output schema and safety annotations, the description plus schema fully specify how to call it. User scope and date inclusivity are stated, and the output schema covers 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?

Schema description coverage is 100%: both fromDate and toDate have format and meaning descriptions, and the schema-level description states the fromDate <= toDate ordering constraint. The tool description adds no parameter-specific detail beyond the schema, so the baseline 3 applies.

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

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

The description uses a specific verb ('Fetches') and a specific resource ('authenticated Fitatu user's nutrition and energy summary'), plus the inclusive date-range scope. This clearly distinguishes it from sibling getters like get_day_plan_items or get_body_measurement without requiring a schema read.

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

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

The description implies the use case: retrieve a nutrition/energy summary for a date range. However, it never explicitly states when to use this tool vs. alternatives or mentions any exclusions, leaving the routing to inference.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds substantial behavioral context beyond that: soft-deleted recipes remain readable with deleted=true and editable=false, and overlapping productId/recipeId spaces are resolved by the recipeId field. These details inform the agent about edge-case behavior and result interpretation, going well 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 efficiently structured: the main purpose is front-loaded, followed by key edge-case behaviors, and finally the return structure. Every sentence adds necessary information—no filler. The length is justified by the technical complexity (ID-space overlap, soft-delete handling) and is still concise.

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

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

Given a single parameter, a full input schema description, and an output schema (indicated by the return structure), the description covers all essential aspects: what it does, when to use it, input constraints, edge cases, and the shape of the result. It does not need to restate return values since an output schema exists. Nothing critical for an agent to call 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 input schema already describes recipeId as 'Raw Fitatu recipe id returned by a recipe-aware MCP tool,' giving 100% coverage. The description adds further semantic value by explaining that 'Raw productId and recipeId spaces may overlap, so the recipeId field determines how the supplied value is interpreted.' This clarifies ambiguity that the schema alone does not address, making the parameter semantics richer.

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: 'Gets canonical per-serving details and add_meal_items measures for a raw recipeId.' It further narrows the input to IDs 'returned by a recipe-aware MCP tool,' distinguishing this read tool from siblings like search_recipes (query-based) and create/update/delete mutations. The term 'canonical' reinforces its role as the authoritative recipe detail fetcher.

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 states the input is a raw recipeId from a recipe-aware MCP tool, which tells an agent when to use it (when it already holds such an ID). It also notes soft-deleted recipes remain readable with deleted=true and editable=false, providing context about behavior in that edge case. However, it does not explicitly name alternative tools or give a 'when not to use' clause, so it lacks explicit exclusions.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds meaningful behavioral context beyond annotations: date resolution defaults to today in the user's Fitatu timezone, which is a non-obvious behavior an agent needs to know. This is valuable added context.

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

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

Two sentences with zero filler. The core action is front-loaded, and the optional-date behavior is stated succinctly. Every sentence earns its place; nothing is redundant or verbose.

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

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

For a simple read-only tool with one optional parameter and an output schema (which covers return values), the description is complete. It explains the primary function and the date-resolution behavior, and the annotations cover safety and idempotency. Nothing essential is missing.

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

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

Schema description coverage is 100%: the date parameter is fully documented in the schema, including its format and default behavior. The description repeats this information without adding new meaning, so it does not compensate beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states the verb ('gets'), the resource ('the authenticated Fitatu user's ... settings'), and the specific settings types (energy, calculated, water). It distinguishes itself from siblings like update_user_settings (a setter) and get_current_user (user profile, not settings) without ambiguity.

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

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

The description implies usage as the read operation for user settings, but it does not explicitly contrast it with alternatives or state when not to use it. The date-resolution behavior is described, but no explicit when-to-use vs. other tools guidance is provided; the guidance is mostly 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?

Discloses the critical side effect that Fitatu creates a new item id during a valid move — information absent from the annotations, which only carry readOnlyHint/idempotentHint/destructiveHint. It then instructs the agent to 'use the returned itemId for later mutations,' preventing a likely follow-up error of reusing the stale id. Including the exact return shape reinforces confirmation behavior beyond what the annotations 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?

Four sentences with the verb+resource action front-loaded, followed by the constraint, side-effect warning, and follow-up guidance — each sentence earns its place. There is no filler or redundant restatement of the title.

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

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

For a 5-parameter mutation with a non-obvious side effect, the description covers selection criteria, destination constraints, item-id recreation, return shape, and post-call usage. The annotations and output schema cover the safety profile and return structure, so nothing essential an agent needs to invoke this correctly is missing.

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

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

Schema coverage is 100%, so the schema already documents all five parameters; baseline is 3. The description adds cross-parameter coordination by tying together the source triad (fromDate, fromMealKey, itemId) and the at-least-one-destination constraint, but this largely mirrors the schema's own description. No new per-parameter facts are introduced.

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 ('Moves and confirms') with a resource ('Fitatu meal item') and exact selection criteria (source date, mealKey, itemId). The verb 'moves' clearly distinguishes it from sibling meal-item tools like update_meal_item, replace_meal_item, and remove_meal_items, which perform different operations.

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?

Sets clear preconditions: 'Provide a destination date, mealKey, or both that differs from the source,' which tells the agent exactly what inputs satisfy a valid move. It does not explicitly name alternatives or state when not to use this tool, so an agent must infer the choice against update/replace/remove siblings from the verb and operation semantics alone.

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 include destructiveHint=true, readOnlyHint=false, and idempotentHint=false. The description adds meaningful behavioral detail: atomicity ('Atomically removes'), failure semantics ('If any requested active item is missing... nothing is synchronized'), and a defined success condition ('Returns { status: 'confirmed' ... } after every selected item is absent'). 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 core action is front-loaded, followed by input sourcing instructions, then atomic behavior and return shape. Every sentence carries essential 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 two-parameter destructive operation with annotations and an output schema, the description is complete: it covers what the tool does, where to obtain the required IDs, what not to pass, atomic rollback behavior, and the confirmed return payload. The output schema handles return structure; no critical calling information 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% and the schema descriptions already explain date, items, the source of mealKey/itemId pairs, and the rejection of productId/recipeId. The description restates those points but adds little new parameter meaning beyond what the schema provides, so the baseline 3 applies.

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

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

Description states a specific verb and resource: 'Atomically removes and confirms exact Fitatu day-plan entries of any food type.' It clearly distinguishes from siblings (add, update, replace, move) by focusing on removal, and even clarifies the input form ('mealKey and itemId pair').

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 operational guidance: 'Copy each mealKey and itemId pair from get_day_plan_items; do not pass productId or recipeId.' This names the source read tool and a negative constraint. It doesn't explicitly contrast with alternative mutation tools like update_meal_item or replace_meal_item, but the action is clear enough that selection is straightforward.

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

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

Goes well beyond the annotations by disclosing key behaviors: replacement is confirmatory, omitted eaten state is preserved, same-catalog replacements are rejected, the exact return shape is provided, and item order is not part of the contract. No contradiction with destructiveHint=true or readOnlyHint=false.

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

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

Five sentences, each carrying essential information: action, identification, eaten semantics, rejection/alternative, return value, and ordering caveat. Front-loaded with the core purpose and free of 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?

Complete for a mutation tool with a nested replacement payload. The description covers identification, payload contract, edge-case rejection, output format, and post-return usage. The schema and output schema provide the remaining structural detail, so nothing an agent needs to invoke 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 schema already documents all parameters and the three replacement variants. The description adds meaningful semantics beyond the schema by stating that replacement uses the same payload contract as add_meal_items, that eaten defaults to preservation, and that the returned itemId should be used for later mutations.

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 ('Replaces and confirms'), a resource ('one existing Fitatu meal item'), and the selection criteria (date, mealKey, itemId). It clearly distinguishes itself from update_meal_item by noting that same-catalog-definition swaps are rejected and should use update_meal_item instead.

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

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

The description explicitly names an alternative tool and the condition that selects it: 'use update_meal_item for quantity, measure, or eaten changes.' It also instructs how to identify the target entry and which payload variant to prefer (PRODUCT/RECIPE before CUSTOM_ITEM), giving unambiguous 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?

The description adds meaningful PATCH semantics not present in the annotations: omitted values stay unchanged and existing values cannot be cleared. It also notes the authenticated-user requirement. The destructiveHint=true annotation is not contradicted because overwriting an existing measurement is still a mutation, even though values cannot be nulled.

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 dense sentences with no filler. The primary verb and scope are front-loaded, and the key exception ('cannot be cleared') is placed at the end without unnecessary detail.

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

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

The description, full schema, and output schema together cover most of what an agent needs to call this correctly. The only notable gap is whether a measurement record must already exist for the date or whether the call can create one, since 'save' and 'partially updates' leave this slightly ambiguous.

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 every parameter with 100% coverage, but the description adds global parameter behavior: omitted optional values remain unchanged and clearing is impossible. This is important semantic information that cannot be inferred from 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 uses a specific verb and resource: 'Partially updates the authenticated Fitatu user's body measurement for an explicit date.' This clearly distinguishes it from the sibling get_body_measurement and other update tools. It is not a tautology of the name or 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 gives clear context for use: it is for partial updates to a body measurement on a specific date, and omitted values remain unchanged. It also implies a when-not case by stating existing values cannot be cleared, though it does not explicitly name alternatives like get_body_measurement for reading.

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

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

Annotations declare readOnlyHint and idempotentHint. The description adds crucial behavioral traits: no alias inference, separate userItems/publicItems lists not merged/deduplicated, candidate id semantics (productId vs recipeId), and constraint on foodType. Contradicts nothing.

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

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

Four tightly packed sentences, all informative, front-loaded with the core search function and caveats. No fluff.

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?

Covers all behavioral caveats an agent needs: alias handling, result grouping, id selection, detail toggling, and forbidden fields. Output schema exists for return format; no gaps.

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 significant meaning beyond the schema: explains query variant grouping, details quota consumption order (user first), and candidate id usage. Enriches parameter understanding.

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 ('Searches'), resource ('Fitatu catalogs for products and recipes'), and explicitly contrasts with the sibling search_food_by_barcodes (barcode vs. phrase search). Clear differentiation.

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

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

Explicitly instructs when to use includeDetails (only when alternative/missing measure needed), how to construct queries (provide alternative phrases together), and what not to send ('Do not send foodType'). Includes exclusions and alternatives.

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

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

Beyond the readOnly/idempotent/non-destructive annotations, the description discloses parallel execution, the 10-item cap, one minimal result group per input barcode, input-order preservation, and duplicate handling. This gives an agent accurate expectations about behavior and output shape without contradicting any annotation.

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 cover scope, return behavior, and workflow, with no filler or repetition. The core action and constraints are 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?

Given rich annotations, full schema coverage, and an output schema, the description supplies the missing behavioral context: parallel lookup, ordering, duplicates, and the handoff to add_meal_items. Nothing an agent needs to call 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 describes all three parameters clearly, so the description adds little per-parameter detail. It usefully explains that results are grouped per barcode, but this is return-shape guidance rather than new parameter semantics; baseline 3 is appropriate.

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

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

The description states a specific action ('Searches'), a precise resource ('Fitatu's public food catalog'), and concrete constraints ('up to 10 GTIN barcodes in parallel'). It also deliberately separates this from add_meal_items by stating it 'only searches and never adds food,' making the tool's identity 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 clearly locates the tool in a workflow: search first, then copy productId and measureId into add_meal_items. It explicitly excludes the adding behavior, but it does not name the sibling search_food as the alternative for non-barcode queries, so the guidance is clear though not exhaustive.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, giving a safety profile. The description adds meaningful behavior beyond that: trimming of query, case-insensitivity, returning raw recipeId values, empty/whitespace query listing all recipes, and the partial-results-with-warnings behavior for scope=all. No contradictions with annotations; the description enhances the behavioral understanding.

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 efficient and front-loaded with the core search behavior, then adds optional flags and edge cases. It covers a lot in a compact text without redundancy. Slightly dense, but each sentence adds information. It doesn't waste words, though it could be split into clearer paragraphs.

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 clarifying the return structure, the description focuses on behavior. It covers all key edge cases: empty queries, scope combinations, warnings, and the optional details flag. Given the tool's moderate complexity and the presence of a rich schema, the description is complete for an agent to correctly invoke it.

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%, but the description adds crucial semantics: 'trimmed' for the query, the raw recipeId return, and the warning behavior for scope=all. These details are not present in the schema and directly inform parameter usage. The description also clarifies the purpose of includeDetails in the day-plan context, which is not captured in the schema's parameter description.

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

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

The description states a specific verb ('searches') and resource ('active recipes'), and defines the matching semantics (trimmed, case-insensitive name substring) and the output (raw recipeId values). This is unambiguous and distinct from sibling tools like search_food or search_food_by_barcodes, which target food items rather than recipes. No confusion about what is being searched.

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 practical guidance: it notes that includeDetails=true provides details useful for adding a recipe to a day plan, and explains the distinction of scope=all (combines catalogs, returns partial results with warnings). While it doesn't explicitly name alternatives like get_recipe or search_food, it provides enough contextual cues for an agent to decide when this tool is appropriate, especially with the sibling list available.

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 reveals key behaviors: PRODUCT/RECIPE measure changes require compatible measures, CUSTOM_ITEM updates are restricted to specific fields with immutable technical measures, and the tool returns a confirmed status only after persistence is observed. These are material behavioral details not visible in the annotations alone.

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

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

Three dense sentences each carry essential information: core action and identity, item-type constraints, and return/confirmation behavior. 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?

The description covers the core behavior, item-type restrictions, measure compatibility, and confirmation semantics, which is substantial for an 11-parameter tool. It could be slightly stronger with an explicit statement of when to choose this over replace_meal_item, but the existing identity-based selection and 'updates' wording largely cover that context.

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

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

With 100% schema description coverage, the schema already documents individual parameters. The description adds cross-parameter and type-specific semantics, such as which fields are valid for CUSTOM_ITEM entries and that PRODUCT/RECIPE quantity/measure changes require a measure belonging to the food definition. This goes beyond the schema's per-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?

The description explicitly states a specific verb ('Updates and confirms'), the resource ('one existing Fitatu meal item'), and the exact selection key (date, mealKey, itemId). This clearly differentiates it from sibling operations like add, replace, remove, or move.

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 clear context for when this tool is appropriate: updating an existing meal item with exact identity fields. It does not explicitly name alternatives or exclusion conditions, but the 'existing' and 'exact date, mealKey, itemId' framing implicitly separates it from adding or replacing operations.

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 rich behavioral detail beyond annotations: omitted fields are preserved, null clears time fields while [] clears lists, identity may be replaced, and returned details.measures are accepted by add_meal_items. It also warns that raw public mealSchema values from get_recipe may not be valid mutation inputs. This substantially exceeds what destructiveHint/readOnlyHint 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?

The description is dense but every sentence carries critical information. It front-loads the core purpose, then covers mutation semantics, identity replacement, tag constraints, and the return contract without redundancy. Length is justified by the tool's complexity.

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

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

For a partial-update mutating tool with 10 parameters, an output schema, and known sibling tools, the description covers the essential behavioral contract, return shape, and edge cases like identity changes and invalid raw mealSchema values. The provided output schema supplies formal return details, so the description is sufficiently 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%, so the baseline is 3, but the description adds semantic value by explaining update semantics: null clears, [] clears lists, one step per array item, and tag category constraints. It also clarifies that returned mealSchema values are not necessarily valid inputs. 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 states a specific action: 'Partially updates and confirms an owned active recipe identified by a raw recipeId.' This clearly distinguishes the tool from siblings like create_recipe, delete_recipe, and get_recipe by identifying both the operation and the target resource.

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 strong usage context: it applies to owned active recipes, uses a raw recipeId from a recipe-aware tool, and references 'the same create limits' from the create path. It does not explicitly list alternatives or when not to use this tool, but the context is clear enough to guide selection among sibling recipe tools.

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

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

Annotations already indicate readOnlyHint=false, destructiveHint=true, and idempotentHint=true. The description adds valuable context: it mentions partial updates, the ability to combine energy and water, and that omitted supported settings and all unsupported settings are preserved. This goes beyond the annotations by clarifying the non-destructive nature to unaffected settings. It does not contradict the annotations; destructiveHint refers to modifying target values, which is consistent with the update behavior described.

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 concise sentences, each earning its place. The first sentence states the core purpose; the second enumerates capabilities; the third clarifies preservation behavior. It is front-loaded with the main action and avoids redundant details that are already in the schema. No fluff or extraneous 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 the tool's moderate complexity (partial updates, multiple optional parameters, two modes), the description covers the essential aspects: what it updates, how modes work, and that omitted settings are preserved. The schema provides detailed field-level info, and an output schema exists, so the description does not need to explain return values. It lacks explicit mention that at least one parameter is required, but the schema's minProperties=1 covers that. Overall, it is sufficiently complete 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 description coverage is 100%, so the schema fully documents each field. However, the description adds semantic value beyond the schema: it clarifies that energyTarget can be a 'complete manual energy target' or switch to 'automatic mode', and explicitly states that energy and water can be combined in one update. It also explains preservation of omitted settings, which is not in the schema. This meaningful addition justifies a score above the baseline of 3.

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 ('updates') and resource ('authenticated Fitatu user's supported settings'), and lists distinct capabilities (manual energy target, automatic mode, water serving size, combined updates). It clearly differentiates from the sibling get_user_settings, which reads settings, while this tool updates them. The phrasing is unambiguous and leaves no room for confusion about the tool's role.

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

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

The description implies usage by stating it updates settings and enumerates what it can change, making it obvious this is the tool to use for modifying Fitatu user settings. It does not explicitly mention when not to use it or name alternatives, but given the sibling list, there is no other update-settings tool. The context is clear, though it could explicitly state 'use this to change settings' rather than leaving it implied.

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