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

Annotations already declare readOnly=false, destructive=false and idempotent=false; the description reinforces this by explicitly warning that repeated calls always produce a new entry rather than merging. What is missing is any statement about failure behavior (e.g., invalid food_id or location_id) or whether permissions are required.

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

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

Three short sentences, front-loaded with the action and immediately followed by required/optional field lists. The required/optional enumeration partly restates the schema, which is mild redundancy, but it makes the definition scannable without padding.

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

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

For a 9-parameter mutation tool with no output schema and no per-field schema descriptions, the definition covers the core write semantics but leaves gaps: what format controls, where the ID values come from, and what the tool returns or errors on. It is adequate to call correctly in the happy path but not complete.

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

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

With 0% schema description coverage across 9 parameters, the description carries the load well: it enumerates all four required fields and four of the five optional ones, plus the YYYY-MM-DD format for expires and the >0 constraint on amount. The only undocumented parameter is format (slim/full), and the description never explains that the *_id values come from list_foods, list_units and list_inventory_locations.

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

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

States a specific verb and resource ("Add food to inventory") and clarifies that it always creates a new entry rather than updating. It does not explicitly name the sibling alternatives (consume_inventory_item, move_inventory_item), but the create semantics are unmistakable.

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 line "Always creates a new entry, even when the same food already has an entry at that location" gives useful usage context for avoiding accidental duplicates. However, there is no explicit guidance on when to use this versus consume/move/update flows, or on prerequisites such as the food existing via create_food.

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

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

Annotations already declare this as a non-read-only, non-idempotent, destructive write, so the safety profile is covered. The description adds the important behavioral detail that the tool doubles as a delete path via servings=0 with list_recipe. It says nothing about duplicate handling, whether the list is appended versus overwritten, or what happens to already-checked entries.

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

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

Three short, front-loaded sentences with no filler. The core add behavior comes first, followed by the two conditional exceptions, which is the right order for an agent skimming the definition.

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 four-parameter mutation tool with full schema coverage and annotations, the description covers the add, all-ingredients, and delete workflows. It stops short of describing the update path through list_recipe or duplicate/append behavior, which a cautious agent might want before calling a destructive write.

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

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

Schema coverage is 100%, so the baseline is 3 and the schema already describes id, servings, ingredients, and list_recipe. The description reinforces the ingredients-omission and servings=0 deletion semantics but adds no syntax or format detail beyond what the schema states. The interaction between servings scaling and list_recipe updating is left implicit.

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

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

The description opens with a specific verb and resource: "Add a recipe's ingredients to the shopping list at N servings," which tells an agent exactly what the tool does. It does not name a sibling alternative (e.g., create_shopping_entry or food_shopping_update), so differentiation has to be inferred from the resource being a recipe.

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

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

It states two concrete conditions: omit ingredients[] to include all ingredients, and use servings=0 with list_recipe to delete an existing shopping-list-recipe. That is clear how-to-use guidance for the parameters, but there is no when-to-use guidance relative to sibling tools that also write shopping entries.

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

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

Annotations already declare this is a non-read-only, idempotent, non-destructive mutation, so the safety profile is covered. The description adds the core behavior that it sets the checked state in bulk, but it omits important bulk-write traits such as partial-failure handling, permission requirements, and return behavior.

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

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

The description is a single front-loaded sentence with no filler; every word contributes to stating the operation and its inputs.

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 two-parameter bulk mutation with rich annotations and no output schema, the description covers the core operation adequately. It omits bulk-write details such as partial-failure behavior and whether all IDs must belong to the same shopping list.

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 compensate. It maps 'ids' to an ID list and 'checked' to check/uncheck, clarifying both parameters' meaning, but it does not specify edge cases such as duplicate or invalid IDs.

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

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

The description uses a specific verb phrase ('Bulk check or uncheck') and names the resource ('shopping entries') plus the selector ('by ID list'). It does not explicitly differentiate from siblings such as bulk_update_shopping_entries or update_shopping_entry, so it falls short of 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 when-to-use guidance, prerequisites, or alternatives are provided. It does not say when to choose this over update_shopping_entry or bulk_update_shopping_entries, so the agent must infer that this is for setting only the checked flag on multiple entries.

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

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

Annotations already declare the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=true), yet the description still adds real behavioral context: nonexistent or invisible ids are silently skipped, list changes do not bump updated_at, and unknown or repeated list ids cause rejection with nothing written. The only gap is that it never says what the response looks like. Minor tension exists between the always-reset completed_at behavior and idempotentHint, which the author does at least disclose.

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?

It front-loads the required parameter and the checked/list-change decision, then moves through constraints in a logical order. The prose is telegraphic and dense, with several run-on clauses, but nearly every sentence states a real constraint an agent needs.

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 six-parameter bulk mutation with no output schema, the description covers inputs, atomicity, and side effects well. It stops short of stating the return value or partial-success semantics beyond 'nothing is written', which leaves the agent guessing about what a successful call hands back.

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 carries the full burden and does so thoroughly: it explains ids, checked (including completed_at side effect), all four list-mutation parameters, the add/remove mutual exclusion, and that empty arrays or remove_all=false are treated as no change. This is effectively a prose specification of a completely undocumented 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 opens with a specific verb and resource plus scope: 'Update many shopping entries in one call.' That separates it from the singular update_shopping_entry, and the detailed list-mutation semantics distinguish it from bulk_check_shopping_entries. It never names a sibling explicitly, so an agent must infer the routing rather than read it.

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?

'Give checked, a list change, or both' tells the agent the valid invocation shapes, and 'set and remove_all must be used alone' is an explicit exclusion. However, there is no guidance on when to prefer this over bulk_check_shopping_entries or looping update_shopping_entry, so usage is implied rather than stated.

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

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

Annotations only assert readOnlyHint=false, destructiveHint=false, idempotentHint=false; the description goes far beyond by disclosing that the entry is never deleted, that over-consumption clamps to 0 and returns a warning, and that zeroed entries disappear from list_inventory_entries unless include_empty is true. It also volunteers a genuine hazard the annotations cannot express: the operation is not atomic and concurrent consumes can lose an update. That is exactly the context an agent needs before retrying or parallelizing.

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?

Dense but disciplined: identification, exclusivity rule, unit constraint, clamping behavior, visibility side effect, then the concurrency caveat, roughly in priority order. Every sentence carries operational weight. The nested parentheticals make it slightly slower to parse than it needs to be, but nothing is filler.

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

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

