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

No annotations are provided, so the description carries the full burden. It does not say that this is a mutating write, whether it requires authentication or ownership, whether the comment is publicly visible, or whether duplicate comments are allowed. The vague '(rating, notas, feedback)' hint is not a behavioral disclosure.

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 no padding, and the action plus target are front-loaded. It is efficient, though its brevity is achieved partly by omitting required 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?

This is a mutation tool with zero annotation coverage and 0% schema description coverage on two required parameters. An output schema exists so return values need not be explained, but the missing slug provenance and write-side effects leave the definition inadequate for correct invocation.

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

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

Schema description coverage is 0%, so the description must explain both parameters and does not: 'slug' is never identified as the recipe identifier or told where to obtain it, and 'text' is not described as free-form comment content or given format/length constraints. The parenthetical gestures at content types but provides no usable semantics.

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 ('Anade un comentario a una receta') and names the platform (Mealie), so the agent knows this creates a recipe comment rather than touching meal plans or shopping lists. Sibling differentiation comes from the resource noun alone; the parenthetical '(rating, notas, feedback)' muddies rather than sharpens the purpose.

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

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

No guidance on when to use this instead of update_recipe or tag_recipe, and no prerequisites such as the recipe needing to exist or the slug needing to come from search_recipes/get_recipe. The agent must infer all call conditions.

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

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

With no annotations, the description carries the full burden and does add value: human approval is required pre-call, items are stored as unparsed notes (no interpretation), and scaling uses the explicit multiplier. It still omits whether entries append or replace existing list contents, how duplicates are handled, and what happens if list_id is invalid.

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 with the behavioral constraint front-loaded and no filler. Slightly terse phrasing ("exactly one source") costs a bit of clarity, but nothing 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 6-parameter mutation tool with no annotations and no output schema, the description covers the consent requirement and partial parameter meaning but leaves the agent guessing on append-vs-replace behavior, per-parameter roles for the mealplan dates, and the result 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 coverage is 0% across 6 parameters, so the description must compensate. It clarifies the semantics of two of them (items as unparsed notes, servings_multiplier for recipe scaling) and implies mutual exclusivity of the three source parameters, but list_id, mealplan_start, and mealplan_end get no explanation at all.

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 verb (add) and general target (a list) are clear, but "exactly one source" is ambiguous — the schema shows three distinct source shapes (items, recipe_slugs, mealplan range) and the description never names them. It also doesn't distinguish itself from siblings like create_shopping_list or get_or_create_shopping_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?

It gives a real precondition ("client must get user approval before calling") and an implicit constraint (exactly one source per call), which are useful usage rules. But there is no guidance on when to pick this tool versus create_shopping_list or get_or_create_shopping_list, nor any exclusion criteria.

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

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

With no annotations, the description carries the full load, and it does disclose one meaningful behavioral trait: an all-or-nothing validation that every item must belong to the list before any state change. It does not say what happens on validation failure (error vs partial write), whether the operation is idempotent, or that it is a mutation.

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 sentence with no filler, so nothing is bloated. But it is front-loaded on a constraint rather than on the core purpose, which is a poor ordering choice for a one-sentence 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 mutation tool with no annotations, no output schema, and 0% parameter documentation, this description is too thin. An agent still lacks the boolean semantics, failure behavior, and the relationship to the sibling read/add/remove tools.

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% with three parameters, so the description must compensate and largely does not. It implicitly touches all three ('checked state', 'every requested item', 'the list') but never explains that 'checked' is a boolean defaulting to true, so an agent cannot tell whether omitting it marks items checked or unchecks them.

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

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

The description states a specific action ('Set checked state') tied to list items, and the tool name supplies the resource. However, it leads with an implementation precondition ('only after verifying...') rather than plainly saying it marks shopping-list items as checked/unchecked, and it does not distinguish itself from siblings like add_to_shopping_list or remove_shopping_list_items.

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

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

There is no statement of when to use this versus the many sibling shopping-list tools (get_shopping_list_items to read state, add_to_shopping_list to add, clear_shopping_list to reset). The precondition is mentioned, but no usage context or exclusion is 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?

