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

With no annotations provided, the description carries the full behavioral burden. It discloses that the updated day is returned after confirmation, that dry_run validates/previews changes without sending, and that ID source handling is automatic (auto mixed support). This is meaningful behavioral context beyond what the schema provides, though it doesn't mention auth requirements, failure modes, or partial-add behavior on invalid IDs.

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 three short sentences, each adding distinct value: purpose, formatting/options, and result behavior. Zero redundancy, front-loaded with the core purpose. Very efficient for the information 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 has 4 params (2 required), an output schema, and 1 enum. The description covers the multi-ID input format, source auto-detection, and the returned day. It doesn't elaborate on return format beyond 'updated day', but given an output schema exists, that burden is covered. The description is complete for a moderate-complexity mutation tool, though it could benefit from noting error behavior on invalid IDs.

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 schema documents parameters fully. The description adds value by explaining the mixed ID format (official numeric vs custom ULID), the exact separator behavior (commas, spaces, newlines), and the auto-detection behavior of recipe_source — details not in the schema. It contributes extra nuance on the recipe_ids and recipe_source parameters beyond the basic schema definitions.

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

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

The description clearly states the verb (Add) and resource (recipes to a Cookidoo meal-plan day), with a specific scope (one or more recipes). It distinguishes this tool from siblings like remove_recipe_from_meal_plan and move_recipe_in_meal_plan by its action (add) targeting meal-plan days. The use of 'meal-plan day' is specific and precise.

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 gives clear context on when to use this tool (to add recipes to a meal plan) and specifies input formatting (mixed IDs, separators). It doesn't explicitly call out when NOT to use it versus alternatives like copy_recipe_to_custom or move_recipe_in_meal_plan, but the sibling set makes the purpose distinct enough. The recipe_source explanation helps clarify when to use auto vs explicit source selection.

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 behavioral disclosure burden. It does explain the technical behavior (UTF-16 position calculation differing from Python indexes), which is genuine behavioral context. However, it doesn't disclose what the return value/offset semantics are beyond the name, and there's an output schema available which likely covers the return shape. The emoji caveat is helpful behavioral detail.

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

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

The description is two sentences and front-loads the core purpose in the first line. The technical explanation in the second sentence earns its place. It's efficient and focused, though the explicit 'Use this tool for...' guidance adds value without bloating 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?

Given the tool has an output schema (which likely covers return values), the description appropriately focuses on input semantics and the technical reason for the tool's existence. It explains the UTF-16 vs Python indexing difference which is the key constraint. It doesn't describe edge cases (multiple markers, occurrence semantics) but the output schema and narrow scope make this reasonably 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%, so the description must compensate. It explains the 'text' and 'marker' parameters implicitly through context (text inside a recipe step, marker for TTS/MODE/etc.), but doesn't explicitly document each parameter. The 'occurrence' parameter (default 1) is not mentioned at all. With 3 parameters at 0% coverage, the description should do more to explain each parameter's 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 description clearly states this tool calculates Cookidoo's offset and length for text markers (TTS, MODE, INGREDIENT, VOLUME) inside recipe steps. It explains the technical why (JavaScript UTF-16 vs Python string indexes with emoji) and names the specific verb+resource. The sibling context confirms this is a unique utility distinct from recipe retrieval and mutation tools.

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 explicitly says 'Use this tool for every TTS, MODE, INGREDIENT, and VOLUME annotation,' which is clear when-to-use guidance. It doesn't explicitly state when NOT to use it or name alternatives, but the purpose is narrow enough that this is largely implicit. Could add a note about when a plain Python index would suffice, but the guidance is strong.

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 full behavioral burden. It effectively discloses that this is a stateful operation (stores a session), describes a 4-step internal process including credential loading from .env and country/language normalization (defaulting to ro/en), and documents error conditions (ValueError for missing credentials, Exception for auth failure). This is rich behavioral disclosure beyond the minimal 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?

The description is well-structured with numbered steps, a return type section, and error documentation. It's comprehensive but not bloated. Minor deduction for the Returns/Raises sections being somewhat formal/code-like, but overall every section earns its place and there is no wasted prose.

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 authentication setup tool, this description is thorough: it explains the full authentication flow, environment file requirements, localization logic, default values, success/failure outcomes, and error types. The output schema exists, so return value details are covered structurally. Given the tool's relative simplicity and the presence of an output schema, this is 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?