For a 7-parameter mutation with no output schema and no annotation coverage of side effects, the description supplies the failure modes, the clamping semantics, and the visibility change that an agent must anticipate. What is missing is any statement about the return payload's shape beyond "a warning", and the purpose of the format parameter, which is the one loose end for a tool with this many knobs.

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 carries the full burden, and it explains six of the seven parameters meaningfully (entry_id, food_id, location_id, amount>0, all: true, unit_id must match with no conversion). The gap is format (slim/full), which is neither described here nor in the schema, leaving one enum unexplained. Strong compensation overall, but not complete.

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?

"Use up some or all of an inventory entry" is a specific verb+resource pair that is immediately distinguishable from add_inventory_item and move_inventory_item among its siblings. The description also states the scoping rule (never deletes, floors at 0), so an agent knows the operation is a partial-state mutation rather than a create/delete.

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?

Gives explicit selection rules for identifying the entry (entry_id, or food_id plus optional location_id, with an error listing candidates on ambiguity) and an exclusive-choice rule for amount vs all: true, plus the constraint that unit_id must match with no conversion. What it omits is a pointer to any alternative tool (e.g. move_inventory_item when relocating rather than consuming), so it stops short of naming when not to use it.

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

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

Beyond the annotations (readOnlyHint=false, idempotentHint=true), it discloses the non-obvious traits: returning an existing food instead of creating, refusing and changing nothing on name/plural-name collisions, creating then setting lists because Tandoor cannot do both at once, rejecting unknown or repeated list ids before any write, and telling the agent not to retry after a partial failure. It also explains downstream list-copying side effects in related tools. This is exactly the behavioral context annotations cannot carry.

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 opening is well front-loaded (verb, required, optional). But the remainder is a dense run-on chain of conditionals covering cross-tool list-copying behavior, with some tangential material (add_recipe_to_shopping_list, shopping_update_food_lists preference) that an agent creating a food rarely needs. Information density is high but readability 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?

For an 8-parameter mutation tool with no output schema and zero schema descriptions, the description covers collision, refusal, ordering, and failure semantics thoroughly. The remaining shortfall is the undocumented `format` parameter and no indication of what the create reply contains, which matters since the tool inspects that reply to detect plural-name matches.

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, and it does well for shopping_list_ids (provenance via list_shopping_lists, empty-list semantics, validation). However, it merely lists plural_name, description, food_onhand, fdc_id, and supermarket_category_id without explaining their meaning or effect, and the `format` enum (slim/full) is never mentioned at all, leaving a real gap.

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

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

The description opens with a specific verb+resource ("Create food") and immediately scopes it by enumerating the required and optional inputs. It clearly distinguishes itself from siblings by naming update_food and list_shopping_lists as the alternate paths, so an agent can route without opening another schema.

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

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

It gives concrete conditions: if a food with this name exists, Tandoor returns it; with shopping_list_ids and an existing name, the tool refuses and the agent should use update_food. That is strong when-to-use routing. It lacks a plain statement of when to prefer create_food over update_food outside the collision case, but the conditional guidance is unusually explicit.

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

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

Annotations already declare this is a non-readonly, non-destructive, non-idempotent write, so safety is partly covered. But the description adds nothing beyond a parameter list and never explains the notable side effect implied by 'addshopping' (adding ingredients to a shopping list) or whether a meal plan can span multiple days via to_date. For a mutation tool this leaves real behavioral questions unanswered.

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

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

Two short sentences, front-loaded with the verb and structured as required-then-optional, so there is no wasted wording. The brevity is under-specification rather than tight editing, though, and the required/optional enumeration duplicates the schema's own required array.

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 8 parameters, zero schema descriptions, no output schema, and a side-effecting write operation, the definition should do far more than list names. It neither covers to_date nor explains return behavior, so an agent cannot confidently call it for anything but the simplest case.

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% across 8 parameters, so the description must carry the meaning and it only partly does. It does add a useful format hint for from_date '(ISO)', but it never explains servings (per person? per plan?), what addshopping actually triggers, what happens when recipe_id is omitted, and it omits the to_date parameter entirely even though it exists in the schema.

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

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

The description opens with the specific verb+resource 'Create meal plan', which cleanly separates it from the sibling update_meal_plan, delete_meal_plan and get_meal_plan. It does not, however, state what a meal plan is scoped to (current space, user) or contrast itself with any alternative.

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

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

There is no when-to-use guidance: nothing says when a caller should create a plan versus updating one, nor any prerequisite such as the meal_type_id or recipe_id having to exist first. The only 'guidance' is the required/optional parameter split, which the schema already encodes.

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

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

Annotations already state it is a non-destructive, non-idempotent write with no open-world access, so the baseline bar is low, yet the description adds nothing beyond them. It does not say whether duplicate names are rejected, what happens with private/internal flags, or what the response contains.

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?

Compact and front-loaded: the required parameters come before the optional ones, and the nested syntax is compressed into bracket notation with zero wasted words. The terse notation is dense but readable.

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 15-parameter nested-object creation tool with no output schema and no annotations about response shape, the description is far too thin. It leaves the majority of parameters undocumented and says nothing about what the created recipe looks like or how defaults are applied.

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 only 7%, so the description must compensate, and it does partially by marking name and steps as required and sketching the nested steps/ingredients shape with unit optional. However, it omits 8 of the 15 parameters (format, private, internal, nutrition, properties, source_url, servings_text, show_ingredient_overview) and the per-step 'time' and ingredient 'note' fields, leaving large gaps.

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?

Opens with a specific verb+resource ('Create recipe'), which distinguishes it from update_recipe and get_recipe. It does not, however, distinguish it from import_recipe_from_url or explain how it relates to create_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?

The description only lists required and optional fields; it gives no guidance on when to use create_recipe instead of import_recipe_from_url or create_meal_plan, and no prerequisites are stated. Usage is left entirely implied by the tool name.

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

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

Beyond the annotations (readOnly=false, idempotent=false, destructive=false), the description discloses hidden behavior: dependence on the user preference shopping_update_food_lists, the fact that list ids are validated before any write, that unknown or repeated ids reject the whole call, and that a post-write list mismatch produces a named-difference error. That is exactly the kind of side-effect and failure detail the annotations cannot carry.

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 required/optional inventory is helpfully front-loaded, but the body is a dense wall of nested clauses that circles back to shopping_list_ids twice and spends sentences on Tandoor internals (later food-list edits not affecting existing entries) that are marginal for invocation. It is information-rich but not tight.

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

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

For an 11-parameter mutation tool with no output schema and no field-level schema docs, the description is largely sufficient: it covers required inputs, the list-resolution contract, and error behavior. The remaining gap is that several optional parameters and the format enum are left undefined, so an agent cannot construct every valid call from the description alone.

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 across 11 parameters, the description compensates well for the hardest ones: shopping_list_ids gets a full semantic model (validate, copy, treat [] as clear) and mealplan_id explains the link to ShoppingListRecipe. However, `format` (the one enum parameter, slim/full) is never mentioned, and order, checked, delay_until, ingredient and list_recipe are only named without meaning.

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

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