With no annotations, the description carries the full load and does disclose the most important behavior for a destructive tool: a dry-run default with an explicit confirm gate. It omits irreversibility, scope of deletion (all entries vs. only mealplan), and permission requirements.

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 tight sentence with zero filler, front-loading the dry-run behavior and then the action trigger. Nothing redundant.

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

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

An output schema exists, so the preview/result shape needn't be explained. But for a destructive operation with no annotations, key facts are missing: whether deletion is irreversible, date format/inclusivity of the range, and whether 'week' in the name constrains the range.

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 confirm meaningfully (default = preview, True = execute), which is the non-obvious parameter, but says nothing about start_date/end_date format or inclusivity despite both being required strings.

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 (remove/clear) and resource (mealplan entries in a date range), plus the preview behavior. It implicitly distinguishes itself from the single-entry sibling delete_mealplan_entry, though it never names it, and the name's 'week' scope is broader in the description as an arbitrary date range.

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 operating condition: call as-is to preview, pass confirm=True to actually clear. That is a real when-to-use rule for the two modes. It stops short of naming delete_mealplan_entry as the alternative for removing a single entry.

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

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

With no annotations, the description carries the disclosure burden and does the most important part: it flags a destructive bulk operation and documents the built-in dry-run safety gate via confirm. It omits whether the cleared items are recoverable and whether the list container survives, which are the remaining behavioral unknowns.

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 tight sentence that front-loads the default preview behavior and then the confirm escape hatch. No filler, no repetition of the tool name.

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

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

An output schema exists, so return values needn't be described, and the two parameters' core semantics are covered. The remaining gap is relationship to the adjacent delete_shopping_list and remove_shopping_list_items tools, which a destructive tool should ideally disambiguate.

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 fully explains the confirm parameter's dual preview/execute semantics and default-off behavior, but says nothing about list_id beyond its name, leaving scope (which list, ID format) undocumented in both places.

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: removes all shopping items from a list, and clarifies the operation is previewed by default. It contrasts implicitly with remove_shopping_list_items by emphasizing 'all', but never names that sibling to make the boundary explicit.

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 clear operational context: calling without confirm produces a preview, and passing confirm=True performs the clear. No exclusions or sibling routing are stated (e.g., use remove_shopping_list_items for selective removal or delete_shopping_list to remove the list itself), so the agent must infer those boundaries.

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?

No annotations are provided, so the description carries the full disclosure burden, yet it only says a recipe is created. It says nothing about required permissions/auth, duplicate-name behavior, which fields are ignored, or whether defaults are applied — all material for a mutation tool with eight inputs.

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 zero filler; the disambiguating clause is attached directly to the action 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?

An output schema exists, so return values need not be explained, and the tool has no nested objects. But with zero annotation coverage and 0% parameter documentation, the definition leaves the agent without any of the field-level or behavioral context needed to call an 8-parameter create tool confidently.

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

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

Schema description coverage is 0% across 8 parameters, so the description must compensate and does not: no parameter is named or explained beyond the vague phrase 'structured fields'. Format expectations for total_time, ingredients, or instructions — none of which are documented in the schema — are left entirely 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?

States a specific verb and resource (create a recipe) plus the mechanism (structured fields), and explicitly contrasts with URL import, which maps onto the import_recipe sibling. An agent can distinguish it from import_recipe and update_recipe 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?

'not URL import' implicitly routes URL-based creation to import_recipe, giving a clear selection rule. It does not name the sibling explicitly or state other exclusions (e.g., when to use update_recipe instead), so it stops short of 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?

With no annotations, the description carries the full disclosure burden. It usefully states the new list will be empty, but says nothing about duplicate-name handling, permissions, whether creation overwrites anything, or idempotency — the failure modes an agent most needs to know about for a create operation.

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

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

A single front-loaded sentence with no filler. It is perhaps too terse given the 0% schema coverage, but it is efficient rather than 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?

An output schema exists, so return values need not be explained, and the single required parameter is simple. However, for a create tool with no annotations and an undocumented parameter, the description leaves duplicate-name behavior and post-creation state implicit.

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 for the undocumented 'name' parameter. 'Con el nombre indicado' merely restates the parameter name; no constraints on format, uniqueness, or length are given.

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 ('Crea una nueva lista de compra') plus the key qualifier 'vacía', which distinguishes it from add_to_shopping_list or get_or_create_shopping_list. It stops short of explicitly naming the sibling it is not, so it lands at 4 rather than 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?

