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

Beyond the annotations (not read-only, not destructive), the description adds behavioral details about visibility and attribution, but does not mention idempotency (creating duplicate comments is possible).

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 concise sentences with no superfluous words; the description is direct and well-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?

The presence of an output schema covers the return type, and the description sufficiently covers the core action and side effects, though it omits potential error conditions or permissions requirements.

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

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

The schema already documents the recipe parameter, but the description does not add any semantics for the text parameter or clarify the meaning of the recipe parameter beyond the schema. Coverage is 50% and no additional information is provided.

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

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

The description clearly states the action (adds a comment) and the resource (recipe), and distinguishes it from delete_recipe_comment and list_recipe_comments by specifying the side effects (visibility and attribution).

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

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

The description implies when to use this tool (when you want to add a comment visible to all group members) and hints at a constraint (attribution to the API token user), though it does not explicitly compare to 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?

The description discloses the merging behavior and the tracking of recipe-to-ingredient associations, which goes beyond the minimal annotations (all false). However, it does not detail side effects, idempotency, or error conditions, leaving some behavioral aspects unclear.

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 two sentences long, direct, and free of fluff. It efficiently conveys the core function, the merge behavior, and the removal pairing without unnecessary detail.

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

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

Given the output schema exists (though not shown in the input), the description fully covers the tool's purpose and relevant behavior. It provides enough context for an agent to understand the operation and its relationship to remove_recipe_from_shopping_list, making it complete for 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?

