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

Annotations only provide idempotentHint, so the description carries most of the burden, and it delivers: it discloses the destructive overwrite-by-name behavior (consistent with idempotency), the fallback defaults for searchTerms and category, and the fields returned in the confirmation. It does not mention auth or error behavior, but the mutation semantics are well surfaced.

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 short sentences, front-loaded with purpose and usage before the defaults tip and return summary. The phrase 'reducing input friction' is mildly editorial but the rest is dense and waste-free.

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 no output schema, the description correctly compensates by summarizing the confirmation payload. Combined with the overwrite warning and default behavior, an agent has enough to call this 5-required-parameter mutation correctly, though nothing is said about failure modes.

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 restates the searchTerms and category defaults already documented in the schema, and does not add format or validation meaning for required fields like complexity, cuisineType, or the ingredient quantity strings.

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 pair (add/update) and resource (recipe), then adds the domain purpose (meal planning and deal scoring). This clearly distinguishes it from siblings like get_recipes, remove_recipe, and score_recipes without needing to open any schema.

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

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

The explicit 'USE WHEN: saving a new recipe or updating an existing one' gives a clear trigger condition, and the overwrite note clarifies that there is no separate update tool to switch to. No alternatives or exclusions are named, but the sibling set contains no competing add/update recipe tool, so guidance is effectively complete.

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

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

Annotations already declare readOnlyHint=true, so safety is covered, and the description adds a real precondition: household stores must be configured via update_household before this tool is useful. It does not describe the return shape or the per-store capping behavior implied by the limit parameter, which keeps it 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?

Three compact labeled clauses (purpose / USE WHEN / NOT FOR) plus a prerequisite sentence. Front-loaded purpose, zero filler, and the structured labels make scanning trivial.

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-required-parameter read tool with full schema coverage and readOnlyHint, the description covers purpose, selection criteria, an alternative, and the configuration prerequisite. No output schema exists, so return values need not be explained.

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

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

Schema coverage is 100% and the single 'limit' parameter is fully documented in the schema (default 30, max per store), so the description needn't restate it. The description adds no syntax or behavior beyond the schema, matching the baseline 3 for schema-documented params.

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 ('Show') and resource ('best current deals from your preferred stores'), and explicitly contrasts itself with the sibling search_deals. An agent can distinguish this browsing tool from product search 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 USE WHEN triggers (browsing cheap items this week, deciding what to cook) and an explicit NOT FOR clause routing specific-product queries to search_deals. It also names the enabling prerequisite (household stores via update_household), leaving nothing to inference.

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

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

Annotations only declare readOnlyHint=true, and the description is consistent with that while adding real behavioral substance: it aggregates quantities across recipes, computes pack sizes, flags expiring deals, and requires that recipes already exist. It does not cover pagination, error behavior, or what happens with duplicate recipes, but the added context is well beyond the 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?

Front-loaded with the core capability, then organized into USE WHEN / NOT FOR / prerequisite segments that are easy to scan. Dense but every clause carries routing or prerequisite value; no filler sentences.

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

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

No output schema exists, but the description sketches the return shape (grouped by store, flagged expiring deals) and states the prerequisite, which is sufficient for a read-only aggregation tool. Minor gaps are pagination and handling of unknown recipe names.

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 (people, recipes, excludePantry) are already documented in the schema, making 3 the baseline. The description reinforces that recipes drive the list but adds no syntax or format detail beyond the schema, e.g. whether recipe names are case-sensitive or fuzzy-matched.

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 ('Deal-optimized shopping list from specific recipes, grouped by store') and immediately differentiates itself from siblings by scoping to chosen recipes and store grouping. An agent can distinguish it from score_recipes and plan_and_shop without opening any schema.

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

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

Explicit USE WHEN with a concrete trigger phrase ('shopping list for Bolognese and Chili'), an explicit NOT FOR naming the alternatives (score_recipes, plan_and_shop), and a prerequisite pointing at add_recipe. Nothing is left to inference.

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

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

Annotations already declare readOnlyHint=true, so safety is covered. The description adds genuinely useful behavior beyond that: it discloses the fallback response ('returns onboarding guidance if not yet configured'), which tells the agent how to handle the unconfigured case. No permission or rate-limit detail, but for a zero-param read tool this is solid.

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 tight sentences: what it returns, when to use it, and the edge-case behavior, all front-loaded. No filler, no repetition of the name, 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?