There is no guidance on when to use this versus get_or_create_shopping_list or get_shopping_lists, both of which are plausible alternatives for the same intent. No mention of prerequisites or what happens if a list with that name already exists.

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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It says deletion happens but omits whether the deletion is irreversible, what happens if the entry_id does not exist, and required permissions — all critical for a destructive operation.

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

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

One short, front-loaded sentence with no wasted words; the action and targeting mechanism appear immediately. It is efficient, though efficiency here partly reflects under-specification rather than discipline.

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 (one required string) and an output schema exists, so return values need no explanation. However, for a delete operation with no annotations and an undocumented parameter, the description should at minimum flag irreversibility and where the entry_id comes from.

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 parameter carries only the title 'Entry Id', so the description must compensate. 'por su ID' merely restates that the argument is an identifier without giving format, source (e.g., from get_mealplan_week), or validation expectations.

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 (Elimina) and resource (entrada del plan de comidas) plus the identifier used to target it. It implicitly distinguishes itself from clear_mealplan_week and set_mealplan_entry by scoping the action to a single entry, though it never names those siblings 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?

There is no guidance on when to use this instead of clear_mealplan_week or set_mealplan_entry, and no stated prerequisites such as needing a valid existing entry_id. The agent must infer usage purely from the name and one-line description.

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

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

With no annotations present, the description carries the full burden and it does disclose the most important trait: the default is a non-destructive preview and only confirm=True destroys data, and the deletion is stated as permanent. It doesn't say what happens to the list's items, whether the call errors on a missing list, or what permissions are needed.

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 sentence, front-loaded with the default (preview) behavior and ending with the opt-in destructive action. Nothing extraneous to trim.

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

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

An output schema exists, so return values needn't be explained, and with only two parameters the description covers the one that matters. Minor gaps remain around side effects on list items and behavior for an invalid list_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 must compensate; it fully explains the confirm flag's two values and the default behavior, which is the only non-obvious parameter. list_id is left implicit, relying on the name alone.

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 a shopping list) plus the two-mode semantics folded into the same sentence. It does not differentiate from the nearby clear_shopping_list or remove_shopping_list_items siblings, which an agent could plausibly confuse with this.

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 operational rule: the default call previews, and confirm=True performs the permanent deletion. What's missing is any guidance on when to prefer this over clear_shopping_list or remove_shopping_list_items.

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?

No annotations are provided, so the description carries the full behavioral burden and delivers almost nothing: no statement about permissions, what happens with an empty range, whether days with no entries are returned, or how the week is keyed. It only discloses the date format, which is a parameter detail rather than behavioral context.

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

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

A single front-loaded sentence with zero padding; the date-format constraint is placed immediately after the scope. It is efficient, though so terse that the 'week' vs. 'range' tension in the name is never resolved.

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

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

An output schema exists, so return values need not be explained, and the format hint covers the main invocation risk. Still, for a two-required-parameter tool with 0% schema coverage and no annotations, the description should state inclusive/exclusive bounds and range constraints to be complete.

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

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

Schema coverage is 0% — the two properties carry only titles ('Start Date', 'End Date') — so the description's '(YYYY-MM-DD)' format note is genuinely valuable and prevents a common formatting error. However, it does not clarify whether start_date/end_date are inclusive, whether end must be >= start, or any maximum range, leaving real ambiguity for two required parameters.

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

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

States a specific verb and resource ('Obtiene el plan de comidas') plus the scope ('un rango de fechas'), which clearly frames this as a read over a time window and separates it from mutation siblings like set_mealplan_entry and delete_mealplan_entry. Minor friction: the tool name says 'week' while the description describes an arbitrary range, leaving a small ambiguity about intended granularity.

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 read nature and date-range scope imply when the tool applies, but there is no explicit when-to-use, no mention of clear_mealplan_week or get_recipe as alternatives, and no prerequisites or limits stated. The agent must infer usage from the verb alone.

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

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

With no annotations, the description carries the burden and does disclose the key side effect: a write occurs when the list doesn't exist. It also notes the return of the ID. It does not cover permission requirements, duplicate-name handling, or case sensitivity of the name match — meaningful gaps for a mutating 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?

