scraps-kitchen-mcp

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

Beyond the idempotentHint annotation, the description adds valuable downstream context ('used for allergen safety and personalized meal suggestions') and discloses the partial-update capability. Could be improved by mentioning error behavior (e.g., duplicate names) or return value.

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 constructed sentences with no redundancy: action definition, data enumeration, business purpose, and usage constraints. Information is front-loaded and every sentence earns its place.

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

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

For a creation tool with 100% schema coverage and no output schema, the description adequately covers the creation workflow, required vs optional fields, business logic (allergen safety), and sibling relationships. No significant gaps remain.

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

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

With 100% schema coverage, the baseline is 3. The description adds workflow context by emphasizing that only 'name' is required while other fields are optional, helping the agent understand the incremental data entry pattern without repeating schema details.

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

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

The description clearly states the core action ('Add a person to the household'), enumerates the specific data tracked (allergens, restrictions, preferences, etc.), and distinguishes from sibling tool update_diner by noting this is for initial creation while updates happen elsewhere.

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 defines the minimal viable invocation ('Only name is required') and clearly identifies when to use the sibling alternative ('dietary details can be added later with update_diner'), providing clear workflow 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 annotation declares idempotentHint: false, and the description adds valuable behavioral context beyond this by explaining the downstream effect ('helps tailor recipe suggestions to what the user can actually make'). This clarifies the purpose of the data persistence. Does not contradict annotations.

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

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

Extremely concise with two high-value sentences. The first defines the action and purpose; the second provides the invocation trigger. No redundancy or filler content. Information is front-loaded and immediately actionable.

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 creation tool with no output schema and clear annotations, the description is complete. It covers the core functionality, the triggering condition, and the side effects on recipe suggestions, providing sufficient context for correct invocation without unnecessary detail.

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 fully documents both parameters (name and notes) with clear examples. The description aligns with the schema by mentioning 'specific tool' but does not add additional semantic information about parameter format, validation rules, or usage patterns beyond what the schema 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 clearly states the specific action ('Add a piece of kitchen equipment') and distinguishes from siblings like get_equipment, remove_equipment, and update_equipment. It also explains the value proposition (tailoring recipe suggestions), which helps the agent understand the tool's role in the broader workflow.

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 positive guidance ('Use when the user mentions having a specific tool') that clearly signals when to invoke the tool. However, it lacks explicit negative guidance or differentiation from update_equipment for cases where the user wants to modify existing equipment rather than add new items.

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?

With only idempotentHint: false in annotations, the description adds valuable behavioral context: the auto-enrichment feature ('auto-enriched with food intelligence'), the return value structure ('Returns the names and IDs'), and the batch limit constraint. It does not contradict the idempotency annotation, though it could clarify what happens if identical items are added twice.

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 zero waste: sentence 1 defines the action and limits, sentence 2 provides usage triggers, sentence 3 discloses side effects/enrichment, and sentence 4 explains return values. Information is front-loaded with the core action and efficiently structured.

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

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