The first sentence gives a specific verb and resource ('Create a shopping list entry'), and the rest distinguishes it from the two sibling tools that also touch shopping lists by contrasting their list-copying behavior. An agent can identify what this does relative to add_recipe_to_shopping_list and food_shopping_update without opening any schema.

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

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

It clearly establishes the required/optional split and explains the decision point for shopping_list_ids (omit vs explicit ids vs []), with sibling comparisons that help selection. It stops short of an explicit 'use this instead of update_shopping_entry when...' statement, so routing against the other write tools is left partly to inference.

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

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

The annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered structurally. The description adds nothing beyond that: it does not say whether the delete is permanent or soft, whether child entries cascade, or what happens when the ID does not exist.

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?

Five words, front-loaded with the verb and free of boilerplate. It is tight rather than padded; the shortfall is under-specification, not verbosity.

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

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

For a destructive mutation the definition is thin: one undocumented parameter, no output schema, and no statement of consequences or error behavior. The annotations cover the read/write and idempotency signals, but an agent still lacks the information needed to call this safely in a multi-step workflow.

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 carry the meaning of the single required parameter — and it offers only the redundant phrase "by ID". It never clarifies that the ID must reference an existing meal plan, nor does it address the number type the schema declares.

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

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

States a specific verb and resource ("Delete meal plan") plus the lookup key ("by ID"), which cleanly separates it from get_meal_plan and update_meal_plan in the sibling list. It lacks any qualification of scope (soft vs. permanent delete) but the core action is unambiguous.

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

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

No guidance on when to use this versus update_meal_plan or get_meal_plan, and no preconditions such as needing a prior get_meal_plan lookup to obtain the ID. The agent must infer everything from the name.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered by structured data. The description adds nothing beyond that: it does not say whether the deletion is permanent or recoverable, what happens if the ID does not exist, or whether it errors on a missing entry.

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

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

A single front-loaded sentence with no filler or redundancy. It is efficient, though the brevity edges into under-specification rather than pure 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?

This is a destructive mutation with no output schema and no annotation-independent context in the description. An agent is left not knowing the outcome of a successful deletion, the failure mode for an unknown ID, or whether dependent shopping list totals are affected.

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

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

Schema description coverage is 0%, so the description carries the burden, yet it only says 'by ID' without clarifying that the number is the shopping entry identifier, where that ID comes from (e.g., list_shopping_entries), or any format constraints. This is minimal compensation for an undocumented parameter.

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

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

The description names a specific verb and resource ('Delete a shopping entry') plus a scoping constraint ('by ID'), which clearly separates it from get_shopping_entry and update_shopping_entry. It stops short of explicitly naming a sibling or distinguishing itself from bulk deletion, so it is clear but not maximally differentiated.

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?

There is no guidance on when to use this instead of bulk_check_shopping_entries, bulk_update_shopping_entries, or update_shopping_entry, and no stated preconditions such as needing the entry to exist. The agent must infer all of this from the tool name and siblings.

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

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

Annotations cover the safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false), and the description adds context beyond them: the group's tools vanish from tools/list and the SDK emits tools/list_changed automatically, so the agent knows the tool-list changes without re-listing. It stops short of saying what happens on an unknown group name, whether the change persists across sessions, or what is returned.

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

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

Four short sentences, front-loaded with the primary effect, then the automatic notification, then the constraint, then the use case. Nothing is redundant or padded.

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 one-parameter, non-destructive, idempotent toggle with annotations and no output schema, the description covers effect, side-effect notification, and the one restriction. Only the error/return behavior for an invalid group name is left implicit, a minor gap given no output schema exists.

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

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

Schema description coverage is 100% and the single 'group' parameter is already described there, including the fact that 'always' cannot be disabled. The description restates the same constraint and adds no naming-format or discovery guidance, so the schema does the heavy lifting.

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

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

States a specific verb ('turn a section off') and resource ('tool group'), plus the concrete effect: all its tools disappear from tools/list. That effect alone separates it unambiguously from enable_tool_group in 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?

Gives an explicit trigger: 'Use this to free context budget once a workflow no longer needs a section.' It also states the exclusion that the "always" section cannot be disabled. It does not name enable_tool_group as the inverse operation, so routing is clear but not fully spelled out.

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

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

Beyond the annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false) it discloses the actual side effect: the SDK emits tools/list_changed and the client refreshes mid-conversation. It also states the monotonicity rule — enabling never narrows, so simple on an already-full section leaves it at full — which concretely explains the idempotentHint rather than restating it.

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?

Five short sentences, front-loaded with the effect before the arguments and the cost warning. The SDK/tools-list_changed sentence carries two clauses but each conveys a distinct consequence, so nothing is padding; it could be slightly tighter but is not bloated.

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 two-parameter, non-destructive operation with annotations and no output schema, the description covers effect, arguments, side effects, and prerequisite. The remaining gap is what the call itself returns (a confirmation, or the refreshed tool list) — minor since the tool list refresh is already explained.

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

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

Schema coverage is 100%, so the baseline is 3, and the description goes past it by explaining tier semantics: default full, rejected for on/off sections, and the non-narrowing behavior when the requested tier is lower than the current one. It does not add anything about the group parameter beyond what the schema already says.

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?

It states a concrete effect: widening a section so its tools appear in tools/list, which is clearly not what disable_tool_group or list_tool_groups does. The only friction is terminology — the tool is named *_tool_group but the body consistently says "section," so the agent must map group=section on its own.

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

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

It names a prerequisite ("Run list_tool_groups first") and a selection rule for the tier argument (simple/full, default full, not accepted on on/off sections). It also gives a usage constraint — "Be sparing: every enabled tool adds its schema to your context budget" — which tells the agent when not to call it, something most definitions omit.

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

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

Annotations already declare destructiveHint=true and non-idempotent, and the description adds the critical scope detail that deletion applies to ALL active lists, not just one. It does not state what happens when the food is absent from a list or whether amount/unit_id are ignored in delete mode.

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

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

Two short sentences, front-loaded with the primary add behavior and followed by the destructive mode. 'this food' is mildly ambiguous in a standalone description but costs little.

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 four-parameter mutation with no output schema, the description covers the modes and destructive scope but leaves gaps: error behavior for unknown ids, whether the operation is a no-op when the food is not listed, and the relationship between amount and unit_id.

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; it explains amount, unit, and delete, and implies id refers to the food. But 'id' is never explicitly identified as a food id, and there is no statement of whether unit_id is required when amount is supplied.

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

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

The description states the resource (a food on active shopping lists) and both modes: add with optional amount/unit, or remove via delete=true. It is clear, though the name 'update' slightly undersells the add/remove duality, and no sibling tools (create_shopping_entry, update_shopping_entry) are named to distinguish it.

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

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