Two short sentences with zero waste, and the conditional behavior is front-loaded before the return guarantee.

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 one-parameter tool with an output schema documenting the returned ID, the description covers the essential behavior. Minor missing context around name matching and permissions keeps it from a 5.

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 'name' parameter, so the description must compensate. 'por nombre' indicates the name is both the lookup key and the creation value, which is useful, but format or uniqueness expectations are not specified.

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 combined operation: looks up a shopping list by name and creates it if absent. The verb+resource is precise and the get-or-create semantics are unambiguous, though it doesn't explicitly name sibling tools like get_shopping_lists or create_shopping_list to differentiate itself.

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 implicit use case is clear — call it when you want a list by name without knowing whether it exists. However, there is no explicit guidance on when to prefer this over create_shopping_list or get_shopping_lists, nor any stated preconditions.

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

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

With no annotations provided, the description carries the full burden. It does disclose the key non-obvious trait: this call has a write side effect (creates the tag when missing) and matching is case-insensitive. It does not state whether the call is idempotent under concurrent calls, whether it requires write permissions, or what happens on name conflicts, which are meaningful gaps for a get-or-create mutation.

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 compact sentence that front-loads the primary behavior (search) and then the conditional fallback (create). No filler, no repetition of the tool name.

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

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

The output schema exists, so return values need not be explained. However, for a tool whose name suggests a read but which performs a conditional write with no annotations at all, the description should say more about permissions, failure modes, and duplicate-handling to be complete.

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

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

Schema description coverage is 0% for the single `name` parameter, so the description must compensate. It adds real value by clarifying that `name` is the lookup key and that matching is case-insensitive, but it says nothing about format constraints (trimming, allowed characters, length limits) that determine whether the lookup will hit an existing tag or silently create a near-duplicate.

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 resource (tag) and states both behaviors: lookup by name and creation if absent, including the case-insensitive match rule. An agent immediately understands this is a lookup-or-create idiom rather than a pure read or pure write. It doesn't explicitly contrast with siblings, but no sibling duplicates this operation (tag_recipe attaches tags to recipes, which is a different action).

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 infers it should call this when it needs a tag reference without knowing whether the tag already exists. There is no explicit statement of when to prefer this over a plain lookup, no prerequisite or ordering guidance, and no note about what to do if the name is ambiguous or invalid.

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

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

With no annotations, the description carries the full burden, and it does disclose one useful trait the schema cannot: missing data is returned as null rather than omitted. It does not address what happens for a nonexistent slug, whether access is scoped to the caller's own recipes, or whether the read is cached/rate-limited.

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 sentence, front-loaded with the verb and the returned content, with the null-handling caveat trailing where it belongs. No filler or redundant restatement of the name.

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

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

An output schema exists, so return shape need not be explained and the description's field summary is a bonus. For a simple one-parameter read, though, the slug lookup semantics and not-found behavior are the remaining pieces an agent needs and they are absent.

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 required parameter, slug, is never mentioned in the description, so an agent gets no guidance on its format (URL slug vs ID) or whether it must be an exact match. The description does nothing to compensate for the coverage 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?

"Read structured ingredients, instructions, taxonomy and times" gives a specific verb and enumerates the resource contents, which clearly separates it from write siblings like update_recipe or create_recipe. It never says the resource is a recipe or that it targets a single one, relying on the tool name for that.

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 statement of when to use this versus search_recipes (discovery) or get_mealplan_week (plan context). Usage is only implied by the word "Read"; there are no alternatives or exclusions named.

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

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

With no annotations, the description carries the full burden, and it does add real signal: 'Read' implies a non-mutating operation and 'paginate locally' discloses that paging happens after retrieval rather than server-side. It omits return shape, item ordering, and whether unchecked/checked/null all behave differently, so the disclosure is partial.

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 compact sentence with the resource and the two key behaviors front-loaded; no filler. It is slightly telegraphic ('paginate locally' is doing a lot of unexplained work), which keeps it from a 5.

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 4-param read tool with no annotations and no output schema, the agent still lacks the item record shape, ordering, and the exact checked-flag semantics. It is minimally sufficient to invoke but not to predict 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?

