mealie-mcp
Server Quality Checklist
Latest release: v0.1.1
- Disambiguation5/5
Each tool targets a distinct action on a specific resource (recipes, meal plans, shopping lists, cookbooks, etc.). Even with 52 tools, there is no ambiguity—import tools differ by input method, delete tools target different entities, and operations like list vs. get vs. create are clearly separated by name and description.
Naming Consistency5/5All tool names follow a consistent verb_noun pattern in snake_case (e.g., get_recipe, create_shopping_list, delete_share_token). No mixed conventions, abbreviations, or vague verbs. The naming is predictable and easy to parse.
Tool Count3/5With 52 tools, the server is far above the typical 3-15 range. While the domain of meal planning and recipe management is broad, and each tool corresponds to a specific API endpoint, the sheer number makes the surface feel heavy. It is borderline, but the detailed descriptions mitigate some overhead.
Completeness4/5The tool set covers nearly all CRUD operations for recipes, meal plans, shopping lists, cookbooks, organizers, share tokens, and foods/units. Minor gaps exist: no update or delete for individual foods/units (only merge and create), and no tool to manage recipe images. These are small but noticeable omissions.
Average 4.1/5 across 50 of 52 tools scored. Lowest: 2.9/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 8 commits in the last 12 weeks
- Last stable release on
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
This repository includes a glama.json configuration file.
This server has been verified by its author.
Add related servers to improve discoverability.
How to sync the server with GitHub?
Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.
To manually sync the server, click the "Sync Server" button in the MCP server admin interface.
How is the quality score calculated?
The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).
Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.
Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).
Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.
Tool Scores
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false and destructiveHint=false, so the description adds minimal behavioral context. It states 'Creates' (write) and 'in the household', but does not disclose potential side effects, duplicate handling, return behavior, or any authentication/rate limits. Annotations are not contradicted.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is front-loaded with the key action and scope. There is no unnecessary verbiage, and it earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple create tool with one parameter and no output schema, the description is incomplete. It lacks usage guidelines, parameter explanation, and behavioral details (e.g., return value, side effects). Given many sibling tools (list_shopping_lists, delete_shopping_list, etc.), the agent would need more to correctly invoke this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must explain the 'name' parameter. It does not mention the parameter at all—no syntax, format, uniqueness, or required nature beyond the schema. The description adds zero value for parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Creates', the resource 'shopping list', and specifies it is 'empty' and 'in the household'. This distinguishes it from sibling tools like list_shopping_lists, get_shopping_list, and add_shopping_list_items.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool vs alternatives. It does not mention prerequisites (e.g., name uniqueness) or when not to use it (e.g., if a list with that name already exists). With many related shopping list siblings, such guidance is absent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false and destructiveHint=false, so the creation nature is consistent. However, the description adds no detail about side effects (e.g., overwrite behavior, uniqueness constraints, permissions) beyond the annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence is highly concise and front-loaded with the core action. It wastes no words, though it could be slightly expanded to include minimal context without harming conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a create tool with 6 parameters and no output schema, the description lacks typical completeness. It does not mention naming rules, uniqueness, or post-creation behavior. Sibling tools are numerous, but the description offers no help in distinguishing when to pick this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 33% (fraction and use_abbreviation have descriptions). The description does not explain the meaning of name, plural_name, abbreviation, or description. It fails to compensate for the low coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'adds' and the resource 'measurement unit to the group vocabulary'. It is specific and distinguishes from sibling tools like list_units (listing) and merge_units (merging).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as merge_units or checking for existing units. No prerequisites, exclusions, or typical scenarios are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate the tool is not read-only and not destructive. The description adds that the selection 'honours meal plan rules', which is a useful behavioral trait beyond the annotations. However, it omits details about what happens when rules cannot be satisfied (e.g., no matching recipe) or whether it overwrites existing entries.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that front-loads the action and avoids extraneous words. It efficiently conveys the core purpose, though slightly more detail could be included without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's 2 parameters and no output schema, the description fails to explain what the agent should expect as a result (e.g., created entry or success message). It also lacks prerequisites (e.g., need for configured rules) and error behavior, leaving significant gaps in context for effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% so the parameter descriptions are already complete. The description restates that the tool uses 'day and slot' (mapped to 'date' and 'entry_type'), but does not add significant new constraints or context beyond the schema. The high baseline means a score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool picks a recipe for a given day and meal slot while respecting household meal plan rules, which matches the title 'Add a random meal'. It distinguishes itself from siblings like 'create_mealplan_entry' by emphasizing randomness and rule adherence, though it does not explicitly confirm that it creates a meal plan entry.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description offers no explicit guidance on when to use this tool versus alternatives such as 'create_mealplan_entry' or 'suggest_recipes'. It implies use when a random selection is desired, but does not state prerequisites, exclusions, or comparisons with sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false and destructiveHint=false, so the tool is expected to be non-destructive but mutating. The description adds the context that it adds to a 'group vocabulary', which implies a state change and persistence, but it does not explain side effects like whether duplicate names are rejected or if integration with existing ingredient lines occurs immediately.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence that front-loads the primary action and purpose. It could further explain parameter details without becoming verbose, but it is appropriately concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 4 parameters, no output schema, and annotations that don't cover behavior beyond mutation status, the description provides minimal but sufficient context for the core action. However, it lacks details on return value, error conditions, or handling of duplicates, which would be helpful for a creation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 25% (only 'label_id' has a description). The tool description does not explain any parameters beyond the stated purpose. For example, 'name' is required with max/min length but its role is implied; 'plural_name' and 'description' are entirely undocumented. Baseline 3 is appropriate given partial schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb ('adds') and specific resource ('food to the group vocabulary') and explains the purpose ('so ingredient lines can be matched against it'). It distinguishes the tool from siblings like 'list_foods' or 'merge_foods' by focusing on creation and vocabulary addition.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives like 'parse_ingredients' or 'create_recipe'. There is no mention of prerequisites (e.g., group must exist) or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true, so read-only behavior is clear. The description adds that it lists comments from other users, implying no destructive side effects. However, it does not disclose any pagination, ordering, or filtering behavior, or whether the user's own comments are included. The description complements 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, very short sentence that directly states what the tool does. Every word is necessary; no superfluous content. It is front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, no output schema, read-only), the description adequately covers the basic purpose. However, it lacks details about the comment format, ordering, or whether deleted comments are shown, which may be relevant for the agent. It is minimally complete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description does not add any new information about the recipe parameter beyond what the schema description already provides (slug or UUID). The description adds no additional semantics or usage context for the parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists comments left by other users on a recipe, which is the specific resource. It does not explicitly distinguish itself from siblings like add_recipe_comment or delete_recipe_comment, but its purpose is clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool (to view comments on a recipe), but provides no guidance on when not to use it or alternatives. There is no mention of prerequisites such as the recipe needing to exist or the user needing to have the correct recipe identifier.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds context beyond the 'readOnlyHint' annotation by specifying what the timeline includes (events and notes). However, it does not disclose potential behavioral traits such as pagination behavior, ordering of events, or error handling (e.g., if recipe does not exist). The added value is moderate 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence of 19 words that efficiently conveys the tool's purpose and content. It is front-loaded with the action and includes necessary detail without any filler. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that there is no output schema, the description partially explains the return value (events with notes) but omits key details such as whether the timeline is ordered, the structure of the response (list vs. paginated), and what happens when no events exist. The required parameter (recipe) is clear, but completeness is average.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% parameter description coverage, so the baseline is 3. The tool description does not add any additional meaning for the parameters (page, recipe, per_page) beyond what the schema already provides. Therefore it meets the baseline but does not exceed it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does 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 'timeline of a recipe', detailing the types of events included (created, updated, cooked) and that notes are attached. This specificity distinguishes it from siblings like 'get_recipe' (which returns recipe details) and 'list_recipe_comments' (which returns comments, not timeline events).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention when to avoid it, such as for creating events (use 'create_timeline_event') or for simple recipe info (use 'get_recipe'). The agent must infer usage from the name and context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations show `readOnlyHint: false` and `destructiveHint: false`, which are consistent with a mutation tool that does not destroy data. The description adds that moves and recipe replacements happen, but it does not disclose whether partial updates are allowed (e.g., only changing the date without a recipe), what happens to omitted parameters, or if permissions or preconditions are required. Given annotations cover mutation safety, the description adds moderate value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence that efficiently captures the two main use cases. It could mention additional edit capabilities (like changing text/title) without becoming wordy, but it is not overly verbose. It is front-loaded and concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 6 parameters with moderate schema coverage and no output schema. The description provides a functional overview but omits that other fields (e.g., `text`, `title`) can be modified independently. For a mutation tool, it could also note what the response looks like or whether the entry must already exist. It meets baseline adequacy but leaves some behavioral gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50%, meaning two parameters (`recipe` and `entry_id`) have descriptions. The description itself does not elaborate on parameters, but the schema provides decent coverage for those two. The description hints at the purpose of `date` and `entry_type` (move to another day or slot) and `recipe` (replace the recipe). The tool has 6 parameters, and the description context helps disambiguate some of them, earning above baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool modifies an existing meal plan entry by moving it to another day/slot or replacing the recipe. It distinguishes itself from `create_mealplan_entry` (creation) and `delete_mealplan_entry` (deletion). However, it does not mention that other properties like `text` or `title` can also be updated, so it slightly constrains the perceived scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a basic idea of when to use the tool (to move or swap a recipe), but it does not explicitly state when NOT to use it. For instance, it could note that `delete_mealplan_entry` should be used to remove an entry entirely, or that `create_mealplan_entry` adds a new one. No alternatives are named directly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the description's 'Fetches' is consistent. The description adds value by specifying that items are included (checked and unchecked), which is non-obvious from the tool name alone. However, it does not disclose failure behavior (e.g., invalid list_id), pagination limits, or any other behavioral traits beyond what annotations imply. Given annotation coverage, a score of 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
A single, well-constructed sentence contains all the essential information with no filler. Every word earns its place, and the structure is front-loaded with the verb and resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description reasonably hints at the return structure ('with all of its items, checked and unchecked'). For a simple fetch tool with only 2 parameters, this is almost complete. It could be slightly improved by clarifying that it returns the full list object including metadata, but the current level is adequate for an AI agent to understand the tool's scope.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both parameters already well-documented in the input schema (list_id as UUID from list_shopping_lists, include_checked with default true). The tool description adds no additional meaning to these parameters. Per the scoring guidelines, baseline 3 is correct when schema fully handles parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does 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 with all its items (checked and unchecked). The verb 'Fetches' is specific, and the resource 'one shopping list' distinguishes it from sibling tools like 'list_shopping_lists' (which lists multiple) and mutation tools like 'create_shopping_list' or 'add_shopping_list_items'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention prerequisites (e.g., needing the list_id from list_shopping_lists), when not to use it (e.g., when bulk listing is needed), or which sibling tool to use instead. The agent is left to infer usage solely from the name and input schema.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare 'readOnlyHint: true', so the agent knows this is a safe read operation. The description adds the key behavioral trait that returned data does not include items, which is useful. However, it does not mention pagination behavior or default ordering, which are relevant for a listing tool. The added value is moderate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence of 12 words, front-loaded with the main action. Every word earns its place; there is no redundancy, fluff, or unnecessary information. It is highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema, so the description should compensate by hinting at what the response contains (e.g., list IDs, names). It does not. For a listing tool, the agent needs to know what fields are returned to use the results effectively. The description is too sparse to be fully complete given the lack of output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema covers 100% of parameters with descriptions, so the baseline is 3. The description does not add any additional meaning beyond what the schema already provides (e.g., 'page' and 'per_page' are already described). No extra param context is given.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'lists', the resource 'shopping lists', and the scope 'of the household'. It also explicitly notes what is excluded ('without their items'), which distinguishes it from related tools like 'get_shopping_list' that would include items. This is specific and actionable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for obtaining a summary overview of all shopping lists, but it does not explicitly state when to use this vs. alternatives like 'get_shopping_list' (for a single list with items) or 'create_shopping_list'. Some guidance is provided through the exclusion of items, but it is not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds the per-user context, which is valuable beyond the annotations (readOnlyHint=false, destructiveHint=false). However, it does not disclose other behavioral traits like idempotency, error handling, or authorization requirements, which would be helpful for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no wasted words. It front-loads the main action and immediately follows with a key contextual note. Every sentence serves a purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple mutation tool, the description covers the main action and the per-user scope. It does not mention prerequisites (e.g., recipe must exist) or return values, but given the lack of output schema, this is acceptable. The description is nearly complete for its purpose.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 67% (rating and recipe have descriptions; is_favorite does not). The tool description does not add any additional parameter meaning beyond what the schema already provides. The missing parameter is self-explanatory, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Sets the personal rating of a recipe and/or marks it as a favourite.' It distinguishes this tool from siblings like set_recipe_last_made by mentioning the specific behavior, and adds context about ratings being per user, which clarifies scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as set_recipe_last_made or other recipe manipulation tools. The agent must infer usage from the purpose alone, which is insufficient for optimal selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint true, so the description doesn't need to reiterate read-only nature. However, it adds value by disclosing that entries are either recipe references or notes, which is beyond schema. It does not describe pagination, ordering, or behavior with empty results. 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is only two short sentences, completely front-loaded with the purpose and a detail about entry types. Every word earns its place with no fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 4 optional params and no output schema, the description provides essential meaning but leaves gaps. It does not explain default behavior when start/end date are omitted (e.g., full plan or recent range?), nor the order of entries or pagination behavior. The mention of entry types is helpful, but more context about return format or behavioral defaults would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with each parameter already having a description (page, end_date, per_page, start_date). The tool description does not add any additional meaning or constraints beyond what the schema provides. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists meal plan entries for a household within a date range. It specifies the verb 'Lists' and the resource 'meal plan of the household', and distinguishes the output as either recipe references or free-text notes. This clearly differentiates it from sibling tools like get_todays_meals (likely single day) and create/update/delete meal plan entries.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for viewing meal plans over a date range, but it does not explicitly state when to use this versus alternatives like get_todays_meals or create_mealplan_entry. No guidance on when not to use, prerequisites, or exclusions is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate it is not read-only or destructive. The description adds useful context: comments are visible to the group and attributed to the token user, which aids understanding of the tool's behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences front-load the purpose and add relevant behavioral context with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers purpose and basic behavior but lacks details on return value (no output schema) and error conditions, making it somewhat incomplete for a mutation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50% (only recipe has a description). The tool description does not add any detail about the text parameter, which remains undocumented. The description does not compensate for the missing parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific verb 'adds' and resource 'comment to a recipe', distinguishing it from sibling tools like list_recipe_comments and delete_recipe_comment.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for adding comments but does not provide explicit guidance on when to use it versus alternatives, nor does it mention prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is a safe write operation (readOnlyHint=false, destructiveHint=false). The description adds the nuance that creation via update_recipe is possible, positioning this tool as an explicit upfront definition. However, it does not disclose idempotency behavior (e.g., what happens if a duplicate name is provided) or any authorization requirements, leaving gaps 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description consists of two short sentences, each carrying distinct value: the first states the core purpose, the second gives usage context. There is no fluff, and critical information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is adequate given the tool's simplicity (2 params, no output schema). It covers purpose and an important usage nuance. However, it lacks information about the return value (what the created object looks like?) and error cases (duplicate names, missing permissions). The presence of sibling tools like list_organizers and update_organizer implies a workflow, but the description does not complete the picture for an agent navigating all organizer tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 50% because the 'name' parameter lacks a description. The tool description does not mention any parameters or add meaning beyond the schema. The only indirect help is referencing the kind values ('tag, category or tool') which are already enumerated. No guidance is given for the 'name' parameter, failing to compensate for the schema gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it creates a tag, category, or tool, and distinguishes it from the automatic creation via update_recipe. The verb 'creates' paired with the resource 'organizer' (tag/category/tool) is specific and matches the title and enum values. It differentiates from sibling creation pathways.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly contrasts this tool with the on-the-fly creation that happens when assigning via update_recipe, telling the agent when to use this upfront definition tool instead. It does not exclude other related tools like update_organizer or delete_organizer, but the primary alternative is well addressed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, and the description reinforces read-only behavior with 'fetches'. Additionally, it reveals that the tool returns recipes that the cookbook 'currently matches', indicating dynamic content at query time—a behavioral detail beyond the annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is only two sentences (16 words) and front-loads the core action and result. The second sentence efficiently clarifies input format. It avoids unnecessary details, though it could be more structured (e.g., bullet points).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description partly compensates by stating it returns a cookbook and its matching recipes. However, it does not describe the structure of the response (e.g., fields of the cookbook object, pagination details for per_page), leaving some uncertainty for the agent about what exactly to expect.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with both parameters (cookbook, per_page) having descriptions. The description restates that cookbook accepts slug or UUID, which adds no new semantics. For per_page, the description offers no additional context, leaving the schema to carry the meaning. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('fetches'), the resource ('a cookbook'), and the outcome ('and the recipes it currently matches'). It also specifies accepted identifiers (slug or UUID), distinguishing it from siblings like list_cookbooks (which lists cookbooks) or get_todays_meals (which is unrelated).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage (when you have a slug or UUID and need cookbook details with recipes) but does not explicitly state when to use this tool over alternatives like list_cookbooks. No exclusion criteria or 'when not to use' guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the description's main behavioral addition is clarifying that share links allow unauthenticated reading of recipes. It does not describe pagination, sorting, or what happens if the recipe parameter is invalid. With strong annotations, a 3 is fair.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, zero wasted words. The first sentence front-loads the main action and result details; the second adds critical security context. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given a single optional parameter, high schema coverage, strong read-only annotation, and simple output expectations, the description covers the essential behavioral and security nuances. Minor gap: doesn't note if an empty result set is possible or the output format structure.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents the optional 'recipe' parameter. The description does not add any extra meaning, syntax details, or behavioral context about the parameter beyond listing it in the context of the tool's purpose. Baseline 3 is correct.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Lists') and resource ('public share links'), clearly stating what each result shows ('recipe... and when it expires'). It differentiates from siblings like 'create_share_token' and 'delete_share_token' by explicitly focusing on listing existing tokens.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use when you need to see existing share links, but offers no explicit guidance on when to choose this tool over alternatives like checking recipe access through 'get_recipe' or browsing via 'search_recipes'. No exclusions or prerequisites are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare destructiveHint=false and readOnlyHint=false. The description adds value by explaining the partial-update behavior ('Only the fields given are touched') and the clearing effect of empty arrays. However, it does not disclose potential side effects, auth requirements, or validation failure modes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences precisely deliver the essential information with no wasted words. The purpose is front-loaded and the behavioral detail is efficiently appended.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 14 parameters, low schema coverage, no output schema, and numerous sibling tools for specific edits, the description is insufficient. It does not mention what is returned, how to handle validation errors, or guide the agent toward more appropriate tools for rating, commenting, or other specific modifications.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is low at 43%. The description adds general parameter semantics about partial updates and list clearing, but does not provide detailed meaning for the 8 parameters lacking schema descriptions. It compensates somewhat but not fully.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'changes' and identifies the resource 'fields of a recipe', clearly distinguishing from sibling tools like create_recipe or delete_recipe. It also adds the nuance that only given fields are touched, which further clarifies scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies that this tool should be used when modifying existing recipe fields, but it does not explicitly state when to use it versus more specific sibling tools like set_recipe_rating or add_recipe_comment. No alternative tools or when-not-to-use conditions are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false and destructiveHint=false, indicating a creation action that does not destroy data. The description adds the mutual exclusivity constraint (recipe vs. title), which is helpful beyond annotations. It does not, however, clarify whether an existing entry for the same date/type gets overwritten or rejected, leaving a behavioral gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise at two sentences, immediately stating the action and the critical constraint. Every word is functional, with no redundancy or filler. This is a model of efficient documentation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 5 parameters, no output schema, and no nested objects, the description does an acceptable job of covering the core logic. However, it lacks guidance on whether entries can be duplicated for the same meal slot, what the return value looks like, or any prerequisites (e.g., does the recipe need to exist?). This leaves room for confusion in edge cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters thoroughly. The description adds value by explaining the mutual exclusion rule (recipe vs. title) and that a plan entry is one or the other, which provides context not in the raw schema. However, it does not elaborate on specific formatting or relationships beyond that.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that it places a recipe or free-text note onto a meal plan for a specific day. It uses a specific verb ("puts") and resource ("meal plan"), and the constraint "one or the other" distinguishes it from sibling tools like update_mealplan_entry and delete_mealplan_entry.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states the core rule of using 'recipe' or 'title' but not both, which is essential guidance. It does not, however, mention when to prefer this tool over alternatives like batch operations or creating a full plan via list_mealplans, which slightly reduces the score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds significant behavioral context beyond the annotations: the annotations already declare destructiveHint=true, but the description reveals the important two-step confirmation requirement and the need to call twice. This is critical behavior not captured by 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.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is just two short sentences, front-loading the core action. However, it could be slightly more structured or hint at the token parameter names, but it is efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that there is no output schema, the description adequately explains the core behavior and the two-step process. The comment_id source is in the schema. The description is sufficient for a simple tool with good schema coverage, though it could mention what response the first call returns or that the token is temporary.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the description adds minimal value beyond what the schema provides. The description implies the token pattern but does not detail parameter meanings better than the schema's descriptions. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Deletes a comment', which is a specific verb and resource. It distinguishes from siblings like add_recipe_comment and list_recipe_comments by focusing on deletion, though it does not explicitly contrast with them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly explains the two-step confirmation process: call once to get a token, then again with that token. This provides clear guidance on when and how to use the tool, and implies that a direct call without the token will not delete, but it does not mention when not to use it or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, and the description is consistent with that. The description adds meaningful behavioral context by explaining that the list is empty on never-seeded instances, which is not available in the schema or annotations. This goes beyond the structured data without contradicting it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no redundant wording. The first sentence fronts the core purpose, and the second provides a relevant edge case. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a straightforward list operation, the description provides the core behavior, an edge-case behavior, and a hint at the return content (abbreviations). Without an output schema, it would benefit from mentioning pagination or response structure, but the schema covers pagination parameters, and the tool is simple enough that this is not a critical gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 75%, leaving the 'search' parameter without a description. The tool description does not mention search at all, nor does it clarify how any parameter affects results. Since the description fails to compensate for the undocumented parameter and adds no parameter-level meaning, it does not meet the baseline for high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description begins with 'Lists the measurement units of the group, with their abbreviations,' which is a specific verb+resource combination. It clearly distinguishes list_units from sibling tools like create_unit or merge_units by focusing on the retrieval aspect. The added detail about abbreviations further clarifies the scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description hints at a comparison to foods ('Like foods') to convey the empty-on-unseeded behavior, which is useful context, but it does not explicitly state when to use this tool instead of list_foods or other alternatives. There is no clear when-to-use or 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.
- Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=false and readOnlyHint=false, so the agent knows it mutates data but is not destructive. The description adds no additional behavioral context, such as whether appending or replacing occurs, what happens on duplicate items, or any authentication requirements. For a mutation tool, the lack of detail on idempotency or side effects is a notable gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, both sentences earn their place: the first states the core action and format, the second provides important behavioral context relative to a sibling tool. No filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no output schema and only 2 parameters with 100% schema coverage, the description adequately covers the key usage context and limitations. A small improvement would be to mention the list_id source explicitly (already in schema, but echoed in description could help). Overall, the description is sufficiently complete for an add-items tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds a free-text example ('2 tbsp olive oil') that reinforces the items parameter's purpose but does not add any meaning beyond what the schema already provides for either parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Adds') and resource ('items to a shopping list'), clarifies that input is free text with an example, and distinguishes itself from the sibling parse_ingredients tool by noting that Mealie does not auto-split ingredients.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly tells when to NOT use this tool for ingredient parsing ('run parse_ingredients first if that matters'), providing clear guidance on the alternative sibling tool and the context for its use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already confirm non-read-only (false readOnlyHint) and non-destructive (false destructiveHint), so the bar is lower. The description adds that it's a note about cooking outcomes, which is helpful context, but doesn't disclose whether it updates any derived state or has any side effects beyond the entry itself.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with zero waste. The first sentence defines the action and context, the second provides a critical sibling relationship. Perfectly front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no nested objects, the description is sufficient for a simple create tool. It covers what the tool does, how it pairs with a sibling, and the role of the timeline. Could mention the output (e.g., returns the created event ID) but isn't strictly necessary for a tool with straightforward side effects.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description's mention of 'note about having cooked it' maps well to the schema fields (message, subject, timestamp), but it doesn't add any new meaning or format hints beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'adds an entry' and the resource 'recipe's timeline', with a specific use case ('note about having cooked it and how it turned out'). It distinguishes from siblings like set_recipe_last_made by naming it, though the overall sibling list is large and the line between this and list_recipe_timeline is implied rather than explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly pairs the tool with set_recipe_last_made for sorting purposes, providing a clear when-to-use and when-not-to-use signal. This is exemplary guidance in a complex toolset, helping the agent choose between related timeline operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=false, indicating non-destructive behavior. The description adds 'leaving the original untouched', which confirms but does not significantly extend beyond the annotation. No additional behavioral traits (e.g., what happens if name exists, required permissions, rate limits) are disclosed. The description adds minimal value beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the action ('Creates a copy of a recipe'), and every word earns its place. No redundancy or filler. Perfectly concise for the tool's simplicity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with 2 parameters, no output schema, and clear behavior, the description covers purpose and usage adequately. It does not mention the return value (likely the duplicated recipe object), but agents can infer this from the tool's name and common patterns. The missing return info is a minor gap, but overall the description is sufficient for this low-complexity tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%—both parameters have detailed descriptions in the schema (e.g., 'Mealie appends a counter when omitted' for name, 'Recipe slug or recipe UUID' for recipe). The description does not add any parameter-specific information beyond what the schema already provides. Baseline is 3 with full coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('creates a copy of a recipe') and a clear resource ('recipe'), with the added context of 'leaving the original untouched'. This distinguishes it from siblings like create_recipe (which creates from scratch) and update_recipe (which modifies). The phrase 'useful as a starting point for a variation' 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.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly mentions when to use it ('useful as a starting point for a variation'), giving clear usage context. However, it does not explicitly state when NOT to use it or name alternatives (e.g., 'for a completely new recipe, use create_recipe'). The guidance is good but lacks exclusionary criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, so the description is not required to emphasize safety. The description adds valuable context that cookbooks are saved filters (not fixed sets), which informs the agent about the dynamic nature of the data. No other behavioral traits (e.g., pagination defaults) are mentioned, but the added insight justifies a score above baseline.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two short sentences that deliver the core purpose and a key conceptual detail. No filler or redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the moderate complexity of sibling tools and the absence of an output schema, the description provides the essential conceptual clarification about cookbooks along with the core listing function. It does not detail return structure or pagination behavior, but for a list tool with clear parameters, this is reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear descriptions for page and per_page, so the baseline is 3. The description does not repeat or add further meaning to the parameters, which is acceptable given the schema already explains them sufficiently.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Lists the cookbooks of the household' with a specific verb and resource, and distinguishes the tool by explaining that a cookbook is a saved filter, not a fixed recipe set, setting it apart 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.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly guide when to use this tool versus alternatives like get_cookbook or search_recipes. While the nature of listing all cookbooks is implied, no direct comparison or exclusion criteria are provided for the agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false and destructiveHint=false, so the write nature is covered. The description adds that the value is displayed and used for sorting, which is useful context. It doesn't mention overwrite semantics or permission requirements, but with annotations present the description contributes enough to warrant a 3.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is exactly two sentences, front-loaded with the primary action, and the second sentence adds meaningful context about visibility and sorting. No wasted words or redundant details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple setter with two fully documented parameters and adequate annotations, the description covers purpose and effect. It doesn't discuss error behavior or overwriting, but that is not a significant gap for this low-complexity tool. Could be slightly more explicit, but it is essentially complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and both parameters (recipe, timestamp) have detailed descriptions including formats and examples. The description itself adds no parameter-specific meaning, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Records') and clearly names the resource ('when a recipe was last cooked'). It distinguishes from sibling tools like set_recipe_rating by targeting the last-made timestamp, and adds the downstream effect of showing and sorting in Mealie.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context: record when a recipe was last cooked, and notes the consequence ('Mealie shows this on the recipe and sorts by it'). It doesn't explicitly name alternatives or exclusion cases, but the intended use is obvious from the text.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is not read-only (false) and not destructive (false), so the description need only add behavioral context. It accurately signals that this is a creation operation (implied mutation) and hints at the need for unique names via the name parameter description. 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.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short (two sentences) and front-loaded with the core purpose. Every sentence adds value. It could briefly mention the required 'name' field, but overall it is efficiently concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of 13 parameters, no output schema, and moderate schema coverage, the description is somewhat thin. However, the key sibling guidance and the purpose clarity are present. The schema's property descriptions fill many gaps. A more complete description might mention that all fields are optional except name, but the schema already makes that clear. This is solid for a create tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 46%, relatively low, so the description should compensate but does not. The body description adds no details beyond 'from the given fields'. However, several schema property descriptions (e.g., on name, ingredients, tags) provide useful semantics that elevate the overall parameter understanding. Since the description itself adds no extra meaning, it scores at baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb+resource ('Creates a recipe from the given fields') and immediately distinguishes itself from the sibling tool import_recipe_from_url, which is the primary source of confusion. It clearly states when to use the alternative.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly tells the agent to use import_recipe_from_url instead when the source is a website, which provides clear when-to-use guidance. However, it does not mention when to use other related tools like duplicate_recipe or suggest_recipes, but the contrast with the sibling is sufficient for the main decision point.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true, so the description adds value by specifying the returned content (ingredients, steps, times, yield, notes, nutrition). This goes beyond the annotation alone without any contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence of 20 words that is front-loaded and succinct. Every word contributes meaning without redundancy or waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read tool with only two parameters (both well-described in schema) and no output schema needed, the description fully covers what the tool returns. No gaps are present given the complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description mentions 'slug or UUID' but this largely repeats the schema's detailed descriptions. It adds minimal extra meaning beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it fetches one recipe with all cooking details (ingredients, steps, etc.) and specifies the identifier types (slug or UUID). This distinguishes it from sibling tools like search_recipes which return lists, or create_recipe which mutates data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use for retrieving a single complete recipe but does not explicitly state when to use versus alternatives such as search_recipes for listing or suggest_recipes for recommendations. No exclusions or when-not guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate it's a non-destructive write. The description adds valuable behavioral details: without filter it matches all recipes, the filter uses a custom query language, invalid filters return a 422. This goes beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences with no wasted words. First sentence defines the tool, second provides key behavioral nuance. Front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a creation tool with four parameters and no output schema, the description covers the core behavior, filter semantics, and error scenario. It doesn't state what is returned (likely the created object), but the missing info is standard. Overall fairly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50%. The description adds meaning for 'query_filter' (explaining it's Mealie's query language and default behavior) and for 'name' (cookbook as named view). However, 'description' and 'is_public' get no extra clarification. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates a cookbook, defined as a named, saved view of recipe collection. It distinguishes from siblings like delete_cookbook, list_cookbooks, etc., and explains the filter behavior.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for creating a saved view. It includes a hint that complex filters are easiest to build in the web UI, providing some context about when to use this tool versus other interactions. However, it doesn't explicitly state alternatives or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false and openWorldHint=true. The description adds value by explaining that the tool requires an external AI provider, that the call fails without it, and that the configuration is role-restricted. 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no wasted words. The first sentence front-loads the purpose and method, the second covers the critical prerequisite. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (external dependency, 3 parameters, no output schema), the description covers the purpose, prerequisite, failure mode, and role restriction. It could mention what the tool returns (e.g., a recipe ID) but is otherwise sufficient for an agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description mentions 'a photo' but does not add details about the base64 encoding, format, or translation parameter beyond what the schema already provides. No additional parameter-level guidance is given.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Creates a recipe') and the resource ('from a photo'), with specific examples of inputs (cookbook page, handwritten card). It distinguishes this tool from siblings like import_recipe_from_url or create_recipe by specifying the AI-driven photo-to-recipe process.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly mentions the prerequisite of an AI provider set up in Mealie and warns that the call fails without it. It also notes that the setting is only visible to admins/group managers. While it doesn't name specific alternative tools, it provides clear context for when to use (and not use) this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations, the description discloses that fetching happens on the Mealie server, which has network and permission implications. It also warns that 'everything the page contains... ends up in the collection as written by whoever controls that site,' revealing that imported content is not sanitized or curated. This adds meaningful 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences and each one earns its place: first the primary action, second the server-side execution boundary, third the scope of imported content and its source-controlled nature. It is front-loaded and contains no fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a relatively simple import tool with no output schema, the description sufficiently covers the purpose, the execution environment, and what content will be saved. It does not explicitly mention return values or failure behavior, but the annotations and input schema already convey safety and parameter requirements, so the description is reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 67%: url and include_tags are documented, but include_categories has no schema description and the tool description does not clarify it. The description adds general context about what content gets imported, but it does not enrich the semantics of the individual parameters beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action and resource: 'Has Mealie fetch a recipe page and save it as a new recipe.' This distinguishes it from siblings like preview_recipe_url and import_recipe_from_html_or_json by emphasizing URL-based, server-side import. The scope is concrete and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives clear context for when to use the tool: when you want Mealie itself to fetch a remote recipe page, and the phrase 'not here' sets an important boundary about where the fetch occurs. However, it does not explicitly name alternatives or state when not to use this tool versus import_recipe_from_html_or_json or import_recipe_from_image.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds value beyond the readOnlyHint annotation by explaining that an empty result is a valid state, not an error, and that many instances store ingredients as plain text. This helps the agent interpret results correctly.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is just two sentences, front-loaded with the action and context. It packs important nuance (empty result) without fluff, making it highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple structure (no output schema, only pagination params), the description covers the key contextual points: the tool's purpose and the meaning of empty results. It could mention the response shape, but annotations and schema cover the rest reasonably.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 75%, so the schema already documents most parameters. The description adds no parameter-level detail, and the search parameter lacks a description in the schema. Since coverage is not low, baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool's function: listing structured foods, and specifies the domain (ingredient vocabulary). It distinguishes itself from sibling tools by explaining the semantic role and adding a key clarification about empty results.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool (to read the ingredient vocabulary) and gives contextual guidance about empty results, but does not explicitly contrast with alternatives like create_food or list_units. The readOnlyHint and wording convey a read operation sufficiently.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the description does not need to repeat that. It adds value by specifying that the output includes IDs and slugs, and that the items are 'defined in the group.' The description is consistent with 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with no waste. The main action and purpose are front-loaded, and the connection to search_recipes is efficiently placed at the end.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 5 parameters, no output schema, and a broad set of sibling tools, the description covers the essential purpose and relationship to search_recipes. It could mention pagination or sorting behavior, but the schema covers those parameters, so the description is adequate for selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description does not add any extra detail about the parameters beyond what the schema already provides; it focuses on the output. No added value for parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that this tool lists tags, categories, or tools with their IDs and slugs, and explicitly distinguishes itself from sibling tools by highlighting that these are the values used for filtering in search_recipes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains that the output values are what search_recipes filters on, giving clear context for when to use this tool. However, it does not explicitly state when not to use it or compare it to other listing tools like list_foods or list_units.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes beyond the annotations (which just say not read-only and not destructive) by explaining the nuanced behavior: items shared with other recipes remain, with reduced quantity. This adds valuable behavioral detail.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is just two sentences, each doing useful work: the first states the core action, the second clarifies the non-trivial side-effect. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of output schema, the description explains the core behavior and a key side-effect. It does not explicitly state return values or error conditions (e.g., what happens if recipe not on list), but the behavioral nuance provided makes it mostly complete for a removal operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with descriptions for all three parameters (list_id, recipe, servings_multiplier), so the description need not add param details. The description provides no extra parameter guidance beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('removes...back off') and resource ('recipe's ingredients from a shopping list'), and clearly distinguishes from its sibling tool add_recipe_to_shopping_list by describing the inverse operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool: to reverse a recipe addition. It does not explicitly state when not to use it or name alternatives, but the context of removing items makes the use case fairly clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses the partial update behavior: 'Only the given fields are changed; the rest of each item is preserved.' This adds value beyond the annotations (readOnlyHint=false, destructiveHint=false), which only indicate non-read-only and non-destructive nature. 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: the first states the purpose, the second adds a critical behavioral note. No redundant words, front-loaded with the primary action. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 5 parameters (2 required, 3 optional), no output schema, and annotations present, the description covers the core behavior and partial update guarantee. It could mention idempotency or that multiple items are updated simultaneously, but the current description is fairly complete for a simple mutation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds global semantics: 'Only the given fields are changed; the rest of each item is preserved.' This clarifies that the tool performs a partial update, which is not explicitly stated in the individual parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'changes' and the resource 'shopping list items', with a specific common use case 'ticking them off'. It distinguishes from sibling tools like 'add_shopping_list_items' and 'delete_shopping_list_items' by implying updates to existing items.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage through the phrase 'most often ticking them off', but it does not explicitly state when to use this tool versus alternatives such as 'add_shopping_list_items' or 'delete_shopping_list_items'. No when-not-to-use or alternative guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false and destructiveHint=false, but the description adds significant beneficial behavior by explaining that ingredients are merged (not replaced) and that the recipe is remembered for later removal. For a mutation that is neither destructive nor read-only, this provides precisely the behavioral nuance needed beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences that are front-loaded with the core action and key merging behavior, then the important pairing with the sibling tool. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and the complexity of the tool (3 params, merging behavior, pairing with removal), the description is complete. It covers what happens to existing items, the recipe tracking, and the complementary tool. No gaps remain for an agent to use this correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds no additional parameter semantics beyond what is already documented in the schema. The schema does a good job explaining list_id and recipe formats, and the serving_multiplier defaults. Hence score 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'adds' and the resource 'a recipe's ingredients to a shopping list' including the key behavior 'merging them with what is already there'. This distinguishes it from siblings like 'remove_recipe_from_shopping_list' and 'add_shopping_list_items'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains that the recipe is remembered on the list so that 'remove_recipe_from_shopping_list can take exactly these ingredients back off again', providing clear context for when to use the complementary tool. While it doesn't explicitly state when not to use this tool (e.g., versus adding individual items), the usage context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations (readOnlyHint=false, destructiveHint=false) indicate a non-read, non-destructive mutation, which the description confirms ('creates a link'). The description adds valuable behavioral context beyond annotations: the two-step confirmation process and the implicit effect of creating a public access link. No contradictions; the description enhances understanding of the tool's usage pattern.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, front-loads the purpose, and includes the critical confirmation requirement. No redundant or unnecessary words; every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description would ideally specify what the tool returns (e.g., the token on first call, the share link on second) or the format of the created link. It briefly mentions 'receive a token' but does not confirm the response structure. For a creation tool, this gap reduces completeness. However, the description covers the core workflow adequately.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds meaning by tying the confirm_token parameter to the two-step flow ('call once to receive a token, then again with that token'), which clarifies the parameter's role beyond the schema description. The description does not elaborate on expires_at or recipe parameters further, but the schema already provides sufficient detail.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses specific verbs ('creates a link', 'lets anyone read one recipe without logging in') and clearly identifies the resource (public share link for a recipe). It distinguishes from siblings like list_share_tokens and delete_share_token by focusing on creation and the two-step confirmation process.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states the two-step confirmation requirement ('call once to receive a token, then again with that token'), providing clear usage direction. It does not explicitly tell when not to use this tool, but sibling context implies alternatives for listing or deleting tokens. A 4 reflects clear context 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.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description aligns with the readOnlyHint annotation by stating 'WITHOUT saving anything' and adds behavioral context about fetching and reporting extraction. It does not contradict annotations and provides useful safety guarantees.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with two sentences, front-loading the purpose and then providing usage guidance. Every sentence adds value with no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, no output schema, clear annotations), the description fully covers purpose, behavioral guarantee, and use cases. No missing information is apparent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a clear description for the 'url' parameter. The description does not add additional meaning beyond what the schema already provides, so a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool fetches a URL and reports what Mealie would extract without saving, using a specific verb and resource. It distinguishes itself from import tools by emphasizing the preview nature.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit use cases: checking a page before importing and debugging empty imports. This gives clear context for when to use the tool, though it does not explicitly mention alternatives like import_recipe_from_url.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotation already declares readOnlyHint=true, so the agent knows it's a safe read operation. The description adds behavioral details about filter combination logic and what the summaries omit, which goes beyond the annotation. However, it doesn't disclose pagination behavior (the response is paginated but no mention of how total pages are indicated or cursors), response format, or performance implications. For a read-only tool with 14 parameters, this is decent 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.
Conciseness4/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences long, front-loaded with the primary purpose, and includes critical usage guidance. It wastes no words. However, the filter logic information could be slightly rephrased for maximum clarity (e.g., 'All filters are combined with AND; within a single filter, entries match if they match ANY of the specified values unless the corresponding require_all_* flag is set'). It's good but not perfect.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 14 parameters, 79% schema coverage, readOnlyHint annotation, and no output schema, the description provides a clear summary of the tool's return value and a key behavioral rule about filters. It doesn't explain pagination handling or response structure (which would be needed since there's no output schema), but for a search tool with these features and siblings, it strikes a reasonable balance. It's missing a bit on the response format expectations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 79%, so the schema already documents many parameters well. The description adds high-level semantic context about filter combination (AND across, OR within) that is not available from individual schema descriptions. However, it could further explain the exact behavior of require_all_* flags more explicitly (e.g., example: 'if set, the filter is AND instead of OR'). The description's key contribution is the overall filter logic, which enhances parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Searches') and clearly identifies the resource ('recipe collection'). It further specifies what the result contains (summaries with name, slug, id, etc.) and what it excludes (ingredients or steps, directing to get_recipe for those). This clearly distinguishes it from its siblings like get_recipe, suggest_recipes, and others.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use this tool ('if you need summaries without ingredients or steps') and when not to ('use get_recipe for those'). It also explains combinational logic (AND across filters, OR within filters unless require_all_* flags are set), which is critical for correct usage. However, it doesn't explicitly exclude other sibling tools like suggest_recipes or the various list functions, though the context of summaries vs. details is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true. The description adds that recipes are not touched, which is a key behavioral detail not in annotations. It also discloses the confirmation token workflow. 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: first states action and side-effect, second describes the confirmation workflow. Every sentence is essential and front-loaded. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core deletion behavior and confirmation mechanism. It does not mention error handling or return values, but for a relatively simple destructive tool with no output schema, this is adequate. The schema covers parameter validation, so the description is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, baseline 3. The description adds value by explaining the overall confirmation flow, which gives context for how to use the confirm_token parameter. It does not add details beyond schema for cookbook_id, but the workflow context is helpful.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it deletes a cookbook and clarifies that recipes are unaffected because a cookbook is only a saved filter. This distinguishes it from other delete tools (e.g., delete_recipe) and from non-deletion cookbook tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly explains the two-step confirmation process: call once to get a token, then again with that token. This provides clear usage guidance. It does not explicitly compare to alternatives, but the purpose is sufficiently self-contained.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the destructiveHint annotation, the description adds significant behavioral detail: the tool is nondestructive to the associated recipe and requires a two-step confirmation with a token. These non-obvious traits are essential for correct invocation and go well beyond what annotations alone convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, each earning its place: purpose, non-destructive scope, and confirmation protocol. It is front-loaded with the core action and completely free of unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple destructive tool with no output schema, the description covers the core action, the key side-effect (recipe untouched), and the non-trivial two-step process. It lacks notes on token expiration, error conditions, or permission requirements, but the provided context is sufficient for basic agent usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema coverage is 100%, with each parameter already well-described (entry_id and confirm_token have detailed schema descriptions). The tool description reinforces the two-step pattern but does not add new parameter-level meaning beyond what the schema provides, meeting baseline expectations.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Removes one entry from the meal plan' with a specific verb and resource. It further distinguishes from deleting the recipe by noting 'The recipe itself is not touched', effectively differentiating 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.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the two-step confirmation process ('call once to receive a token, then again with that token'), providing critical usage context. However, it does not explicitly compare when to use this tool versus alternatives like update_mealplan_entry or create_mealplan_entry, nor does it list exclusion cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide destructiveHint=true and readOnlyHint=false. The description adds valuable behavioral context: permanent deletion, inclusion of comments/timeline/images, and the two-step confirmation mechanism. This goes beyond what annotations offer and does not contradict them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, front-loaded with the main action and consequence, and contains no redundant or unnecessary information. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a deletion tool with two parameters and no output schema, the description covers the essential aspects: what is deleted, the permanence, and the confirmation flow. It could mention that the token is returned in the first call's output, but that is inferable from the schema. Overall, it is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents both parameters adequately. The description implicitly explains the confirm_token via the two-step process, but adds no new semantic detail beyond what the schema provides. Baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'deletes' and the resource 'recipe permanently' along with associated items (comments, timeline, images). It distinguishes the tool from siblings like update_recipe or duplicate_recipe by specifying the destructive action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on the two-step confirmation process ('call once to receive a token, then again with that token'). While it doesn't explicitly contrast with alternative tools (e.g., delete_organizer), the context of recipe deletion is clear and the confirmation requirement is a key usage guideline.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the destructiveHint annotation, the description explicitly states that deletion includes 'everything on it', making the scope of destruction unambiguous. It also reveals the two-step confirmation token mechanism, which is essential behavioral context that the annotation and schema do not convey. This goes beyond the structured data and is directly actionable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, each packed with essential information: the destructive action and the required two-step confirmation. No filler, no repetition of schema details, and the most critical usage constraint (confirmation token) is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive tool with a confirmation token, the description covers the essential flow and scope. It does not mention error conditions (e.g., invalid token) or differentiate from removing items from a list, but the schema already covers parameter types. This is adequate for an AI to operate safely.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides 100% parameter descriptions, but the description adds the confirmation flow: 'call once to receive a token, then again with that token.' This clarifies how confirm_token is used and why the first call omits it, giving the agent practical guidance beyond static schema definitions. It adds value without redundancy.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a precise action: "Deletes a shopping list and everything on it." This clearly identifies both the resource and the destructive scope, distinguishing it from tools that delete individual items (e.g., delete_shopping_list_items). The two-step confirmation is a distinctive detail that sets this tool apart from other delete operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies when to use the tool (when a shopping list must be fully removed) and explains the required confirmation flow. However, it does not explicitly state when not to use it, such as when only removing individual items via a sibling tool would be appropriate. This omission leaves room for an agent to overuse the destructive delete.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false and destructiveHint=false, so description adds value by disclosing the slug regeneration side effect and the impact on existing references. This is useful behavioral context beyond the annotation defaults.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences: the first states the purpose concisely, the second adds the critical behavioral note. Every sentence earns its place with zero filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given only 3 parameters, full schema coverage, and no output schema, the description covers the key behavioral point (slug regeneration). It does not describe the return value or error conditions, but output schema is absent and importance is lower for an update tool. A 4 is appropriate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all three parameters. The description adds minimal parameter semantics beyond what the schema provides, but the clarification of 'kind' enum values and the UUID pattern in the schema is comprehensive. Baseline 3 is elevated to 4 because the schema itself is exceptionally clear.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('renames') and the three specific resources ('tag, category or tool'). It distinguishes from sibling tools like 'create_organizer' and 'delete_organizer' by specifying this tool performs a rename update, not creation or deletion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly notes a consequence of renaming—slug regeneration causing old slugs to stop matching—which guides when to use this tool versus alternatives. It does not explicitly list when not to use it or name an alternative, 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.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the tool as destructive (destructiveHint: true), so the description's job is to add context. The description clarifies that revocation is immediate ('no confirmation needed') and that the action only reduces access, which is useful behavioral insight. It does not repeat the annotation but adds nuance about the nature of the change.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, tightly written with no wasted words. The first sentence explains the action, and the second provides critical behavioral context about confirmation and access scope. Every sentence is necessary and informative.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has a single required parameter with a clear schema, annotations that cover destructiveness, and no output schema, the description is complete. It explains the effect, the lack of confirmation, and the access direction. There is nothing missing for an agent to use this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with the parameter 'token_id' described as a UUID from 'list_share_tokens'. The description does not detail the parameter further, which is acceptable since the schema is complete. The description adds no extra parameter info, but the baseline is 3 and the schema does the heavy lifting; the description's brief addition about the tool's action slightly raises the score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool revokes a share link, making the recipe no longer readable through it. It uses a specific verb ('Revokes') and resource ('share link'), and the title 'Revoke a public share link' reinforces this. This distinguishes it well from siblings like 'create_share_token' and 'list_share_tokens'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states 'Needs no confirmation', which guides the agent about the tool's immediate effect without additional steps. It also notes 'this narrows access rather than widening it', helping the agent understand the tool is about restriction, not expansion. However, it does not explicitly mention when to not use it or name alternative tools for opposite actions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With readOnlyHint=true already indicating a safe read operation, the description adds valuable behavioral detail: the response is a bare list rather than a paginated envelope, and the date calculation follows Mealie's household 'today' logic. This goes beyond the annotation's safety hint and informs the agent of response shape and timezone nuances.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is succinct at two sentences, front-loaded with the primary action, and every clause adds value: the return content, the household-specific date handling, and the response format. There is zero filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a parameterless read-only tool with no output schema, the description is complete: it states what is returned, how the date is determined, and the response shape. No additional context is needed for an agent to select and invoke this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so there is no parameter semantics to describe. The schema coverage is trivially 100% with an empty properties object. The description compensates by clarifying the tool's purpose, which is sufficient for a no-argument tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns recipes planned for today, with the specific verb 'Returns' and resource 'recipes planned for today.' It distinguishes from sibling tools like list_mealplans by focusing on today's meals specifically, and adds the nuance of how Mealie computes 'today' for the household.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does 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 today's meals) and provides context about the response format, but it does not explicitly mention alternatives or exclusions. However, the sibling list includes list_mealplans, which could be an alternative for broader queries, and the description makes the tool's specific scope clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=false and destructiveHint=false, so the description does not need to reiterate these safe mutation traits. The description adds behavioral context about the tool's direct data submission approach versus fetching, which is valuable for an AI agent. A 4 is justified as it clearly explains the key behavioral difference without needing to over-explain the obviously non-destructive nature.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, front-loading the core action in the first sentence and usage context in the second. Every word serves a purpose, no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (1 parameter, no enums, no output schema) and the presence of a complete schema description, the description fully covers when and how to use the tool. It distinguishes from siblings and provides clear guidance, leaving no gaps for an AI agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers all 1 parameter with 100% coverage, so the baseline is 3. The description mentions 'page HTML' and 'schema.org Recipe JSON document' as valid inputs, which aligns with the schema description but adds context about the purpose (direct submission). It does not provide additional format or syntax details beyond the schema, so a 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'creates' and the resource 'recipe', specifies the two input formats (HTML or schema.org JSON), and explicitly contrasts with sibling tools like import_recipe_from_url by noting it works when Mealie cannot fetch or a login is needed. This strongly distinguishes 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.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use this tool: for pages requiring a login or when import_recipe_from_url fails. It also indicates an alternative ('without Mealie fetching anything'), making the usage context clear and actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=false and destructiveHint=true, which covers the basic mutability and destructive nature. The description adds crucial behavioral context: it explains the confirmation token mechanism (call once to receive a token, then again with that token) and that the source unit is deleted. This goes beyond the annotations by detailing the workflow and the destructive effect on the source unit. However, it does not mention what happens to ingredient references if they cannot be repointed or if there are dependencies, but given the annotation coverage, the added detail is sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core action and then the critical confirmation requirement. Every word adds value; there is no filler or redundancy. It is concise yet complete for the key workflow.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (a destructive merge with a two-step confirmation), the description covers the essential workflow and parameter semantics. The schema is detailed, and annotations cover the destructive hint. However, it lacks information about error handling (e.g., what happens if the token is invalid, or if the units are already merged) and edge cases like merging a unit into itself. The absence of an output schema means the description could specify what the response contains (e.g., the token on first call), but it does not. Still, it is reasonably complete for an experienced user.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides detailed descriptions for each parameter, including the UUID patterns and the meaning of 'from_id' (deleted) and 'to_id' (kept). The description reinforces this by explaining the overall repointing and deletion process, which adds semantic clarity to the parameters. The confirm_token parameter is also clearly explained in both schema and description. With 100% schema description coverage and this additional context, the description exceeds the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the function: 'Points every ingredient that uses one unit at another one and deletes the source unit.' This is a specific verb (merge) with a clear resource (units) and explicitly describes the outcome. It distinguishes itself from the sibling 'merge_foods' by focusing on units, and the detail about deleting the source unit clarifies its scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context on how to use the tool: it requires a two-step confirmation process, which is a key usage guideline. However, it does not explicitly mention when to prefer this over alternatives like 'create_unit' or 'merge_foods', nor does it state any prerequisites (e.g., checking for existing ingredient references). The confirmation step is clear, but there is no guidance on what happens if the merge is invalid or if the units are in use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true, so the agent knows this is a safe query. The description adds important behavioral context: the tool returns nothing on plain-text ingredient collections, and the ranking is by 'how little is missing.' This exceeds what annotations provide. A score of 5 would require additional details like pagination or return format.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences long with no wasted words. Each sentence serves a distinct purpose: stating what the tool does, defining prerequisites, and providing an alternative. It is front-loaded with the core action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the 5 parameters (all optional), 80% schema coverage, no output schema, and the complexity of ranking logic, the description adequately covers what an agent needs to know to decide when and how to invoke this tool. The prerequisites and alternative are clearly stated.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 80%, and the description mostly explains the overall function rather than each parameter. It mentions that foods and tools come from the pantry, which aligns with the schema, but doesn't elaborate on 'max_missing_foods' or 'max_missing_tools' beyond what the schema already says. The description adds minimal parameter-level value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses specific verbs ('suggests', 'ranked by how little is missing') and clearly identifies the resource ('recipes that can be cooked from foods and tools marked as "on hand" in Mealie'). It distinguishes itself from the sibling 'search_recipes' by explaining the ranking logic and the prerequisite of structured data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when this tool is appropriate (instance with structured foods, units, and on-hand pantry) and when it is not ('on a collection of plain text ingredients it returns nothing'). It provides a clear alternative: 'Use search_recipes there.'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses key behavioral traits beyond annotations: the destructive action (deleting the source food) aligns with destructiveHint=true, and it adds the two-step confirmation token requirement. It also explains that ingredients are redirected (not just deleted). 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description consists of two sentences, front-loaded with the core action. Every word is necessary and efficient. No redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description adequately covers the two-step process and the merge action. It does not specify the return value (e.g., the token format), but the schema already defines confirm_token as a string. Given the lack of an output schema, the description provides enough context for the agent to understand the flow and expected behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear descriptions for each parameter. The description adds value by explaining the token flow ('call once to receive a token, then again with that token'), which clarifies the confirm_token parameter's role beyond the schema's static description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('points... and deletes') and clearly identifies the resource ('foods'). It explains the merge operation: redirecting ingredients from one food to another and deleting the source. This clearly distinguishes it from sibling tools like 'create_food' or 'merge_units'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states the two-step confirmation process: 'call once to receive a token, then again with that token.' This provides clear guidance on how to use the tool. It does not explicitly contrast with alternatives, but the context of merging foods is unique among siblings, making the usage intent clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description reinforces the annotation's readOnlyHint=true by stating 'Nothing is saved.' It adds behavioral context: confidence reporting, parser options (nlp vs brute), and explicitly explains why the 'openai' parser is excluded due to external data sending. No contradictions; the description enriches the annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description consists of two sentences: the first states the tool's function and effect, the second provides usage guidance. Every word is meaningful, no repetition or filler. It is front-loaded with the essential purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (2 parameters, no output schema), the description covers purpose, side effects (none), usage timing, and parser choices. It mentions confidence reporting but does not detail the output structure or how confidence is represented. While not exhaustive, it is largely complete for a parsing utility.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so both parameters are described. The description goes beyond by explaining the 'parser' enum options in practical terms (why 'openai' is not exposed) and gives an example for 'ingredients' ('e.g. "2 tbsp olive oil"'). It also hints at the output (confidence), which is not in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action: 'Splits free-text ingredient lines into quantity, unit, food and note, and reports how confident Mealie is about each part.' It specifies the resource (ingredient lines) and the outcome (parsed components plus confidence). This distinguishes it from sibling tools, which are primarily about creating, updating, or retrieving recipes and shopping lists.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Use it to check how a line will be understood before writing it to a recipe or a shopping list,' providing clear when-to-use guidance. It does not list alternative tools for when parsing is not needed (e.g., direct write tools), but the context and sibling list imply the alternatives, making the guidance useful though not exhaustive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (destructiveHint: true), it explains that recipes are kept but lose assignment, and details the confirmation mechanism. No annotation contradiction; description adds significant 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, all content earns its place: first sentence states what it does and side effect, second explains the confirmation flow. No fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and complete schema coverage, the description covers all needed behavioral aspects: action, side effects, confirmation process. No gaps remain for safe usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. Description adds value by explaining confirm_token workflow (not in schema description) and provides context for kind enum values ('free-form labels', 'primary classification'). The description could briefly clarify id format since it's a UUID.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Deletes') and resource ('tag, category or tool'), with clear scope. It distinguishes from siblings by explaining deletion behavior vs. recipe preservation, which isn't covered by other tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly describes the two-step process: first call gets a token, second call uses it for confirmation. No alternative tool is needed as deletion is unique; guidelines are complete and actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description clearly states the tool is destructive ('for good', 'requires confirmation'), which aligns with the annotations 'destructiveHint: true' and 'readOnlyHint: false'. The description adds significant value by explaining the confirmation token flow that the annotations do not cover. There is no contradiction with 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.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each with a clear purpose: first states the action, second provides an alternative, third explains the required workflow. No wasted words, and critical information is front-loaded. This is a model of concise, structured documentation for a tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no output schema, the description does not need to explain return values. The destructive nature is clear, the two-step confirmation process is explained, and the alternative sibling tool is mentioned. For a list deletion tool with two parameters, this description is complete enough for an AI agent to use it correctly and safely.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema description coverage is 100% (both parameters have descriptions). The first parameter description references the sibling tool 'get_shopping_list' for source of UUIDs, which adds context. The second parameter description explains the confirmation protocol. The description itself generally adds minimal extra parameter details beyond further clarifying the confirmation flow, keeping the score high but not a 5 since the schema already does a good job.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('removes') and a clear resource ('shopping list items'), with a definitive adverb ('for good') that establishes the permanent nature. It also explicitly distinguishes itself from the sibling tool 'update_shopping_list_items' by contrasting the 'removes' vs. 'checked' action, which is essential given the many sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use this tool (to permanently delete items) and when to use an alternative tool ('update_shopping_list_items' with 'checked=true' for ticking off). It also provides a clear two-step usage pattern: call once to get a token, then call again with that token. This is exemplary guidance for a destructive action.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that the tool is read-only (consistent with annotation), and goes beyond by detailing the exact output (version, identity components, permission flags) and their relevance to write tool success. It also contextualizes the tool as a diagnostic entry point for 403 errors, adding behavioral context not captured by the readOnlyHint annotation alone.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with zero waste. The first sentence front-loads the core reporting function, and the second adds a critical usage hint. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no parameters, no output schema, but has annotations, the description fully covers what the tool does, what it returns, and when to use it. It is complete for a simple diagnostic info tool, leaving no ambiguity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and schema coverage is trivially 100%. The description compensates by clearly explaining what the tool returns (version, identity, permissions), which is the only meaningful semantics. This goes beyond the baseline of 3 (for high coverage) or 4 (for zero params) by providing rich output context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Reports' and specifies the resources: Mealie version, identity (user, group, household), and permission flags. It also adds a diagnostic usage hint, distinguishing it from sibling tools (none of which are about system info). This is a specific and complete purpose statement.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Start here when a call fails with a 403,' providing a direct and actionable usage scenario. It also implies that checking permissions via this tool is a prerequisite for understanding write tool behavior, which helps the agent decide when to call it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
GitHub Badge
Glama performs regular codebase and documentation scans to:
- Confirm that the MCP server is working as expected.
- Confirm that there are no obvious security issues.
- Evaluate tool definition quality.
Our badge communicates server capabilities, safety, and installation instructions.
Card Badge
Copy to your README.md:
Score Badge
Copy to your README.md:
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/ni-c/mealie-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server