It gives the trigger for the delete mode ('Pass delete=true to remove...'), which is useful, but provides no guidance on when to prefer this over create_shopping_entry or update_shopping_entry, and no prerequisites such as the food already existing.

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

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

Annotations already declare readOnlyHint, idempotentHint and closed-world behavior, so the safety profile is covered. The description adds only that the result depends on the calling token's active space, which is genuinely useful context, but says nothing about the response shape or whether the space can change between calls.

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?

One front-loaded sentence with no filler. It is as short as it can be, though its brevity is arguably under-specification rather than disciplined 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?

There is no output schema, so the description carries the burden of explaining what a 'space' is and what the caller receives, and it does neither. The only parameter is also left unexplained, leaving an agent unable to predict the result or choose a format.

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% and the single 'format' parameter (enum slim/full) is completely undocumented in both schema and description. The description does not explain what slim versus full returns, which is exactly the information an agent needs to choose a value.

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

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

States a specific verb and resource ('Get the space') with the scoping qualifier 'currently active for this API token', which no sibling tool duplicates. It is clear what the tool returns conceptually, though what a 'space' contains is never defined.

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 call this versus other context/introspection tools (e.g. get_version) or what an agent should do with the result. The token-scoping hint implies a purpose but does not state a use condition.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive, and closed-world, so safety is covered structurally. The description adds nothing beyond that — notably it never explains what the 'format' flag does (slim vs full responses), which is the one genuinely behavioral detail worth disclosing for a read tool.

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

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

Four words, front-loaded, with zero filler. It is terse rather than padded, so the only criticism is under-specification rather than verbosity.

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

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

For a simple two-parameter read tool with full annotation coverage and no output schema, the minimal description is nearly adequate. The unresolved gap is the 'format' parameter and any statement of what is returned or what happens on a missing ID.

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

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

Schema description coverage is 0%, so the description carries the burden and fails: it only restates that 'id' identifies the food and says nothing about the optional 'format' parameter or what 'slim' versus 'full' return. The enum values are visible in the schema but their effect is undefined anywhere.

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

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

The description states a concrete verb and resource ('Get food by ID'), so the basic action is clear. However, it offers no differentiation from siblings such as list_foods, create_food, or update_food, and does not clarify whether 'food' is a catalog item, inventory entry, or recipe ingredient.

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?

There is no guidance on when to use this lookup versus list_foods or search_recipes, and no mention of prerequisites or fallback behavior when the ID does not exist. The agent must infer usage entirely from the name.

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

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

The annotations already cover safety (readOnlyHint, idempotentHint, non-destructive, closed-world), so the description only needs to add operational context. It usefully discloses the key scoping fact that counters are "since process start" (i.e., reset on restart), but says nothing about the response shape or whether values are cumulative counts, which matters for a metrics tool with no output schema.

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

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

Two short sentences, front-loaded with what is inspected, followed by the practical use case. No filler or redundant restatement of the title.

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

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

For a simple parameterless read, the description covers what is measured and the reset window, which is the essential part. However, with no output schema, the description never indicates what the returned object looks like (counter names, nesting, totals), leaving a real gap for an agent trying to consume the result.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline applies. The schema is empty and fully consistent with a parameterless stats read.

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

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

States a specific verb ("Inspect") and a specific resource ("security-guard rejection counters") and even names the concrete counter types (PathGuardError, SsrfBlockedError). It does not need to differentiate from siblings, since none of the listed tools are analogous, but it also doesn't explicitly frame itself against anything else.

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?

Gives two concrete use contexts: dashboards and "is anything probing me?" checks. That is clear positive guidance, though there are no stated exclusions or pointers to an alternative tool when a deeper security audit is needed.

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

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

Annotations already declare this as read-only, idempotent, non-destructive, and closed-world. The description adds no behavioral context such as what the 'format' parameter changes, what fields are returned, or how missing IDs behave.

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 single sentence is front-loaded and free of filler. However, brevity here veers into under-specification rather than efficient communication.

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

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

For a simple read tool with annotations and no output schema, the description is too sparse. It leaves the 'format' parameter unexplained and provides no clue about return shape or when to prefer this over list_keywords.

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 carry parameter meaning, but it only restates that lookup is by ID. The 'format' parameter with its slim/full enum is completely undocumented and its effect is undefined.

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

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

The description states a specific verb ('Get') and resource ('keyword') scoped to lookup by ID. It is clear what the tool does, but it does not distinguish itself from the sibling list_keywords tool or clarify why one would retrieve a single keyword.

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?

There is no guidance on when to use this tool versus list_keywords or other lookup tools. The only implied usage is retrieving a known ID, but that is not stated as a condition.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered by structured fields. The description adds nothing beyond that — no note on what happens if the ID does not exist, no auth/space context, no mention of shape or size of the returned plan.

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

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

Four words, zero padding and front-loaded, which is structurally sound. However, the brevity comes at the cost of under-specification rather than true conciseness — nothing beyond the title is conveyed.

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

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

The tool is simple and annotations carry the behavioral profile, but with no output schema the description should at least sketch what a meal plan record looks like or how a missing ID is surfaced. Neither is present, leaving the agent to call blind.

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

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

The single parameter has 0% schema description coverage, so the schema offers only 'number' with no meaning attached. 'By ID' merely confirms the id parameter identifies a meal plan; it gives no hint about where to obtain such an ID (e.g., from list_meal_plans) or whether the number is a global or space-scoped identifier.

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

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

States a specific verb ('Get') and resource ('meal plan') with a scoping qualifier ('by ID'), which distinguishes it from the sibling list_meal_plans. It is not a tautology, but it does not name the alternatives or clarify what a meal plan record contains.

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 versus list_meal_plans (find one) or update_meal_plan/delete_meal_plan (operate on one). The agent must infer from the tool name alone that this is the single-record lookup path.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is fully covered elsewhere. The description adds nothing beyond that - no note on behavior for a missing ID (error vs empty), no indication of whether the lookup is cached or scoped to the current space.

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 filler or redundancy. It is efficient, though its brevity comes at the cost of the missing detail noted elsewhere.

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

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

For a simple two-parameter read tool with rich annotations and no output schema, the description is still too thin: the slim/full format switch and the missing-ID behavior are the two things an agent most needs and neither is covered.

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

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

Schema description coverage is 0%, so the description carries the burden, yet it only vaguely implies that 'id' identifies the meal type. The 'format' enum (slim vs full) is entirely unexplained - an agent cannot tell what changes between the two shapes.

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 names a specific verb (get) and resource (meal type) plus the lookup key (ID), which is clear enough to distinguish a single-item fetch from the sibling list_meal_types. It does not explicitly name that sibling, so it stops short of the 5 tier.

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?