Schema description coverage is 0%, so the description must compensate, and it does touch all four params indirectly: 'one list's items' (list_id), 'filter checked state' (checked), 'paginate' (page/per_page). It leaves the checked polarity ambiguous (does true return only checked items or exclude them?) and never mentions the per_page=100 / page=1 defaults.

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: 'Read one list's items', which separates it from the list-level sibling get_shopping_lists. It never names the item-mutating siblings it could be confused with (check_shopping_list_items, add_to_shopping_list), so it is clear but not sibling-differentiating.

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

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

The description implies usage (you need a known list_id and may want to filter by checked state) but gives no explicit when-to-use or when-not. It does not route the agent away from get_shopping_lists or toward check_shopping_list_items for item mutation.

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?

No annotations are provided, so the description carries the full burden. It discloses the scope of the result ('todas las listas del hogar') which is useful context, but says nothing about read-only nature, permissions, pagination, or behavior when the household has no lists.

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. It is appropriately sized, though being one clause it cannot carry much structure.

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

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

An output schema exists, so return-value explanation is not required, and there are no parameters to document. However, for a tool with no annotations at all, the description omits any mention of scope limits (e.g., shared vs personal lists) or safe read behavior, leaving minor gaps.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline is 4. The description correctly signals that no filtering arguments exist by saying 'todas'.

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 ('Devuelve todas las listas de compra del hogar') and names the returned fields (IDs and names), so the agent knows exactly what it gets. It does not distinguish itself from siblings like get_or_create_shopping_list or get_shopping_list_items, so an agent must infer the difference.

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: 'todas las listas del hogar' suggests a discovery/listing call, typically used before add_to_shopping_list or get_shopping_list_items. There is no explicit when-to-use, when-not-to-use, or named alternative, so routing between the many shopping-list siblings is left 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?

With no annotations, the description does real work: it warns that video previews can download media and incur LLM costs, and that image creation has no read-only preview (a genuine side-effect warning). It doesn't state what an import actually creates, whether it's reversible, or what is returned, so the burden from missing annotations isn't fully met.

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, factual sentences with the cost/side-effect caveats front-loaded after the core purpose. No filler, though it could be tighter by pairing caveats with the parameters they apply to.

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 cost-incurring import with no annotations and no output schema, the description covers the major risks (LLM cost, no image preview, unsupported local paths) but leaves parameter meanings and the result of a real import undocumented, so an agent still lacks enough to call it precisely.

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?

Six parameters at 0% schema coverage means the description must carry all parameter meaning, and it does not. It only implicitly gestures at dry_run ('preview' vs 'import'), kind ('video'/'image'), and source ('local media paths unsupported'); max_recipes, min_confidence, and language are entirely unexplained.

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

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

States a specific verb ('import') and resource ('recipes'), plus the preview capability. It's distinguishable from create_recipe by implying ingestion from an external source, but it never names the adjacent siblings (create_recipe, add_recipe_comment) to sharpen the boundary.

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?

'Preview or import' plus the note that image creation has no read-only preview implies the when-to-use context (safely preview video, beware image). However there is no explicit guidance on choosing this over create_recipe, nor on defaults like dry_run=true, leaving the agent to infer usage.

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?

No annotations are provided, so the description carries the full behavioral burden, and it discloses almost nothing: 'Registra' implies an additive write, but there is no statement on permissions, whether entries are editable/removable, or whether repeated calls duplicate. No output schema explanation is needed, but for an unannotated mutation tool this is a significant gap.

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 tight sentence with the action and scope front-loaded and the bilingual gloss aiding disambiguation; no filler. Its brevity tips into under-specification rather than being 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?

For an unannotated write tool with two required, undocumented parameters, the description leaves the agent guessing at the semantics of 'subject' and at the mutation's side effects. An output schema exists, so return values need not be described, but the input side is badly under-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% across three parameters, so the description must compensate and does not. It implies 'slug' identifies the recipe, but 'subject' — a required parameter — is never explained (event type? title?), nor is the optional 'message' differentiated from 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?

States a specific verb ('Registra') and resource ('un evento en el timeline de una receta'), with the parenthetical English gloss clarifying 'cooking log / historial'. An agent can tell it creates a log entry on a recipe timeline, though it never distinguishes itself from the closest sibling, add_recipe_comment, which also attaches text to 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?