With no output schema, the description carries the burden of describing returns, and it does so by listing the config fields plus the unconfigured fallback. Missing only minor edge cases (e.g., error conditions or auth requirements), but for a simple read tool it is essentially 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 tool takes zero parameters, so per the rubric the baseline is 4. There is nothing to disambiguate, and the description correctly describes the returned content rather than implying any inputs.

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 (get) and resource (household config) and enumerates the returned contents: people, dietary restrictions, preferred stores, servings. This clearly separates it from siblings like update_household, get_pantry, or list_stores without needing to open 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 WHEN:' clause gives concrete triggering contexts (checking setup before meal planning, verifying store preferences), which is more than most read tools offer. It does not explicitly state when NOT to use it or name update_household as the alternative for making changes, but the intended 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 declare readOnlyHint=true, so safety is covered. The description adds useful behavioral context by specifying what is returned: 'meal entries with dates, recipe names, and who ate', which compensates for the absence of an output schema. It does not mention ordering, pagination, or limits, so it falls short of full 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?

Three short sentences that are front-loaded and waste no words. Purpose, usage, and return content are each stated once and in a logical order.

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 retrieval tool with one optional parameter and no output schema, the description covers the essentials: what it returns, when to use it, and the resource scope. Minor gaps like default behavior for the weeks parameter or result ordering are not critical 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% for the single 'weeks' parameter, so the schema already carries the semantic burden. The description does not add any parameter-specific meaning or formatting guidance, making the baseline 3 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 resource (recent meal history) and a clear purpose (rotation planning). It distinguishes itself from log_meal and recipe tools by focusing on historical retrieval, though it does not explicitly name a sibling it is not.

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 an explicit 'USE WHEN' section naming two concrete scenarios: avoiding repetition and reviewing eating patterns. It lacks explicit when-not conditions or alternative siblings, but the context is clear enough for an agent to select it.

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?

readOnlyHint=true already establishes the safety profile, so the description only needs to add nuance. It does: the parenthetical explains that pantry items are excluded from shopping lists (domain behavior not in annotations) and states the return shape ('list of pantry item names'), which matters since there is no output 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?

Three short sentences, front-loaded with what the tool returns and scoped by an immediately following usage trigger. Every clause earns its place with no filler.

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

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

For a zero-parameter read tool with readOnlyHint and no output schema, the description supplies everything needed: the resource, the return shape, and the moment to call 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?

The tool takes zero parameters, so there is no schema surface for the description to compensate for; baseline is 4. The description correctly says nothing about arguments rather than inventing filtering options that don't exist.

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

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

States a specific verb ('List') and resource ('pantry items'), and adds a distinguishing scope note ('excluded from shopping lists') that separates it from cart/shopping-list siblings. An agent can tell it apart from update_pantry and generate_shopping_list without opening any schema.

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

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

The 'USE WHEN' clause gives an explicit triggering context (before generating a shopping list), which is genuinely actionable. It does not name exclusions or rival tools (e.g. get_household) explicitly, so it falls short of a full 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?

readOnlyHint=true already covers the safety profile, and the description goes beyond it by disclosing the payload and the empty-state behavior (returns onboarding guidance when no recipes exist), which is genuinely useful context for an agent. It says nothing about ordering, pagination or result limits, so it is not exhaustive.

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 tight sentences, all front-loaded: purpose first, then usage, then the non-obvious empty-state behavior. No filler and nothing repeated from the name or annotations.

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 no input parameters, a read-only annotation and no output schema, the description is nearly self-sufficient — it explains both the normal return contents and the zero-recipe case. Only ordering/pagination details are absent, which is a minor gap.

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

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

The tool takes zero parameters, so there is nothing to disambiguate and the schema is trivially complete (100% coverage). No syntax or format details are needed here.

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

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

States a specific verb (List) plus the resource (saved recipes) and enumerates what comes back (ingredients, metadata, search terms). It is clearly distinguishable from the write-oriented siblings add_recipe/remove_recipe and the analysis tool score_recipes, though it never names them explicitly.

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 WHEN' clause gives two concrete contexts (reviewing the recipe library, checking availability for meal planning), which is clear positive guidance. It stops short of naming alternatives or stating when not to use it, so it misses the top band.

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?