Despite lacking an output schema, the description compensates by specifying what the tool returns ('names and IDs of added items'). It adequately covers the tool's moderate complexity (batch operations with enrichment) and sparse annotations. Minor gap: no mention of error handling for invalid categories or duplicate handling.

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 baseline score is 3. The description mentions the batch limit ('up to 50') which corresponds to maxItems in the schema, but does not add semantic clarification beyond what the schema already provides for the nested item properties (name, unit, category, quantity).

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 the core action ('Add one or more items to the user's pantry'), specifies the batch constraint ('up to 50 at a time'), and clearly distinguishes this from sibling tools like remove_pantry_item, update_pantry_item, and add_shopping_list_item by specifying the target resource (pantry) and operation (add).

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 contextual triggers for when to use the tool ('after grocery shopping, receiving a delivery, or when the user mentions new ingredients'), which helps the agent recognize appropriate invocation contexts. However, it does not explicitly name sibling alternatives (e.g., update_pantry_item for modifying existing items) or provide negative guidance (when not to use).

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

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

The annotation declares idempotentHint=false; the description reinforces this by stating the tool helps 'build a history' (implying accumulation/appending behavior). It appropriately adds context about the session-based nature of the data beyond what the boolean flag conveys. Does not mention error states or deletion capabilities.

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 well-structured sentences with zero waste: purpose/content definition, usage timing/outcome, and prerequisite. Information is front-loaded and every sentence earns its place.

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

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

Given the 4 parameters (all well-documented in schema), the description adequately covers workflow and intent. No output schema exists; while the description doesn't specify return values, this is acceptable for a simple append-only operation, though mentioning success confirmation would improve 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?

With 100% schema description coverage, the schema carries the primary documentation burden. The description maps abstract concepts ('observations', 'modifications', 'rating') to the note and rating parameters, providing semantic context, but does not elaborate on cooked_date formats or validation 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 uses specific verbs ('Record') and clearly defines the resource (cook note) and scope (observations, modifications, or rating from a specific cook session). It effectively distinguishes from siblings like update_recipe (modifies core recipe vs. adding session history) and rate_recipe_for_diner (diner ratings vs. cook session notes).

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

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

Provides clear temporal guidance ('Use after cooking') and outcome ('build a history'). Explicitly names prerequisite tool ('Get recipe IDs from get_recipes first'). Lacks explicit 'when-not-to-use' or direct comparison to rate_recipe_for_diner, which also handles ratings.

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 single idempotentHint annotation, the description adds crucial behavioral context about the 'structured ingredient data' requirement and the 'enrichment' process. It clarifies the scope ('all ingredients'). Does not mention duplicate handling if called twice, but the idempotentHint=false annotation covers the safety profile.

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

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

Four sentences each earning their place: (1) core function, (2) usage trigger, (3) data constraint, (4) prerequisite. Front-loaded with the action, no filler text, efficient information density.

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

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

For a single-parameter tool with 100% schema coverage and no output schema, the description is complete. It covers prerequisites, data quality constraints, usage context, and distinguishes from siblings appropriately.

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

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

With 100% schema coverage, the baseline is 3. The description adds workflow value by specifying that recipe_ids must be obtained 'from get_recipes first,' reinforcing the tool dependency and proper usage sequence beyond the raw schema definition.

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 specific action ('Add all ingredients'), source ('from a saved recipe'), and destination ('to the shopping list'). It distinguishes from sibling 'add_shopping_list_item' by emphasizing 'all ingredients' and 'saved recipe' vs. individual manual additions.

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

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

Provides explicit when-to-use ('Use when the user wants to shop for a specific recipe'), prerequisite workflow ('Get recipe IDs from get_recipes first'), and data requirements ('Requires the recipe to have structured ingredient data'). Names the specific prerequisite tool 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 provide idempotentHint: false, which the description doesn't contradict. The description adds contextual scope (single item vs. bulk) but doesn't elaborate on side effects, persistence behavior, or state changes beyond what the annotation implies.

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 zero waste: purpose statement, usage condition, and alternative routing. Information is front-loaded and every sentence earns its place.

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

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

For a simple 4-parameter creation tool with no output schema and clear annotations, the description provides sufficient context. Purpose, usage boundaries, and sibling differentiation are all covered; parameter details are adequately handled by the schema.

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

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

Schema coverage is 100% for all 4 parameters (name, unit, category, quantity), establishing baseline 3. The description doesn't add parameter-specific guidance, examples, or validation rules beyond what's in the schema.

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

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

The description states the specific action ('Add') and resource ('shopping list item') clearly. It explicitly distinguishes from the sibling tool 'add_recipe_to_shopping_list' by specifying this adds a single item versus bulk ingredients.

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

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

Provides explicit when-to-use guidance ('when the user says they need to buy something') and explicitly names the alternative tool for bulk operations ('To add all ingredients from a recipe at once, use add_recipe_to_shopping_list instead').

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 idempotentHint: true. The description adds valuable context that the tool is bidirectional ('checked or unchecked'), clarifying it can toggle states, not just mark complete. However, it omits side effects, error behaviors, or confirmation of what 'checked' means in the system 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 waste. First sentence states the core action and bidirectional capability; second provides the prerequisite. Every word earns its place with no redundant phrasing or tautology.

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?

Appropriate for a 2-parameter toggle tool with no output schema. Covers the essential workflow prerequisite. Could be improved by mentioning error handling (e.g., invalid ID behavior), but complete enough for correct invocation given the simple operation.

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%, establishing a baseline of 3. The description adds critical workflow context for the 'id' parameter by specifying it must come from get_shopping_list, which helps the agent understand the parameter's source and validity constraints beyond the schema 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 uses specific verbs ('Mark') and clearly identifies the resource ('shopping list item') and states ('checked/unchecked'). It distinguishes from sibling tools like add_shopping_list_item (creates new) and remove_shopping_list_item (deletes) by specifying this modifies the checked status of existing 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?

Provides explicit prerequisite workflow ('Get item IDs from get_shopping_list first'), guiding the agent to use the sibling tool first. Lacks explicit 'when not to use' guidance (e.g., contrast with clear_checked_shopping_items for bulk operations), but the prerequisite naming is strong.

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

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

While the destructiveHint annotation confirms the deletion behavior, the description adds crucial operational context by specifying the target state ('checked-off items') and the workflow timing ('after a shopping trip'). It does not contradict the destructive 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 efficiently structured: action definition, usage context, and alternative pointer. No redundant words; every sentence provides distinct value beyond the tool name and 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?

Given zero parameters and the presence of destructiveHint annotation, the description adequately covers the operation's scope, prerequisites (items must be checked off), and sibling relationships. No output schema exists, but for a bulk deletion operation, the description provides sufficient completeness.

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 has zero parameters, which per guidelines establishes a baseline of 4. The description correctly requires no parameter explanation, as the operation is self-contained.

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 the tool 'Remove[s] all checked-off items from the shopping list at once,' providing a specific verb, resource, and scope (checked-off only). It clearly distinguishes itself from remove_shopping_list_item by specifying 'all' versus single-item removal.

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 temporal context for when to use ('after a shopping trip when the user has bought everything marked') and explicitly names the sibling alternative for different granularity ('To remove a single item, use remove_shopping_list_item instead').

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 idempotentHint=true, and the description adds domain-specific behavioral context by explaining the 'staleness clock' mechanism being reset. This helps the agent understand the internal state change beyond the annotation's safety hint.

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 efficiently structured: effect sentence first, trigger conditions second, prerequisites third. Zero redundancy; every sentence provides actionable guidance.

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

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

For a single-parameter idempotent operation without output schema, the description fully covers what the tool does, when to invoke it, and how to source required data. Sufficient for correct agent 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% ('Pantry item IDs to confirm as fresh'), establishing baseline 3. While the description mentions getting IDs from get_pantry, this is workflow guidance rather than additional parameter syntax, format, or semantic 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?

Specific verb 'Reset' + resource 'staleness clock' + scope 'pantry items the user confirms are still good' clearly defines the operation. Distinguishes from sibling tools like add_pantry_items, update_pantry_item, or remove_pantry_item by focusing specifically on freshness confirmation.

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 trigger conditions provided: 'Use when the user says items are fine, or after a pantry check.' Includes prerequisite workflow: 'Get item IDs from get_pantry first,' which clarifies the required data source and sequencing.

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?

While annotations declare destructiveHint and idempotentHint, the description adds crucial context: specific data types destroyed (cook notes, ratings, images), irreversibility ('cannot be undone'), and the prerequisite workflow. It does not mention error states (e.g., invalid ID behavior), preventing a perfect score.

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 zero waste: sentence 1 defines action and scope, sentence 2 warns of irreversibility, sentence 3 states prerequisites. Information is front-loaded and dense.

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

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

For a single-parameter destructive operation with good schema coverage and annotations, the description is nearly complete. It covers scope, consequences, and workflow. Lacks only explicit mention of idempotency behavior or error handling for missing IDs.

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

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

With 100% schema coverage, the baseline is 3. The description adds value by reinforcing the parameter's ecosystem: 'Get recipe IDs from get_recipes first' clarifies the data source and dependency chain for the 'id' parameter beyond the schema's basic 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 clearly states the specific action ('Permanently delete'), the target resource ('a recipe'), and precisely enumerates the scope of deletion ('all associated data (cook notes, diner ratings, image)'). This distinguishes it from siblings like update_recipe or remove_diner.

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 workflow guidance ('Get recipe IDs from get_recipes first') and clear prerequisites. The warning 'This cannot be undone' effectively signals when NOT to use this tool (i.e., when preservation is desired) and implies irreversible consequences.

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 aligns with the readOnlyHint annotation (using 'Returns'), confirming it is a safe read operation. It adds domain context by specifying what constitutes equipment (appliances/tools vs. ingredients), but does not disclose additional behavioral traits like pagination, caching, or default values when no equipment 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 consists of exactly two high-value sentences with zero waste. It is properly front-loaded with the core action ('Returns...'), followed immediately by usage context and concrete examples, making it easy for an agent to parse quickly.

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 (no parameters, read-only) and lack of output schema, the description adequately explains what data is returned conceptually (an inventory of kitchen tools). It would be improved by briefly describing the return format (e.g., 'returns a list of equipment items'), but the examples provided offer sufficient semantic completeness for selection purposes.

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 input parameters, which establishes a baseline score of 4. The description appropriately does not invent parameter documentation where none is needed, focusing instead on the return value semantics.

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

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

The description uses a specific verb ('Returns') and resource ('kitchen equipment inventory') to clearly define the tool's function. It effectively distinguishes itself from sibling tools like get_pantry (ingredients) and get_shopping_list through concrete examples of equipment (slow cooker, food processor, cast iron skillet).

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

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

The description provides explicit context for when to use the tool ('when suggesting recipes to ensure the user has the necessary tools'), linking it to a specific workflow. However, it lacks explicit guidance on when NOT to use it or direct comparisons to alternatives like get_pantry.

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?

While annotations declare readOnlyHint=true, the description adds valuable behavioral context about what data structure to expect (dietary profiles with specific fields) and critical safety implications regarding allergens. It compensates for the missing output schema by detailing the return contents.

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 well-structured sentences with zero waste. Front-loaded with the core action ('Returns all household members'), followed by usage context, and ending with safety-critical guidance. Every sentence earns its place.

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

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

For a simple read operation with no parameters, the description is complete. It compensates for the lack of output schema by enumerating the specific dietary profile fields returned and explaining the safety relevance, providing sufficient context for an agent to use this tool effectively.

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 contains zero parameters. Per evaluation guidelines, the baseline score for zero-parameter tools is 4. The description correctly implies no filtering parameters are needed by stating it returns 'all' household members.

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

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

The description clearly states the tool 'Returns all household members (diners)' with specific details about what data is included (allergens, restrictions, preferences, etc.). It effectively distinguishes this getter from sibling mutation tools like add_diner, update_diner, and remove_diner by focusing on data retrieval.

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

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

Provides clear positive guidance on when to use ('understand who the user cooks for', 'Essential context for safe meal suggestions') and explicitly links usage to the suggest_quick_meal sibling ('check allergens before recommending any recipe'). However, it does not explicitly name alternative tools for when this isn't the right choice.

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

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

While annotations confirm readOnlyHint=true, the description adds crucial behavioral context: it lists the data fields returned (compensating for missing output schema), explains the default value behavior of in_stock_only, and clarifies the business logic of 'stale' items and 'use it up' workflows.

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?

Perfectly structured with zero waste: sentence 1 defines the return payload, sentence 2 gives usage contexts, sentences 3-4 explain parameter behaviors. Every sentence earns its place and is front-loaded with critical 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 lack of output schema, the description effectively compensates by enumerating the returned data fields. With readOnlyHint annotation and 100% schema coverage, the description provides sufficient context for invocation, though it could optionally mention pagination or result limits.

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?

Despite 100% schema coverage, the description adds meaningful usage context beyond the schema: it notes that in_stock_only defaults to true and explains the practical purpose of stale_only ('useful for "use it up" suggestions'), helping the agent understand parameter intent.

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

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

The description clearly states the tool returns pantry items with specific attributes (category, quantity, stock status, perishability, storage hints). Using 'Returns' distinguishes it from sibling mutation tools like add_pantry_items, remove_pantry_item, and update_pantry_item.

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

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

Provides explicit when-to-use contexts: 'planning meals,' 'checking what ingredients are available,' and 'identifying items that need using up.' Lacks explicit when-not-to-use or named alternatives, though the verb 'Returns' implies read-only access vs. sibling mutations.

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 indicate readOnlyHint=true, confirming safe read access. The description adds valuable behavioral context by detailing exactly what data structures are returned (ingredients, steps, markdown, cook notes, ratings), which compensates for the missing output schema and helps the agent understand the tool's utility.

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 zero redundancy: first defines the output payload, second defines the trigger condition, third defines the prerequisite. Information is front-loaded and every sentence earns its place.

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

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

For a simple read operation with one required parameter and no output schema, the description is complete. It compensates for the missing output schema by listing return fields, establishes the dependency on get_recipes, and leverages the readOnlyHint annotation to cover safety concerns without verbose repetition.

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 fully documents the 'id' parameter. The description reinforces the parameter's semantic relationship to get_recipes ('Get recipe IDs from get_recipes first'), but does not add syntax, format constraints, or examples beyond what the schema provides, warranting the baseline 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 states the specific action ('Get'), resource ('single recipe'), and exact scope of returned data ('full content (ingredients, steps, markdown), cook notes, and ratings'). It clearly distinguishes from sibling get_recipes by specifying this returns a single item with full content versus a 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?

Provides explicit when-to-use context ('when the user wants to cook a specific recipe or see its details') and establishes the prerequisite workflow ('Get recipe IDs from get_recipes first'), implicitly guiding the agent to use get_recipes for listing. Lacks explicit when-not-to-use language (e.g., 'do not use for listing'), preventing a perfect score.

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

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

Annotations declare readOnlyHint=true. Description adds valuable behavioral context: specific fields returned (compensating for lack of output schema) and scope limitation (summary vs full content). Does not mention pagination or rate limits, but covers primary behavioral traits.

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 zero waste: sentence 1 defines scope/returns, sentence 2 gives usage context, sentence 3 covers parameters, sentence 4 provides sibling alternative. Front-loaded with action and resource.

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, so description appropriately documents return values (title, status, rating, etc.). Distinguishes from sibling get_recipe. With readOnlyHint covering safety profile and 100% schema coverage, the description provides complete contextual information.

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%, establishing baseline 3. Description mentions parameters exist ('Supports search by keyword and filtering by status or favorites') but adds minimal semantic depth beyond what schema already provides (e.g., no syntax examples or enum value explanations).

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?

Specific verb 'Returns' plus resource 'saved recipes' and specific fields (title, status, rating, diet tags, timestamps). Clearly distinguishes from sibling 'get_recipe' by stating this returns summary data vs full content.

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

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

Explicit when-to-use: 'Use to browse what the user has cooked or wants to make.' Explicit alternative named: 'To get full recipe content and cook notes, use get_recipe with a specific ID.' Clear guidance on tool selection.

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

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

Annotations declare readOnlyHint=true, confirming safe read operation. Description adds valuable behavioral context not in schema: the specific data structure/fields returned (name, quantity, unit, checked status) since no output schema exists. Also clarifies semantic mapping of filter values to 'remaining' vs 'completed' items.

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, zero waste. Front-loaded with return value description, followed by usage context, then parameter guidance. Every sentence earns its place without redundancy.

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

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

For a single-parameter retrieval tool with simple structure, description is complete. Compensates for missing output schema by listing return fields. readOnlyHint covers safety profile. Minor gap: no mention of pagination or limits if list is large, but adequate for standard shopping list scope.

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?

Input schema has 100% description coverage for the 'checked' parameter ('Filter: true = only checked-off items...'). Description reinforces this with 'Filter by checked status' but adds minimal semantic value beyond the already-excellent schema documentation. Baseline 3 appropriate for high schema coverage.

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

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

Description uses specific verb 'Returns' with resource 'shopping list items' and details exact fields (name, quantity, unit, checked status). Clear distinction from mutation siblings like add_shopping_list_item or check_off_shopping_item through the 'Returns' framing and readOnly annotation.

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 usage triggers: 'when the user asks what they need to buy, or before suggesting a grocery run.' Also explains filter use case ('see only remaining or completed items'). Lacks explicit naming of alternatives (e.g., 'use check_off_shopping_item to mark items done'), though readOnlyHint makes the read-vs-write distinction 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?

Beyond the idempotentHint annotation, the description adds critical behavioral details: fuzzy name matching, automatic skipping of staples (salt/oil), and the return value structure (depleted vs skipped items). This disclosure of filtering logic and side effects is valuable for an agent.

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 efficiently cover: purpose, matching behavior, exception handling (staples), and usage timing/returns. Every sentence earns its place with no redundancy or generic 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 complexity (fuzzy logic, staple filtering, state mutation) and lack of output schema, the description adequately covers return values verbally and explains key behaviors. A minor gap is the lack of explicit warning about the destructive nature of the depletion, though 'consumed' implies mutation.

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 baseline is 3. The description adds workflow context ('as used in the recipe') that aligns with the fuzzy matching behavior mentioned, but does not significantly expand on parameter syntax or validation rules beyond the schema.

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

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

The description clearly states the core action ('Mark ingredients as consumed') and resource (pantry ingredients), distinguishing it from sibling tools like add_pantry_items or remove_pantry_item by specifying this is for post-cooking consumption with automatic fuzzy matching.

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 temporal context ('Use after a cook session') explaining when to invoke the tool. However, it does not explicitly name alternative tools (e.g., when to use remove_pantry_item instead) or provide negative constraints (when not to use 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?

Complements the idempotentHint=true annotation by explaining the upsert semantics ('Creates or updates the rating if one already exists'). Also adds business context about the data purpose ('who loved it' data) that the annotation lacks.

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 cover purpose, value, behavioral mechanics, and prerequisites without redundancy. Front-loaded with the core action, each subsequent sentence adds distinct operational context.

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 4-parameter tool with full schema coverage, the description adequately covers the upsert behavior and prerequisites. Minor gap: without an output schema, it could briefly mention the return value (e.g., confirmation of the recorded rating), but the side effects are clearly documented.

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

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

With 100% schema coverage, the baseline is 3. The description adds value by specifying the data sources for the two required parameters (get_recipes and get_household), helping the agent understand the dependency chain beyond the schema's basic type definitions.

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

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

The description opens with a precise action ('Record how a specific household member felt') and specific resource ('a recipe'), clearly distinguishing this rating/tracking function from sibling tools like add_recipe_note or update_recipe which handle different aspects of recipe management.

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

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

Explicitly states the value proposition ('improves future meal suggestions') to indicate when to use it, and names specific prerequisite steps ('Get recipe IDs from get_recipes and diner IDs from get_household first'), providing clear workflow 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?

While annotations declare destructiveHint=true, the description adds crucial behavioral context about cascade deletion ('also removes their recipe ratings') which clarifies the scope of destruction beyond just the member record.

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 zero waste: action definition, cascade effect disclosure, and prerequisite workflow. Information is front-loaded and every sentence earns its place.

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

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

Appropriately complete for a single-parameter destructive operation. Covers the cascade impact on ratings and references the required predecessor tool. No output schema exists, so return value explanation is not expected.

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 has 100% description coverage ('Diner ID (from get_household)'). The description repeats this sourcing instruction but does not add additional semantic details about the ID format, validation rules, or constraints beyond the schema.

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

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

The description clearly states the specific action (Remove) and resource (household member and dietary profile), distinguishing it from sibling tools like update_diner or add_diner through the explicit mention of removal and cascade effects.

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

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

Provides clear prerequisite instruction ('Get diner IDs from get_household first') establishing the workflow dependency. Implies destructive use case by warning about recipe ratings removal, though could explicitly contrast with update_diner for completeness.

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. Description adds workflow context about ID retrieval but does not disclose cascade effects, permanence details, or recovery options beyond the annotation hints.

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

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

Two sentences with zero waste. Front-loaded with the core action, second sentence provides essential prerequisite. 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?

Adequate for a single-parameter destructive operation. Prerequisites are covered via description and annotations. No output schema exists to explain. Could benefit from explicit mention of irreversibility or cascade behavior, though destructiveHint provides safety 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?

Schema has 100% coverage with parameter description already indicating the ID source. Description reinforces this workflow ('Get equipment IDs from get_equipment') but adds no additional syntax, format constraints, or examples 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?

Clear verb 'Remove' with specific resource 'kitchen equipment from the inventory'. Distinct from sibling tools like remove_diner, remove_pantry_item, and update_equipment.

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

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

Explicitly states the prerequisite workflow 'Get equipment IDs from get_equipment first', guiding when to use the tool. Lacks explicit 'when not to use' or alternative suggestions (e.g., update_equipment for modifications).

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

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

Annotations declare destructiveHint=true and idempotentHint=true. The description adds valuable domain context by emphasizing 'Permanently' and explaining the semantic difference between deletion and marking out-of-stock (soft-delete). It does not contradict annotations, though it could explicitly mention idempotency for completeness.

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

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

Two tightly constructed sentences with zero waste. The first establishes purpose, the second provides usage guidelines and prerequisites. Information is front-loaded and immediately actionable.

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 this is a single-parameter destructive operation with clear annotations, the description provides complete context for correct invocation. It covers purpose, behavioral implications, sibling distinctions, and data prerequisites without needing output schema details.

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 fully documents the 'id' parameter including its source ('from get_pantry'). The description repeats this workflow guidance but does not add semantic meaning beyond what the structured schema provides, warranting the baseline 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 'Permanently delete a pantry item,' providing a specific verb (delete) and resource (pantry item). It effectively distinguishes itself from the sibling tool update_pantry_item by clarifying this is for full removal, not status changes.

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?

Excellent guidance: explicitly states when to use ('when the user wants to fully remove an item'), when not to use ('not just mark it out of stock'), names the specific alternative ('use update_pantry_item with in_stock=false'), and lists prerequisites ('Get item IDs from get_pantry first').

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. The description reinforces the destructive nature with 'permanently' and adds valuable procedural context that the operation requires obtaining IDs from get_shopping_list first, which is behavioral workflow information beyond the annotations.

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

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

Three tightly constructed sentences with zero redundancy: purpose statement first, alternative differentiation second, prerequisite instruction third. Every sentence earns its place and the structure follows logical usage 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 single-parameter deletion tool with complete annotations and no output schema, the description is comprehensive. It covers the operation, destructive warning, sibling differentiation, and parameter sourcing prerequisites—everything needed 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?

With 100% schema coverage, the baseline is 3. The description elevates this by adding procedural context—emphasizing that the ID must be obtained from get_shopping_list 'first'—transforming a static schema field description into a workflow instruction that clarifies the parameter's lifecycle.

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 ('remove') and resource ('item from the shopping list'), and the word 'permanently' clarifies the scope. It effectively distinguishes itself from the bulk-removal sibling 'clear_checked_shopping_items' by contrasting single-item vs. all checked-off removal.

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 alternative selection ('use clear_checked_shopping_items instead' for bulk removal) and clear workflow prerequisites ('Get item IDs from get_shopping_list first'), guiding the agent on exactly when to use this tool versus its sibling and what preparation steps are required.

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 establish readOnly and openWorld hints; description adds crucial operational context: rate limiting (1 call/IP/24h), authentication requirements (none), output structure (title, markdown, etc.), and explicit scope limitations (no pantry integration). No contradictions with annotations.

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

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

Every sentence earns its place: purpose, return values, usage condition, auth/rate limits, and sibling differentiation. Front-loaded with the core function. Dense but scannable with no redundancy.

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

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

For a single-parameter tool without output schema, the description comprehensively covers invocation constraints, output format details, and sibling relationships. The rate limit warning is particularly critical for agent planning. No gaps remain given the tool's simplicity.

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

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

Schema has 100% description coverage for the single 'ingredients' parameter, including type, constraints, and examples. Description references 'list of ingredients' but does not add semantic details (e.g., handling of partial matches, unit formatting) beyond what the schema already provides, warranting the baseline 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?

States specific action (Generate), resource (recipe), and input mechanism (from ingredients). Explicitly distinguishes from sibling tools by clarifying it does NOT use pantry/household data, directing users to get_pantry/get_household for personalized contexts 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?

Provides explicit when-to-use ('when the user has ingredients and wants a meal idea'), when-not-to-use (doesn't use personalized data), and names specific alternatives (get_pantry, get_household). Also includes operational constraints (rate limits) that guide invocation timing.

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?

Annotation provides idempotentHint=true. Description adds crucial behavioral context: array fields replace entirely rather than merge, and workflow dependency on get_household. Does not clarify behavior for omitted scalar fields (unchanged vs cleared), but covers the destructive array behavior well.

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 zero waste: purpose front-loaded, critical array warning second, prerequisite third. No redundant information; every sentence earns its place.

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

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

For an 8-parameter update operation with 100% schema coverage and idempotent hint, description covers the critical complexity (array replacement) and prerequisites. Minor gap: does not explicitly state that omitted scalar fields remain unchanged (though implied by 'Update' vs 'Replace').

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 has 100% coverage (baseline 3). Description adds workflow context for 'id' parameter (must come from get_household) and generalizes the array replacement pattern across multiple fields, adding semantic value beyond the individual schema descriptions.

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

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

Specific verb ('Update') + resource ('household member's dietary profile') clearly stated. Distinguishes from siblings like add_diner (creation) and remove_diner (deletion) by focusing on profile updates.

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 prerequisite stated ('Get diner IDs from get_household first') and critical usage pattern documented (array replacement semantics). Lacks explicit 'when not to use' (e.g., contrast with add_diner for new members), but the prerequisite provides strong contextual 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 annotation provides idempotentHint=true, covering the safety/behavioral profile. The description adds minimal behavioral context beyond this—it implies partial updates are possible (name 'or' notes), but doesn't disclose error handling (e.g., what happens if the ID doesn't exist), side effects, or return value structure. Adequate given the annotation support, but not rich.

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

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

The description consists of two efficient sentences with zero waste. The first sentence states the core purpose immediately; the second provides the essential prerequisite. Every word earns its place, and there is no redundant or filler text.

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

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

For a straightforward CRUD update operation with 100% schema coverage and idempotency annotations, the description is sufficiently complete. It identifies the resource, the updatable fields, and the data prerequisite. While it could explicitly mention that omitted fields remain unchanged (partial update semantics), this is reasonably implied by the schema structure and the word 'or'.

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 fully documents all three parameters including the source of the ID ('from get_equipment'). The description essentially restates this information ('Get equipment IDs from get_equipment first') without adding syntax details, format constraints, or examples beyond the schema definitions.

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 ('Update') with a clear resource ('kitchen equipment') and identifies the exact fields that can be modified ('name or notes'). It clearly distinguishes from siblings like update_pantry_item, update_recipe, and remove_equipment by specifying the domain (kitchen equipment) and the limited scope of editable fields.

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

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

The description provides explicit prerequisite guidance ('Get equipment IDs from get_equipment first'), establishing a clear workflow sequence. However, it lacks explicit when-not-to-use guidance (e.g., mentioning that add_equipment should be used for new items instead) or alternative tools for different scenarios.

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 idempotentHint=true. Description adds context that this can 'mark something as out of stock' (behavioral effect of in_stock parameter) and implies partial updates are supported by listing optional fields. However, it lacks details on error handling (e.g., invalid ID), return values, or side effects beyond the idempotent 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 well-structured sentences: purpose definition, usage context, and prerequisite workflow. Front-loaded with the core action. No redundant information; every sentence earns its place by guiding correct invocation or distinguishing usage.

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

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

Appropriately complete for a straightforward CRUD update operation. Covers purpose, specific use cases (corrections, stock status), and prerequisites. Absence of output schema is acceptable as the tool's effect is adequately described (updated fields) without needing return value documentation.

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

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

Schema coverage is 100% with clear field descriptions (e.g., 'New name', 'Set to false to mark as out of stock'). Description consolidates these fields into a sentence but adds minimal semantic value beyond the schema, though it reinforces the ID source requirement already documented in the schema's id 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?

Specific verb (Update) + resource (pantry item) + specific fields (name, quantity, unit, category, stock status). Clearly distinguishes from sibling tools add_pantry_items (create) and remove_pantry_item (delete) by specifying this modifies existing 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?

Explicitly states when to use ('correct item details or mark something as out of stock') and provides critical workflow prerequisite ('Get item IDs from get_pantry first'), effectively guiding the agent to invoke get_pantry before this tool and distinguishing this from creation/deletion 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?

Beyond the idempotentHint annotation, the description adds critical workflow context: the external system boundary (Scraps app manages content) and the prerequisite dependency on get_recipes. Does not cover error handling or return value details, preventing 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?

Four sentences with zero waste: fields covered, use cases, scope limitation, and prerequisite. Information is front-loaded with the core action, 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?

Complete for a partial update operation given the lack of output schema. Covers field scope, external boundaries, and ID sourcing. Lacks description of return values or error conditions (e.g., invalid ID), which would be necessary for a perfect score without an output schema.

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

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

With 100% schema description coverage, the baseline is 3. The description elevates this by mapping use cases to parameters ('mark as cooked' → status, 'rate it' → rating), adding practical semantic context beyond the schema's technical definitions.

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 specific action (update) and exact resources/fields affected (title, status, rating, favorite, public sharing). It distinguishes from siblings by explicitly stating it 'Does not update recipe content' and referencing the external 'Scraps app' boundary.

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

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

Provides explicit when-to-use ('Use to mark a recipe as cooked, rate it, or toggle favorite'), when-not-to-use ('Does not update recipe content'), and prerequisites ('Get recipe IDs from get_recipes first'). Names the alternative system (Scraps app) for content updates.

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