There is no when-to-use guidance, no exclusions, and no mention of the plausible alternative (add_recipe_comment) for attaching text to a recipe. The agent must infer that this is for cooking-history entries rather than comments purely from the noun 'timeline'.

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

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

With no annotations, the description carries the full burden, and it does disclose the important safety trait: a dry-run default with an explicit confirm gate. It stops short of stating irreversibility, permission requirements, or what happens to item_ids that don't match verified list contents.

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 clause that puts the safety-relevant preview behavior first and the destructive trigger second. Zero filler and nothing buried.

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 with no annotations, no output schema, and zero parameter documentation, the description covers the execution gate but not the scope question (list_id), the ID verification mechanism, or any hint of the preview payload shape. Just enough to call it, not enough to call 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 compensate for all three parameters. It explains confirm (default false → preview, true → executes) and adds the constraint that item_ids must be 'verified' IDs, but list_id and the format/verification source of item_ids are left undocumented.

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 ('item removal') scoped to a shopping list, and the 'Preview ... confirm=True deletes' phrasing makes the two-phase nature explicit. It doesn't name distinguishing siblings like clear_shopping_list or delete_shopping_list, but the operation itself 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?

The description implies the default call is a safe preview and that confirm=True is the destructive path, which is useful when-to-use signal. It never says when to prefer this over clear_shopping_list or delete_shopping_list, so the agent must infer the boundary from sibling names alone.

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

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

With no annotations provided, the description carries the full disclosure burden, and it does establish this is a non-mutating introspection call (it describes rather than changes configuration). It does not state whether the config is static or reflects live registration state, whether the response is cached, or the shape of the returned data.

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

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

One front-loaded sentence with no filler; each phrase carries meaning (configured toolsets vs. actually registered tool surface). It is appropriately sized, though the terminology could be made more concrete without adding 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 no annotations, no parameters, and no output schema, the description is the only source of information, and it stops at naming the topic. An agent still doesn't know whether the response is a list of tool names, per-toolset configs, or enabled/disabled flags, which matters for a discovery tool with no schema to fall back on.

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, which is the baseline-4 case; no parameter semantics are needed or missing. The description correctly frames the call as argument-free by describing a global inspection of configuration.

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 pairs a specific verb ("Describe") with a concrete resource (configured toolsets and the registered tool surface), which is clearly distinct from every sibling's recipe/shopping-list/mealplan domain. The terms "toolsets" and "registered tool surface" are mildly abstract, leaving some ambiguity about exactly what is reported, so it stops 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?

Usage is only implied: an agent can infer this is a discovery/introspection call to run before (or instead of) guessing which capabilities exist. There is no explicit statement of when to call it, when not to, or what to do with the result relative to the sibling recipe tools.

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

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

No annotations are provided, so the description carries the full burden. It hints that pagination is handled 'upstream' and that filtering is by stable IDs rather than names, but never states that this is a read-only operation, what the defaults are, or how the 11 filters combine.

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. It is efficient, though its brevity comes at the cost of the missing semantics noted above.

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?

Eleven undocumented parameters, zero schema descriptions, and no annotations means the agent must guess at filter-combination behavior and result sizes. Only the presence of an output schema lightens the burden slightly; the description as written is inadequate for a tool of this complexity.

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 11 parameters, so the description must compensate and barely does. It mentions sorting by name and pagination, but leaves opaque the critical 'require_all' flag (AND vs OR of filters), 'direction', 'per_page', and how tag_ids/food_ids/tool_ids/category_ids/cookbook_id interact.

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?

Names a specific verb ('Search') and resource ('recipes') and adds scope detail (filter-ID based, paginated, sortable by name). It does not distinguish itself from sibling 'suggest_recipes', which an agent could plausibly confuse with a text-search tool.

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 and no named alternative among the many recipe siblings (get_recipe, suggest_recipes, create_recipe). Usage is only implied by the verb 'Search'.

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?

No annotations are provided, so the description carries the full behavioral burden. It does not say whether an entry at the same date/type is overwritten or duplicated, what permissions or preconditions are required (e.g., recipe_slug must exist), or anything about the mutation's effects.

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

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

Two short sentences with no filler and the purpose is front-loaded. However, the brevity comes at the cost of under-specification rather than being a model of tight structure.

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

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