There is no guidance on when to use this versus list_meal_types or how to obtain a valid ID. No prerequisites, no exclusions, no mention of what to do when the ID is unknown.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds real behavioral value by disclosing the default slim payload and what the 'full' format unlocks (substitutes, properties, nutrition, image), which shapes whether an agent needs a follow-up call. It omits error behavior for a missing ID.

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

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

Two tight sentences with the default behavior front-loaded and the opt-in escalation second. Every clause carries information an agent would otherwise have to discover by calling the tool.

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 no output schema, the description usefully compensates by describing the return shape at both detail levels. For a 2-parameter read tool with full annotations this is nearly complete; only missing-recipe behavior and pagination/limits are unaddressed.

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

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

Schema coverage is 100%, so the baseline is 3, and the description does add genuine meaning for 'format' by enumerating what slim returns versus what full adds. The 'id' parameter, however, gets no elaboration beyond the schema's 'Recipe ID'.

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

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

The description states a specific verb and resource ('Get recipe by ID') and immediately clarifies the two response modes, which lets an agent distinguish it from list_recipes/search_recipes siblings by its ID-keyed, single-record scope. It stops short of naming any sibling explicitly, so the differentiation is inferable rather than stated.

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?

Usage is implied: call this when you already have a recipe ID. There is no explicit guidance on when to prefer it over search_recipes or list_recipes, nor any note about what to do if the ID is unknown. Adequate but leaves the alternative-selection reasoning to the agent.

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

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

The annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered elsewhere. The description adds nothing beyond that — no note on what is returned, whether missing IDs error or return null, or what the format variants change.

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 filler or redundancy. It is efficiently written, though its brevity reflects under-specification rather than tight editing.

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

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

For a simple read tool with no output schema, the description should at minimum explain the format parameter's effect and the not-found behavior. Neither is present, and with 0% schema coverage nothing else fills the gap.

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

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

Schema description coverage is 0% for two parameters, so the description carries the full burden and largely fails: it clarifies only that the required id is the entry identifier. The optional "format" enum (slim vs full) — the one parameter whose meaning an agent cannot guess — is never mentioned.

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 names a specific verb ("Get") and resource ("a shopping list entry") plus the lookup key ("by ID"), so an agent knows exactly what the call retrieves. It does not contrast itself with siblings such as list_shopping_entries or the update/delete variants, so sibling differentiation is left 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?

There is no when-to-use or when-not-to-use guidance: nothing says to prefer list_shopping_entries when the ID is unknown, or that this is the single-entry counterpart of the list tool. The only hint is the phrase "by ID," which weakly implies a known identifier is required.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the bar is lower. The description still adds real value beyond them: it discloses that results come from startup-cached state rather than a live call, and enumerates the compatibility values (ok | unsupported | unknown). It stops short of warning that cached state may be stale after a server change.

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 carrying purpose, return contents, the status enum, and the no-network behavior. Nothing is redundant with the name or annotations.

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?

There is no output schema, so the description must convey return values, and it does: server name/version, Tandoor version, and a three-valued compatibility status. For a zero-argument read tool with full annotation coverage, nothing needed for correct invocation is missing.

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

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

Zero parameters, so the baseline is 4. The description confirms 'No arguments', which matches the empty schema exactly and removes any doubt an agent might have about needing a server identifier.

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

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

States a specific verb (Report) and precisely names the three things returned: the MCP server's name/version, the Tandoor server version, and the compatibility status. No sibling tool in the list does anything similar, so an agent can select it unambiguously.

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 makes the use case clear (diagnostic/version lookup) and notes that it takes no arguments and causes no network call, which implies it is the cheap first step. It does not explicitly state when *not* to use it or name an alternative, but no sibling overlaps.

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

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

Beyond the annotations (which only say non-read-only, open-world, non-idempotent, non-destructive), the description discloses the internal fallback chain, the failure mode ('throws with an attempts log'), and the side effect of create_stub_on_failure writing an empty placeholder recipe. That is exactly the mutation and error behavior an agent needs before calling.

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 mechanism and its fallback are front-loaded, followed by a numbered recovery list that is easy to scan. The three numbered fallbacks are somewhat verbose for an agent that mainly needs the primary path, but each item maps to a real alternative tool.

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 mutation tool with no output schema, the description covers mechanism, failure behavior, stub creation, and recovery paths thoroughly. The only gap is that it never hints at what a successful response contains (e.g. what slim vs full return), which the agent must infer from the format enum.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds cross-parameter meaning the schema states only locally: create_stub_on_failure applies only when all stages fail, and name is only consumed in that stub path. It does not explain the slim/full format values beyond the enum, keeping it just short of a 5.

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

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

The description opens with a specific verb+resource ('Import a recipe from a URL') and immediately distinguishes this tool's mechanism (Tandoor scraper, then schema.org JSON-LD fetch) from sibling importers such as import_recipe_from_image and the manual create_recipe. An agent can tell exactly what this tool does and does not cover.

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

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

It gives explicit routing rules: use import_recipe_from_image for image/PDF pages (AI provider required), fall back to create_recipe for paywalled or JS-rendered URLs, and retry with create_stub_on_failure=true to capture a stub. When-to-use, when-not, and named alternatives are all present.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context beyond that: the input is a previously stashed payload, the operation extracts only what is needed, and examples show the expected output shapes. It does not cover failure modes such as invalid filters or expired handles, so it stops short of a 5.

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

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

Front-loaded with the core action and the triggering condition before the filter examples. Every sentence is relevant, though the example filter list partially duplicates the schema's `filter` description, so it is slightly redundant rather than wasteful.

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 no output schema, the description carries the burden of explaining returns and does so ('return the focused subset'), and it explains the stash lifecycle context that makes the handle meaningful. Missing are notes on what happens with an invalid filter or a stale handle, which would matter for a two-required-param query tool.

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

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

Schema coverage is 100%: both `handle` (with a UUID pattern) and `filter` are fully documented in the schema, including examples. The description adds only the framing that the handle comes from a prior tool result, and its filter examples largely duplicate those already in the schema. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

States a specific verb and resource: run a jq filter against a previously stashed tool result, returning a focused subset. The concept of a 'stash' is defined well enough (a JSON document produced by a prior tool) that it is clearly distinct from the sibling jq_stash_stats, which reports on stashes rather than querying them.

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?

Gives an explicit trigger condition: use this when a prior tool returned `{stashed:true, handle, shape, sample_filters}` instead of the full payload. That is a strong, checkable when-to-use signal. It does not name alternatives (e.g., jq_stash_stats) or state any when-not cases, which keeps it short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and a closed world, so the safety profile is fully covered by structured data. The description adds genuine context beyond that: the stash is in-memory, the response is a count plus byte total, and the tool is diagnostic in nature. It stops short of saying whether the stash is process-local or what counts toward the byte total, hence not a 5.

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

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

