Mealie MCP Server
Server Quality Checklist
Latest release: v0.1.0
- Disambiguation3/5
The domain-specific tools are clearly distinct, but the generic API tool cluster (mealie_api_operation_request, mealie_api_request, mealie_api_get, mealie_api_download, mealie_api_multipart_operation_request) creates ambiguity with overlapping purposes for GET/JSON operations. Descriptions differentiate them, but an agent could easily select the wrong one.
Naming Consistency4/5Most tools follow a consistent mealie_<verb>_<object> pattern (e.g., create_shopping_list, get_recipe, delete_mealplan). Deviations include mealie_about, mealie_status, and the generic API tools that use noun-heavy or mixed naming, but these are a minority.
Tool Count2/538 tools is excessive for a recipe/meal planning server, even with external integrations and generic API passthrough. The count heavily exceeds the typical well-scoped range and dilutes the tool surface.
Completeness3/5Core workflows for recipes, shopping lists, and meal plans are largely covered, but notable gaps exist: no dedicated delete-recipe tool, no general update-recipe metadata tool, and no get-mealplan-by-id. These gaps force reliance on generic API tools or workarounds.
Average 3.5/5 across 38 of 38 tools scored. Lowest: 2.4/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 2 commits in the last 12 weeks
- No stable releases found
- 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.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add
glama.jsonto the root of your repository:{ "$schema": "https://glama.ai/mcp/schemas/server.json", "maintainers": [ "your-github-username" ] }Then . Browse examples.
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?
With no annotations, the description carries the full burden of disclosing behavioral traits. It only states the basic action ('add') but does not reveal side effects, permissions, or how optional parameters like confirmed_by_user affect behavior. This is a significant gap 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.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, making it concise, but it includes a redundant phrase 'using Mealie v3' that is already implied by the tool name. It is not overlong, but it under-specifies, earning a middle score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has four parameters, no output schema, and no annotations, the description is severely inadequate. It provides no information about return values, side effects, parameter usage, or prerequisites, making it very difficult for an agent to invoke the tool correctly.
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% and the tool description provides no information about the four parameters. The names and titles in the schema (e.g., 'Recipe Id', 'Shopping List Id') are not explained, and the tool description adds no semantic meaning to help the agent understand how to fill them.
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 uses a specific verb and resource ('Add a recipe's ingredients to a shopping list'), which clearly conveys the tool's function and distinguishes it from siblings like add_shopping_item. However, it does not explicitly mention alternative tools, so it falls short of a perfect 5.
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?
There is no guidance on when to use this tool versus alternatives. The description simply states the action without context, prerequisites, or exclusions, leaving the agent without any usage direction.
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?
With no annotations provided, the description must carry the burden of behavioral disclosure. It only says 'Return', implying a read operation, but does not describe what the response contains, whether the tool makes external API calls, how suggestions are computed, or any side effects or limitations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence and is front-loaded with the core action. However, it is under-specified: it offers no additional context or structure, making it less helpful than it could be. It is concise but falls short of being well-rounded.
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 lack of annotations, output schema, and low schema description coverage, the description is incomplete. It does not explain what 'recipe suggestions' are, what the response shape is, or how 'limit' affects the result, leaving an agent with insufficient context to invoke the tool confidently.
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 0%, and the description does not mention the 'limit' parameter at all. The schema provides a type and default, but the description should clarify that limit controls the number of suggestions returned and how it affects the output. It does not.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5Does the description clearly state what the tool does and how it differs from similar tools?
The description states the tool returns Mealie recipe suggestions, which identifies the action and resource at a high level. However, it does not explain what 'suggestions' means (e.g., random, personalized, or based on meal plans) and offers no differentiation from sibling tools like mealie_search_recipes or mealie_get_recipe.
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. There is no mention of use cases, prerequisites, or situations where another sibling tool like mealie_get_todays_meals or mealie_search_recipes would be more appropriate.
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?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions 'controlled local directory' and 'non-sensitive', offering some safety cues, but it does not explain side effects such as file overwriting, return value, authentication needs, or error handling. This leaves significant gaps for a download tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence with no redundant words, which is concise. However, it is under-specified, sacrificing necessary details for brevity, so it does not fully earn its place as a standalone guide.
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?
Despite the presence of an output schema, the description is too minimal for a generic download tool with four parameters and no annotations. It lacks information about how to construct the request, what the tool returns, or any constraints, making it incomplete for reliable invocation.
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% and the description does not explain any of the four parameters (output_name, path_params, operation_id, query_params). It only hints at the operation being a binary GET, leaving operation_id's role and other parameter usage completely implicit.
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 specifies a clear verb 'Download' and identifies the resource as a 'binary GET operation', which distinguishes it from sibling tools like mealie_api_get that likely return JSON. However, the qualifier 'non-sensitive' is vague and the exact resource is generic, preventing a 5.
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 downloading binary content from a GET endpoint, but it does not explicitly state when to use this tool over mealie_api_get or mealie_api_request, nor does it provide exclusions or alternative recommendations. The usage context is only implied, not fully articulated.
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?
With no annotations, the description carries the full burden for behavioral disclosure. It implies a read-only operation ('List') but provides no details about pagination, search behavior, response format, or any side effects. The description is too sparse to inform an agent about potential limitations or required permissions.
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 concise sentence, front-loaded with the verb and resource list. It contains no filler or redundancy. However, its brevity sacrifices essential detail, so it is near-optimal but not exceptional.
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 4 parameters, no output schema, and no annotations. The description only lists supported kinds, omitting how to use pagination/search, what the response contains, or the meaning of 'organizers'. For a list tool with these potential complexities, this is insufficient context.
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 0%, so the description must compensate. The description implies the 'kind' parameter accepts the enumerated organizer types, but it doesn't explain 'page', 'search', or 'per_page' semantics. The parameter names are conventional, but the description adds minimal value beyond what the schema already reveals.
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 specific verb ('List') and enumerates the resources covered (tags, categories, foods, units, cookbooks, comments, timeline events). This clearly identifies the tool's scope, though it doesn't explicitly differentiate from similar list tools like mealie_list_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 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. Sibling tools like mealie_list_shopping_lists and mealie_list_mealplans suggest overlapping functionality, but the description provides no exclusions or selection criteria.
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?
No annotations are present, so the description must carry the full burden. It only states 'List household shopping lists' without disclosing pagination behavior, default page sizes, or the read-only nature beyond the verb 'List'. No additional behavioral context is provided.
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, front-loaded sentence with no wasted words. While concise, it is also under-specified, but the dimension rewards efficient structure, so a 4 is appropriate for its brevity.
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?
For a simple list tool with an output schema, the description states the core purpose adequately. However, it omits any mention of pagination, which is relevant given the page/per_page parameters. The output schema covers return values, so the description is minimally complete but lacks richer context for effective use.
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?
The schema has 0% description coverage for parameters. The description does not mention 'page' or 'per_page', leaving the parameter semantics entirely to the schema. Since schema coverage is low, the description should compensate, but it does not.
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 action (List) and the resource (household shopping lists), making it distinguishable from siblings like mealie_get_shopping_list (single list) and mealie_list_shopping_items (items). However, it does not explicitly differentiate from these alternatives, which is a minor gap.
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, nor does it mention pagination or any prerequisites. There is no context about typical use cases or exclusions.
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?
With no annotations provided, the description must disclose behavioral traits itself. It only mentions 'full-model PUT endpoint', which implies replacement but does not explain side effects, required fields, or the meaning of 'confirmed_by_user'. This leaves significant ambiguity.
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 with no redundancy. It is appropriately short, though it sacrifices necessary detail.
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 mutation tool with a complex nested 'updates' parameter and no annotations, the description is far too sparse. It does not cover parameter structure, usage context, or behavioral implications, leaving an AI agent under-equipped to invoke it correctly.
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% and the description provides no meaning for item_id, updates, or confirmed_by_user. The 'updates' object is free-form (additionalProperties true), making it especially ambiguous without further explanation.
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 ('Update') and the resource ('shopping item'), distinguishing it from sibling tools like add/get/delete. It also notes the specific API endpoint (PUT), adding precision.
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 guidance on when to use this tool versus alternatives such as add or get. It does not mention prerequisites, exclusions, or scenarios where a different tool would be more appropriate.
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 discloses that the tool is authenticated and validates requests against the live OpenAPI and security tags, which is useful behavioral context. However, it does not describe response handling, error behavior, or whether redirects are followed. With no annotations, more detail would be expected.
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, front-loaded sentence with no filler words. It conveys the core message efficiently, though it is under-specified in other dimensions.
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 simplicity, one might expect more context about what paths are valid and how params are used. There is no output schema, and the description is too sparse for an agent to reliably construct requests. The presence of many sibling tools makes the role of this generic tool less obvious.
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?
The description does not explain the 'path' or 'params' parameters beyond what the schema already shows. Since schema description coverage is 0%, the description was expected to compensate by clarifying the format (e.g., is path a URL fragment? are params query parameters?), but it does not.
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 identifies the tool as a generic authenticated GET request, using a specific verb and resource (Mealie API). It distinguishes itself from specific sibling tools like mealie_get_recipe by being generic, and from other API tools like mealie_api_request by explicitly stating 'GET'. However, it does not elaborate on the intended use case beyond being a catch-all.
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 sibling alternatives like mealie_api_request or mealie_api_operation_request. The description only states what the tool is, not when to choose it over other 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?
With no annotations, the description carries the full disclosure burden. It discloses that operations are 'non-sensitive' and that mutations require explicit confirmation, adding useful behavioral context. However, it omits details on response format, error handling, and authentication requirements.
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?
Two sentences, front-loaded purpose, and no redundant wording. It earns a 4 because it is concise but could benefit from clarifying the term 'non-sensitive' or adding a brief example.
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 is a generic multipart operation executor with no annotations, no output schema, and 0% schema description coverage, this description is insufficient. It does not explain how to discover operation IDs, what the response looks like, or what errors may occur, making it unsafe for an agent to invoke correctly.
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 0%, so the description must explain all parameters. It only clarifies 'file_sources' (maps field names to URLs/paths) and 'confirmed_by_user' (via mutation confirmation requirement). The remaining parameters (operation_id, fields, path_params, query_params) are left undefined.
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?
Description states it 'Execute a non-sensitive multipart Mealie operation by OpenAPI operation ID', which is a specific verb+resource scope. However, it does not distinguish from its sibling tool 'mealie_api_operation_request', which likely serves the same purpose for non-multipart operations.
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 explicit guidance on when to use this tool versus alternatives. It implies usage for multipart operations and notes mutations require confirmation, but does not mention when not to use or provide alternative tool names.
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?
With no annotations provided, the description carries the full burden of disclosing behavioral traits, but it only mentions support for queryFilter syntax. It does not disclose whether the operation is read-only, how pagination behaves, or potential side effects. The sparse description leaves the agent without crucial 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 two concise sentences with no filler. It front-loads the primary purpose and adds a key feature (queryFilter syntax) in a compact manner. Every word earns its place, making it an excellent example of minimalistic structure.
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?
Despite having an output schema, the description is insufficient for a tool with six parameters, no annotations, and many sibling tools. It lacks context about pagination, ordering, default behavior, or how this search differs from other recipe-related tools. The description feels incomplete for the complexity involved.
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 compensate by explaining parameter meanings, but it does not. The six parameters (page, search, order_by, per_page, query_filter, order_direction) are not mentioned or described. The only hint is the reference to 'queryFilter syntax,' which is too vague to understand the query_filter parameter's format or usage.
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 function with a specific verb and resource: 'Search Mealie recipes.' It also distinguishes itself from sibling tools like mealie_get_recipe or mealie_search_chefkoch by specifying 'Mealie' and mentioning 'queryFilter syntax' for advanced filtering.
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 explicit guidance on when to use this tool versus alternatives. It does not mention exclusions, prerequisites, or when to prefer another search tool like mealie_search_chefkoch. The intended usage is implied as a general search, but no concrete direction is given.
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?
With no annotations, the description carries the full burden of behavioral disclosure. It adds the date format requirement, which is useful, but does not mention potential side effects (e.g., duplicate handling), required permissions, or what happens on creation. The output schema may cover return values, but the description provides minimal behavioral context beyond 'create'.
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 and front-loads the core purpose. Both sentences add value: the first identifies the action, the second provides a crucial constraint. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has six parameters, no annotations, and zero schema descriptions, the description is severely incomplete. It only addresses purpose and date format, leaving the behavior and semantics of the other parameters undefined. Even with an output schema, this is not enough to guide correct invocation.
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 compensate for the six parameters. It only explains the 'date' format, leaving text, title, recipe_id, entry_type, and confirmed_by_user entirely unexplained. This is a significant gap for a tool with multiple parameters.
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 ('Create a household mealplan entry') and identifies the resource (mealplan entry). It distinguishes from sibling tools like mealie_update_mealplan and mealie_delete_mealplan by specifying creation, and adds a specific constraint for the date format.
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 creating new mealplan entries but does not explicitly state when to use this tool versus alternatives (e.g., updating or deleting). It does provide a critical usage requirement (ISO date format), which adds some guidance, but lacks exclusions or alternative context.
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?
With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions 'full-model PUT endpoint,' which hints at full replacement semantics, but does not explain the implications (e.g., whether missing fields are reset, or that the entire object is sent). It also omits any side effects, permission requirements, or the purpose of the confirmed_by_user parameter.
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, front-loaded sentence that efficiently states the action and key technical detail (PUT endpoint). It avoids verbosity, though it sacrifices completeness for brevity.
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 a nested 'updates' object and a confirmation parameter, but the description gives no guidance on constructing the updates payload, the role of confirmed_by_user, or the behavior of the PUT operation. Given the absence of annotations and parameter descriptions, the description is insufficient for an agent to invoke it correctly.
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%, and the description provides no explanation of any parameters. The 'updates' object is ambiguous without guidance on whether it is partial or full-model, and 'confirmed_by_user' is unexplained. The description fails to compensate for the lack of 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 identifies the action ('Update a mealplan entry') and the resource ('mealplan entry'), and it distinguishes itself from sibling tools like mealie_create_mealplan and mealie_delete_mealplan. Mentioning Mealie v3's full-model PUT endpoint adds specificity that separates it from generic API request 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 implies usage for modifying existing mealplan entries, but it does not explicitly state when to use this tool over alternatives like the generic mealie_api_request tools. It does hint that a full-model PUT is required, which provides some usage context, but lacks explicit exclusions or alternative recommendations.
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?
With no annotations provided, the description carries the full burden of behavioral disclosure. It only states the core action and does not disclose the meaning of the 'confirmed_by_user' parameter, whether duplication creates a new recipe or modifies the original, or any side effects. This is a significant gap 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 a single, well-structured sentence that is front-loaded with the primary action. It contains no extraneous content and is easy to parse.
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 has 3 parameters, no annotations, and no output schema, the description is insufficient. It does not explain the full behavior, the significance of 'confirmed_by_user', or how the duplication is performed. This would leave an agent uncertain about the tool's side effects and prerequisites.
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 0%, so the description must compensate. It adds meaning for 'new_name' by stating it is optional and assigns a new name, but it leaves 'slug_or_id' and 'confirmed_by_user' unexplained. The tool name hints at slug_or_id's role, but the description fails to clarify the confirmation 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 clearly states the action 'Duplicate a recipe' with a specific resource and an optional parameter. It distinguishes from all sibling tools, as no other tool mentions duplication. The verb 'Duplicate' is specific 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 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 create_recipe_from_url or create_recipe_from_text. It does not mention prerequisites, exclusions, or context in which duplication is appropriate.
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?
There are no annotations, so the description must disclose behavior. It reveals that the upload uses multipart and targets an existing recipe, but it does not explain side effects, required permissions, overwrite behavior, or failure modes. The term 'real file asset' hints that it expects actual file data, but lacks depth.
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, front-loaded with the key action and target. Every word contributes to clarity, with no redundant information.
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 five parameters, zero schema descriptions, and no annotations, this one-sentence description is insufficient. It doesn't explain how to construct the multipart request, what the parameters mean, or what the expected response is. An agent would struggle to use this tool correctly.
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 0%, yet the description does not explain any parameters. It implies slug_or_id identifies the recipe and asset_source is the file, but asset_name, icon, and confirmed_by_user remain unexplained. This leaves the agent guessing about required formats and 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 uses a specific verb 'Upload' and identifies the resource as 'a real file asset to an existing recipe via multipart.' This clearly states the tool's function and distinguishes it from sibling tools like mealie_update_recipe_image which targets images specifically.
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 usage guidance is provided. The description does not mention when to prefer this over alternatives (e.g., mealie_update_recipe_image) or any prerequisites. The only implied usage is for uploading file assets to recipes.
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?
No annotations are provided, and the description only adds that the information is 'public'. It does not disclose response details, potential errors, or any behavioral traits. Minimal value beyond the name.
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, front-loaded sentence that directly states the purpose. No wasted words 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?
The tool is simple with no parameters and has an output schema, so the description does not need to explain return values. The description sufficiently defines the scope for a basic 'about' endpoint.
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 the baseline score is 4. The description does not need to explain parameters, and the empty schema confirms none are required.
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 uses a specific verb ('Return') and identifies the resource ('public Mealie app/version information'). It is clear, but it does not explicitly distinguish from sibling 'mealie_status', which may serve a similar purpose.
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 about when to use this tool versus alternatives like mealie_status or mealie_api_request. The word 'public' hints at usage, but there is no explicit context or exclusion.
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?
With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions the need for user confirmation but does not explain what happens if confirmed_by_user is false, whether the operation is destructive or reversible, or any side effects. This is minimal transparency 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 a single, efficient sentence that front-loads the core action. Every word earns its place, and there is no redundant information.
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?
Despite having an output schema (so return values need no explanation), the description is incomplete for a tool with two parameters and zero schema descriptions. It lacks necessary details about parameter usage, the confirmation requirement, and how this creation tool fits with sibling operations, leaving significant gaps for an agent to safely invoke it.
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 0%, so the description must compensate. It only hints at the confirmed_by_user parameter through 'explicit user confirmation', but it does not explain the name parameter or the semantics of the boolean flag (e.g., must be true, default false). It adds little 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 ('Create') and resource ('shopping list'), clearly indicating the tool's action. It also distinguishes itself from siblings like mealie_add_shopping_item and mealie_get_shopping_list by focusing on creation, and the nuance 'after explicit user confirmation' adds a unique behavioral 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 only after explicit user confirmation, which is a clear contextual signal. However, it does not explicitly mention when not to use it or compare it to alternatives such as adding items to an existing list, leaving the guidance somewhat implicit.
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?
With no annotations provided, the description carries the full burden of behavioral disclosure. It only mentions date format, but fails to disclose pagination behavior (page, per_page), default date ranges, or return value shape. This leaves significant unknowns about how the tool behaves when invoked.
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 and wastes no words. It leads with the core purpose ('List household meal plans') and adds a relevant note about date format, making it efficiently front-loaded.
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?
Although an output schema exists (reducing the need to describe return values), the description omits essential context about pagination and date filtering semantics. With 4 optional parameters and no annotations, this under-specification makes it difficult for the agent to select and calibrate the call correctly.
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 0%, so the description must compensate for the 4 parameters. It adds meaning only to start_date and end_date by specifying 'ISO yyyy-mm-dd strings,' but says nothing about page or per_page, their defaults, or their interaction. This minimal compensation is inadequate 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 uses a specific verb 'List' and identifies the resource 'household meal plans,' clearly indicating the tool enumerates meal plans. This distinguishes it from siblings like mealie_get_todays_meals (which retrieves a specific day's meals) and create/update/delete actions.
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 usage context is implied by the name and basic purpose, but the description does not explicitly state when to use this tool versus alternatives like mealie_get_todays_meals or mealie_list_shopping_lists. No exclusions or alternative tool references are provided, leaving the agent to infer applicability.
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?
With no annotations provided, the description carries the full burden of behavioral disclosure. It only states the action 'set' without revealing side effects (e.g., overwrites the existing timestamp), the meaning of the 'confirmed_by_user' parameter, or any authentication or prerequisite requirements. This is a mutation tool with minimal behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence of 12 words. It is front-loaded with the action and includes the essential format detail. Every word earns its place, with no redundancy or unnecessary elaboration.
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 write operation with 3 parameters, no output schema, and no annotations, the description is too sparse. It does not explain the effect of the 'confirmed_by_user' parameter, the behavior on existing timestamps, or what the response will be. While the tool is simple, the lack of behavioral and parameter detail makes it incomplete for an agent to invoke correctly with confidence.
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 0%, so the description must compensate. It adds the ISO 8601 date-time format for the 'timestamp' parameter, which is valuable. However, it provides no explanation for 'slug_or_id' or 'confirmed_by_user', leaving most parameters under-explained. The partial compensation is insufficient for a 3-parameter 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 a specific action: 'Set a recipe's last-made timestamp using an ISO 8601 date-time.' It identifies the verb (set), the resource (recipe's last-made timestamp), and a key format constraint. This distinguishes it from sibling tools like mealie_get_recipe or mealie_update_recipe_ingredients.
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 need to mark a recipe as made, this tool is appropriate. However, it does not explicitly state when to use it versus alternatives or provide any exclusions or prerequisites. There are no competing tools that perform the same action, so the implied usage is sufficient but not explicitly guided.
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?
With no annotations, the description carries the full burden for behavioral disclosure. It only states that it fetches a shopping list by id, but does not disclose whether the response includes items, how errors are handled (e.g., 404 if not found), or any permission requirements. Reads more like a tautological statement of the tool's function.
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, front-loaded sentence with no unnecessary words or repetition. It communicates the essential action, target, and method efficiently.
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?
For a simple single-parameter fetch tool with an output schema, the description is adequate but leaves some ambiguity about the scope of the returned object (e.g., full list with items versus metadata only). It does not reference sibling tools like list_shopping_lists to set expectations, and it lacks any detail about when to use this tool in a broader workflow.
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?
The input schema has 0% description coverage, and the description does not elaborate on the shopping_list_id parameter beyond confirming it is the identifier used to fetch the list. The parameter name and title make it somewhat self-explanatory, but the description adds no format, type details, or examples, so it does not fully compensate for the schema's lack of 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 uses a specific verb 'Fetch' with a specific resource 'household shopping list' and identifies the lookup method 'by id'. This clearly differentiates it from sibling tools like mealie_list_shopping_lists (which fetches multiple) and mealie_get_shopping_item (which fetches an item).
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 should be used when you have a specific shopping_list_id, but it does not explicitly state when to use it versus alternatives like mealie_list_shopping_lists or mealie_get_shopping_item. There is no '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.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It adds the context of 'explicit confirmation', suggesting that the tool expects a user confirmation to proceed, which is useful. However, it does not disclose what happens if confirmation is not given, whether deletion is permanent, or any permission requirements, leaving significant gaps.
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 direct and front-loaded with the primary action. It contains no fluff or redundant information, making it highly concise and well-structured.
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 this is a delete tool with a safety confirmation parameter and no annotations, the description is somewhat incomplete. It does not explain the purpose of confirmed_by_user or the likely failure mode when confirmation is not provided. However, the presence of an output schema reduces the burden for return-value explanation, and the tool's simplicity keeps the overall completeness at a minimum viable level.
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 0%, meaning the description must compensate for the lack of parameter explanations. The description mentions 'explicit confirmation' which hints at the confirmed_by_user parameter, but it does not explain item_id or the exact semantics of confirmed_by_user (e.g., must be true to delete). Parameter names are somewhat self-explanatory, but the description adds minimal value beyond the schema itself.
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 ('Delete') and the target resource ('a mealplan entry'), using a specific verb and object. It distinguishes itself from sibling tools like mealie_delete_shopping_item by specifying 'mealplan entry'. The addition of 'after explicit confirmation' also hints at a safety requirement, making the purpose even clearer.
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 phrase 'after explicit confirmation' implies a prerequisite (user must confirm before deletion), but it does not explicitly state when to use this tool versus alternatives or mention any exclusions. It provides minimal context on usage conditions, but no clear guidance on alternatives like mealie_update_mealplan or mealie_create_mealplan.
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?
With no annotations provided, the description carries the full burden. It discloses the key behavioral requirement of user confirmation, which is valuable. However, it does not mention side effects, the need for the shopping list to exist, or the nature of the response beyond what the output schema might indicate.
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, well-structured sentence that is front-loaded with the core action and adds a necessary context clue. No wasted words.
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 tool with six parameters and no annotations, the description is overly terse. It does not clarify what 'display' refers to, how to specify the shopping list, or the meaning of 'quantity', 'note', and 'checked'. The existence of an output schema mitigates return-value concerns, but the input side remains under-specified.
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?
The schema has 0% description coverage, leaving all parameter explanation to the description. The description only indirectly hints at the 'confirmed_by_user' parameter via 'explicit user confirmation' but says nothing about 'shopping_list_id', 'display', 'quantity', 'note', or 'checked'. This is insufficient for a tool with six parameters.
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 function: 'Add an item to a shopping list' with a specific verb and resource. It also includes a qualifier 'after explicit user confirmation,' which distinguishes this from similar shopping-list tools like update or delete.
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 phrase 'after explicit user confirmation' provides clear guidance on when the tool should be invoked—only after user confirmation. It does not explicitly name alternatives, but the context is sufficient for an agent to know not to use it without confirmation.
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?
With no annotations, the description carries full burden for behavioral disclosure. It reveals important constraints: only non-sensitive paths, and non-GET methods need explicit confirmation and mutation scope. However, it lacks details on error behavior, response format, or what happens on sensitive paths, leaving significant gaps for a generic API 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?
Two sentences with front-loaded purpose and immediately useful safety/alternative guidance. Every sentence contributes essential information, 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?
For a generic API request tool with no output schema or annotations, the description covers key safety constraints but omits practical details like how to construct paths, what 'non-sensitive' means, or error handling. It is adequate for a low-level tool but not comprehensive.
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 0%, so the description must compensate. It indirectly explains 'method' (non-GET implies method) and 'confirmed_by_user' (explicit confirmation), but provides no meaning for 'body', 'params', or 'path' beyond their names. Two of five parameters are partially addressed, which is insufficient.
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 this is a generic JSON API request for non-sensitive paths, providing a specific verb ('request') and resource. It also distinguishes itself from the sibling tool mealie_api_operation_request by noting the latter is preferred for validation. However, it doesn't fully specify the range of operations (e.g., CRUD) or what makes paths sensitive.
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 to prefer mealie_api_operation_request for validation and states that non-GET methods require user confirmation and mutation scope. This gives clear when-to-use and when-not-to-use guidance, addressing both alternatives and prerequisites.
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?
No annotations are provided, so the description must disclose behavior. It adds the requirement of explicit confirmation, which is a behavioral gate not implied by the schema. But it lacks details on side effects, error conditions, or what happens without confirmation.
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, front-loaded sentence with no wasted words. It conveys the core action and a key condition without fluff.
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?
Despite having an output schema, the description is minimal for a tool with 4 parameters and no annotations. It does not differentiate among sibling tools or explain the full parameter set, making it insufficient for reliable selection and invocation.
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 0%, so the description must compensate. It provides meaning for 'url' (public web URL) and 'confirmed_by_user' (explicit confirmation), but says nothing about include_tags or include_categories, leaving these parameters unexplained.
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 'Import/create a recipe from a public web URL', which is a specific verb (import/create), resource (recipe), and scope (public web URL). It distinguishes from sibling tools like create_recipe_from_text by specifying the URL source.
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 phrase 'after explicit confirmation' gives a clear condition for use, and 'public web URL' implies the scope. However, it does not explicitly name alternatives or exclusions beyond the confirmation requirement.
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?
With no annotations, the description carries the burden of disclosing behavior. The verb 'Fetch' clearly indicates a non-mutating read operation, which is useful. However, it does not detail response format, errors, or permissions, though the presence of an output schema mitigates this. It adds minimal context beyond the verb.
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 six words, with no filler or redundancy. It front-loads the verb and resource, making it immediately clear what the tool does.
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 one-parameter fetch tool with an output schema, the description is sufficient to understand purpose and invocation. It specifies the object (household shopping list item) and criterion (id). It could mention potential errors or prerequisites, but such details are not essential for this straightforward operation.
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?
The schema provides no parameter descriptions (0% coverage), so the description must compensate. It states 'by id', which clarifies that item_id is the identifier, but adds little beyond the parameter name. It does not specify format, source, or how to obtain the ID, leaving a 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 uses the specific verb 'Fetch' and identifies the resource as 'one household shopping list item by id', clearly distinguishing this from sibling tools like mealie_get_shopping_list (list) and mutation tools. It precisely states what the tool does in a single sentence.
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 an item_id to fetch a specific item, but does not explicitly mention when to use this versus alternatives like mealie_get_shopping_list or list_shopping_items. No exclusion 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.
- Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of behavioral disclosure. It communicates the destructive nature ('Delete') and the requirement for explicit confirmation, which is valuable. However, it does not disclose irreversibility, permission needs, or what happens if confirmation is false. The description adds some transparency but could be richer for a destructive operation.
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, front-loaded sentence with no filler. Every word earns its place, making it highly concise and well-structured for quick comprehension.
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 simplicity of the tool (two parameters, one required) and the presence of an output schema, the description is adequate but not complete. It covers the core action and the confirmation gate, but lacks details on parameter semantics and the behavioral rules for the confirmation flag (e.g., what happens if false). No return-value explanation is needed because an output schema exists.
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 0%, so the description must compensate. It only hints at the confirmation parameter ('after explicit confirmation') but does not name confirmed_by_user or explain that slug_or_id is the recipe identifier. The schema itself provides only types and required status, leaving the meaning of parameters underspecified. This is a clear 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 the action (Delete), the resource (recipe cover image), and a key condition (after explicit confirmation). This distinguishes it from sibling tools like mealie_update_recipe_image and mealie_upload_recipe_asset, which perform different operations on the same resource.
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 clear context: this is for deleting a recipe cover image, and it must be explicitly confirmed. It does not explicitly mention alternatives or exclusionary conditions, but the purpose is scoped enough that an agent can infer when to use this tool versus update/upload. No direct reference to sibling tools is given, so it misses the top score for explicit guidance.
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 verb 'Fetch' implies a non-destructive read operation, which is the main behavioral trait. However, with no annotations provided, the description does not disclose error behavior, authentication needs, or any additional constraints, leaving the agent to infer from the tool name and 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 a single concise sentence with no redundant information, front-loading the core purpose and parameter semantics effectively.
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 one-parameter fetch tool, the description is sufficiently complete. It clearly states what it does and how to identify the recipe, and the presence of an output schema covers return values. It lacks notes on edge cases or usage scenarios, but these are not critical for this simple operation.
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 0% for the single parameter, but the description explicitly explains that the identifier can be either a slug or an id, adding meaning beyond the schema's property name 'slug_or_id'. This clarifies the parameter's accepted values.
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 'Fetch one recipe by slug or id' uses a specific verb (Fetch), resource (one recipe), and identifier (slug or id), clearly distinguishing it from sibling tools like mealie_search_recipes or mealie_get_todays_meals.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
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. The description does not mention that this is the preferred tool for retrieving a single recipe when the slug or id is known, nor does it compare it to search or list 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?
With no annotations provided, the description carries the burden of disclosing behavior. It implies a read-only 'List' operation and mentions filter options, but it doesn't disclose pagination behavior (page/per_page) or potential output size limits. For a simple listing tool, this is adequate 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?
A single, well-structured sentence delivers all the core information: what it lists and the optional filters. No wasted words, ideal conciseness.
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 is relatively simple, has an output schema, and no nested objects. However, given no annotations and missing pagination description, the tool is adequate but incomplete for an agent that might need to handle large result sets. More detail on pagination or result set behavior would improve completeness.
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 0%, so the description must compensate. It explains 'shopping list' and 'checked' filters, but completely omits 'page' and 'per_page', which are important for pagination. Thus it only partially explains the 4 parameters, leaving half undocumented in both schema and 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 clearly states the verb 'List' and the resource 'shopping list items', with optional filters by shopping list and checked state. This distinguishes it from sibling tools like 'mealie_get_shopping_list' (which retrieves a whole list) and 'mealie_get_shopping_item' (singular item), making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for when to use this tool—when listing shopping list items—and mentions optional filtering capabilities. It doesn't explicitly name alternatives or exclusionary conditions, but the usage context is clear enough for an agent to select it appropriately among siblings.
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?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the destructive nature ('Delete') and adds the confirmation requirement, but it does not mention permanence, error handling, or side effects, which are important for a delete operation.
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 concise sentence that communicates the core purpose and key condition without any redundant information.
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 is simple, has an output schema, and the description covers the basic purpose. However, the relationship between 'explicit confirmation' and the confirmed_by_user parameter is ambiguous, and there is no guidance on what happens if confirmation is not provided. This leaves a gap for correct 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?
The schema has 0% description coverage. The description's 'after explicit confirmation' indirectly hints at the confirmed_by_user parameter, but it does not explain that the parameter must be set to true, nor does it clarify item_id beyond what the self-explanatory parameter name suggests.
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 'Delete' and the resource 'one shopping list item', and adds the condition 'after explicit confirmation'. This distinguishes it from sibling tools like mealie_add_shopping_item or mealie_update_shopping_item.
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 phrase 'after explicit confirmation' provides a clear usage prerequisite: only call the tool when the user has confirmed the deletion. However, it does not explicitly mention alternatives or cases where deletion should be avoided.
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 no annotations provided, the description carries the full burden. It discloses that the tool only handles non-sensitive JSON operations, that mutations need explicit confirmation via the confirmed_by_user parameter, and that mutations are restricted by a scope environment variable. It does not mention return format or error handling, but for a generic low-level operation request tool this covers the critical behavioral aspects.
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 carrying distinct value: the core purpose, the prerequisite discovery step, and the safety/scope constraints. It is front-loaded with the primary action and avoids redundancy or filler.
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 adequately covers the tool's generic purpose and safety constraints, but with five parameters and no output schema, it leaves gaps around parameter syntax and expected return values. For a low-level generic tool, the key usage context is present, but the lack of parameter semantics keeps it from being fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description provides no explanation of any of the five parameters (operation_id, body, path_params, query_params, confirmed_by_user). While the parameter names are somewhat self-explanatory, the description does not compensate for the complete lack of schema documentation, especially the meaning and interaction of confirmed_by_user and the params objects.
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 function: executing a non-sensitive JSON Mealie operation by OpenAPI operation ID. It uses a specific verb ('Execute') and identifies the resource ('Mealie operation'), while explicitly distinguishing this from multipart/binary operations that require a dedicated tool.
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 gives explicit usage guidance: 'Use mealie_api_operations first' to discover operation IDs. It also notes that mutations require explicit confirmation and are restricted by MEALIE_MCP_MUTATION_SCOPE, and that multipart/binary operations are out of scope. This provides clear when-to-use and when-not-to-use context relative to siblings.
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?
With no annotations provided, the description carries the full burden. It discloses the return data (ingredients, instructions, times, etc.) and notes that nutritional values are only 'falls vorhanden' (if available), but it does not mention network access, authentication, error handling, or whether the operation is strictly read-only. The basic retrieval behavior is implied but not fully specified.
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, front-loaded with the main purpose, and contains no redundant information. Every sentence contributes to understanding the tool's function and usage.
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 one-parameter getter, the description is fairly complete: it states the return data, the condition of data availability, and the intended downstream use (display/import). An output schema exists, so return details are not strictly necessary. It could mention error handling or prerequisites, but overall it covers the essential context.
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 schema has one required 'url' parameter with no description (0% coverage), and the tool description does not explicitly explain this parameter. However, the tool name and the recipe context make it evident that the URL points to a Chefkoch recipe. The description adds little beyond this inference, so it only partially compensates 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 states the action clearly: 'Rufe ein vollstaendiges Chefkoch-Rezept mit allen Details ab' (retrieve a complete Chefkoch recipe with all details). It specifies the resource (Chefkoch recipe) and lists the included data (ingredients, steps, time, category, rating, nutrition), distinguishing it from sibling tools like mealie_get_recipe (Mealie recipes) and mealie_search_chefkoch (search).
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 the tool by stating that the bot uses the data to display the recipe or import it into Mealie. However, it doesn't explicitly contrast with alternatives such as mealie_get_recipe or mealie_create_recipe_from_url, nor does it state any 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?
With no annotations, the description carries the full burden. 'Fetch' clearly indicates a read-only operation, and 'today's household meal plan entries' adds scoping. However, it does not explicitly mention the absence of side effects, return format, or any potential edge cases (e.g., empty results), so it provides only basic behavioral clarity.
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 concise sentence, front-loaded with the action ('Fetch') and the resource. It wastes no words and is immediately scannable for an agent.
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 zero-parameter read-only tool, the description is sufficiently complete. It names the resource and timeframe, and given the absence of an output schema, the description provides enough context for an agent to know what the tool returns conceptually. It could be slightly richer to mention the distinction from list_mealplans, but overall it is adequate.
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 the schema is trivially complete. The description correctly avoids inventing parameters, and there is nothing meaningful to add beyond the schema. Baseline for 0 params is 4, and the description does not undermine this.
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 'Fetch' and clearly identifies the resource (today's household meal plan entries), distinguishing it from siblings like mealie_list_mealplans (which presumably covers all dates) and the create/update/delete mealplan tools. The scope is explicit with 'today's household'.
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 word 'today's' implies the intended use case, but the description does not explicitly state when to use this tool over alternatives like mealie_list_mealplans. There is no mention of exclusions or alternative tools for other date ranges, making the usage guidance only implicitly understood.
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 no annotations provided, the description carries the full burden and discloses key behavioral traits: that admin/auth/user/backup/maintenance operations are hidden by default and remain documentation-only even with include_sensitive=True. This adds meaningful context beyond the schema and is a valuable transparency note.
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, front-loaded with the main purpose, followed by return contents and the sensitivity caveat. Every sentence earns its place; no redundant or filler language.
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 tool has an output schema, so detailed return formatting need not be in the description. The description covers core behavior (search a live catalog, return metadata) and the important sensitive-ops nuance. It is sufficiently complete for a catalog search tool with optional filters, though it could briefly mention how 'limit' and 'query' interact.
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 schema has 5 parameters with 0% description coverage, so the description must compensate. It explains the include_sensitive parameter's effect (hidden operations remain documentation-only), but does not explain tag, limit, query, or method. These parameter names are relatively self-explanatory, but the description adds only partial compensation.
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 'Search' and resource 'live Mealie OpenAPI operation catalog', immediately clarifying the tool's function. It lists returned fields (operation IDs, methods, paths, tags, parameters, content types), distinguishing it from sibling tools that execute operations rather than discover 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 clearly implies the catalog is for discovering operations (returns operation IDs) and gives context that sensitive ops are hidden by default. However, it does not explicitly name alternatives like 'mealie_api_operation_request' or state when to use this discovery tool before invoking an operation, so it lacks explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
- Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It openly describes the preprocessing steps (grayscale, contrast, binarization) and that the output is raw, unstructured text. This goes beyond a simple 'extracts text' statement and gives the agent a clear picture 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?
The description is concise, front-loaded with the main purpose, and uses efficient formatting (dashes for preprocessing steps). Every sentence adds value: the workflow, the preprocessing detail, and the cost-saving motivation. 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?
Given the tool's moderate complexity (image loading, OCR, preprocessing) and the presence of an output schema, the description sufficiently covers the key aspects: what it does, how it works, and its role in a larger recipe-import pipeline. It lacks only minor details like supported image formats or explicit error behavior, but overall it is complete enough 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 0%, so the description must compensate. It implicitly explains the primary parameter image_url by stating the tool loads images from a URL or local path. However, it completely omits any explanation of the ocr_lang parameter (default 'deu+eng'), leaving half the parameters without added meaning.
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 starts with a clear, specific verb+resource: 'OCR: Extrahiere Rohtext aus einem Kochbuchfoto/Screenshot' (extract raw text from a cookbook photo/screenshot). This unambiguously states what the tool does and differentiates it from sibling tools like mealie_create_recipe_from_text or mealie_create_recipe_from_url, which handle structured text or URL-based recipe retrieval.
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 clear usage context: it explains the workflow (extract raw text → structure with a text LLM → import with mealie_create_recipe_from_text) and mentions the cost-saving benefit ('spart teure Vision-API-Aufrufe'). This implies when to use it, though it does not explicitly list exclusions or alternatives.
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?
With no annotations provided, the description carries the full burden of behavioral disclosure. It does state that the tool returns structured results and gives an example input, which is useful. However, it does not explicitly disclose whether the operation is read-only, whether any side effects occur, error handling behavior, or rate limits. For a parse operation, this is acceptable but not fully transparent.
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 concise and well-structured. It opens with the main action, provides an illustrative example, lists output fields, and closes with a practical usage tip. Every sentence adds value; there is no fluff.
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 tool is simple (one parameter, no annotations) and has an output schema. The description explains the input format, gives an example, lists the output fields, and suggests a downstream integration. It is complete enough for an agent to use it correctly, though it could mention potential errors or edge cases for full completeness.
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 has only one parameter (ingredients) with no description, and schema description coverage is 0%. The description compensates by explicitly stating it 'Accepts a list of raw ingredient strings' and provides a concrete example. This adds meaning beyond the schema, though it does not specify constraints like list size or formatting edge cases.
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 function: 'Parse ingredient lines via Mealie's ingredient parser.' It specifies the input (list of raw ingredient strings) and the output (structured results with quantity, unit, food, note fields). This distinguishes it from sibling tools that handle updates, deletions, or other recipe operations.
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 clear context by explaining when this parser is useful: when raw ingredient strings need to be converted into structured fields. It also gives an explicit downstream integration tip: 'The parsed results can be passed directly to mealie_update_recipe_ingredients.' However, it does not explicitly mention when not to use the tool or name any alternative parser 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?
No annotations are provided, so the description carries the full burden. It honestly states the tool checks reachability and authentication, implying a read-only operation. However, it does not disclose potential failure modes, side effects (none expected), or detailed behavior, leaving room for more transparency.
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 concise sentence, front-loaded with the action verb. It contains no filler or redundant information, earning a perfect score for efficiency.
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 (zero parameters, status check), the description adequately covers the essential purpose. An output schema exists, so return format documentation is not necessary. However, it could briefly note that it is a safe read-only operation, which would make it fully 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?
The tool has zero parameters, and the input schema is an empty object. Per the baseline rule, with 0 parameters, the description does not need to add parameter-specific details, and a baseline of 4 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 uses a specific verb ('Check') and names the exact resources ('server reachability', 'authentication works'). This clearly distinguishes it from sibling tools like CRUD operations or recipe-specific tools, making it 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?
The purpose implies a diagnostic use case, but the description does not explicitly state when to prefer this tool over alternatives or mention exclusions. It gives clear context for status checking, but stops short of full guidance.
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?
No annotations are provided, so the description carries the full burden. It discloses the entire update flow: fetches current recipe, replaces ingredient list, applies update_fields, and patches via API. It also explains backward compatibility and return value (updated slug and ingredient count). However, it does not mention potential side effects like overwriting existing ingredient data or permissions needed, but the flow description covers key behavior.
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 moderately sized but well-organized: a short summary, a note on input formats, a step-by-step of the operation, and clear examples. It front-loads the core purpose and then adds necessary details. It could be slightly more concise in the raw string example, but no sentence is wasted.
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 and lack of annotations, the description covers the main aspects well: what it does, what inputs look like, how it works, and what it returns. The output schema is not provided, but the description states the return value. The main gap is not mentioning the effect on existing ingredients (it replaces them, which is implied) or any potential errors, but overall it is complete enough for an agent to use.
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 0%, so the description must compensate. It explains the 'ingredients' parameter in detail, including the required fields and optional fields, and provides example formats for both structured dicts and raw strings. It also clarifies 'update_fields' as additional fields to apply. The 'slug' and 'confirmed_by_user' parameters are not explicitly described, but they are self-explanatory from 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 function: 'Replace the ingredient list of an existing Mealie recipe with structured data.' It uses a specific verb (replace) and resource (ingredient list of a Mealie recipe), and distinguishes it from sibling tools like mealie_parse_ingredients (which parses) and mealie_update_recipe_image (which updates a different aspect).
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 when to use it (to update ingredients) and mentions integration with mealie_parse_ingredients for structured input. It doesn't explicitly state when not to use it or name alternatives, but the context is clear enough that an agent can infer the appropriate use case.
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 no annotations, the description carries the burden. It describes the operation as searching (read-only) and lists the returned fields, but does not mention rate limits or external API specifics.
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, front-loaded purpose, then details and usage. 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 output schema exists, the description provides sufficient usage context, return field examples, and points to the follow-up tool for full details. Complete.
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?
The description only indirectly covers the `query` parameter via 'Suchanfrage' but does not explain `limit`. With 0% schema description coverage, this is a 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 the tool searches Chefkoch.de for recipes and returns a list of basic info. It distinguishes from siblings like mealie_get_chefkoch_recipe by mentioning that full details are obtained separately.
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 states to use it before a Mealie import to find the right recipe, and points to mealie_get_chefkoch_recipe for full details, which serves as an alternative.
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 no annotations, the description carries the burden, and it discloses key behavioral traits: confirmation requirement, ingredient storage in display/note for mobile rendering, and the cover crop fallback chain. It doesn't detail overwrite_existing behavior, but the self-explanatory default and output schema mitigate this.
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 front-loaded with purpose and uses concise paragraph breaks for prerequisites, workflow, and crop logic. It is longer than ideal but every section covers distinct useful behavior without 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 19-param mutation tool with no annotations, the description gives enough context about prerequisites, workflow, and image handling to invoke correctly. The presence of an output schema covers return values, so the remaining gaps are minor.
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 0%, but the description explains the non-obvious parameters including confirmed_by_user, cover_crop_box, cover_crop_units, cover_crop_source_url, and source image fallback order. It leaves basic fields like cook_time and servings to their self-explanatory names, which is reasonable given the complexity.
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 specific verb and resource: 'Create a Mealie recipe from OCR/vision-extracted text and optional images.' This clearly differentiates it from sibling tools like mealie_create_recipe_from_url and describes the transformation.
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?
It explicitly states when to use: after showing a preview and getting confirmation, and requires mutations enabled AND confirmed_by_user=True. It also gives crop guidance for cookbook/photo imports, providing enough context to choose this tool over URL-based import.
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?
With no annotations provided, the description fully carries the behavioral burden. It discloses that the image is uploaded as a real multipart file, never stored as an external URL, requires explicit user confirmation, and explains crop unit semantics. This is strong transparency 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?
Four sentences, front-loaded with the exact purpose, and every sentence adds meaningful detail without redundancy. It is well-structured 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 5-parameter mutation tool with no annotations, the description covers the core workflow, prerequisites, and parameter semantics thoroughly. It does not explain return/error behavior, but an output schema exists, so that omission is acceptable.
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 0%, but the description compensates well by explaining image_source (HTTP/file/local path), crop_box format ([left, top, right, bottom]), and crop_units (percent/fraction/pixels). slug_or_id and confirmed_by_user are not explicitly detailed but are inferable from names and 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?
Purpose is stated with a specific verb and resource: 'Upload or replace the cover image of an existing Mealie recipe.' This clearly distinguishes it from sibling tools like delete_recipe_image and upload_recipe_asset.
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?
Provides clear context: existing recipe, image source types, and explicit prerequisites ('Requires mutations enabled and an explicit user confirmation'). It does not explicitly name alternatives or when-not-to-use scenarios, but the context is sufficient for selection.
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/bitmonster/mealie-mcp-server'
If you have feedback or need assistance with the MCP directory API, please join our Discord server