Gamito is a fully local, deterministic meal-planning MCP server that manages household profiles, meal plans, recipes, shopping lists, and pantry — all without cloud calls.
Profile Management
Create, retrieve, and update household profiles including name, language, allergies, dietary preferences, skill level, kitchen tools, disliked ingredients, cuisine preferences, and time constraints.
Update liked/disliked tags to refine future recommendations.
Meal Planning
Generate deterministic, budget-aware, allergy-safe weekly meal plans based on profile constraints, budget, days, servings, and meals per day (with optional max cooking time and recipe exclusions).
Retrieve plans by ID (supports 'latest' shortcut), list all saved plans (filterable by labelled/favourite status), and label plans with custom names or mark as favourites.
Regenerate plans from a previous one, incorporating ratings, keeping high-rated slots, and avoiding poorly-rated recipes.
Plan Editing
Swap individual meals using natural language queries (with optional price cap).
Rescale meal servings within a persisted plan.
Rate meals to influence future plan generation.
Shopping & Pantry
Generate shopping lists for a plan with pantry-aware "need to buy" vs. "already have" splitting.
Retrieve and update household pantry staples (with canonicalisation).
Recipe Management
Search the local recipe index with optional hard filters (profile allergies, course, max time, max price per serving).
Add, update, or delete custom household recipes with full ingredient, allergen, dietary, and cooking details.
List custom recipes with optional filters for cuisine, time, and keyword.
Data & Safety
All data (profiles, plans, ratings, pantry, recipes) is persisted in a local SQLite store.
Hard allergy/diet filters and budget constraints are strictly enforced with deterministic results.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Gamito Plan 5 dinners for 2 people on a 60 EUR budget"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Gamito Local is a fully local, deterministic meal-planning engine exposed to AI agents through the Model Context Protocol (MCP). It turns a household's profile, budget, pantry, and taste history into budget-disciplined, allergy-safe weekly meal plans, shopping lists, and meal swaps — entirely on your own machine, with no cloud calls.
The system ships in two halves that are designed to work together:
The MCP server (gamito-mcp) — 20 deterministic tools backed by a local
recipe index and a local SQLite store. All math (budgeting, pricing,
rescaling, hard allergy filters) is plain Python; nothing is left to a model.
The Agent Skill (skills/gamito/SKILL.md) — the judgment layer that
teaches an orchestrating assistant (e.g. Hermes) when to call which tool,
in what order, and how to recover from errors. The server enforces safety; the
skill supplies the workflow.
Design principle: Language understanding happens in the agent. Gamito's tools never parse free-form intent — the agent translates a request into a structured tool call, and the server returns deterministic, chat-forwardable results. The SQLite store (not conversation memory) is the single source of truth for every safety constraint.
An MCP server alone exposes tool schemas, but a model still has to guess how to sequence them safely. The paired skill closes that gap:
Layer | Responsibility |
MCP server | Deterministic execution, hard allergy/diet filters, pricing, persistence |
Skill | Identity rules, onboarding interview, tool ordering, error recovery |
This separation means allergies and dietary restrictions are enforced as hard filters in code — never as a polite request to the model — while the skill keeps the conversation coherent across planning, edits, feedback, and the household cookbook.
Related MCP server: household-agent
What the MCP + skill pairing is built to do:
Plan a week of meals — "Plan 5 dinners for 2 people on a 60 EUR budget." Generates a full plan, shopping list, and budget check in one call.
Stay allergy- and diet-safe — allergies, dislikes, and dietary preferences are stored per profile and applied as hard filters to every plan and swap.
Respect a food budget — every plan is cost-checked against the stated budget, and assignment actively targets useful budget utilization instead of simply picking the cheapest matching recipes.
Swap, rescale, and refine meals — "Make Tuesday dinner cheaper / vegan / faster" or "scale Friday up to 4 servings" without rebuilding the plan.
Generate shopping lists with pantry awareness — items are split into "need to buy" vs. "already have" using the household pantry.
Track the pantry from a photo — the agent reads long-shelf-life staples off a shelf/fridge photo; the server canonicalises and stores them.
Learn household tastes — numeric ratings and soft feedback ("less spicy next time") bias future plans toward liked recipes and away from disliked ones.
Improve a previous plan — regenerate from a source plan, automatically keeping highly-rated slots and avoiding poorly-rated ones.
Keep a household cookbook — save "mama's recipe" from text or a photo as a custom recipe that competes for slots alongside the base dataset.
Save and favourite plans — label plans ("Cheap weeknights"), mark favourites, and list them later.
Automate recurring plans — e.g. "Every Sunday 18:00, generate next week's plan and send the text to the family group."
The 20 tools span six namespaces: Profiles, Planning, Plan
Lifecycle, Edits, Shopping & Pantry, Feedback, and Recipes.
See skills/gamito/references/tool-index.md
for the full signatures and error contract.
Household / Hermes agent
│ natural language
▼
skills/gamito/SKILL.md ← judgment: when/which tool, ordering, recovery
│ structured tool calls (gamito:<tool>)
▼
gamito-mcp (FastMCP, stdio) ← 20 deterministic tools
│
├── retrieval/ fastembed + brute-force vector index (data/index/)
├── planning/ LangGraph pipeline: assign → budget → shopping → render
├── pricing/ canonical ingredient pricing
├── pantry/ canonicalisation
└── db/ SQLite store (profiles, plans, ratings, pantry, recipes)Requirements: Python 3.12+ and uv.
# 1. Clone
git clone https://github.com/nerkyzas157/gamito.git
cd gamito
# 2. Install dependencies into a local virtualenv
uv sync
# 3. Initialise the SQLite store (profiles, plans, pantry, recipes)
uv run gamito db init
# 4. Ensure data/index exists before serving requests.
# Prefer copying a prebuilt data/ directory from a workstation:
rsync -az --delete /path/to/prebuilt/gamito/data/ ./data/The index build encodes the bundled data/recipes_dataset.csv with the
BAAI/bge-small-en-v1.5 model into data/index/ (embeddings, metadata, and a
manifest). It is resumable — re-run the command to continue an interrupted
build — but it is CPU/RAM intensive enough to overwhelm a small VPS. For
low-memory hosts, build once on a stronger machine and copy the whole data/
folder to the deploy checkout instead of running the builder in production.
If you do need to rebuild locally:
uv run python scripts/build_local_index.pyuv run python scripts/seed_demo.pyPaths are overridable via environment variables:
Variable | Default | Purpose |
|
| Dataset and index root |
|
| Prebuilt retrieval index |
|
| SQLite store path |
The server speaks MCP over stdio:
uv run gamito-mcpTo register it with an MCP client (e.g. Claude Desktop, Cursor, or Hermes), add an entry like:
{
"mcpServers": {
"gamito": {
"command": "uv",
"args": ["run", "gamito-mcp"],
"cwd": "/absolute/path/to/gamito"
}
}
}Then make the skill available to the orchestrating agent by pointing it at
skills/gamito/SKILL.md. The agent calls tools by their fully-qualified name,
e.g. gamito:generate_meal_plan.
The bundled recipe corpus is derived from the public Kaggle dataset:
Extended Recipes Dataset — 64k Dishes, by Wafaa El Husseini — https://www.kaggle.com/datasets/wafaaelhusseini/extended-recipes-dataset-64k-dishes
data/recipes_dataset.csv is a salvaged, normalised subset of that source
(currently 14,619 recipes across 36 columns). At index-build time the
retrieval pipeline normalises fields (e.g. total_time → total_time_min,
list-like columns → JSON) before embedding. The committed index manifest records
the source dataset's SHA-256 for reproducibility.
Please refer to the original Kaggle dataset page for its license and terms of
use. Pricing and pantry canonicalisation rely on local lookup tables; see
data/README.md for the provenance and current status of
those auxiliary assets.
src/gamito/
retrieval/ fastembed encoder + brute-force vector index + hard filters
planning/ LangGraph plan pipeline and nodes
pricing/ canonical ingredient pricing
pantry/ ingredient canonicalisation
db/ SQLite schema, connection, and data access
models/ Pydantic models (profile, pantry, planning, meal)
rendering/ chat-forwardable text rendering (compact / full / labels)
mcp/ FastMCP app, server entry point, and the 20 tools
cli.py dev CLI (db init, custom-recipe import/list/re-embed)
skills/gamito/ Agent Skill (SKILL.md) + tool-index reference
scripts/ index build, retrieval eval, demo seed, test runner
data/ recipe dataset, prebuilt index, lookups
docs/ retrieval eval baseline
tests/ local unittest suiteGamito allocates the requested budget across meal slots before recipe assignment. Each non-leftover slot targets roughly 80% of its allocation, then combines semantic relevance with price fit so the plan stays realistic for the requested budget. To avoid cheap recipes dominating higher-budget plans, the assignment node supplements semantic retrieval results with filtered recipes ranked by closeness to the slot's target cost.
Shopping totals are estimated from canonical ingredient pricing when the local
lookup tables in data/lookups/ are available. If those lookup tables are
missing or empty, Gamito falls back to the selected recipes'
estimated_cost_total_eur values whenever ingredient-level pricing would
undercount the plan. This keeps budget summaries useful on small deploys that
ship only data/index/.
Run the local test suite:
scripts/test # or: make test
uv run python -m unittest discover -s testsEvaluate retrieval quality against the golden set:
uv run python scripts/eval_retrieval.pyThe current retrieval baseline (12-query golden set) is recorded in
docs/eval_baseline.md: 100% hard-filter integrity,
~17 ms warm p95 latency per query, and a manual precision@5 floor of 0.60.
This project follows Semantic Versioning and
Keep a Changelog; releases are managed with
Commitizen. See
CHANGELOG.md for the release history.
Save a structured household recipe and make it searchable.
| Name | Required | Description | Default |
|---|---|---|---|
| title | Yes | ||
| ingredient_names | Yes | ||
| ingredient_amounts | Yes | ||
| ingredient_units | No | ||
| directions | No | ||
| cuisines | No | ||
| courses | No | ||
| tastes | No | ||
| total_time_min | No | ||
| difficulty | No | ||
| servings | No | ||
| tools | No | ||
| dietary_flags | No | ||
| allergens | No | ||
| notes | No | ||
| added_by_profile_id | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, and the description does not disclose behavioral traits such as idempotency, return value, error handling, permissions, or rate limits. For a creation tool, critical missing information.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, which is concise, but it lacks substance for a tool with 16 parameters. It earns its place but does not add enough value; borderline under-specification.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the high complexity (16 parameters, no output schema, no annotations), the description is woefully incomplete. It does not cover required inputs, return values, validation, or interaction with sibling tools. Completely inadequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description must compensate but fails to add any meaning beyond the schema. It mentions 'structured household recipe' without explaining parameter relationships (e.g., parallel arrays for ingredients) or optional fields. The agent gets no help interpreting the many parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool saves a structured recipe and makes it searchable. The verb 'save' and resource 'recipe' are specific. However, it doesn't explicitly differentiate from 'update_recipe' or 'delete_recipe', but creation vs modification is implicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like 'update_recipe' or 'search_recipes'. No prerequisites or exclusions are mentioned, leaving the agent without context for appropriate usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a custom recipe, optionally orphaning historical plan references.
| Name | Required | Description | Default |
|---|---|---|---|
| recipe_id | Yes | ||
| force | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully bears the burden of behavioral disclosure. It only hints at orphaning behavior, but does not state deletion permanence, required permissions, effects on referenced entities, or error handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence (7 words) that front-loads the core purpose and includes optional behavior. No extraneous words or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with two parameters and no output schema or annotations, the description covers the main purpose and a key behavioral nuance. It is adequate but could include edge cases like what happens if the recipe is not found or if force is false and references exist.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds some meaning beyond the schema by mentioning historical plan references, which likely maps to the force parameter. However, the mapping is ambiguous, and since schema description coverage is 0%, the description only partially compensates.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the verb 'Delete' and the resource 'custom recipe', with the optional behavior of orphaning historical plan references. This distinguishes it from sibling tools like add_recipe or update_recipe.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions an optional behavior (orphaning references) but does not provide explicit guidance on when to use the force parameter or when to avoid deletion. No alternatives are mentioned compared to sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate and persist a deterministic meal plan.
| Name | Required | Description | Default |
|---|---|---|---|
| profile_id | Yes | ||
| budget_eur | Yes | ||
| servings | Yes | ||
| num_days | Yes | ||
| meals_per_day | Yes | ||
| max_time_min | No | ||
| exclude_recipe_ids | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description must fully disclose behavioral traits. It mentions 'persist' but does not clarify whether an existing plan is overwritten, if the plan is idempotent, or what 'deterministic' means operationally. Critical side effects and data flow are missing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is only two sentences and front-loaded, which is concise. However, it sacrifices substance for brevity; every sentence should add value but the second sentence is under-serving.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given seven parameters, no output schema, no annotations, and many sibling tools, the description is far from complete. It lacks explanation of how the meal plan relates to the profile, budget constraints, or deterministic behavior, leaving the agent without essential context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, yet the description adds no parameter information. The agent cannot infer the meaning of profile_id, budget_eur, servings, or other parameters from the description alone, making invocation error-prone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool generates and persists a meal plan. 'Generate and persist' are specific verbs, and 'deterministic' adds nuance. However, it could better distinguish from siblings like regenerate_plan by explaining how a new plan creation differs from regeneration.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus siblings such as get_meal_plan, regenerate_plan, or swap_meal. The agent has no context to decide which tool is appropriate for a given task.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return a stored meal plan, accepting plan_id='latest' with profile_id.
| Name | Required | Description | Default |
|---|---|---|---|
| plan_id | Yes | ||
| profile_id | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It declares the operation is read-only ('Return'), but does not mention side effects, authentication needs, error behavior (e.g., missing plan), or rate limits. Basic transparency is achieved, but lacks depth for edge cases.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, highly concise and front-loaded with the verb. Every word serves a purpose. However, it sacrifices completeness for brevity, which is acceptable given the tool's simplicity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given two parameters, no output schema, and no annotations, the description is minimal. It lacks details about return value format, error scenarios, and how profile_id interacts with plan_id. Sibling tools are not addressed, limiting completeness for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%. The description adds the special value 'latest' for plan_id and implies that profile_id is required when plan_id='latest', going beyond the schema. However, it does not explain other valid plan_id values or the exact role of profile_id, leaving ambiguity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description specifies the verb 'Return' and the resource 'stored meal plan', and mentions a special accepted value for plan_id ('latest'). It clearly indicates the tool's function, though it could more explicitly distinguish it from siblings like list_plans or generate_meal_plan.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives (e.g., list_plans for listing all plans, generate_meal_plan for creation). The description implies retrieval of a single stored plan, but does not state when it is appropriate to use or not use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return canonical pantry staples for a profile.
| Name | Required | Description | Default |
|---|---|---|---|
| profile_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden of behavioral disclosure. It only says 'Return,' implying a read operation, but omits details on data freshness, error conditions, permissions, or side effects. The agent learns nothing beyond the basic operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. It is appropriately brief for a simple read tool, though it could include more detail without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of annotations and output schema, the description is too sparse. It does not explain what 'canonical pantry staples' entails, does not describe the return format, and leaves the agent with incomplete context for reliable invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has one parameter (profile_id) with zero description coverage. The tool description does not elaborate on what profile_id means, how to obtain it, or its expected format. The description fails to add any semantic value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Return'), the resource ('canonical pantry staples'), and the scope ('for a profile'). This distinguishes it from sibling tools like 'update_pantry' (which modifies) and 'get_shopping_list' (different resource).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives, nor are there any prerequisites or exclusions. The description simply states what it does without contextualizing its role among sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return a full persisted profile summary.
| Name | Required | Description | Default |
|---|---|---|---|
| profile_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, and the description fails to disclose behavioral traits such as error handling (e.g., profile not found), performance, or what 'persisted profile summary' entails beyond the minimal statement.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (one sentence) but lacks structure; it does not front-load crucial information like the required parameter or any constraints.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple get tool, the description is incomplete; it does not explain the output content or any edge cases, leaving the agent with insufficient information to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single required parameter 'profile_id' has no description in the schema (0% coverage), and the tool description does not mention or explain it, leaving the agent without guidance on how to specify the profile.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Return a full persisted profile summary' clearly indicates retrieving a profile, but does not distinguish from sibling tools like list_profiles or save_profile, which could cause confusion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives, nor any prerequisites or context for using get_profile.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return a rebuilt shopping list for a persisted plan.
| Name | Required | Description | Default |
|---|---|---|---|
| plan_id | Yes | ||
| use_pantry | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description must fully disclose behavior. It only says 'return' (implying read-only) but 'rebuilt' suggests possible mutation or generation. No mention of side effects, rate limits, 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no redundancy. Could be expanded without harming conciseness, but currently efficient. Front-loaded with verb and resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 2 parameters, no output schema, and no annotations, the description is too sparse. It does not explain the output format, what 'rebuilt' entails, or how the boolean parameter affects results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must explain parameters. It references 'persisted plan' for plan_id but does not explain use_pantry (default true) or its effect. Insufficient compensation for missing schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns a shopping list for a persisted plan, specifying verb and resource. However, 'rebuilt' is ambiguous—does it mean generated or recalculated? This slight vagueness prevents a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus siblings like get_meal_plan or get_pantry. The description does not mention conditions, prerequisites, or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Attach a short label and/or favorite flag to a persisted plan.
| Name | Required | Description | Default |
|---|---|---|---|
| plan_id | Yes | ||
| label | No | ||
| is_favorite | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavior. It only states the action 'attach' without mentioning idempotency, whether the label replaces or appends, or any side effects. There is no information about mutability, authorization, or error states.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, which is concise, but it lacks structure and important details. It front-loads the action but omits parameter contexts, making it under-specific. A slightly longer, more structured description would be more helpful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of output schema, annotations, and parameter explanations, this description is incomplete. A labeling tool would benefit from specifying whether existing labels are overwritten, whether the favorite flag toggles, and what the response indicates (e.g., success or updated state).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate by explaining parameters. It only generically mentions 'short label and/or favorite flag', but does not define plan_id, the string format for label, or permissible values for is_favorite. This leaves the agent without essential usage details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Attach') and the resource ('persisted plan') with specific attributes ('short label and/or favorite flag'). It effectively distinguishes from sibling tools like generate_meal_plan, swap_meal, and list_plans, which perform different operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, such as update_preferences or regenerate_plan. There are no usage conditions, prerequisites, or notes about not using this tool in certain scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List saved household recipes for disambiguation and browsing.
| Name | Required | Description | Default |
|---|---|---|---|
| query_en | No | ||
| cuisine | No | ||
| max_total_time_min | No | ||
| limit | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It describes a read-only list operation but does not mention auth requirements, rate limits, pagination, or ordering. The term 'household recipes' is vague and doesn't clarify scope. Minimal transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence, which is concise but lacks structure. It does not front-load critical information like parameters or results. While not verbose, it sacrifices completeness for brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 4 parameters, no output schema, and no annotations, the description is severely incomplete. It does not explain return values, ordering, filtering behavior, or how parameters interact. The agent lacks sufficient context to use the tool effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description should add meaning to the 4 parameters. It does not mention any parameter (query_en, cuisine, max_total_time_min, limit). The agent must guess their behavior from names alone, which is insufficient for correct usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (list) and the resource (saved household recipes), with a specific purpose (disambiguation and browsing). It distinguishes itself from siblings like search_recipes, add_recipe, and delete_recipe by focusing on listing for selection.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when browsing or disambiguating recipes, but provides no explicit guidance on when not to use it or alternatives. For example, it doesn't mention that search_recipes would be more appropriate for specific queries. The context is inferred but not stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List persisted plans for a profile with average meal ratings.
| Name | Required | Description | Default |
|---|---|---|---|
| profile_id | Yes | ||
| favorites_only | No | ||
| labelled_only | No | ||
| limit | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description must fully disclose behavior. It only states the action without mentioning side effects, permissions, or data limitations. 'Average meal ratings' is mentioned but unexplained, and there is no indication of read-only nature or output details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that immediately conveys the main action. However, it is slightly under-specified for the parameter count, but the conciseness itself is effective.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 4 parameters, no output schema, and no sibling differentiation, the description is incomplete. It does not cover filtering, limits, or return structure, leaving significant gaps for an AI agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description fails to explain any parameters beyond implying 'profile_id'. The boolean fields 'favorites_only' and 'labelled_only', and 'limit' are not described, providing no additional meaning over their names and types.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists persisted plans for a profile with average meal ratings, using a specific verb and resource. However, it doesn't distinguish from siblings like 'get_meal_plan' which retrieves a single plan, leaving slight ambiguity for an AI agent.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives, such as 'get_meal_plan' for a single plan or 'generate_meal_plan' for creation. The description lacks any contextual usage hints.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List household profiles in stable display order.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden. It discloses the read operation and stable ordering, but omits details like authentication requirements, scope (current user's profiles?), and whether empty list is possible.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence with no unnecessary content. Every word serves a purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity (0 params, no output schema), the description is mostly complete but could specify read-only nature and household scope more explicitly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters (0, schema coverage 100%), so the description does not need to add parameter information. Baseline for 0 parameters is 4; the description meets this.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List', the resource 'household profiles', and adds context with 'in stable display order', distinguishing it from sibling tools like get_profile (single) or save_profile (write).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives such as get_profile or search_recipes. The description implies it returns all profiles, but does not provide when-not or alternative usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Store a per-meal rating and apply deterministic tag deltas.
| Name | Required | Description | Default |
|---|---|---|---|
| plan_id | Yes | ||
| slot_key | Yes | ||
| rating | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses the side effect of applying deterministic tag deltas, which is a behavioral trait, but does not explain what tags are affected, reversibility, or authorization needs.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no wasted words, but it lacks structure. It could be reorganized to present purpose, parameters, and side effects more clearly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 3 required params with no schema descriptions, no output schema, and no annotations, the description is insufficient. It does not explain input semantics, output behavior, or the nature of tag deltas.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%. The description does not explain the meaning of `plan_id`, `slot_key`, or `rating` (e.g., rating range or format). The agent gets no help understanding parameters beyond their types.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('store a per-meal rating') and adds specificity with 'apply deterministic tag deltas'. It distinguishes from sibling tools like label_plan, though the term 'tag deltas' is somewhat ambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. There is no mention of prerequisites, when not to use, or how it relates to sibling tools like label_plan or update_preferences.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate a new plan from a previous plan using ratings or overrides.
| Name | Required | Description | Default |
|---|---|---|---|
| plan_id | Yes | ||
| keep_slot_keys | No | ||
| avoid_recipe_ids | No | ||
| budget_eur | No | ||
| servings | No | ||
| num_days | No | ||
| meals_per_day | No | ||
| max_time_min | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavior. It mentions 'using ratings or overrides' but does not explain what that entails, whether the operation is destructive, or what happens to the previous plan. Limited transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short (one sentence), which is efficient but under-specified. It front-loads the core action but misses important details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 8 parameters, no schema coverage, and no output schema, the description is far from complete. It fails to explain 'ratings or overrides', how regeneration works, or expected output.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description should explain parameter meaning. It does not. Even the purpose of the required plan_id is not clarified beyond the tool's name. No parameter semantics provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool generates a new plan from a previous one using ratings or overrides. It provides a specific verb ('generate') and resource ('new plan from a previous plan'), but does not explicitly differentiate from sibling tools like generate_meal_plan.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. The description lacks context on prerequisites (e.g., need existing ratings) or conditions for using overrides.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Rescale a persisted meal slot to a new serving count.
| Name | Required | Description | Default |
|---|---|---|---|
| plan_id | Yes | ||
| slot_key | Yes | ||
| servings | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, and description only states action without disclosing side effects, permissions, or behavior like whether rescaling recalculates nutrition or modifies in place.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence is concise and front-loaded, but lacks necessary detail. Efficiency is good but completeness suffers.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 3 required parameters, no output schema, and no annotations, description is insufficient to guide correct invocation. Missing context on parameter relationships and expected input formats.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% description coverage, and description does not explain any parameter beyond the tool's purpose. No details on how to obtain slot_key or valid values for servings.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states verb 'Rescale' and resource 'persisted meal slot' with specific action 'to a new serving count'. Distinguishes from sibling tools like swap_meal or add_recipe.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives. No mention of when not to use or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create or update a profile from flat MCP parameters.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| language | No | en | |
| dietary_pref | No | ||
| allergies | No | ||
| disliked_ingredients | No | ||
| kitchen_tools | No | ||
| cuisine_preferences | No | ||
| skill_level | No | intermediate | |
| meal_prep_ok | No | ||
| leftovers_ok | No | ||
| max_time_min | No | ||
| profile_id | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility. It only says 'Create or update' without disclosing mutation behavior, overwrite semantics, validation rules, or error handling. The agent cannot infer safety or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence, which is concise but under-specified. It sacrifices clarity for brevity. Could be expanded to 2-3 sentences without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 12 parameters, no output schema, and no annotations, the description is drastically incomplete. It fails to explain return value (presumably the saved profile), error cases (e.g., missing profile_id for update), or important constraints. This is insufficient for effective agent use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description must clarify parameter meanings. It only states 'from flat MCP parameters' without explaining any parameter defaults, allowed values, or relationships (e.g., profile_id triggers update). Parameter names are somewhat self-explanatory but key details like language default 'en' are omitted.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Create or update a profile from flat MCP parameters' clearly states the action (create/update) and resource (profile). It distinguishes from sibling tools like get_profile (read) and list_profiles (list). However, it could be more explicit about the update logic based on profile_id.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives like update_preferences or get_profile. No mention of when to create vs update, which is critical given the 'create or update' nature. Agents need explicit prompts for conditional usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search the local recipe index with optional profile hard filters.
| Name | Required | Description | Default |
|---|---|---|---|
| query_en | Yes | ||
| profile_id | No | ||
| max_price_per_serving_eur | No | ||
| max_total_time_min | No | ||
| course | No | ||
| limit | No | ||
| include_custom | No |
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 that the tool 'Search's, but does not reveal whether it is read-only, what side effects exist, return format, pagination, or any rate limits. The lack of behavioral context makes it hard for an agent to assess risks.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no repetition. It efficiently states the core action and key feature (optional filters). However, it could benefit from slight expansion to cover critical parameters without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 7 parameters, no output schema, and no annotations, the description is insufficiently complete. It does not explain the return value, ordering, default behavior of limit (10), or effects of include_custom. An agent would struggle to use this tool effectively without additional context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, so the description must compensate for the 7 parameters. However, it only mentions 'profile hard filters', ignoring query_en (required), max_price_per_serving_eur, max_total_time_min, course, limit, and include_custom. This adds minimal value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Search' and the resource 'local recipe index', and mentions optional 'profile hard filters'. However, it does not differentiate from sibling tools like list_custom_recipes, which also list recipes. Still, it is specific enough to convey the tool's primary function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives such as list_custom_recipes or get_pantry. The phrase 'optional profile hard filters' is vague and does not clarify when profile_id should be set or what constitutes a hard filter. No exclusions or alternative hints provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Swap a plan slot to the best local recipe for an English query.
| Name | Required | Description | Default |
|---|---|---|---|
| plan_id | Yes | ||
| slot_key | Yes | ||
| query_en | Yes | ||
| max_price_eur | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It indicates mutation ('swap') but does not disclose whether it is destructive, requires permissions, or what happens to the original recipe. No details about 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is front-loaded and concise. However, it is too brief for a tool with 4 parameters, lacking necessary detail without being overly long.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of annotations and output schema, the description should provide more context about behavior, return values, and parameter constraints. It only covers the basic action, leaving significant gaps for agent understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%. The description mentions 'plan slot' and 'English query', which partially explains 'slot_key' and 'query_en', but does not explain 'plan_id' or 'max_price_eur'. The parameter meaning is not adequately conveyed beyond names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the verb 'swap' and specifies the resources (plan slot, recipe) and the query language (English). It clearly distinguishes the action from siblings like 'add_recipe' or 'delete_recipe', but does not clarify what 'local' means, which could be ambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as 'regenerate_plan' or 'rescale_meal'. There is no mention of prerequisites or context for use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Canonicalise and update slow-use pantry staples.
| Name | Required | Description | Default |
|---|---|---|---|
| profile_id | Yes | ||
| add_items | No | ||
| remove_items | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description implies data mutation but does not disclose any behavioral traits: no mention of side effects, required permissions, or whether the update is incremental or replaces the entire pantry. With no annotations, the description should provide more context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
While the description is short, it is under-specified and sacrifices clarity for brevity. The single sentence does not earn its place as it fails to convey essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of annotations, output schema, and parameter documentation, the description is severely incomplete. It does not explain the tool's behavior, return value, or operational context for a mutation tool with multiple parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has three parameters with 0% description coverage, and the tool description provides no explanation of what 'add_items' or 'remove_items' represent, their expected format, or how they relate to 'canonicalise'. This leaves the agent guessing about usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the verb 'canonicalise and update' which is somewhat specific, but 'canonicalise' is unclear jargon. The resource 'pantry staples' is vague and doesn't clearly distinguish from sibling tools like 'get_pantry'. A clearer statement like 'Add or remove items from the pantry list' would improve clarity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as 'get_pantry' for reading or 'add_recipe' for adding a recipe. The description does not include any context about prerequisites or scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Apply conversational preference deltas to profile tags.
| Name | Required | Description | Default |
|---|---|---|---|
| profile_id | Yes | ||
| liked_tags | No | ||
| disliked_tags | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden but fails to disclose behavioral traits. It does not explain whether updates are additive (deltas) or replace the entire list, what side effects occur, or any authorization or idempotency details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise (one sentence, six words). While brevity is good, it sacrifices clarity and informativeness. It is not front-loaded effectively because it fails to convey essential meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of output schema, annotations, and param descriptions, the description is incomplete. It does not explain return values, success states, or how the tool integrates with other profile-related tools. The context of 'conversational' is unexplained.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description should compensate. However, it only mentions 'preference deltas' and 'profile tags', providing no explanation of liked_tags, disliked_tags, or profile_id. It adds minimal semantic value beyond the parameter names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Apply conversational preference deltas to profile tags' indicates a verb and resource but is ambiguous. 'Conversational preference deltas' is not clearly defined, and it doesn't distinguish well from sibling tools like save_profile or get_profile. It gives a general idea but lacks specificity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No usage guidelines are provided. The description does not specify when to use this tool versus alternatives, nor does it mention prerequisites or restrictions. The agent receives no guidance on context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Patch a custom recipe and refresh its embedding when needed.
| Name | Required | Description | Default |
|---|---|---|---|
| recipe_id | Yes | ||
| title | No | ||
| ingredient_names | No | ||
| ingredient_amounts | No | ||
| ingredient_units | No | ||
| directions | No | ||
| cuisines | No | ||
| courses | No | ||
| tastes | No | ||
| total_time_min | No | ||
| difficulty | No | ||
| servings | No | ||
| tools | No | ||
| dietary_flags | No | ||
| allergens | No | ||
| notes | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It mentions 'refresh its embedding' as a side effect, but does not disclose authentication needs, atomicity, or limitations. The behavioral disclosure is minimal and insufficient for safe invocation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief but incomplete. It uses 'when needed' redundantly and omits critical parameter and usage details. Conciseness here sacrifices utility, but the structure is front-loaded with the core verb.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 16 parameters, no annotations, and no output schema, the description is far from complete. It does not specify that only custom recipes are eligible, what the response contains, or how embedding refresh is triggered. The agent lacks enough information to invoke the tool confidently.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, yet the description adds no information about any of the 16 parameters. Parameter names from the schema convey only basic intent; the description fails to clarify, for instance, that ingredient_names, amounts, and units should be synchronized, or how difficulty is formatted.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses 'patch' to indicate partial update and specifies 'custom recipe', differentiating it from sibling tools like add_recipe and delete_recipe. However, it does not explicitly name siblings or provide distinguishing cues beyond the context from the sibling list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention prerequisites, constraints, or when not to use it, leaving the agent without context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.6.0add_recipedelete_recipegenerate_meal_planget_meal_planget_pantryget_profileget_shopping_listlabel_planlist_custom_recipeslist_planslist_profilesrate_mealregenerate_planrescale_mealsave_profilesearch_recipesswap_mealupdate_pantryupdate_preferencesupdate_recipeEach tool targets a distinct resource-action combination (e.g., plan, recipe, profile, pantry). No two tools have overlapping purposes; even related tools like get_meal_plan and list_plans are clearly differentiated by specificity.
All tools follow a consistent verb_noun pattern with lowercase underscores. Verbs are imperative and nouns are singular or plural where appropriate, making the intent predictable and scannable.
With 20 tools covering recipes, meal plans, profiles, preferences, pantry, and shopping lists, the count is well-scoped for a comprehensive meal planning server. Each tool serves a clear purpose without unnecessary bloat.
The tool surface covers core CRUD and lifecycle operations for recipes, plans, profiles, and pantry. Minor gaps exist (no explicit delete for plans or profiles, no rating removal), but these are manageable for typical workflows.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Household-aware cooking brain: pantry, meal suggestions, dietary safety, recipes, shopping lists.
Family meal planning run by your agent: weekly dinners, household votes, grocery list minus pantry.
AI meal plans that fill your Kroger/Instacart cart - pantry-aware lists, all from chat.
AI-powered kitchen management — pantry, recipes, meal plans, shopping lists
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/nerkyzas157/gamito'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
