Recipe Signal

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds the 'known slugs' scoping requirement and the specific metadata dimensions compared. However, it doesn't describe the output format or behavior edge cases (e.g., what happens if a slug is unknown). With annotations present, this is adequate but not rich.

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 packs verb, resource, scope, and comparison dimensions with zero filler. Every component 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?

Given a single parameter, good annotations, and an output schema present, the description covers what is needed. The parameter is constrained by schema bounds (2-5 items, max length 180), and the comparison metrics are enumerated. The main gap is not clarifying output structure, but the presence of an output schema mitigates this.

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

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

Schema description coverage is 0%, so the description carries the burden for the 'slugs' parameter. It adds meaning by specifying the range (two to five), the format requirement ('known slugs'), and the max length. However, the description doesn't clarify slug format specifics (e.g., whether slugs are case-sensitive) beyond what 'known' implies, and the schema already provides min/max constraints.

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 ('compare') with a clear resource (recipe slugs) and enumerates the exact comparison dimensions (published time, rating, rating volume, yield, cuisine, publisher metadata). It also restricts the tool to 2-5 known slugs, which distinguishes it from search_recipes. However, it doesn't explicitly name sibling alternatives for differentiation, though the scope limits effectively imply what it 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 states the input requirement (two to five known slugs) and the comparison dimensions, giving clear context for when to use it. However, it doesn't explicitly state when NOT to use it versus get_recipe (single recipe retrieval) or search_recipes (discovery), relying on sibling names rather than spelling out the 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, which covers the safety profile. The description adds that the result is 'human-reviewed' and includes source URLs — mild value-add. It doesn't describe pagination, response size, or ordering behavior, but for a read-only single-slug lookup with strong annotations, 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?

The description is one efficient sentence that front-loads the purpose, enumerates valid inputs, and lists return contents. Every phrase earns its place. Slightly verbose with 'including criteria, editorial notes, and original source URLs' but that's informative, not padding.

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

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

For a simple single-parameter read tool with strong annotations (readOnly, idempotent, non-destructive) and an enum-constrained slug, the description is complete: it explains what's returned and the valid inputs. No output schema exists, so the description partially covers return contents (criteria, notes, URLs). A bit more on output structure would push to 5, but this is largely 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 description coverage is 0%, so the description must compensate for the single slug parameter. It does so by enumerating the four valid values (kadhi chawal, rajma chawal, idli sambar, pizza) in the prose, which the enum schema also defines — so there's some redundancy. However, enumeration in the description does convey the semantic meaning of what slugs map to, adding clarity beyond the bare enum 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 (Retrieve) with a specific resource (human-reviewed Recipe Signal comparison) and enumerates the exact set of recipes covered (kadhi chawal, rajma chawal, idli sambar, pizza), plus what it returns (criteria, editorial notes, original source URLs). It's clear, though it doesn't explicitly distinguish from the sibling compare_recipes tool, keeping it from 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?

The description implies 'when you want a comparison guide' but provides no explicit when-to-use or when-not-to guidance, and doesn't contrast with the sibling compare_recipes tool. With openWorldHint=false and a constrained enum, a note about when to use this vs. compare_recipes would help, but none is present.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds that it returns facts and the original publisher URL rather than copied instructions, which is useful scoping context beyond the annotations but doesn't address pagination, errors, or slug format specifics.

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 sentences, zero wasted words. Front-loaded with the action and resource, followed by a clarifying negative statement about what it does not return. Every clause 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 single-parameter tool with a clear read-only safety profile, rich annotations, and an output schema present, the description is complete. It conveys purpose, scope, and what the return distinguishes. The output schema handles return-structure explanation.

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 fully carries the parameter burden. It explains that 'slug' is a 'stable Recipe Signal slug' used to retrieve the record, adding semantic meaning (stability, attribution) beyond the schema's bare name/string type. The single parameter is well contextualized.

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 ('Retrieve one attributed recipe metadata record') and identifies the key criteria (stable Recipe Signal slug). It clearly states what the tool returns (facts and publisher URL, not recipe instructions), distinguishing its metadata-focused purpose from content-focused 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 implies the tool is for fetching metadata by slug rather than comparing or searching (siblings are compare_recipes, get_comparison_guide, search_recipes). It notes the scope limitation (returns metadata not instructions), implying when it would be useful, though it doesn't explicitly name alternatives or 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds the scope note that it searches 'attributed recipe metadata' (not full recipe content), which is useful. However, it doesn't describe pagination behavior, result ordering, or what happens with the default empty query, though these are partly covered by the output schema.

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

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

Two sentences, both dense with meaning. The first establishes the tool's purpose and filter dimensions; the second provides immediate usage guidance referencing a sibling. Zero wasted words or 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?

The tool has 6 parameters, an output schema, and strong annotations covering safety. The description covers purpose and usage concisely. Some minor gaps exist (e.g., default empty-query behavior, whether partial matches count), but the output schema and well-described schema parameters compensate for most completeness concerns. For a read-only search tool, this is adequately 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 83%, meaning most parameters already have descriptions in the schema itself (query, source, cuisine, category, maxTotalTime). The description adds that the query can include dish, ingredient, cuisine, or publisher text, which slightly enriches the 'query' semantic beyond the schema. The limit parameter is undocumented in schema but is self-explanatory, so the description doesn't need to elaborate. Baseline 3 is appropriate given high 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 uses a specific verb ('Search') with a clear resource ('attributed recipe metadata') and enumerates the query dimensions (dish, cuisine, category, publisher, maximum total time). It explicitly distinguishes the tool from its sibling get_recipe by noting it should be used when the exact slug is unknown, providing strong differentiation.

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 when to use this tool: 'Use this before get_recipe when the exact slug is unknown.' This gives clear usage context and names the alternative (get_recipe), which matches the sibling list. It provides a concrete sequencing recommendation that helps an agent decide between search vs direct retrieval.

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