An output schema exists, so return values needn't be explained. But for a 4-parameter mutation tool with zero annotation and zero schema-description coverage, key details (date format, recipe linkage, duplicate handling) are missing.

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

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

Schema description coverage is 0%, so the description must compensate, and it only clarifies entry_type's allowed values (lunch|dinner|breakfast|side) — valuable since the schema lacks an enum. It leaves date_str's expected format, title's meaning, and the optional recipe_slug linkage completely undocumented.

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 ('Añade') and resource ('entrada al calendario de Mealie'), so the agent knows it creates a meal-plan entry. It is implicitly distinct from get_mealplan_week and delete_mealplan_entry, but doesn't name or contrast with them.

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

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 siblings like delete_mealplan_entry, clear_mealplan_week, or how it interacts with get_mealplan_week. The agent must infer the calling context entirely.

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

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

With no annotations, the description carries the full burden, and 'preserving missing foods and tools' is the only behavioral hint — it vaguely gestures at allowing incomplete matches but doesn't state that results may omit ingredients, how they're ranked, or that this is a non-mutating query. Defaults like max_missing_tools=0 that silently restrict results go unmentioned.

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, so it is concise, but for a six-parameter tool it is undersized — brevity here comes at the cost of information rather than from efficiency.

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

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

An output schema exists, so return values needn't be described, but with no annotations, six undocumented parameters, and no differentiation from search_recipes, an agent lacks what it needs to invoke this confidently. The one-line description is not adequate for this complexity.

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 every parameter depends on prose. The sentence mentions foods and tools, but limit, max_missing_foods, max_missing_tools, and include_foods_on_hand are never explained, and even the two named params get no format or semantics beyond '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 verb 'suggest' and resource 'recipes' are specific, and 'from food/tool IDs' narrows the input domain. However, it never distinguishes itself from the sibling search_recipes, so an agent cannot tell which of the two to pick without opening both schemas.

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 at all: nothing says this is for ingredient-driven recommendations versus explicit search, nor when the missing-ingredient tolerance should be relaxed. The relationship to search_recipes is left entirely 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?

With no annotations, the description must carry the behavioral burden. It usefully discloses that the operation is additive and preserves existing tags, but it does not mention permissions, idempotency, duplicate handling, or error 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 two short, front-loaded sentences with no wasted text. The key behavior is stated immediately and clearly.

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

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

The tool is a simple two-parameter mutation with an output schema, but both parameters are undocumented and there are no annotations. The description covers additive behavior but leaves important parameter and operational context unspecified.

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

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

Schema description coverage is 0%, so the description should compensate by explaining the parameters. It mentions tags conceptually and refers to a recipe, but does not clarify that 'slug' identifies the recipe or that 'tags' is an array of tag names.

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

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

The description states a specific verb and resource: assigning tags to a recipe. The additive behavior is also clear, but it does not explicitly distinguish this tool from alternatives such as update_recipe or create_recipe.

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

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

The phrase 'Conserva tags existentes y anade los nuevos' implies that this tool should be used when appending tags without replacing existing ones. However, it does not explicitly name alternatives or state when not to use this tool.

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

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

With no annotations and no schema descriptions, the description carries the full behavioral burden. It discloses one important trait—arrays replace whole lists—and hints at preview mode, but says nothing about permissions, irreversible changes, the role of the confirm flag, or what happens on validation errors.

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 core action and followed by a critical semantic note about arrays. It is efficient and avoids waste, though its terseness leaves the reader wanting more detail given the tool's complexity.

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

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

The tool has a nested patch object, three parameters with zero schema descriptions, no annotations, and a confirm flag that is never explained. The description is far too thin to be helpful for correct invocation, even though an output schema exists to cover return values.

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 explains array replacement semantics for the patch object but never mentions the required slug, the confirm boolean, or the nested patch structure. It adds limited meaning beyond what the schema titles already imply.

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 says 'Preview or PATCH selected fields', which implies partial update but never names the resource (recipe). The tool name provides context, but the description alone gives only a vague purpose without explicitly distinguishing it from siblings like create_recipe or import_recipe.

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

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

No explicit guidance on when to use this tool versus alternatives such as create_recipe or import_recipe. The mention of 'Preview or PATCH' hints at a dry-run vs apply pattern, but there are no conditions, prerequisites, or named alternatives to help an agent choose correctly.

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