Two short clauses, zero filler, and the core resource is front-loaded ahead of the caveat. Nothing could be removed without losing either the purpose or the usage warning.

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 zero-argument read-only diagnostic with no output schema, the description is nearly sufficient: it explains the resource, the return shape, and the intended (rare) usage. A small gap remains in not clarifying scope — whether the stash is shared across the space or local to the request.

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

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

The tool takes zero parameters, so the schema is trivially complete and there is nothing for the description to compensate for. Baseline for a no-parameter tool applies.

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

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

States a specific verb and resource ("inspect the in-memory stash") and even names the return shape (count + total bytes), which is more than the title provides. It doesn't explicitly contrast itself with nearby sibling diagnostics like get_guard_stats, but the resource is distinct enough to be identifiable.

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?

"Diagnostic; not normally needed" gives a useful when-not-to-use signal that will keep an agent from calling it during normal recipe/shopping workflows. However, no alternative tool is named and no positive condition for when it IS appropriate is given, leaving the agent to infer that it is a troubleshooting-only call.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is fully covered by structured data. The description adds nothing behavioral beyond that: no pagination behavior, no default page size, no statement about what happens when query matches nothing, and no note on how tree/root interact.

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 definition is compact and front-loaded, with the purpose first and parameters after. It is telegraphic to the point of being fragmentary, but no sentence is wasted.

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 10-parameter tool with zero schema descriptions and no output schema, this description is too thin. Three parameters go undocumented and pagination/return-shape behavior is unstated, leaving the agent to guess at how to combine tree, root, and root_tree.

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 carries the full documentation burden. It gives useful glosses for query (case-insensitive name match), root (0 for top-level), tree, limit, page, and page_size, but omits format (an enum with slim/full), root_tree, and updated_at entirely, and the gloss for random ("random") conveys no meaning about expected value or format.

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?

"List foods" states a verb and resource, so the basic purpose is clear, but it essentially restates the title and gives no hint of how it differs from siblings like get_food or list_recipes. An agent knows it lists foods, but not the scope (all foods? tree of foods? filtered?) without reading the parameter hints.

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?

There is no when-to-use guidance, no prerequisites, and no mention of alternatives such as get_food for a single item or search_recipes for the recipe equivalent. The agent must infer usage entirely from the parameter glosses.

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

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

Annotations already cover readOnly, idempotent, and non-destructive, so the description's main added value is the non-obvious default that entries with amount 0 or less are hidden unless include_empty is true. That is a genuinely useful behavioral disclosure, though pagination behavior and any result ordering remain unstated.

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

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

Two compact clauses with the purpose front-loaded and the parameter list kept terse. Nothing is redundant, though the bare comma-separated name list is less scannable than a structured list would be.

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 6 parameters, no schema descriptions, and no output schema, the description leaves the format enum and pagination defaults undocumented. It covers the filtering semantics well enough to call the tool but not fully enough to use it 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%, so the description must carry parameter meaning. It explains include_empty well and lists location_id, food_id, page, and page_size by name only, and it omits the 'format' parameter (slim vs full) entirely.

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

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

States a specific verb+resource ("List inventory entries") and adds a clarifying gloss, "what is on hand, where," that distinguishes it from sibling tools like list_inventory_locations and list_foods. It does not explicitly name a sibling it is not, so it stops short of 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?

Usage is only implied: listing entries with optional filters by location and food. There is no explicit when-to-use statement, no mention of when to prefer list_inventory_locations, search_recipes, or a get_* tool, and no prerequisites described.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered elsewhere. The description adds no behavioral context of its own — nothing about ordering, result size, or whether locations are user-defined or fixed system values.

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?

One short sentence plus a parameter note — tightly front-loaded with no padding. The terseness borders on under-specification rather than wastefulness, but structure itself is clean.

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 tool with zero schema descriptions, one undocumented enum, and no output schema, the description should explain what a 'location' object contains and what slim vs full returns. It does neither, leaving the agent to guess at the payload shape.

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% across 3 parameters, so the description must compensate and largely fails: it names 'page' and 'page_size' but gives no defaults, bounds, or type info, and omits the 'format' enum (slim/full) entirely — the one parameter whose meaning is least obvious from its name.

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

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

States a specific verb and resource ('List inventory locations') and clarifies the domain with parenthetical examples (pantry, fridge, freezer). It reads clearly against siblings like list_inventory_entries, though it doesn't explicitly say how locations differ from entries.

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 when-to-use guidance, no exclusions, and no reference to the closely related siblings (list_inventory_entries, add_inventory_item). The agent must infer from the name alone that this is a lookup/ID-discovery call.

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

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

The annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered. The description adds only the semantic gloss "recipe tags" and a bare parameter list; it says nothing about pagination behavior, result ordering, or how tree/root modes change what is returned.

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

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

Two short sentences with the purpose front-loaded, so there is no padding. However, the brevity is under-specification rather than efficiency: the parameter dump conveys almost no usable information for its length.

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 10 optional parameters, 0% schema coverage, and no output schema, this description is far too thin to let an agent call the tool correctly. It omits three parameters entirely and gives no return-shape or paging context; only the annotations rescue basic safety expectations.

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% across 10 parameters, so the description carries the full burden and names 7 of them without any meaning attached. Worse, the omitted parameters (format, root_tree, updated_at) appear nowhere, and the ambiguous ones (tree vs root, random, limit typed as string) get no explanation of expected values.

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?

"List keywords" states a specific verb and resource, and the parenthetical "(recipe tags)" usefully disambiguates what a keyword is in this domain. It does not distinguish itself from the sibling get_keyword or explain how keyword listing relates to recipe listing, so it falls short of 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?

The only guidance is "Optional: query, root, tree, random, limit, page, page_size," which is a parameter inventory rather than a statement of when to use this tool. There is no mention of when to prefer get_keyword, when to use tree versus flat listing, or any precondition for calling it.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. Beyond that the description adds nothing: no default page size, no maximum, no ordering, and no indication of what a meal plan record contains or whether date filtering applies to plan dates or contained entries.

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

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

Two short, front-loaded fragments with no filler; the parameter list is compact. The opening sentence duplicates the title, which is the only wasted space.

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 no output schema and a zero-coverage input schema, the description carries most of the burden and leaves key questions open: pagination defaults, result ordering, and what fields a meal plan exposes. Adequate to invoke, but not complete enough for reliable use.

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

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