The tool has 0 parameters, so schema coverage is 100% by default. The description adds value by explaining that credentials come from the .env file and that COOKIDOO_COUNTRY/COOKIDOO_LANGUAGE are optional environment-based values with defaults (ro/en), which helps the agent understand where configuration lives without needing parameters. This is meaningful context beyond just 'no params'.

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

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

The description clearly states this tool authenticates with Cookidoo and stores the session. The verb 'Authenticate' with the specific resource 'Cookidoo' is precise, and it clearly distinguishes itself from sibling tools which all perform recipe/meal-plan operations rather than authentication.

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 explicitly states 'This tool must be called before using other Cookidoo tools,' providing clear when-to-use guidance. While it doesn't name specific sibling alternatives, the ordering requirement is explicit and actionable for an agent, and the context that all siblings depend on this session makes the usage boundary obvious.

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 transparency burden and does well: it discloses that this copies into the account ('creates a private copy'), that dry_run validates/previews without changing the account (side-effect control), and that official recipes are full-fidelity copied. It doesn't state permissions/auth requirements or reversal options, but the mutation nature and dry_run safety valve are well documented.

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 focused short paragraphs, front-loaded with the core action in the first line. Every sentence earns its place: the purpose, the why/context, and the dry_run safety behavior. Zero waste, well structured.

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 mutates account state but has no annotations (making transparency more critical), has an output schema, and 3 params at 0% schema coverage. The description covers the mutation nature and dry_run well. The main gap is servants semantics and return value behavior (output schema exists so return format need not be detailed), plus permissions. Solid but not exhaustive.

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 dry_run semantically ('validate and preview creation without changing the account'), which is genuinely useful. However, recipe_id and servings get no explanation beyond the schema, and servings' behavior (does it scale the copied recipe?) is ambiguous. Partial compensation only.

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+resource ('Copy an official Cookidoo recipe into the account's custom recipes') that clearly states what the tool does. It distinguishes itself from siblings by explicitly noting this is the supported path to obtain full recipe content before translating/editing, and the 'dry_run' validation feature is highlighted.

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 clearly implies when to use it ('the supported way to obtain the full ingredients and instructions of an official recipe before translating or editing it'), which contextualizes it against read-only siblings like get_recipe_details. However, it doesn't explicitly name alternative tools or state when not to use it, so some implicit guidance only.

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 description discloses that the tool validates all fields and returns a JSON structure, and notes it has an output schema (pointing to structured results). It adds behavioral context about structuring steps apart. With no annotations provided, the description bears the transparency burden; it covers the core behavior but doesn't detail edge cases, error handling, or what happens with invalid input—though having an output schema reduces the burden somewhat.

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 compact—roughly 60 words across three short paragraphs—and opens with the core purpose sentence. The step-formatting guidance earns its place as crucial usage detail. The final instruction about separating ingredient additions from machine actions is valuable but slightly redundant with the steps parameter description in the schema ('Ingredient additions and machine actions must be on separate lines'), creating minor duplication.

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 an output schema, reducing the need to describe return values. With 7 parameters at 100% schema coverage, the schema handles parameter documentation. The description adds value on the recipe-structuring guidance and integration workflow with upload_custom_recipe. It's reasonably complete for a generation/validation tool given the rich schema; the main gap is not clarifying how this differs from validate_guided_recipe_structure among siblings.

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%, so parameters are well-documented in the schema itself. The description adds meaningful guidance on step formatting ('Ingredient additions and machine actions must be on separate lines') that complements the schema's brief parameter notes. The formatting guidance in the description enhances understanding beyond what the schema alone provides, though it doesn't enumerate each of the 7 parameters individually.

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

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

The description clearly states the tool's function: 'Generate and validate a recipe structure ready for upload to Cookidoo.' It uses specific verbs (generate, validate) and identifies a clear resource (recipe structure) and integration with the upload_custom_recipe tool. However, it doesn't explicitly distinguish from the sibling tool validate_guided_recipe_structure, which could cause confusion about which validation tool to use.

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

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

The description provides clear guidance on how to structure recipe data, including the explicit instruction to 'Always put weighing/adding ingredients in one step and the subsequent chopping, mixing, cooking, or kneading action in a separate step.' It also notes the tool validates fields before upload. It lacks explicit when-not-to-use guidance or comparison against the sibling validate_guided_recipe_structure, but the integration context with upload_custom_recipe is helpful.

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 provided, so description carries the full burden. It discloses that the tool returns plain text (not guided-cooking annotations) and directs users to update tools for annotation work. This adds useful behavioral context beyond schema, though it doesn't cover error cases or return structure.

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 concise sentences, first is front-loaded and zero waste. Each sentence adds distinct value: what it does, sibling distinction, return format, and pointer to update tools.

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?

Single-param tool with output schema present, so return structure is covered by schema. The description clarifies the custom-recipe scope and plain-text nature, which is significant. Slightly more could be said about content size or availability, but for this simplicity level it's solid.

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 there's only 1 param (recipe_id). The description clarifies that recipe_id refers to a custom recipe (vs. general recipe), and the output is 'full text content' with plain ingredient/instruction text. With 1 param, baseline is near-max and description adds reasonable context.

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?

Specific verb+resource: 'Get the full text content of a recipe'. Clearly distinguishes from sibling get_recipe_details by noting it includes preparation instructions. Establishes scope ('custom recipes') 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 a clear contrast with get_recipe_details (includes preparation instructions), which helps differentiate. However, it doesn't state when to choose this vs. the alternative, or when NOT to use it — no exclusions or 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 provided, the description carries full responsibility for behavioral disclosure. It transparently reveals that it 'fills all seven days' (vs. Cookidoo omitting empty days) and that it resolves custom recipe IDs to names, images, durations, and links — a data-enrichment behavior beyond a plain read. The 'matches the `?date=YYYY-MM-DD` parameter' note adds API-parity context. Slightly less strong because it doesn't disclose error cases or auth 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?

The description is three sentences with zero waste. The first sentence states the purpose, the second explains behavioral enhancements, and the third provides API-parity context. Every sentence earns its place with distinct 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?

The tool has a single simple parameter, an output schema is present (so return values are covered), and no nested objects. The description covers purpose, behavioral enhancements, and API parity. It's slightly short of a 5 because it doesn't note any prerequisites (e.g., requiring a Cookidoo connection via connect_to_cookidoo, a clear sibling dependency given the sibling 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 100% — the single `date` parameter is fully documented as 'First day of the seven-day window, formatted YYYY-MM-DD.' The description reinforces this meaning by explaining that the returned window 'starts with the requested date.' Baseline 3 is appropriate since the schema already fully documents the parameter and the description adds modest confirming 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?

The description clearly states the tool's purpose: 'Get Cookidoo's complete seven-day meal-plan window.' It specifies the verb (get), the resource (meal plan), and the scope (seven-day window), which distinguishes it from siblings like get_recipe_details or get_shopping_list_ingredients.

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 explains when to use this tool by contrasting it with Cookidoo's normal behavior ('omits empty days and returns custom recipes as bare IDs'). It clarifies what the tool adds (fills all seven days, resolves custom recipe IDs). The mention of the `?date=YYYY-MM-DD` parameter ties it to the web planner context, though it doesn't explicitly name sibling alternatives for exclusions.

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 disclosure burden. It does mention the connection prerequisite and positions this as a read/inspiration tool. However, it doesn't disclose what happens when the recipe doesn't exist, whether it requires specific permissions, or what the returned output structure looks like. The one-ID-per-call scoping is implied but not fully explicit.

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 compact and front-loaded, with the primary purpose in the first sentence and secondary context (usage scenario + prerequisite) in the second. No wasted words, though the separation of 'inspiration' context could potentially be merged more tightly.

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

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

Given the tool has only one parameter with full schema coverage and an output schema present, the description is reasonably complete. It addresses the key context (requires prior connection, used for inspiration before custom recipe creation). It lacks explicit behavioral notes like error handling or return format, but for a single-param lookup tool with output schema, this is adequate.

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% with a clear example of the recipe_id format ('r59322', 'r907015'). The description adds that the recipe_id targets standard Cookidoo recipes, which slightly supplements the schema. With full schema coverage, baseline 3 is appropriate; the description provides minimal additional parameter insight beyond the schema.

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

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

The description clearly states the tool gets detailed information about a specific recipe by its ID, with a specific verb-object pair. It distinguishes itself from siblings like get_custom_recipe_details by noting it's for standard Cookidoo recipes, though it could be more explicit about the distinction from custom recipe tools.

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 gives clear usage context: use for recipe inspiration before creating a custom recipe. It also specifies a prerequisite (must be connected via connect_to_cookidoo first). However, it doesn't explicitly contrast with get_custom_recipe_details or state when NOT to use it, which would elevate it to 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?

With no annotations provided, the description carries the full burden of disclosure. It doesn't mention whether this is a read-only operation, whether it requires an active Cookidoo connection (sibling connect_to_cookidoo suggests auth/state matters), what happens if the shopping list is empty, or how owned vs non-owned ingredients are handled in output. The description stays purely high-level and provides no behavioral nuance.

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 concise sentence, front-loaded with verb and resource. No wasted words. Slightly minimal but appropriately sized for the tool's simplicity.

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

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

The tool has an output schema and 100% parameter coverage, so much of the burden is lifted. However, with no annotations and no mention of connection prerequisites or potential failure states (shopping list not synced, no items, etc.), there's a moderate gap. Given the simple interface and rich schema, a 3 is reasonable but it could be higher with a note about connection requirements.

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 three parameters (recipe_id, include_owned, include_additional_items) are all well-documented in the schema itself. The baseline 3 applies. The description phrase 'grouped by recipe' adds meaningful context about how output is organized, slightly justifying a 4.

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 'Get Cookidoo shopping-list ingredients grouped by recipe' — a specific verb (Get), resource (shopping-list ingredients), and grouping behavior (by recipe). This clearly distinguishes it from sibling tools which deal with meal plans, recipes, or custom recipes. However, it doesn't explicitly differentiate from any similar-looking list tool among the siblings, so not a 5.

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

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

No guidance on when to use this tool vs alternatives. There's no mention of prerequisites (like needing a connection established via connect_to_cookidoo), no exclusions, and no note about when this is appropriate versus get_recipe_details or other listing tools. The recipe_id param description implies an optional filter, but no scenario guidance 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It does well by revealing the two-step transaction order and the rollback guarantee on partial failure, which is exactly the kind of non-obvious behavior an agent needs. It could add details on idempotency or prerequisites (e.g., must be connected to Cookidoo), but the core mutation semantics are clearly disclosed.

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 purpose, with no wasted words. The ordering guarantee and rollback behavior each earn their place in the second and third sentences. It's an example of efficient, high-density writing.

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 description is complete given an output schema exists (so return values need no elaboration) and all 5 parameters are documented in the schema. The tool involves compound state-changing behavior (add + remove + rollback), which the description fully covers. A small gap: no mention of connection prerequisites or confirmation semantics for the dry_run mode, but the tool's complexity is well-served by current 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 100%, so the baseline is 3 and the schema already documents all parameters. The description adds a bit of context by clarifying the move semantics that tie from_date and to_date together, but doesn't elaborate beyond what the schema provides. The dry_run and recipe_source parameters are fully covered by the schema descriptions.

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

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

Description uses a specific verb+resource ('Move one recipe from one Cookidoo calendar day to another') which clearly states the action and scope. It distinguishes from siblings naturally: it's a move operation that combines add and remove, distinct from add_recipes_to_meal_plan and remove_recipe_from_meal_plan, and the rollback note further clarifies its compound behavior.

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 explicitly documents the execution order ('added to the target first and then removed from the source') and rollback behavior on failure, which gives clear expectations for when it's safe to use. However, it doesn't explicitly name when NOT to use it versus calling add plus remove separately, so it stops 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?

No annotations are provided, so the description carries full behavioral disclosure burden. It doesn't state that this is a mutation (destructive) operation, doesn't explain dry_run semantics beyond the schema, doesn't mention what happens to the meal plan if removal succeeds/fails, and doesn't describe the response shape. For a mutation tool with zero annotation coverage, this is a meaningful 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?

The description is a single, efficient sentence that states the core function with zero wasted words. It's appropriately front-loaded. It could add a brief usage note without hurting conciseness, but as written it's structurally 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?

There is an output schema present, which covers return-value expectations. The tool has 4 params, all of which are schema-covered, and no nested objects. But it's a mutation tool with no annotations—the description is one sentence and doesn't address the mutation safety profile, dry_run's role in validation, or relationship to siblings like move_recipe_in_meal_plan. Given moderate tool complexity and full schema coverage, score 3 is fitting.

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%, so all four parameters (date, recipe_id, dry_run, recipe_source) are already documented in the schema. The description adds no extra meaning beyond what the schema provides—it doesn't explain how date and recipe_id interact, nor how dry_run output should be interpreted. Baseline 3 is appropriate given full schema coverage.

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+resource: 'Remove one recipe from a Cookidoo meal-plan day.' It clearly indicates the action (remove) and resource (recipe/day), and differentiates from siblings like add_recipes_to_meal_plan and move_recipe_in_meal_plan. However, 'day' is slightly ambiguous—does it remove the recipe completely or just from that day's slot? The single sentence purpose is clear enough but doesn't deepen the distinction.

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 gives no when-to-use guidance, no prerequisites (e.g., whether connection to Cookidoo is required before removal), no indication of when to prefer this over move_recipe_in_meal_plan, and no exclusion cases. There's implied context that this is for removing items from an existing meal-plan day, but no explicit alternatives or preconditions are provided.

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 discloses that this is a partial update (preserves other fields), explains the dry_run behavior (validates without patching), and describes the input format expectation (JSON array). It doesn't mention authentication requirements or reversibility, but the core behavioral traits of mutation and validation are well disclosed.

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 compact and front-loaded with the purpose. It adds meaningful detail on ingredients format and dry_run behavior without redundancy. Could be slightly tighter but every sentence earns its place.

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 no annotations and 0% schema coverage, so the description must do heavy lifting. It covers the input format, partial update semantics, and dry_run behavior. With an output schema present, return values are already documented. It's reasonably complete for the tool's complexity, though it could mention when to connect_to_cookidoo first (a prerequisite given the sibling 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 coverage is 0%, so the description must compensate. It explains ingredients_json must be a JSON array and describes its item structure (plain text or INGREDIENT object with VOLUME annotation). It explains dry_run's validation behavior. recipe_id is left to schema semantics, but the other two params are meaningfully documented.

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+resource: 'Replace a custom recipe's ingredients.' It clarifies this is a partial update that preserves other fields, clearly distinguishing it from siblings like update_custom_recipe_steps and upload_custom_recipe. The function purpose 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 explains it performs a partial update preserving other fields, giving clear context on scope. It explicitly mentions the dry_run validation mode for testing without patching. However, it doesn't explicitly name alternatives or state when NOT to use this tool versus other update tools like update_custom_recipe_steps, though the distinction is fairly implicit.

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 discloses that this is a partial update preserving other fields, and explains dry_run validation behavior. It does disclose the steps_json format requirements. However, it doesn't state auth requirements or error behavior on invalid JSON, though the format details are reasonably thorough.

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 sentences, each earning its place. The description is efficiently organized: core action first, then format details, then usage constraint, then validation behavior. Slightly dense in the second sentence but not 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?

The tool has an output schema (which explains return value shape) and 3 parameters with 0% schema coverage. The description provides substantial detail on parameter semantics and usage constraints. Given the moderate complexity (annotations, dry_run mode), the description is fairly complete, though it could add more on error handling for malformed JSON.

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 schema's lack of parameter documentation. It explains steps_json format in detail (JSON array, plain text or STEP objects with TTS/MODE/INGREDIENT annotations) and dry_run semantics (validate without patching). It does not explain recipe_id, but that name is self-explanatory.

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?

Specific verb+resource: 'Replace a custom recipe's preparation steps.' Clearly states the action (replace steps) and the target (custom recipe). Distinguishes from sibling update_custom_recipe_ingredients and upload_custom_recipe tools by focusing specifically on preparation steps. The partial-update nature is 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?

Provides explicit usage guidance: separate steps for weighing/adding vs cooking/mixing/chopping/kneading. States a constraint that a single step cannot contain both INGREDIENT and TTS/MODE annotations. Explains dry_run behavior for validation without patching. This is actionable guidance beyond implicit 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?

With no annotations provided, the description carries the full burden. It communicates that this is a mutating operation (creates a recipe) and that input must be pre-validated via generate_recipe_structure. However, it doesn't disclose outcomes like whether an existing recipe with the same name gets overwritten, what the success response looks like, or whether a Cookidoo connection/authentication must be active (there's a 'connect_to_cookidoo' sibling suggesting auth is separate).

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

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

The description is concise and front-loaded with the primary purpose in the first sentence. The second paragraph adds the workflow guidance. It wastes no words, though it could arguably be even tighter. Clear two-paragraph structure: what it does, then how to use it.

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 an output schema, which likely describes the returned recipe/confirmation, so return values need not be explained. Complexity is moderate: it's a create operation requiring pre-validated input, and the description covers the prerequisite flow. However, it doesn't address auth requirements (connect_to_cookidoo sibling suggests this matters) or failure modes for invalid JSON, leaving some 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 100%, so both parameters are documented in the schema itself. The description adds value by explaining that recipe_json must be the output of generate_recipe_structure (tying it to the validation workflow) and that dry_run validates without persisting. This exceeds what a bare schema provides, though it doesn't detail the JSON structure.

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

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

The description clearly states the tool uploads a custom recipe to a Cookidoo account and creates a brand new recipe from scratch. It distinguishes itself from 'copy_recipe_to_custom' (which copies an existing recipe) by emphasizing 'from scratch'. However, it doesn't explicitly contrast with sibling 'update_custom_recipe_steps' or 'update_custom_recipe_ingredients', though 'creates brand new' implies creation as opposed to modification.

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

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

The description provides clear usage guidance: use 'generate_recipe_structure' first to validate data, then pass the resulting JSON. It also mentions the dry_run param implicitly by noting validation. It doesn't explicitly say when NOT to use this tool (e.g., when updating an existing recipe), but the sequential workflow guidance is strong and practical.

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 disclosure burden. It conveys meaningful behavioral detail: format conversion to JPEG, the signed customer-recipe flow, isImageOwnedByUser enabling, and the 10 MB size cap. This gives the agent actionable expectations about side effects (ownership flag) and constraints beyond what a schema could express. It doesn't detail reversible behavior but covers the key operational traits.

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 three compact sentences with the core purpose front-loaded in the first line. Every sentence adds distinct value: purpose, then format/size behavior, then attachment specifics. No filler or redundancy.

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

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

Given the output schema exists and inputs are fully covered, the description covers the key operational concerns: format conversion, upload mechanism, ownership flag, and size cap. It's a complete treatment for a file-upload tool of this complexity, though it could name the sibling upload_custom_recipe for disambiguation in the guidelines.

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%, so the parameters are already documented. The description adds context about the file (converted to JPEG) and the size limit, supplementing image_path meaning, and clarifies that dry_run previews without sending requests. With full schema coverage and a dry_run param built into the schema, the description's marginal value is modest but present.

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 precise verb+resource: 'Upload a local image and attach it to a custom Cookidoo recipe.' It immediately clarifies the scope (local file, custom recipe) and distinguishes from siblings like upload_custom_recipe (which handles the recipe itself, not its image). The required parameters (recipe_id, image_path) map cleanly to the stated 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?

The description implicitly scopes usage to uploading/attaching images to custom recipes, which separates it from recipe creation (upload_custom_recipe) but doesn't explicitly state when to use this vs alternatives. It mentions acceptance limits (10 MB) and format conversion, offering some practical usage context, but lacks explicit when-not-conditions or named alternatives.

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 explains the underlying Cookidoo request schema, positional indexing semantics (zero-based JavaScript UTF-16 ranges), and the distinction between VOLUME and other annotation positions. This is a validation tool, so read-only behavior is implied, but the detailed schema conventions usefully disclose the validation contract.

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 well-organized with clear line breaks and bullet-like enumeration of annotation types. Each section adds value: purpose, annotation types, placement rules, and positional semantics. It's somewhat long but dense with necessary technical detail; no 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 validation tool with an output schema and one parameter, the description covers the key context: what gets validated, annotation type semantics, placement rules, and positional encoding. It could possibly clarify the expected return/error format, but the output schema presumably handles that. Given the moderate complexity of guided-cooking validation, this is reasonably 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 and only one parameter (recipe_json, a string), the description compensates by explaining what the JSON contains: TTS, MODE, INGREDIENT annotations with specific semantic meaning. While it doesn't describe the exact JSON structure format, it clarifies the annotation types and their placement rules, which is meaningfully beyond the bare schema.

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

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

The description clearly states the tool validates a complete custom recipe including guided-cooking annotations, which is a specific verb+resource purpose. It distinguishes reasonably from siblings like generate_recipe_structure and update_custom_recipe_steps by focusing on validation of annotation structure, though it doesn't explicitly name alternative tools.

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

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

The description provides substantial context on when this tool applies: validating complete recipes with guided-cooking annotations and includes important placement rules (INGREDIENT annotations in ingredient-only steps, TTS/MODE in separate machine-action steps). It also tells the user about the companion tool calculate_annotation_position for position handling, giving clear operational guidance.

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