All three parameters have descriptions that add significant context beyond the schema: recipe accepts slug or UUID with a cross-reference to search_recipes, list_id is tied to list_shopping_lists, and servings_multiplier explains scaling. This enriches the otherwise terse 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 (adds a recipe's ingredients), the target resource (shopping list), and the merging behavior. It also distinguishes itself from the sibling remove_recipe_from_shopping_list by explaining the tracking/removal relationship.

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 explains what the tool does and its connection to removal, but it does not explicitly state when to use this tool over other add-related tools (e.g., add_shopping_list_items). The usage context is implied rather than directly stated.

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

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

Annotations already indicate a non-read-only, non-idempotent write. The description adds the behavioral trait that Mealie does not split items into food/unit automatically, which is valuable context beyond the annotations.

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

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

Two sentences with no waste: the first states the action and example, the second gives a caveat. The main purpose is front-loaded and every word earns its place.

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

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

The output schema exists to cover return values. The description covers the core purpose, example, and the parsing caveat. It doesn't mention error handling, but that is not critical for a simple add 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% with descriptions for both parameters. The description reinforces semantics with a concrete example ('2 tbsp olive oil') and clarifies the free-text format, adding value beyond the schema.

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

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

States the verb 'adds', the resource 'shopping list', and specifies the items are free text with an example. This clearly distinguishes it from sibling tools like add_recipe_to_shopping_list (which adds a recipe) and update_shopping_list_items (which 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?

Provides a clear conditional workflow hint: run parse_ingredients first if structured parsing matters. While it doesn't explicitly exclude alternatives like add_recipe_to_shopping_list, the free-text nature makes the appropriate context obvious.

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

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

Discloses key behavior beyond annotations: is_public is not immediate and requires a confirm token on a second call, while private cookbooks are created immediately. Also mentions that invalid query filters are rejected with a 422. This matches the non-idempotent, non-read-only annotations without contradiction.

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

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

The description is compact and well-structured, with each sentence serving a distinct purpose: defining the resource, explaining the filter, and clarifying the public/confirmation behavior. No redundant or vague 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?

Covers the essential context an agent needs: what a cookbook is, how filters behave, the confirmation requirement for public cookbooks, and the validation failure mode. The output schema handles return details, so nothing critical is missing.

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

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

Schema descriptions cover 60% of parameters. The tool description adds important meaning for query_filter, is_public, and confirm_token, but 'name' and 'description' rely on their obvious parameter names. Overall, the semantics are clear and enhanced by the 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?

Clearly identifies the resource (cookbook) and the action (create), and frames it as a named, saved view of the recipe collection. This distinguishes it from sibling tools like get_cookbook, update_cookbook, delete_cookbook, and list_cookbooks.

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 concrete usage guidance: explains that an empty filter matches all recipes, warns that filters are written in Mealie's own query language and are easiest to build in the web UI, and clearly describes the two-step confirmation flow for public cookbooks.

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

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

The description is consistent with annotations (readOnlyHint=false, destructiveHint=false) and adds context about the group-vocabulary side effect. It does not disclose possible duplicate handling, but annotations already indicate a non-idempotent write.

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

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

A single front-loaded sentence with no redundant wording. Every word contributes to identifying the operation and its purpose.

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

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

The tool has four parameters and an output schema, and the description explains the core purpose but not the optional parameters or behavioral edge cases. The output schema covers return values, but the missing parameter guidance makes the definition incomplete.

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 only 25%, yet the description names no parameters and provides no meaning for plural_name or description. The name parameter is only implied by the tool's own wording, leaving optional fields unexplained.

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

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

The description uses a specific verb-resource pair ('Adds a food') and explains the underlying purpose ('so ingredient lines can be matched against it'). This clearly distinguishes create_food from siblings like create_unit or create_recipe.

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 case is implied: call it when a new food needs to be added to the group vocabulary. However, it does not state when to prefer an alternative such as merge_foods or how to handle duplicate/overlapping food names.

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

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

Annotations already indicate this is not read-only, not idempotent, and not destructive. The description adds useful behavior by explaining that Mealie stores a plan entry as either a recipe or a title, reinforcing the exclusivity constraint and the side effect of creating a new plan entry.

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 two sentences, focused, and free of unnecessary detail. It conveys the core purpose and the most important usage constraint without padding.

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

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

The description covers the essential creation behavior and the main constraint. Given that the output schema is present and parameter descriptions cover the input details, the description is sufficiently complete for an agent to use the tool correctly.

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

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

All parameters have schema descriptions, and the description additionally clarifies the relationship between recipe and title. It does not redefine every parameter but it adds the cross-parameter constraint that the schema alone does not enforce.

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

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

The description clearly states the tool's purpose: putting a recipe or free-text note onto the meal plan for one day. It distinguishes this creation action from related mealplan operations like update and delete by its focus on adding a new entry.

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

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

The description gives actionable usage guidance, especially the important constraint to provide either a recipe or a title but not both. It does not explicitly name update_mealplan_entry or delete_mealplan_entry as alternatives, but the create-vs-update distinction is reasonably implied by the phrasing.

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?

Consistent with annotations (write operation, non-destructive); adds that assigning via update_recipe would create on the fly, contextualizing the side effect of creation, though no detail on duplicate handling or idempotency is needed given idempotentHint=false.

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

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

A single clear sentence with a useful contrast, 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?

With an output schema present and a clear creation purpose, the description is complete enough; slight ambiguity in 'recipe tool' wording is minor.

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 fully describes kind enum and provides length constraints for name, but name has no semantic description and the description adds no parameter-level detail; however, name is largely self-explanatory.

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 it creates a tag, category, or tool, and distinguishes from on-the-fly creation via update_recipe, making the resource and action clear.

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

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

Explicitly names update_recipe as the alternative for on-the-fly assignment and explains this tool is for defining an organizer up front, giving clear when-to-use guidance.

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

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

The description implies a state-changing action by using 'pick' and 'Add', and the annotations indicate non-read-only behavior. However, it does not explicitly disclose that a meal plan entry will be created or what side effects occur, so transparency relies partly on the annotations.

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

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

The description is a single, well-structured sentence that communicates the core behavior without unnecessary words or repetition.

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

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

The description gives enough context for the tool's purpose and behavior, but it does not mention possible outcomes such as what happens if no matching recipe is found or what the return value represents. Since an output schema is present, this is only 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 schema already covers both parameters with clear descriptions and an enum for entry_type, so the tool description adds no extra parameter-level meaning. With 100% schema coverage, a neutral score is appropriate.

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

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

The description clearly states a specific action: 'Lets Mealie pick a recipe for a day and slot' and distinguishes the tool from siblings by emphasizing the random selection and meal plan rule honoring. The title 'Add a random meal' reinforces the purpose.

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

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

The description implies the use case—when a random meal should be assigned—but does not explicitly compare against alternatives like create_mealplan_entry or suggest_recipes, nor does it state when not to use 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=false, destructiveHint=false, etc., covering the basic safety profile. The description adds no behavioral context beyond 'Creates a recipe' – it does not mention side effects, permissions, or behavior on duplicate slugs (though the schema notes this). With annotations present, the bar is lower, but the description still provides no extra behavioral insight.

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 two sentences with zero waste. The first sentence states the purpose; the second provides the alternative. The key information is front-loaded and concise.

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

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

With 13 parameters and only 46% schema coverage, the description is insufficient for an agent to understand how to properly construct the call. It does not mention required fields, constraints, or any behavioral details beyond the basic create action. The output schema exists, which helps with return values, but the input side is under-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 description coverage is only 46%, and the description adds no parameter-specific meaning. It only says 'from the given fields', which is vague. The schema itself documents some parameters (e.g., name, tags, categories), but many are undocumented in both schema and description. The description does not compensate for the low 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?

The description clearly states the tool's purpose: 'Creates a recipe from the given fields.' It explicitly contrasts with the sibling tool 'import_recipe_from_url', which is for adding from a website. This gives a specific verb (create) and resource (recipe), and differentiates it from a likely alternative.

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

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

The description provides direct usage guidance by naming the alternative ('import_recipe_from_url') and the condition for choosing it ('To add one from a website'). It implies this tool is for manual entry from given fields. This is explicit when/when-not guidance.

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

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

With all annotation hints false, the description carries the transparency burden. It discloses the side effect (creating a link), the access grant (anyone can read one recipe), and the confirmation requirement. It does not mention output details, but an output schema 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?

Two concise sentences with no unnecessary details. The core action is front-loaded, and the critical confirmation instruction follows immediately.

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

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

An output schema exists, so return values do not need to be described in prose. The description plus schema provides enough context for successful invocation, including the essential two-call confirmation behavior.

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

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

Schema coverage is 100% with rich descriptions for recipe, expires_at, and confirm_token. The prose itself adds no additional parameter meaning, so it stays at the high-coverage 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?

Clearly states it creates a public share link for one recipe with anonymous read access, and mentions the required confirmation flow. The purpose is unambiguous and distinguishes it from list/delete share-token siblings.

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

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

Explicitly explains the two-step procedure: call once to receive a token, then call again with that token. It does not explicitly contrast with list_share_tokens or delete_share_token, but the creation intent is clear enough for correct use.

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

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

Annotations already communicate that this is a write operation (readOnlyHint=false) and is not idempotent or destructive. The description adds that the list is initially empty and scoped to the household, but it does not disclose what happens on duplicate names or any side effects beyond creation.

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

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

The description is a single front-loaded sentence with no filler. Every word earns its place: the verb 'Creates' identifies the action, 'empty' clarifies the initial state, and 'in the household' gives scope.

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 creation tool with annotations and an output schema, the description is nearly sufficient: it states action, scope, and initial state. The only notable gap is the undocumented meaning of the 'name' parameter, though the name itself is fairly self-explanatory.

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 0%, so the description carries the burden for explaining the required 'name' parameter, but it does not discuss it. The only semantic link is inferring that 'name' labels the new shopping list, with no information about uniqueness, format, or behavior if a name is reused.

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, 'Creates an empty shopping list in the household', and clearly identifies the action and scope. The word 'empty' distinguishes this creation behavior from tools that add or manage items, and the target resource separates it from sibling create_* tools.

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

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

The verb 'Creates' implies the tool is for initial creation of a shopping list, and the sibling list_shopping_lists/add_shopping_list_items tools suggest the surrounding workflow. However, the description does not explicitly state when to prefer this tool over alternatives or provide any exclusions, leaving usage context 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?

The annotations already mark this as a non-read-only operation; the description confirms it by saying 'Adds an entry' but doesn't reveal additional side effects beyond creation. No contradictions.

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 concise sentences that pack the core action, typical usage, and a hint about a related tool—no fluff or redundancy.

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

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

The description gives enough context to understand the tool's role relative to set_recipe_last_made and its typical use case, making it self-sufficient for an agent to decide when to invoke it.

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

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

The schema comprehensively describes all four parameters, so the description text adds no parameter-specific meaning. Baseline 3 applies given 100% 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?

The description clearly states the action ('Adds an entry to a recipe's timeline') with a specific resource and verb, and distinguishes it from the related set_recipe_last_made tool by explaining what that alternative does.

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

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

It explicitly mentions the companion tool set_recipe_last_made and clarifies its different purpose (affects recipe view sorting), giving the agent context on when to choose each. It doesn't exhaustively list alternatives but provides a useful pointer.

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 are present (readOnlyHint=false, idempotentHint=false, etc.) but provide minimal info. The description adds 'to the group vocabulary' but does not disclose side effects, error handling, or permissions. Given the annotations are all false, the description carries a moderate burden but falls short on details.

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

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

The description is a single, clear sentence that gets straight to the point without unnecessary details. It is appropriately sized for a simple create operation.

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

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

The description is sufficient for a basic create operation, and since an output schema exists, return values are not required. However, it lacks information about uniqueness constraints or potential errors, which could be relevant but are not critical for a simple 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?

The input schema has 6 parameters with only 2 having descriptions (33% coverage). The tool description does not add any parameter-specific meaning, failing to compensate for the low schema coverage. Parameter details like 'plural_name' and 'abbreviation' are left undefined.

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

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

The description clearly states the tool's function: 'Adds a measurement unit to the group vocabulary.' It distinguishes from siblings like 'merge_units' and 'list_units' by focusing on creation.

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

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

The description implies when to use the tool (when adding a new unit) but does not explicitly contrast it with alternatives like 'merge_units' or 'create_food'. No explicit guidance is provided, so the usage is only implied.

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

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

The description discloses the destructive action, the non-destructive effect on recipes, and the two-step confirmation process. This goes beyond the annotations by explaining the exact sequence and side effects.

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

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

The description is brief, well-structured, and contains no redundant information. Every sentence contributes essential details about the operation, the confirmation requirement, and the non-destructive nature for recipes.

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

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

Given the moderate complexity of a two-step destructive operation, the description provides all necessary context: what is deleted, what is not affected, and the exact confirmation process. No critical 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?

The schema already provides full parameter descriptions with 100% coverage. The tool description adds meaningful context about the confirmation token flow, which clarifies the role of confirm_token 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 tool deletes a cookbook, specifies that recipes are not affected, and differentiates cookbooks from recipes by calling them saved filters. This distinguishes it from sibling tools like delete_recipe.

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

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

It explicitly explains the required confirmation workflow: call once to get a token, then call again with that token. It also clarifies that recipes are not touched, which helps the agent decide when this tool is appropriate versus other deletion tools.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true. The description adds valuable behavioral context: it clarifies the scope (only the entry, not the recipe) and the non-obvious confirmation token requirement. This goes beyond the annotations, which do not mention the two-step flow. No contradictions found.

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

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

The description is concise (two sentences) and front-loaded with the primary action. The scope clarification and confirmation requirement are efficiently conveyed without redundancy. Every sentence earns its place, making it easy for an agent to quickly grasp the tool's purpose and critical usage detail.

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

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

For a destructive operation with a two-step confirmation, the description covers the essential requirements: the action, the scope (entry vs. recipe), and the confirmation process. It does not mention error handling for invalid tokens or timeout behavior, but these are minor for an agent to infer. The output schema is present (though not shown), so return-value documentation is not the description's responsibility. Overall, it is sufficiently complete for correct invocation.

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

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

Schema coverage is 100%, with both parameters already well-described in the input schema. The description reinforces the confirmation flow but adds little new information about parameter meaning. It mentions the token requirement but the schema already states 'Omit on the first call.' Thus, the description provides marginal value over the schema, warranting the baseline score of 3.

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

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

The description clearly states the action (removes), the resource (one entry from the meal plan), and explicitly distinguishes it from deleting the recipe itself ('The recipe itself is not touched'). This differentiates it from sibling tools like delete_recipe. The title and description align, providing unambiguous purpose.

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

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

The description explains the required two-step confirmation process ('call once to receive a token, then again with that token'), which is essential for correct usage. It does not explicitly list alternatives or when-not scenarios, but the context (sibling tools) makes it clear this is the only tool for deleting meal plan entries. The guidance is sufficient but lacks explicit exclusions.

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

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

The description discloses the destructive nature (deletes), the confirmation requirement, and the effect on recipes (they lose the assignment). It does not mention irreversibility or cascading effects, but annotations already cover destructiveHint and idempotentHint.

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, no fluff, essential information only. The confirmation flow is clearly stated in a compact manner.

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

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

Given the output schema exists and the description is sufficient for typical usage, it is complete. Slight gap: no mention of error cases (e.g., invalid token) or whether the operation is reversible, but these are not critical for basic invocation.

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

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

The description clarifies that confirm_token comes from a previous call and explains the meaning of 'kind' with examples. Schema already covers types and constraints, so the description adds meaningful context without redundancy.

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 clearly states the verb 'deletes' and the specific resource types (tag, category, tool). It also notes the effect on recipes, distinguishing it from create/update counterparts.

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 two-step confirmation process is described, but no explicit guidance on when to use this tool versus alternatives like update_organizer or delete_recipe is given. The context from sibling tools is implicit.

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

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

The description goes beyond the annotations by explaining the permanent deletion of related data and the confirmation token mechanism, which is a behavioral feature not covered by the annotations. This adds valuable transparency.

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

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

The description is concise, consisting of two clear sentences. It efficiently conveys the destructive action and the confirmation workflow without unnecessary elaboration.

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 schema already documents parameters, the description adds essential context about what is deleted (comments, timeline, images) and the confirmation flow. This makes the tool self-contained and complete for an agent.

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

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

Both parameters are fully described in the schema with details on accepted formats (recipe slug or UUID from search_recipes) and the confirmation token's role. The tool description also reinforces the token's usage, providing complete parameter understanding.

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

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

The description clearly states the tool's purpose: permanently deletes a recipe along with its comments, timeline, and images. It also explains the two-step confirmation process, making the action and resource unambiguous.

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

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

The description provides explicit usage instructions ('call once to receive a token, then again with that token') but does not explicitly distinguish when to use this tool versus sibling deletion tools like delete_cookbook. However, the name and context make it 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?

The description adds the confirmation-token workflow, which is not fully captured by the annotations. The destructiveHint and readOnlyHint already signal safety profile, so the extra disclosure about the two-step process is useful but 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?

Two concise sentences lead with the action and then explain the confirmation requirement without extraneous detail. The structure is highly scannable and front-loaded.

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

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

The description covers the necessary workflow and parameter origins, and an output schema exists to provide return details. It doesn't mention irreversibility, but the destructiveHint annotation covers that, so the tool is adequately specified.

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

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

The schema descriptions already cover both parameters, including how to obtain comment_id and that confirm_token should be omitted on first call. The description does not add significant semantic meaning beyond repeating the confirmation flow, so baseline 3 applies.

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

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

Description states 'Deletes a comment' with a specific verb and resource, making the core action unambiguous. It also highlights the two-step confirmation requirement, which clearly differentiates it from other delete tools.

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

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

It explicitly instructs to call once to receive a token and then again with that token, providing necessary usage steps. It doesn't explicitly contrast with sibling delete tools, but the comment-specific scope is clear enough.

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

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

The description transparently discloses the destructive nature (revoking) and the confirmation requirement, which aligns with the destructiveHint and idempotentHint annotations. It does not contradict annotations and adds specific behavioral detail about the two-step token process.

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 two sentences with no redundant wording. It is compact and directly to the point, making it easy for an agent to parse.

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

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

The description covers the essential procedural context (confirmation flow) and the primary effect of the action. It does not describe the output schema or error conditions, but those are not critical for initiating the call, and the description is sufficient given the simple two-parameter interface.

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 description explains the confirm_token parameter by describing the token-receiving process. Token_id is already well-described in the schema as coming from list_share_tokens. The description adds useful context for the confirmation parameter.

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

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

The description clearly states the action ('Revokes a share link') and the effect ('so the recipe is no longer readable through it'). This unambiguously identifies the tool's purpose.

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

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

The description provides explicit guidance on the confirmation flow: it requires a person's consent and, in the absence of a dialog, instructs the agent to call once to obtain a token and call again with it. This is useful operational guidance, though it does not contrast with alternative tools.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the destructive nature is known. The description adds valuable context beyond those: it deletes 'everything on it' (items within the list) and describes the confirmation token mechanism. It does not contradict annotations and provides meaningful behavioral detail about the two-step process and the scope of deletion.

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 exactly two sentences with zero redundancy. The first sentence states the core action and scope, and the second explains the required confirmation procedure. It is front-loaded with the essential purpose and adds the operational nuance immediately after, 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?

For a destructive tool with a two-step confirmation, the description fully equips the agent: it knows to call twice, that a token must be used, and that the entire list is deleted. The presence of an output schema covers return values, so nothing essential is missing. Given the tool's complexity, this description is complete.

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

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

Schema description coverage is 100% for both parameters, with list_id documented as a UUID from list_shopping_lists and confirm_token explained as a token from a previous call. The tool description itself does not add parameter-level detail beyond what the schema already provides; the confirmation flow is explained at the usage level rather than parameter semantics, so baseline 3 is appropriate.

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

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

The description clearly states the verb ('Deletes'), the resource ('shopping list'), and its scope ('and everything on it'), which immediately distinguishes it from other delete tools like delete_recipe or delete_cookbook. The confirmation step is also mentioned, adding a unique operational detail that sets it apart from simpler delete tools.

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

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

The description explicitly explains the required two-step confirmation flow ('call once to receive a token, then again with that token'), leaving no ambiguity about the call sequence. It does not need to list alternatives because the tool name and scope already make it the only choice for deleting shopping lists, and no sibling does the same job.

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 adds the crucial two-step confirmation token flow, clarifying that deletion is permanent and requires explicit confirmation. No contradiction with annotations.

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

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

Two sentences with no filler; the core purpose is front-loaded, and the alternative tool and confirmation requirement are stated clearly. 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?

For a destructive operation with a two-step flow, the description covers purpose, alternative, and confirmation procedure. The schema describes the item_ids origin (from get_shopping_list) and the output schema exists, so no return value explanation needed.

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

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

Both parameters have descriptions in the schema (100% coverage). The description adds the semantic meaning of confirm_token: 'call once to receive a token, then again with that token,' which clarifies the required sequence beyond the schema's generic 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 a specific verb 'Removes' and a specific resource 'items from a shopping list', and explicitly contrasts with the sibling update_shopping_list_items for ticking items off. This clearly differentiates it from other list tools.

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

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

It explicitly directs when not to use this tool ('To merely tick something off, use update_shopping_list_items with checked=true') and explains the required two-step confirmation process, giving clear guidance on invocation.

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

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

The description adds the key behavioral promise of leaving the original untouched, which complements the annotations (non-read-only, non-idempotent, non-destructive). It does not cover error conditions but covers the essential side effect.

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 concise sentences, front-loaded with the primary action and followed by a practical use case. No unnecessary detail.

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

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

The description covers purpose, use case, and a key behavioral guarantee. It lacks explicit notes on failure modes (e.g., nonexistent source recipe or name conflicts), but these are not critical for a simple duplication 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?

The parameter descriptions go beyond the schema: name explains the counter-appending behavior when omitted, and recipe specifies both slug and UUID formats and points to search_recipes as the source.

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 creates a copy of a recipe under a new name, explicitly noting the original is untouched. This distinguishes it from create_recipe (new from scratch) and update_recipe (modifies existing).

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

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

The phrase 'Useful as a starting point for a variation' provides a clear use case, though it does not explicitly contrast with alternatives like create_recipe or update_recipe.

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

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

Annotations already indicate readOnly/idempotent/non-destructive. The description adds useful context that the permission flags determine which write tools will succeed, going beyond the annotations to explain the practical relevance of the returned data.

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 concise sentences pack the core purpose and a specific use case without redundancy. The structure is clear and front-loaded with the main function.

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 no parameters and a simple output (version and identity info), the description is sufficient. It does not describe the output schema in detail, but the nature of the data is obvious from context, and the omission is minor.

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 no parameters, so the schema fully covers the input side. The description accurately reflects that no parameters are needed, avoiding any confusion.

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 reports the Mealie version and the identity (user, group, household) plus permission flags. It distinguishes this from the many other tools by focusing on instance-level metadata.

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

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

Explicitly instructs to use this tool when a call fails with a 403, providing a concrete trigger condition. It also implies using it as an entry point for understanding permissions, which is actionable 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?

Description adds 'and the recipes it currently matches' beyond the read-only annotation, clarifying the return content. It does not mention error handling, but the read-only nature is already covered by annotations and the description stays within expected scope.

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?

Single sentence, no redundancy, and directly describes the action and key parameter. Highly concise and well-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?

For a simple read operation with an output schema present, the description is sufficiently complete. It covers the core purpose and the identifier format, leaving no critical gaps.

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

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

Schema descriptions already fully cover both parameters: cookbook (slug or UUID) and per_page (count, default, max). The description adds no new information, so baseline 3 is appropriate.

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

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

Description clearly states the tool fetches a cookbook and its matching recipes, with the specific identifier type (slug or UUID). This distinguishes it from sibling tools like list_cookbooks (which lists all) and delete_cookbook (which removes one).

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

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

Implicitly indicates when to use it: when you have a specific cookbook identifier (slug or UUID). It does not explicitly contrast with list_cookbooks, but the phrasing 'Accepts the slug or the UUID' makes the intended use case 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?

The annotations already provide readOnly, idempotent, and destructive hints, and the description's 'Fetches' is consistent. No additional behavioral details (e.g., error handling, response format) are given, but the annotation coverage lowers the bar.

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 extremely concise, using just two sentences with no redundant information. It efficiently conveys the purpose and the identifier types.

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

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

The description lists the key content fields (ingredients, steps, etc.) and the identifier types. It does not describe the return format in detail, but the output schema exists and this is a simple read operation, so it is reasonably 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?

Both parameters have schema descriptions that fully explain their meaning (recipe slug/UUID, detail options). The tool description adds no extra parameter context, but the schema already provides 100% coverage, so the baseline is 3.

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

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

The description clearly states the action ('Fetches') and the specific resource ('one recipe'), and lists the content included. It distinguishes this from search_recipes by focusing on a single recipe identified by slug or UUID.

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

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

The description implies when to use this tool (when you have a specific recipe identifier) and the parameter description notes that search_recipes returns both slug and UUID, effectively guiding choice. It does not explicitly contrast with search_recipes, but the context is clear.

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

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

Annotations already cover read-only, idempotent, and non-destructive behavior. The description adds that it returns items including checked/unchecked, which is useful content context, but does not describe error handling or other execution details beyond the annotation coverage.

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

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

The description is a single, direct sentence that clearly states the action and scope without unnecessary detail. It is well-structured and easy to parse.

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

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

For a simple retrieval operation with two parameters, the description is sufficient. It clarifies the output includes all items (checked and unchecked) and the schema provides parameter details, so no additional context is needed.

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

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

Schema descriptions cover both parameters fully (100% coverage), including the UUID provenance for list_id and the meaning/default for include_checked. The tool description does not add additional parameter semantics beyond what the schema already provides, so baseline 3 applies.

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

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

The description clearly states the tool fetches one shopping list, including all items, both checked and unchecked. This distinguishes it from list_shopping_lists (which lists all lists) and other item-specific tools, providing a specific verb and resource.

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

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

The phrase 'one shopping list' implies this is for retrieving a single list by ID, which provides clear context. However, it does not explicitly name alternatives like list_shopping_lists, so guidance on when to use this over others is implied but not stated outright.

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

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

The description adds value beyond the annotations by clarifying that 'today' is computed as Mealie does for the household, which addresses potential timezone or context nuances. It also specifies the response format (bare list, not paginated), giving insight into the tool's behavior. 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?

The description is concise, consisting of two sentences that directly state the purpose and a key output characteristic. There is no redundant or extraneous information, making it efficient and well-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?

Given the lack of parameters and the simple nature of the operation, the description sufficiently covers the tool's purpose and output format. It could specify the shape of the items in the list, but that is not critical for invocation. Overall, it provides enough context for use.

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

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

There are no parameters in the schema, so schema_description_coverage is effectively 100%. The description does not need to add parameter details, and the baseline of 3 applies since no additional information is required.

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

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

The description clearly states that it returns the recipes planned for today, specifying the exact resource and scope. It also distinguishes itself from other list operations by noting that it returns a bare list, not a paginated envelope, which helps differentiate it from similar tools.

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

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

The description provides some guidance on when to use this tool by mentioning the output format (bare list vs. paginated), implying it should be used when a simple, unpaginated list of today's meals is needed. However, it does not explicitly contrast with alternatives like list_mealplans, so guidance is slightly implicit.

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

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

The description discloses side effects beyond the annotations: it creates a recipe, and it will still fetch image addresses found in the document. It also reveals the security behavior of checking and refusing internal addresses, while warning that hidden addresses may still be requested.

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

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

The description is longer than strictly needed, especially the second paragraph about image fetching and security. However, most of the extra length carries important behavioral and security context, so it is still reasonably concise.

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

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

The description covers key context: when to use it, what data to pass, and the main security caveat. Since an output schema is present, not detailing return values is acceptable; the remaining minor gap is lack of explicit error scenarios for malformed input.

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

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

The schema itself covers the data parameter well with a clear description. The tool description adds extra meaning by clarifying that the data is supplied directly rather than fetched, and by explaining the distinction between HTML and Recipe JSON in practical terms.

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 creates a recipe directly from supplied HTML or schema.org Recipe JSON, which is a specific verb plus resource. It explicitly distinguishes itself from import_recipe_from_url by noting that Mealie does not fetch the page.

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 concrete use cases: pages that require login or pages that import_recipe_from_url could not parse. It also provides an important security-based limitation about not pasting content from untrusted sources, which helps the agent choose when to use this tool over 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?

The description clearly indicates a write operation (creates a recipe) and discloses a failure condition (missing AI provider), which aligns with the annotations. The annotations already mark the tool as non-read-only and non-destructive, and the description adds practical behavior about prerequisites without contradicting them.

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

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

The description is concise: two sentences that convey purpose, input, method, prerequisites, and a failure mode. There is no redundant or filler content, and the most important information is front-loaded.

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

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

Given the output schema is present and annotations cover read-only/destructive/idempotent hints, the description provides enough context for correct invocation. It covers what the tool does, what it requires, and what happens when the requirement is unmet, so no critical context is missing.

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

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

The schema already provides 100% coverage with clear descriptions for all three parameters, including format, base64 encoding constraints, and translation language. The description adds no significant semantic information beyond what the schema supplies, so the baseline score is appropriate.

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

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

The description clearly states that the tool creates a recipe from a photo, specifies the input type (image) and mechanism (Mealie's AI provider), and gives concrete examples like cookbook pages and handwritten cards. It effectively distinguishes this tool from URL and HTML/JSON import siblings by focusing on image input.

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

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

The description explicitly identifies the prerequisite of having an AI provider configured and states that the call fails without one, which is strong usage guidance. It also notes the admin/group-manager visibility of the setting, giving the caller context for potential permission issues. It does not explicitly compare alternatives, but the image-based scope is clear enough.

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

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

The description states it creates a new recipe and that content is saved 'as written,' which conveys a non-modifying behavior. It also highlights that the fetch is server-side, a relevant behavioral detail. Annotations (readOnlyHint false, destructiveHint false) align with the description, so no contradiction. Could be slightly more detailed about side effects, but adequate.

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

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

The description is concise, with two sentences that convey the action, the server-side nature, and the verbatim import behavior. No redundant information or fluff.

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

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

The description provides sufficient context for understanding the operation: it's a create from URL, server-side, and copies content verbatim. It doesn't mention return values or error cases, but the output schema exists and the core behavior is clear. Minor gaps but not significant.

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

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

The schema covers 67% of parameters (url and include_tags have descriptions; include_categories lacks one). The description does not elaborate on the parameters beyond the URL, leaving include_categories' semantics implied rather than explicit. Since coverage is moderate and the description doesn't compensate, a mid-range score 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 explicitly states the action (fetch and save) and the resource (recipe from URL). It clearly differentiates from sibling tools like import_recipe_from_html_or_json and import_recipe_from_image by specifying the URL source, making the purpose unambiguous.

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

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

The description notes that the fetch happens on the Mealie server, implying a server-side operation. While it doesn't explicitly enumerate when to use this tool versus alternatives, the source (URL) is clear from the name and description, and the sibling list provides context. Lacks an explicit 'use this instead of X' statement but is still clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, covering side-effect expectations. The description adds useful conceptual context by explaining what a cookbook is, which is beyond the annotation-only information.

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 concise sentences with no filler. The first states the action and scope, and the second adds a meaningful clarification about cookbook semantics.

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 listing operation with fully described pagination parameters and an available output schema, the description is complete enough. The conceptual clarification adds useful context without leaving important gaps.

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

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

The schema already provides complete descriptions for both parameters (page and per_page), including defaults and maximum values. The description does not add anything beyond what the schema already conveys.

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

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

States a specific verb ('Lists'), a clear resource ('cookbooks'), and a scope ('of the household'). Also clarifies that a cookbook is a saved filter, not a fixed set of recipes, which distinguishes the concept from a simple collection.

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

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

The description clearly implies a collection-listing operation, and sibling tools like get_cookbook, create_cookbook, and delete_cookbook provide contrast, but it does not explicitly state when to prefer this tool over 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?

The annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds behavioral context beyond the annotations by explaining that many instances return no foods and that an empty result should not be treated as an error, which helps agents avoid false failure interpretations.

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 two sentences, front-loads the core purpose, and adds one important clarification without unnecessary detail. Every sentence contributes meaning, making it concise and well 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?

Given that an output schema is present and there are no nested objects, the description does not need to detail return fields. It sufficiently covers the main behavioral context, including empty results, though it could have briefly explained the search parameter's semantics for complete 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?

The schema already describes three of the four parameters (page, per_page, order_direction), and the description adds no additional parameter-level detail. The search parameter lacks a description in both the schema and the tool description, leaving a minor gap, but overall parameter coverage is adequate.

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

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

The description clearly states the tool lists structured foods, identifies them as the ingredient vocabulary Mealie matches ingredient lines against, and distinguishes the resource from other list tools like list_units and list_organizers. The added clarification about empty results further sharpens the purpose.

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

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

The description provides useful interpretive guidance by explaining that an empty result is meaningful rather than a failure. However, it does not explicitly say when to use this tool over sibling alternatives such as list_units or search_recipes, so usage guidance is only partially covered.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the description does not need to repeat safety. It adds useful context about the entry format (recipe reference or free-text note), which goes beyond annotations. However, it does not disclose pagination behavior or other operational details, which are partially covered by the 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?

The description is extremely concise, with two sentences that front-load the action and scope, then clarify the entry types. No unnecessary words or repetition; 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 tool's simplicity, the presence of an output schema, and strong annotations, the description is largely complete. It covers the core purpose and entry types, but lacks explicit differentiation from similar list tools (e.g., get_todays_meals). This minor gap is acceptable for a straightforward list 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 description coverage is 100%, so all parameters are already documented. The description does not add any parameter-specific information, matching the baseline of 3 for high coverage. It does not repeat or conflict with 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 action (Lists), the resource (meal plan of the household), and the scope (in a date range). It also distinguishes the content type (recipe reference or free-text note), making the purpose unambiguous and differentiating it from other list tools like get_todays_meals.

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

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

The description implies usage for listing meal plans within a date range, but does not explicitly mention alternatives or when not to use it. Given the sibling tools such as get_todays_meals, explicit guidance would improve selection accuracy, but the core usage is still inferable from the text.

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

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

Annotations already cover read-only and idempotent behavior, and the description is consistent. It adds transparency by noting the result includes ids and slugs, and that the output is used for filtering. No side effects need disclosure because there are none.

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

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

Two sentences with no unnecessary words. The key information—what is listed, what it contains, and its relationship to search_recipes—is conveyed efficiently.

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

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

The description is complete for a list operation. Output schema exists so return details are covered. The purpose and the relationship to search_recipes finish the context. No missing information that an agent would need to decide to call 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 parameters are fully documented. The description does not add extra meaning beyond the schema, which is appropriate. Per the rubric, baseline is 3 for high coverage without additional description information.

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

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

The description clearly states the verb 'Lists' and the resource 'tags, categories or tools', and specifies the scope 'defined in the group'. It also explains the purpose—these values are what search_recipes filters on—which distinguishes it from search_recipes and other tools.

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

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

The description implies when to use this tool: when you need the available filter values for search_recipes. It provides that context explicitly, though it doesn't contrast with other list tools like list_foods or list_units. Slight room for more explicit alternative guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds no additional behavioral context (e.g., pagination, ordering, or content of comments) but does not contradict the annotations. Since annotations carry the burden, a neutral score is appropriate.

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

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

The description is a single sentence that is front-loaded with the action and resource, with no wasted words. It is concise and directly serves its purpose without extraneous detail.

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

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

For a simple list tool with one well-documented parameter, an output schema, and annotations covering safety, the description is complete. There is no missing information an agent would need to call it correctly; any return format details are provided by the 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?

The single parameter 'recipe' is fully documented in the schema with examples and a reference to search_recipes. Schema coverage is 100%, so the description correctly does not duplicate parameter information. The baseline of 3 applies because the schema already provides the necessary meaning.

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 ('Lists'), the resource ('comments'), and the target ('on a recipe'), clearly distinguishing it from sibling tools like add_recipe_comment and delete_recipe_comment. It also adds the nuance 'other users of the instance' which clarifies scope beyond just the name.

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

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

The description implies usage (listing comments for a recipe) but does not explicitly state when to use this tool versus alternatives, nor does it mention exclusions. The context of sibling tools makes the intent obvious, but the guidance is implied rather than stated.

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

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

The annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds meaningful behavioral detail by specifying the timeline event types (created, updated, cooked) and that notes are included, without contradicting the read-only nature.

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

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

The description is a single, compact sentence that conveys the essential purpose and content of the timeline without unnecessary detail or repetition.

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

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

Given the output schema is present and the description explains the nature of the returned timeline events plus the attached notes, the tool is adequately described for an agent to understand what it returns and when 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?

All three parameters are described in the schema with clear meanings, defaults, and constraints. The recipe parameter description even explains the accepted formats (slug or UUID) and points to search_recipes as the source, going beyond a basic 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 uses a specific verb ('Lists') and a clear resource ('the timeline of a recipe'), and it explains exactly what the timeline contains: creation, updates, cooking events, and attached notes. This clearly distinguishes it from sibling tools like list_recipe_comments and create_timeline_event.

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

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

The description implies use when a recipe's history or event log is needed, but it does not explicitly state when to prefer this tool over alternatives or when not to use it. There is no direct comparison to list_recipe_comments or create_timeline_event, so guidance is only implicit.

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

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

Annotations already indicate read-only and idempotent behavior. The description adds useful context about share links being publicly accessible without an account, which goes beyond the annotation metadata and helps the agent understand the security model.

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 two sentences with no redundancy. The main purpose is stated first, followed by a brief explanation of what the share links are, making it efficient and well-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?

The description states what is listed (share links, recipe, expiration) and there is an output schema to cover the response format. It is reasonably complete for a simple list operation, though it does not mention any filtering behavior beyond the schema parameter.

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 only parameter 'recipe' already has a full description in the schema ('Restrict the result to one recipe'). The tool description provides no additional meaning or usage notes for this parameter, so it adds nothing beyond the schema.

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

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

The description clearly states the tool lists all public share links with their associated recipe and expiration date. This distinctly separates it from sibling tools that create or delete share tokens.

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 does not explicitly mention when to use this tool versus alternatives like create_share_token or delete_share_token. The purpose is obvious, but no direct contrast or conditions for choice are provided.

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 read-only and non-destructive behavior, and the description's 'Lists' wording reinforces a side-effect-free operation. It does not describe pagination behavior despite page/per_page parameters, but this is less critical because the schema documents them.

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

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

A single, direct sentence that efficiently conveys the tool's purpose and scope without unnecessary words or repetition.

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

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

The description, combined with the provided output schema and parameter annotations, gives enough context for a basic list operation. It could be slightly stronger by explicitly referencing the pagination parameters or the get_shopping_list sibling for item-level details, but it is not incomplete.

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

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

The schema provides full descriptions for both page ('1-based page number, default 1') and per_page ('Number of entries to return, default 50, max 100'), so with 100% schema coverage the description adds no additional parameter meaning.

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 ('Lists'), resource ('shopping lists'), and scope ('of the household'), and distinguishes itself by noting it returns lists 'without their items', which separates it from the singular get_shopping_list sibling.

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?

Clearly conveys this returns shopping lists without items, implying it is for overviews rather than full item details; however, it does not explicitly name alternatives like get_shopping_list when item contents are needed.

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

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

The annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds a meaningful behavioral detail: that the list is empty if the instance never seeded units. This complements the annotations but does not fully elaborate on response format or pagination behavior. Overall, it adds value beyond the annotations.

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

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

The description is two sentences, concise and free of extraneous details. It front-loads the core purpose and adds a single clarifying note, making it efficient and easy to parse.

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

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

The description fully conveys the tool's purpose and even anticipates a common edge case (empty on unseeded instances). It does not explain the output schema or parameter behavior, but those are sufficiently documented in the schema. Given the read-only nature and the presence of an output schema, the description is complete enough for an agent to use the tool correctly.

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

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

The schema descriptions cover page, per_page, and order_direction, but search lacks a description. The tool description does not provide additional semantic meaning for any parameter; it only describes the overall action. Since schema coverage is high (75%), the baseline is 3, and the description does not improve parameter understanding.

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

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

The description clearly states that the tool lists the measurement units of the group with their abbreviations, using the specific verb 'Lists' and a clear resource. It also provides a useful behavioral note about empty instances, which adds clarity without ambiguity.

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

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

The description does not explicitly specify when to use this tool versus alternatives. It mentions that it behaves like foods (empty if never seeded), which gives some context about data state, but there is no direct comparison with sibling list tools or guidance on when to choose this over others.

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 states that the source food is deleted and that confirmation is required, which supplements the destructiveHint and readOnlyHint annotations. It does not contradict the idempotentHint, though the confirmation flow is not described in extreme detail.

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

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

The description is concise, consisting of two short sentences. The first sentence is slightly awkward but not verbose, and all essential information is included.

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

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

Given the output schema and annotations, the description covers the key context: the merge action, source deletion, and the confirmation requirement. It could mention that the first call does not perform the deletion, but the two-step flow is implied clearly enough.

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

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

The schema provides complete descriptions for all three parameters, including deletion of from_id, preservation of to_id, and the confirm_token flow. The main description adds no additional parameter meaning beyond the already comprehensive input 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 identifies the tool as merging two foods, reassigning ingredient references, and deleting the source food. The wording 'Points every ingredient' is slightly awkward, but the purpose is understandable and distinct from merge_units.

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

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

The description explicitly explains the required two-step confirmation process: call once to receive a token, then call again with that token. It does not explicitly contrast with merge_units, but the food-specific naming and description make the usage 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 flag destructiveHint=true and readOnlyHint=false; the description adds concrete behavioral details beyond that: the source unit is deleted, ingredient references are rerouted to the target unit, and a two-step confirmation token is required. It does not discuss reversibility or the blast radius of changes, but with annotation coverage this is valuable and non-contradictory 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?

The description is exactly two sentences: the first establishes the core purpose and destructive effect, the second covers the critical confirmation protocol. There is no filler or redundant detail; the structure is efficient and front-loaded.

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

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

Given that an output schema exists and annotations convey the safety profile, the description provides the essential operational behavior: merge action, source deletion, and the token round-trip. It is sufficient for an agent to select and start invoking the tool correctly, though it does not mention edge cases like merging a unit into itself or idempotence behavior.

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

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

Schema description coverage is 100%, and each property is already described in the schema: from_id is 'the unit to merge away — this one is deleted', to_id receives references, and confirm_token is 'from a previous call... Omit on the first call'. The description's token explanation is essentially a restatement of what the schema already carries, so it adds little extra meaning.

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

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

The description states a specific action and resource: it 'points every ingredient that uses one unit at another one and deletes the source unit', which clearly conveys the merge-and-delete semantics. This distinguishes it from sibling tools like merge_foods, where the target is foods rather than units.

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

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

The description explicitly explains the confirmation flow: 'call once to receive a token, then again with that token', giving the agent a precise invocation pattern. It does not, however, describe exclusions or explicitly contrast with alternatives such as merge_foods, so it stops short of full when/not-to-use guidance.

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

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

The annotations already indicate read-only, idempotent, and non-destructive behavior, and the description adds 'Nothing is saved' and the preview use case. It does not mention potential parser limitations or errors, but the side-effect transparency is well covered.

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

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

The description is concise and well structured, using only two sentences to convey purpose, output, side effects, and use case. There is no redundant or extraneous content.

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

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

Given the input schema, annotations, and stated output schema, the description is complete enough for the intended preview use case. It could mention error behavior or parser choice implications, but the available context covers the essential 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?

The schema descriptions already cover both parameters, including the enum values and the example for ingredients. The tool description adds little beyond the schema, so it meets the baseline but does not elevate parameter understanding.

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

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

The description clearly states a specific verb ('splits'), the resource (free-text ingredient lines), and the output (quantity, unit, food, note with confidence). It also distinguishes itself from sibling tools by emphasizing that nothing is saved and that it is for previewing before writing.

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

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

It explicitly tells when to use the tool: to check how an ingredient line will be understood before writing it to a recipe or shopping list. It does not provide detailed guidance on choosing between the nlp and brute parser options, but the primary use case 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 indicate read-only and idempotent behavior; the description adds the explicit statement 'WITHOUT saving anything,' which reinforces non-destructive behavior. No unexpected side effects are disclosed, but the existing annotation coverage lowers the burden.

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

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

The description is two concise sentences with no redundant information. It efficiently conveys purpose, usage, and non-destructive behavior.

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

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

The description is sufficient for the tool's simple read-only nature. It does not need to explain the output format because an output schema exists, and the use cases cover expected scenarios.

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

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

The schema provides a complete description of the url parameter with min/max length and role ('Address of the recipe page to test'). The tool description does not add further semantics, but schema coverage is 100%, so baseline 3 is appropriate.

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

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

The description clearly states that the tool fetches a URL and reports extraction results without saving, which distinguishes it from the sibling import_recipe_from_url that actually performs an import.

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 provides two concrete use cases: checking a page before importing and diagnosing why an import came out empty, giving clear guidance on when to use this tool over 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?

Annotations only indicate readOnlyHint=false and destructiveHint=false, so the description adds valuable context: items shared with other recipes remain but with reduced quantity. This is a key behavioral trait beyond what annotations provide. It does not mention idempotency or error handling, but the core mutating behavior is well 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?

The description is two sentences, front-loaded with the main action and the critical nuance about shared items. There is no redundancy or fluff, making it efficient and easy to parse.

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

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

The tool has an output schema, so return values are defined there. The description covers the essential behavior including the shared-item handling. It does not mention edge cases like a recipe not being present or the effect of servings_multiplier on shared items, but the core logic is complete enough for typical use.

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 all parameters have descriptive schema entries. The tool description does not add additional parameter-specific meaning beyond what the schema already states, such as the format for recipe and list_id. The baseline of 3 is appropriate since the schema handles the parameter documentation.

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

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

The description clearly states the verb ('Takes... back off') and the resource ('a recipe's ingredients from a shopping list'), and it differentiates itself from siblings like delete_shopping_list_items by explaining the nuance of shared items. It immediately conveys the core function.

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

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

The description implies when to use it (to remove a recipe's contribution) but does not explicitly name alternatives like delete_shopping_list_items or update_shopping_list_items. However, the distinction from add_recipe_to_shopping_list is implicit and the purpose is clear enough for an agent to select it appropriately.

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

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

Discloses substantial behavior beyond the annotations: return format, filter resolution, error behavior, and cookbook exception. The only blemish is the mention of a 'date range' for which no corresponding parameter exists in the schema, a minor inaccuracy that keeps this from 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?

The description is compact and front-loaded with the main purpose, followed by only the necessary filter-combination details and cookbook exception. No redundant or repetitive content.

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

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

Given the tool's complexity, the description supplies enough context to invoke it correctly: what is returned, what is omitted, how filters combine, and what is rejected. Output schema exists, so a detailed return description is not required.

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?

Descriptions add real meaning: tags/tools/categories accept names, slugs, or UUIDs; foods require UUIDs from list_foods and describe HTTP 500 for other forms; defaults and sort semantics are explained. The global require_all_* sentence covers the three boolean parameters that lack individual 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 verb and resource clearly: 'Searches the recipe collection.' Also distinguishes from sibling get_recipe by specifying summaries without ingredients or steps, so an agent knows which tool to choose for detail 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?

Explicitly directs to get_recipe for ingredients/steps and lays out query composition semantics: AND across filter kinds, OR within a filter unless require_all_* is set, and cookbook exclusion. This tells the agent exactly how to combine parameters.

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

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

Annotations already convey that this is a write operation (readOnlyHint false), non-idempotent (idempotentHint false), and not destructive (destructiveHint false). The description adds context about the effect (shows on recipe and sorts by it), which is useful. It does not mention whether the timestamp is overwritten or whether there are prerequisites, but given the simple nature and annotation coverage, a 3 is appropriate.

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 two concise sentences with no filler. The core purpose is front-loaded, and the second sentence adds relevant behavioral context about how the value is used. 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?

For a simple mutation tool with a well-documented schema and annotations, the description is sufficient. It explains the purpose and effect, and the schema covers parameters and output. No additional context (like prerequisites or error handling) is necessary for an agent to use it correctly, though mentioning that the recipe must already exist could be an improvement. Overall, it's complete enough.

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

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

The schema description coverage is 100%, with both parameters (recipe and timestamp) fully documented in the input schema, including formats and examples. The description adds no additional parameter semantics beyond what the schema already provides, so the baseline score of 3 applies.

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

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

The description clearly states the action ('records when a recipe was last cooked') and the resource (recipe), and explains the downstream effect (displayed on recipe and used for sorting). This distinguishes it from sibling mutations like set_recipe_rating or add_recipe_comment, which serve different purposes.

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

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

The description implies when to use this tool (to record a last-cooked timestamp) but does not explicitly mention alternatives or exclusions. It doesn't say 'use this instead of X when...' but the purpose is obvious enough for an agent to infer. However, without explicit guidance, there's some ambiguity about when not to use it, e.g., for rating or comments.

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 explains the primary action (setting rating/favorite) but omits details like clearing the rating with 0 or partial-update behavior. The schema partially covers rating, but the description does not add much beyond the basic action, and the annotations provide minimal behavioral 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?

The description is concise, using two short sentences without unnecessary filler. It front-loads the core action and adds a relevant context note about per-user ratings, making it efficient to parse.

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

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

The description is sufficiently complete for a simple setter operation, conveying the main purpose and a key domain rule. It does not mention return values, but an output schema exists, and the tool's behavior is relatively straightforward. Minor omissions like clearing behavior are covered in 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?

The schema covers the recipe and rating parameters with descriptions, and the description hints at is_favorite. However, is_favorite has no schema description, and the description does not clarify its exact usage (e.g., boolean semantics). Overall, parameter understanding relies on inference.

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

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

The description clearly states the tool's purpose: setting a recipe's personal rating and/or marking it as a favorite. This distinguishes it from sibling tools like set_recipe_last_made or update_recipe.

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

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

The description gives no explicit guidance on when to use this tool versus alternatives such as update_recipe or set_recipe_last_made. It does provide the useful nuance that ratings are per-user, but does not specify conditions for choosing this tool over others.

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