readOnlyHint=true already tells the agent this is a safe, non-mutating read, so the safety burden is largely covered by structured data. The description adds a modest amount of value by outlining the return content (entries, totals, weekly averages), but says nothing about pagination, limits, or whether a logging entry is created elsewhere. Adequate but thin against an already-covered 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 short sentences, front-loaded with what the tool returns before the USE WHEN cue. Minor redundancy: 'weekly averages' appears twice, which slightly dilutes an otherwise tight structure.

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 single-optional-parameter read tool with no output schema and a covering readOnlyHint, the description gives enough: what it returns and when to reach for it. Only the absence of any pointer to the log_spend counterpart keeps it from being fully complete.

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

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

Schema description coverage is 100% with a single optional parameter ('weeks', default 8) already documented in the schema. The description adds no syntax, range, or interpretation beyond the schema, so the baseline 3 for full coverage 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 states a specific resource (spending history) and the shape of what it returns (entries with weekly averages and totals). It is clear and distinct from the write-side sibling log_spend, though it never explicitly names that counterpart, so it falls short of the 5-level sibling differentiation bar.

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: reviewing grocery budget, tracking spending trends' gives concrete usage contexts that map onto the household/grocery sibling set. It omits any when-not guidance and does not point to log_spend as the alternative for recording spend, so it stops short of the explicit alternatives the 5-level rubric wants.

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 establish readOnlyHint=true, so safety behavior is covered. The description adds useful return-content context not found in structured fields: prices, unit prices, store name, and expiry dates. It falls short of disclosing ordering, pagination beyond the schema limit, or freshness 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 front-loaded with purpose, then routing guidance, then return contents. Every sentence adds useful information with no repetition or wasted 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?

For a read-only list tool with an annotation covering safety, full schema descriptions, and no output schema, the description supplies the missing return-value context and routing guidance. Nothing needed to invoke it correctly appears absent.

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 both parameters are already documented in the input schema, including the instruction to use list_stores for store lookup. The description adds only the conceptual framing of 'specific store' and no syntax or format details beyond the schema, making the baseline 3 appropriate.

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

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

The description states a specific verb and resource: 'List current offers from a specific store.' It also distinguishes the tool from siblings search_deals and deals_this_week, so an agent can identify its exact scope without opening another schema.

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

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

