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

The description goes well beyond the annotations by explaining atomic all-or-nothing behavior, retry semantics, the need for user confirmation, failure on unknown IDs, and the idempotency_conflict outcome. These are meaningful behavioral details that an agent cannot infer from the input schema or the generic annotation flags.

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

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

Three tight sentences deliver the essential behavior, retry rule, confirmation requirement, and failure semantics with no filler. The most important phrase is front-loaded, and 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?

For a create operation with an output schema available, the description covers the critical success/failure behavior, idempotency rules, and user-confirmation prerequisite. Nothing essential for invoking the tool correctly appears to be 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. It does so well for idempotency_key by explaining exact reuse semantics and conflict behavior, and for recipe_ids by noting that unknown IDs fail the entire plan. plan_name is left implicit, but its meaning is self-evident from the title and default 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 opens with 'Atomically save a complete plan,' which clearly states the verb (save), the resource (a complete meal plan), and a defining behavioral property (atomicity). This separates it from the read/search siblings like get_meal_plan or search_recipes. The wording is specific and not a tautology.

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 operational context: it must be used to save an entire plan, requires user confirmation, and enforces idempotency on retries. It does not explicitly name alternatives like get_meal_plan or generate_shopping_list, but the save-versus-read/generate distinction is strongly implied by the tool name and 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?

The description adds substantial behavioral detail beyond annotations: it uses locally saved recipe details once per unique recipe at original batch size, combines compatible quantities exactly, surfaces unresolved measurements instead of hiding them, and avoids inferred conversions. This goes well beyond the readOnly/idempotent hints and gives the agent reliable expectations about edge-case handling.

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

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

The description is front-loaded with the core purpose and then uses every subsequent sentence to communicate meaningful behavioral constraints and edge-case policies. No filler or redundant restatement of the schema is present.

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

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

For a one-parameter read-only tool with rich annotations and an output schema, the description covers all essential context: input source, uniqueness and batching behavior, quantity combination policy, and explicit non-behaviors. Nothing critical for correct invocation is missing.

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

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

The schema only provides the name and length for plan_id, with 0% description coverage. The description compensates by clarifying that plan_id refers to a saved plan whose locally stored recipe details are consumed. For a single, simple identifier this is sufficient context, though it does not describe how to obtain or validate the ID.

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

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

The description opens with a specific verb and resource: 'Consolidate a saved plan's ingredients into a shopping list.' This clearly distinguishes the tool from siblings like get_meal_plan (which likely returns the plan itself) and search_recipes (which finds recipes). It also includes the important scope qualifier 'without writes'.

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 tool is used when a saved plan exists and a consolidated ingredient list is needed, and it states what the tool does not do (no scaling, no conversions, no upstream API calls). However, it does not explicitly name sibling alternatives or state when to prefer another tool, such as get_meal_plan or get_recipe_details.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the description's 'Read' aligns with them. It adds no extra behavioral context (e.g., errors, response format), but the annotations cover safety, so a 3 is appropriate.

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

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

A single, front-loaded sentence with no unnecessary words. It directly states the action and resource, earning 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?

The tool is simple with one parameter and has an output schema and annotations covering safety. The description is sufficient for an agent to call it correctly; nothing critical is missing.

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

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

The description specifies that plan_id is a 'generated UUID', adding semantic meaning beyond the schema's length constraints. Since schema coverage is 0%, this helps the agent understand the expected format, though it is minimal.

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 'Read' and the resource 'saved meal plan', and identifies the identifier as a 'generated UUID'. This distinguishes it from siblings like create_meal_plan (write) and search_recipes (search).

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 tool is used when you have a UUID and want to read a specific meal plan, providing clear context. It doesn't explicitly mention alternatives or exclusions, but the purpose is unambiguous given the sibling 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?

Annotations already disclose non-read-only (readOnlyHint=false) and non-idempotent (idempotentHint=false) behavior. The description adds that it 'saves' a recipe (a side effect) and that each call can differ (consistent with idempotent=false). It does not provide additional behavioral context like rate limits, side effects on data, or prerequisites. Since annotations cover the core safety profile, the description adds only marginal value.

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 concise sentences with no filler. The primary action and the variable output are stated immediately. Every word contributes to the tool's understanding.

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 no parameters and an output schema that defines the return, the description is fully sufficient. It conveys the tool's purpose, side effect (saving), and variability. Nothing an agent needs to decide whether to call it is missing.

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

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

There are no parameters, so the description has nothing to add beyond the empty schema. Baseline for zero-parameter tools is 4; the description correctly avoids inventing parameter details and keeps the tool's call signature self-evident.

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?