Schema description coverage is 0%, so the description must compensate. It names all four parameters and supplies the YYYY-MM-DD format for from_date/to_date, which is genuinely useful, but page and page_size get no semantics (defaults, limits) and the date-range inclusivity is unstated.

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?

"List meal plans" states a verb and resource, so an agent can tell it is a read/list operation rather than get/create/update/delete. However, the sentence is essentially a restatement of the title and name, and it draws no distinction from siblings like get_meal_plan or search_recipes.

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?

There is no guidance on when to use this versus get_meal_plan (single plan) or other list tools, and no mention of prerequisites or paging strategy. Usage is only implied by the verb "List".

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

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

The annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered by structured data. The description's only addition beyond that is the example value set, which helps set expectations about the result domain but says nothing about ordering, completeness, or whether the list is fixed or space-configurable.

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 short sentence with the resource and examples front-loaded and no wasted words. It is minimally structured (one fragment plus parenthetical) but nothing needs to be trimmed.

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 zero-parameter list tool with full annotation coverage, the description is nearly sufficient, but with no output schema the agent gets no hint about the shape of each meal type (id plus name?) or the ordering of results. One clause on the return shape would close the remaining gap.

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

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

The tool takes zero parameters, so the baseline is 4 and the schema has nothing that needs explaining. The description correctly implies no input is needed, matching the empty input schema.

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

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

The description states a specific verb ('List') and resource ('meal types') and parenthetically enumerates representative values (breakfast, lunch, dinner), so an agent immediately knows the returned domain. It does not, however, distinguish this from the sibling get_meal_type, which fetches a single meal type.

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?

Usage is implied rather than stated: an agent can infer this is the discovery/enumeration call, but there is no explicit 'use this when you need valid meal type values' framing and no mention of get_meal_type as the single-item alternative. No prerequisites or exclusions are given.

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

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

Annotations already establish readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely non-obvious behavior: the default slim payload's exact fields, that format="full" returns the raw API response, the complete sort_order vocabulary, and that unresolved names are silently dropped in the sibling tool. It does not mention pagination defaults or result-size limits despite page/page_size params.

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?

Front-loads the default return shape and the format toggle, then routing, then failure recovery — a sensible order. The inline sort_order enumeration is long but is high-value information an agent would otherwise have to guess at; there is little filler elsewhere.

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 44-parameter filter tool with no output schema, the description does well on output shape and tool routing, which is the highest-risk area. It falls short on the filter-semantics surface: the AND/OR/NOT array variants and the multiple date-range parameters are the main source of incorrect calls and are not addressed at all.

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 only 7% across 44 parameters, so the description must carry weight; it explains format, the sort_order value set, and that books/foods/keywords take ids rather than names. However, the large and easy-to-confuse families (foods_or vs foods_and vs foods_or_not, keywords equivalents, books_or_not, cookedon_/createdon_/updatedon_/viewedon_ range pairs, timescooked_gte/lte, makenow, num_recent, random) receive no explanation, leaving most parameters undocumented anywhere.

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

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

States a concrete verb and resource ("List/search recipes with extensive filtering") and immediately positions itself against search_recipes for name-based filtering. It is clear what the tool does, though the dual "list/search" framing leaves the primary intent slightly ambiguous compared with the sibling that is explicitly for searching.

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

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

Explicitly routes the agent: prefer search_recipes when filtering by food/keyword/book NAMES because it resolves names to ids and reports _meta.unresolved. It also prescribes recovery steps when the result set is empty (broaden query, drop filters, switch tools), covering both when-to-use and what-to-do-on-failure.

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

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

Annotations already declare this read-only, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds useful context about the payload shape being stripped of nested fields, but says nothing about pagination, limits, or how 'format' interacts with that payload.

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

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

Two tightly written sentences that lead with the distinguishing characteristic and end with the routing rule. No filler or restated naming.

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 no output schema, the description carries the burden of describing returns and does so by contrasting minimal metadata against the nested keywords/foods/steps of list_recipes. Only minor gaps remain around 'format' behavior and result volume/pagination.

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

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

Schema coverage is 100% and the single 'format' enum with its default is fully documented in the schema, so baseline 3 applies. The description never mentions 'format' and its 'returns minimal recipe metadata' wording slightly muddies what format=full would produce.

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

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

States a specific verb+resource ('returns minimal recipe metadata' for a recipe listing) and explicitly positions itself as a lighter variant of list_recipes. An agent can distinguish it from list_recipes from the text alone, though the sibling search_recipes is not addressed.

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?

Gives a clear use condition ('large browse queries') and names the alternative (list_recipes) with the condition that selects it (need keywords/foods/steps nested). No exclusions or guidance relative to search_recipes, which is the main gap.

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

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

Annotations already cover the read-only/idempotent/no-destroy profile, and the description adds real context beyond them: the server-side auto-filter to unchecked and recent entries, which materially affects what an agent will see. It stops short of explaining what 'recent' means or pagination defaults.

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

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

Three tight sentences with the core behavior front-loaded and zero filler; the parameter list is compact. The structure is efficient, though the parenthetical aside about filtering sits awkwardly at the end rather than near the relevant scope statement.

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 five-param, no-output-schema list tool, the description covers the critical filtering behavior and the list-filtering limitation, so an agent can call it. Gaps remain: the meaning of the mealplan number and any pagination defaults are absent, which matters given 0% schema coverage.

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 carry parameter meaning and it only partially does — it enumerates all five params and clarifies updated_after is ISO, but leaves 'mealplan' (a number) unexplained and says nothing about page/page_size defaults, even though format's enum is self-documenting in the schema.

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

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

States a specific verb and resource ('List shopping list entries') and adds a scope trait — results are auto-filtered to unchecked + recent by Tandoor. It implicitly distinguishes itself from list_shopping_lists by noting entries cannot be filtered by list, though it never names that sibling or get_shopping_entry explicitly.

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

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

Provides one useful usage constraint: entries cannot be filtered by shopping list, so callers should read the shopping_lists field of the results instead. It gives no guidance on when to use this versus get_shopping_entry or the bulk_* variants, leaving selection to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description still adds real value by disclosing the returned field set {id, name, description, color} and the sharing semantics across space members. It omits ordering and pagination defaults, which keeps it at 4.

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

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

Three short sentences, front-loaded with the resource and its scope, with no filler. The trailing "Optional: page, page_size" is the one sentence that earns little, since it repeats property names without adding 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?

With no output schema, the description usefully supplies the shape of returned items, so return values are adequately covered. However, for a paginated list tool it leaves defaults, ordering, and the purpose of the slim/full `format` option unexplained, so an agent can call it but not tune it.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning, and it largely does not. It names page and page_size only as "Optional" with no defaults or limits, and the `format` parameter with its slim/full enum is not mentioned at all, leaving an agent unable to choose a value.

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

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