It gives explicit USE WHEN and NOT FOR guidance, including a concrete example ('what's at Netto this week') and names the alternative tools for cross-store and preferred-store searches. This leaves no ambiguity about when to select this tool.

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

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

Annotations already establish readOnlyHint=true, so the safety profile is covered. The description adds meaningful non-obvious context — full directory for DK but only curated grocery chains for NO/SE/FI — which an agent could not infer from the schema. It does not mention result ordering or pagination, which keeps it 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?

Front-loaded purpose sentence followed by labeled USE WHEN / NOT FOR clauses and a return-shape note. Every sentence carries distinct routing or coverage information, with no filler.

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

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

Covers purpose, country scope, the per-country coverage asymmetry, downstream consumers, and exclusions. For a two-parameter read-only listing tool with no output schema, nothing an agent needs to select or call it correctly is missing.

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

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

Schema description coverage is 100%, with 'all' and 'query' both documented in the schema, so the baseline is 3. The description adds no parameter-level detail 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?

States a specific verb and resource ('List grocery chains with dealer IDs') plus the scope constraint that defines the result set (DK/NO/SE/FI). It clearly separates itself from siblings like search_deals and get_store_offers without needing the schema.

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

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

Explicit USE WHEN names two concrete downstream consumers (get_store_offers, update_household), and an explicit NOT FOR clause redirects to search_deals and deals_this_week. Both the when and the when-not are spelled out with 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?

Adds substantive behavior beyond the single idempotentHint: deduplication by date + recipe name, and return confirmation contents (date, recipe, people). This tells the agent what happens on duplicate writes, which the annotation alone does not.

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 front-loaded sentences: purpose, when-to-use, behavior/return. No waste, easily 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 3-param write with only idempotentHint annotation and no output schema, the description covers purpose, trigger, dedup behavior, and return shape. Minor gap: no note on whether people list must be non-empty or how meal history retrieval interacts.

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

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

Schema coverage is 100%, so all three params are documented in schema. The description mentions dedup key 'date + recipe name' implicitly supporting date and recipe semantics, but adds no format or constraint details 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?

States a specific verb+resource ('Record a cooked meal') and the domain purpose (rotation tracking to avoid repeating meals). Among 18 siblings, this is clearly distinguishable from plan_and_shop or log_spend.

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 'USE WHEN: logging what was cooked to avoid repeating meals in future planning.' Names the use case and its goal. No explicit exclusion conditions or named alternatives (e.g. vs get_meal_history), but the intent 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 declare idempotentHint=false and destructiveHint=false, and the description is consistent with that. Since there is no output schema, the description usefully adds the return shape ('confirmation with amount, store, date, and item count'), though it says nothing about permissions or duplicate-entry 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?

Two sentences, front-loaded with the purpose and immediately followed by the triggering condition, with no filler. Every clause 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 5-parameter mutation tool with no output schema, the description covers purpose, trigger, and the confirmation payload, which is most of what an agent needs. Minor gaps remain around auth/permissions and what happens on repeated logging.

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 80%, so the schema already documents date, store, estimatedTotal, items, and notes. The description adds no parameter-level meaning (units, format, whether items is a count vs list) beyond the schema baseline.

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

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

States a specific verb and resource — 'Record grocery spending for budget tracking' — which is clearly separable from read-only siblings like get_spend_log. It does not explicitly name a sibling or contrast with log_meal, but the write intent 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?

'USE WHEN: logging what was spent after a shopping trip' gives a concrete triggering context, which is more than implied usage. It lacks any exclusion or pointer to the alternative (e.g., use get_spend_log to read, log_meal for meals), so it stops short of full 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 only assert readOnlyHint=true, so the description adds real value by disclosing the output shape: a day-by-day meal plan with costs followed by a deal-optimized shopping list grouped by store. It does not clarify whether the plan is persisted or what happens on repeated calls, which is the remaining gap for a 8-param planning tool.

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

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

The capability statement is front-loaded, followed by trigger phrases, the routing claim, and exclusions in a tight block. Slightly dense, but every clause (triggers, NOT FOR alternative, return shape) carries information an agent needs.

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 no output schema the description covers the return structure, and all 8 parameters are fully documented in the schema. The main omission is side-effect/persistence behavior, minor given the readOnlyHint annotation and the explanatory return summary.

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 every parameter already carries its own default and semantics (e.g. preferCuisines as a soft-preference map, slowOnlyOnDays 1-indexed). The description adds no parameter-level detail beyond that, which is the expected baseline when the schema does the work.

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 three concrete actions (score recipes, optimize a weekly meal plan, generate a shopping list) and declares itself 'the main entry point for weekly dinner planning.' It explicitly separates itself from the sibling generate_shopping_list, so an agent can route 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?

It supplies literal trigger phrases ('plan my week', 'what should we eat?'), a positive routing statement ('main entry point for weekly dinner planning'), and an explicit NOT FOR case with the named alternative (generate_shopping_list for pre-chosen recipes). Nothing is left to inference.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds genuinely new behavior: case-insensitive name matching and the return shape ("confirmation or 'not found' message"). It does not cover permissions or multi-match handling, so not 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?

Three short sentences, front-loaded with the action, then usage, then behavioral details. No filler text and every sentence adds 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 one-parameter mutation tool with no output schema, the description covers purpose, timing, matching semantics and the return message, which is enough to invoke it correctly. Minor gaps remain around permissions and behavior on ambiguous/multiple matches.

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 there is only one parameter, so the schema carries the baseline. The description adds meaningful semantics beyond the schema by specifying that name matching is case-insensitive, which directly affects how the agent supplies the value.

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

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

States a specific verb and resource ("Remove a recipe by name"), which clearly separates it from add_recipe and get_recipes in the sibling list. It stops short of explicitly naming the sibling it complements, but the purpose is unambiguous.

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

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

"USE WHEN: cleaning up the recipe library" gives a concrete usage context. There is no when-not guidance and no alternative tool named (e.g., what to use to inspect before removing), so it is clear but 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, so safety is covered. The description adds genuine behavioral context beyond that: it discloses the return content (deal coverage %, estimated cost, confidence levels per ingredient), which matters because there is no output schema. It does not mention cost/latency of the compute or whether the optimized plan is persisted, so it stops 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?

Three tight sentences with the core action front-loaded, followed by clearly delimited USE WHEN and NOT FOR clauses. Every sentence carries routing or output information; there is no filler.

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

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

For a 9-parameter tool with nested objects and no output schema, the description covers purpose, routing, and the shape of the returned scoring data, which compensates for the missing output schema. It leaves the interplay of 'optimize' with the plan-constraint parameters to the schema, so it is not quite exhaustive, but no essential 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 description coverage is 100%, so the schema already explains all nine parameters (days, optimize, cuisine/protein caps, exclusions). The description adds only the vague phrase 'optionally optimize,' not new semantics for any parameter. 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 uses a specific verb and resource ('Score all saved recipes against current deals') and states the optional behavior ('optionally optimize a weekly meal plan'). It also names the sibling tools it is not (generate_shopping_list, plan_and_shop), so an agent can distinguish it without opening any schema.

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

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

It has an explicit USE WHEN section with a concrete example intent ('what's cheapest this week') and an explicit NOT FOR section that routes to two named alternatives. There is nothing left to infer about when to select this tool.

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

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

Annotations already declare readOnlyHint=true, so safety is covered. The description adds useful behavioral context: country support is driven by household country setting and results are sorted by relevance with unit prices. It does not discuss authentication or pagination, but the core retrieval behavior is disclosed.

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

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

It is appropriately sized and front-loaded: purpose first, then usage boundaries, then return behavior. Every sentence earns its place with no repetition 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?

Given the simple two-parameter read-only search, annotations, and no output schema, the description supplies all the context an agent needs: what it searches, where it works, when to use it, when not to, and what the results look like.

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

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

Schema description coverage is 100%, so both parameters are already documented in the input schema. The description reinforces that search is by keyword but adds no syntax or format detail beyond the schema's own local-language examples.

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: search grocery deals across stores by keyword. It also names the supported countries and distinguishes itself from sibling tools by naming get_store_offers and generate_shopping_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 provides explicit USE WHEN conditions (finding products, checking prices, comparing stores) and explicit NOT FOR conditions with named alternatives (get_store_offers, generate_shopping_list). No inference is required from the agent.

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 idempotentHint, so the description carries most of the behavioral burden. It helpfully discloses the return summary (country, people count, store count, servings) and the idempotent nature is reinforced, but it never clarifies whether omitted fields are cleared or preserved (set vs. partial-update semantics) for a mutation tool with zero required params.

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

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

Front-loaded with the core action, then structured with USE WHEN, a constraint, a TIP, and return info. Slightly dense but every clause earns its place; 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?

No output schema exists, yet the description summarizes the returned config, and parameter meaning is fully covered by the schema. The main missing piece is partial-vs-full update semantics for a zero-required-param mutation, keeping it short of 5.

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%, so the baseline is 3, but the description adds value beyond the schema by telling the agent to use list_stores to find dealer IDs and reiterating the country market codes. This cross-references sibling tools rather than restating field names.

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 ("Set") plus the exact resource and the fields it governs (members, restrictions, stores, country, servings). An agent can immediately distinguish this from the read-only sibling get_household without opening the schema.

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

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

Provides an explicit USE WHEN clause ("first-time setup or changing household config"), a prerequisite/ordering constraint ("Required before shopping lists can filter by preferred stores"), and a cross-tool tip pointing to list_stores. Routes the agent clearly.

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 provide idempotentHint=true. The description adds that pantry items are excluded from shopping lists, items are matched case-insensitively, and the updated list is returned. It does not cover permission needs or whether removals are permanent, but it surfaces several behavioral traits beyond the 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 tight sentences with the purpose front-loaded and a USE WHEN marker. Every sentence earns its place by adding purpose, usage, matching behavior, or return value.

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

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

For a simple two-parameter tool with no output schema, the description covers purpose, usage, behavior, and return value. It does not address edge cases like overlapping add/remove or error handling, but those are minor for this tool.

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 add/remove parameters are fully documented in the schema. The description adds semantic meaning by stating that items are matched case-insensitively, which goes beyond the schema's basic 'items to add/remove' 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: 'Add or remove pantry items'. The parenthetical '(excluded from shopping lists)' distinguishes it from shopping-list tools, but no sibling alternative is named. Clear but not fully sibling-differentiated.

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 WHEN' clause gives explicit usage context: updating stock after shopping or noting staples you always have. It does not state when not to use the tool or name alternatives like get_pantry, but the trigger condition is clear.

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