Clearly states a specific action (fetch and save) on a specific resource (one random recipe). The 'random' qualifier distinguishes it from search_recipes and get_recipe_details, which are targeted lookups. No ambiguity about what this tool does.

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 a use case (when you need a random recipe) but does not explicitly contrast it with sibling tools like search_recipes or get_recipe_details. It lacks any 'when not to use' guidance or alternative references, leaving the decision to the agent's inference.

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

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

Annotations already indicate non-read-only, idempotent, open-world behavior. The description adds meaningful context by revealing the two-mode behavior (reading saved details vs fetching and saving), which is not derivable from annotations alone. No contradiction with annotations.

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

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

The description is a single, front-loaded sentence with no filler. Every word contributes to conveying the purpose and behavior.

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

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

For a one-parameter tool with an output schema, the description covers the essential behavior (read or fetch-and-save) and the input type. It could be more explicit about when to use it versus sibling search tools, but the output schema handles return-value documentation.

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 schema has no description for recipe_id (0% coverage), so the description must compensate. It mentions 'numeric ID', which aligns with the schema pattern, and clarifies that the ID identifies a recipe. However, it adds little beyond what the schema pattern already conveys.

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 (read or fetch-and-save) on a recipe by numeric ID, which clearly distinguishes it from search tools that take text criteria or random selection. It is not a tautology and names the resource and input scope.

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 use when you have a numeric recipe ID, but it does not explicitly contrast with sibling tools like search_recipes or get_random_recipe, nor does it state when not to use it. The when-to-use is implied rather than spelled out.

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

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

Annotations declare readOnlyHint=false (mutation expected), idempotentHint=true, and destructiveHint=false. The description says 'save recipes', which implies a write operation, aligning with readOnlyHint=false. However, it provides no additional context about what 'save' means (e.g., persists to a database, what happens on repeated calls), nor does it explain the side effect beyond the annotations. With annotations present, the bar is lower, but the description adds minimal behavioral context beyond 'save'.

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

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

The description is a single sentence with no redundant words. It front-loads the core purpose and is appropriately concise. However, it could have added parameter guidance without becoming verbose.

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

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

The tool has an output schema, so return values are likely defined elsewhere. However, the description lacks clarification on the 'save' behavior, the meaning of max_results, and how this tool differs from search_recipes. Given the complexity (2 params, mutation side effect, open world hint), the description is incomplete for an agent to confidently invoke it correctly.

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

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

Schema description coverage is 0%, so the description must compensate for explaining both parameters. However, the description only mentions the 'letter' parameter ('whose names begin with one ASCII letter') and does not explain the 'max_results' parameter (limit/controls the number of recipes returned). Since max_results has a default and bounds but no description, the agent lacks guidance on its meaning. This is a significant gap given zero 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 action ('Find and save recipes') and a specific resource ('recipes') with a clear criterion (names begin with one ASCII letter). It is not a tautology and conveys a clear purpose. However, it does not explicitly differentiate from sibling tools like search_recipes, but the first-letter criterion is a distinctive 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 implies usage: use this tool when you need recipes starting with a specific letter. It does not provide explicit when-not-to-use guidance or mention alternatives like search_recipes for general searches. The 'save' behavior hints at a side effect, but no exclusions are stated.

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

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

Annotations already convey idempotence and non-destructiveness, and the description adds the behavioral detail of 'save their details' plus returning IDs and summaries. However, it does not clarify what 'save' actually does, whether it causes side effects, or what happens to previously saved 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?

The description is a single sentence with no filler and the core action ('Find recipes by dish name') is front-loaded. Every clause contributes identifiable information, even if 'save their details' is ambiguous in meaning.

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

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

With an output schema present, return values need not be elaborated, but the description still omits max_results semantics and fails to position the tool against search_by_first_letter. The ambiguous 'save their details' behavior also leaves an important gap for an agent deciding to invoke it.

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

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

Schema description coverage is 0%, so the description must compensate. It mentions 'dish name', which maps to the dish_name parameter, but it never addresses max_results, its default value, or how result limiting behaves. Thus, one of two parameters is left entirely 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?

The description clearly states a specific verb ('Find') and resource ('recipes') with a filtering criterion ('by dish name') and expected outputs ('IDs and summaries'). However, the phrase 'save their details' is ambiguous about whether the tool persists data, and it does not differentiate this from the sibling search_by_first_letter.

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

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

There is no guidance on when to use this tool versus alternatives such as search_by_first_letter or get_recipe_details. The description implies searching by dish name but does not state exclusions, prerequisites, or preferred contexts.

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