States a specific verb and resource ("List the named shopping lists of this space") and adds scope plus an example ("one per store"), which makes it clearly distinct from list_shopping_entries. It never explicitly names a sibling or exclusion, so it stops just short of 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?

Usage is only implied: an agent can infer this is the enumeration call before touching entries or creating lists, but the description never says when to choose it over list_shopping_entries or list_meal_plans, nor any prerequisites. "Every member of the space sees the same lists" is behavioral context, not selection guidance.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so safety is covered; the description adds the domain model instead — tiered (off/simple/full) vs on/off sections, the permanent 'always' section, and the fact that mode changes emit tools/list_changed so the client refreshes mid-conversation. That is meaningful context an agent cannot get from annotations or the empty schema. It stops short of describing the exact shape of the returned section entries (no output schema exists), which keeps it below a 5.

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

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

Four short sentences, front-loaded with what is returned, then the mode taxonomy, then the side effect, then the call-ordering advice. Every sentence carries distinct information; nothing is repeated from the name or title.

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

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

With no parameters, no output schema, and simple read-only semantics, the description covers everything needed: what is listed, what each entry contains, what the modes mean, which section cannot be changed, and the refresh side effect. An agent can call it correctly on the first try.

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

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

The tool takes zero parameters, so the baseline is 4 and there is nothing for the description to disambiguate. The description correctly adds no parameter detail rather than inventing any.

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

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

States a specific verb and resource ('List every tool section') plus exactly what is returned per section ('its current mode and the modes it accepts'). It is clearly distinguished from the sibling mutators enable_tool_group and disable_tool_group, which are named directly.

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?

Gives an explicit ordering rule: 'Use this first to discover what is available before reaching for enable_tool_group.' It also implicitly excludes the write path (enable/disable) by pointing at them as follow-ups, so an agent knows which sibling to call next.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is covered without help. The description adds no behavioral context beyond that: no pagination behavior, no ordering defaults, no indication of what random returns.

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?

It is short and front-loaded, but the brevity comes at the cost of substance rather than being achieved through efficient wording. The parameter list is bare tokens with no structure or grouping.

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 seven parameters, zero schema descriptions, an unexplained enum, and no output schema, the description should carry substantial weight and does not. An agent cannot tell from this definition what a unit is or how to page or filter deterministically.

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% and the description merely re-lists five parameter names without meaning. It omits the format enum and the updated_at parameter entirely, and never clarifies the relationship between limit and page_size or what the string-typed random parameter does.

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 gives a verb and resource ("List units"), which is at least a statement of function, but "units" is never defined and the phrasing is essentially a restatement of the title. It offers no hint of how this differs from siblings such as list_foods, list_recipes, or list_inventory_entries.

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?

There is no when-to-use guidance, no indication of what a unit is in this domain, and no mention of alternatives. The agent is left to infer usage entirely from the name.

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

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

The annotations already declare this is a non-readonly but idempotent and non-destructive operation. The description adds meaningful behavior by noting that sub_location is optional and that null clears it, but it omits error behavior, what happens to the source entry, and the meaning of format.

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

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

Two short sentences are front-loaded with the core action and then the required/optional parameter details. There is no redundant or wasted wording.

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

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

The tool is a low-complexity mutation with annotations covering safety and idempotency, and the description covers the required parameters and null-clearing behavior. However, it omits explanation of the format parameter and any return or error context, which is notable because there is no output schema.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It explains three of four parameters, including the useful null-clearing semantics for sub_location, but it never explains the format enum (slim/full), leaving that parameter opaque.

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

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

The description states a specific verb and resource: 'Move a whole inventory entry to another location.' The word 'whole' adds useful scope, distinguishing it from partial inventory adjustments, but it does not explicitly differentiate itself from sibling tools such as add_inventory_item or consume_inventory_item.

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

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

It implies usage through the verb 'Move', but provides no explicit when-to-use or when-not-to-use guidance. It also does not mention alternatives like update or consume tools, so an agent must infer the selection context.

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

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

It discloses the non-obvious side effect that Tandoor writes new Food and Unit rows as a side effect, which goes well beyond the readOnlyHint=false annotation. It also covers edge cases the annotations cannot: blank text yields a 400, missing units return an empty string with unit_id omitted, and the heuristic parser can misfire on compound or non-English input.

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

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

Every sentence carries distinct information: output shape first, then write side effects, then normalization behavior, then error and reliability caveats. There is no filler, and the most consequential facts (database writes, idempotent-ish normalization) are front-loaded.

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

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

For a one-parameter tool with no output schema, the description supplies the return fields, side effects, normalization rules, error behavior, and reliability limits. An agent has everything needed to call it and interpret the response without further discovery.

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% for the single text parameter, but the description compensates with an inline example ("2 cups flour") and the blank-text failure mode. It explains return-field meanings (amount, unit, unit_id, food, food_id, note) rather than additional input semantics, so it does not fully exhaust what could be said about the input string.

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 first sentence names a specific verb (parse) and resource (free-form ingredient string) and lists the exact output fields, so the agent knows precisely what the call produces. It also implicitly distinguishes itself from create_ingredient and create_food by describing parsing rather than record creation.

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

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

The description establishes the parse-then-create workflow by noting that food_id and unit_id 'pass straight to create_ingredient', which tells the agent this is a preprocessing step. It stops short of explicitly stating when not to use it or naming an alternative for cases like already-structured input, so it falls just below full when/when-not guidance.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description adds genuinely new behavioral content the annotations do not carry: the default response is a slim projection of id + name, and format="full" returns the raw upstream API payload. It stops short of noting ordering, result limits, or what happens with an unknown id.

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

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

Two short clauses with zero filler; the default behavior is stated before the opt-in override. Nothing is repeated from the title and every phrase carries 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?

For a simple two-parameter read-only tool with no output schema, the description covers the essentials: what is returned by default, how to get everything, and what the id means. Only minor gaps remain, such as whether an empty result is possible or how the returned ids can be fed into get_recipe.

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 50%: the enum on format is documented in the schema, but id has no description. The description partially compensates by framing id as 'this one' (the source recipe whose relations are listed) and by restating the slim/full trade-off in terms of payload detail. Given the moderate coverage gap, this lands at the baseline rather than above it.

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 gives a specific verb and resource ('List recipes') plus a clear scope qualifier ('related to this one') and names the underlying mechanism (Tandoor similarity), which distinguishes it from plain list_recipes or query-based search_recipes. It does not explicitly name those siblings, so an agent must infer the distinction rather than being told it.

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?

Usage is implied by 'related to this one' and by the id parameter, but there is no explicit when-to-use versus when-to-use-something-else statement, nor any prerequisite guidance (e.g. that the recipe id must exist). The format guidance is parameter-level, not usage-level.

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