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

Beyond the readOnly/idempotent/non-destructive annotations, the description discloses a non-obvious behavioral quirk: the site serves another page when it does not hold the address, and pages past the last one silently return the first page. This is exactly the kind of edge-case behavior an agent needs before invoking the tool.

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

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

Four sentences, and each earns its place: the core operation, the two input modes, the slug-authoring warning, and the pagination fallback behavior. The main purpose is front-loaded and the caveats are placed after the primary semantics.

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 read-only paginated browsing tool with rich schema descriptions and an output schema, the definition covers the dangerous non-obvious behaviors that could otherwise cause an agent to misread results: slug tolerance and page wrapping. Nothing essential 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 already documents all parameters at 100% coverage, but the description adds usable guidance about where category slugs come from, that listing values are mutually exclusive with category, and the warning against hand-built slugs. It reinforces but does not deeply extend the schema's parameter descriptions, so a 4 is appropriate.

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: 'Read the recipes under one category of Ptitchef, page by page, or one of the lists the site keeps standing.' It clearly states both operating modes and distinguishes this from siblings like list_categories (which returns categories) and search_recipes (which returns search results).

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 explicit input-selection rules: pass 'category' with a slug from list_categories or a search's 'topic_slug', or pass 'listing' with one of the named standing lists. It also gives a strong exclusion: never hand-build a category slug. It does not explicitly name the sibling tools to use instead, but the context is clear.

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

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

Annotations already cover read-only, open-world, idempotent, and non-destructive behavior. The description adds valuable behavioral detail beyond that: it explains the 'scaling' field's values ('scaled', 'rounded', 'unscaled') and their meaning for quoting quantities, and states that absent site figures come back null, never zero. 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?

Four sentences, each earning its place: scope, id sourcing, servings, and output semantics. It is dense but front-loaded with the core purpose, and no sentence is filler.

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

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

With an output schema present and annotations covering the safety profile, the description provides enough context for correct invocation. It handles id provenance, optional servings, scaling nuances, and null semantics; minor omissions like invalid-id behavior are not critical.

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 already documents both parameters. The description adds value by specifying that valid 'id' values come from rows of three sibling tools and clarifies that 'servings' rescales ingredients, echoing the schema in more actionable terms.

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 ('Read'), a unique resource ('one Ptitchef recipe'), and enumerates what is returned (ingredients, method, times, rating, nutrition, cost). It also differentiates from search siblings by instructing the agent to pass an id from search_recipes, browse_recipes, or search_by_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?

It gives clear context: use with an id coming from the three listed search tools, and optionally pass servings to rescale. It names the upstream tools that produce valid ids, but doesn't explicitly state when not to use it (e.g., when scale_ingredients might be more appropriate), so it stops short of full exclusion guidance.

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

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

Annotations already indicate read-only, idempotent, open-world, and non-destructive behavior. The description adds meaningful nuanced behavior: the translation pairing is site-defined and repeated rather than title-matched, the count varies by recipe, and an empty list still means the read succeeded. This goes well beyond the annotation hints.

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 is not padded. A few repeated details from the schema and the illustrative language examples add length, but each sentence contributes useful operational or interpretive context for an agent.

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 read tool with an output schema and strong annotations, the description is complete: it explains when to use this tool instead of get_recipe, how to source the id, what the result represents, how size varies, and how to interpret an empty 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 100%, and the schema already explains that 'id' is 'The id of a row from a search or a listing, which is the recipe's own page path.' The description repeats this same guidance without adding substantial new parameter semantics, so the baseline of 3 is appropriate.

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 names a specific verb and resource: 'List the other languages a Ptitchef recipe was published in, with the page of each.' It explicitly contrasts with the sibling get_recipe, which already contains this list, so an agent can immediately distinguish this tool from the main recipe-fetching tool.

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

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

The description gives a clear when-to-use rule: call this only when the rest of the recipe is not wanted, because get_recipe already carries the translations list. It also tells the agent exactly what input to pass: the 'id' of a row from a search or listing.

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

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

Annotations already establish that this is read-only, idempotent, non-destructive, and open-world. The description adds valuable behavioral context beyond those annotations by warning that slugs are written freely by the site, that guessed slugs land on non-existent pages, and that entries carry the slug to pass back. This directly addresses the open-world nature of the catalog and prevents a common failure mode.

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

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

The description is compact and front-loaded: the core action and the two-mode behavior appear first, followed by a necessary warning about slug instability. Every sentence contributes either to correct invocation or to avoiding an error, with no filler or repetition of schema content.

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's two-level hierarchy, optional parameters, rich annotations, and existing output schema, the description covers everything an agent needs: how to start, how to descend, and why slug guessing is unsafe. Pagination and return details are already handled by the schema and output schema, so nothing essential 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?

Schema description coverage is 100%, so the schema fully documents 'limit' and 'family.' The description reinforces that 'family' should come from a previous call and that omitting it reads the families, but it does not add meaning significantly beyond the schema. Baseline 3 is appropriate because the schema carries the parameter documentation burden.

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

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

The description states a specific verb and resource: 'List the categories Ptitchef browses its recipes by.' It also clarifies the hierarchical relationship between families of ingredients and categories, which separates it from sibling tools like search_recipes, browse_recipes, and get_recipe. The two-call pattern (no argument for families, family slug for categories) makes the tool's purpose 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 gives explicit instructions for both usage modes: called without arguments it returns families, and passing a family's slug as 'family' returns its categories. It also warns against hand-building slugs. It does not explicitly name sibling alternatives or state when to prefer this tool over search/browse tools, but the context is clear enough for an agent to select it for category-tree navigation.

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

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

The annotations already declare readOnly, idempotent, and non-destructive behavior, but the description goes far beyond them: it explains rounding to readable values, the half/whole rounding rule based on countable items, treatment of approximate measures, parsing of articles as one unit, and that unquantified lines are returned untouched and flagged. This is rich behavioral disclosure with no contradiction to the 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 opening sentence front-loads the core purpose and the no-network constraint. The following sentences pack dense but relevant detail: parameter alternatives, French-list applicability, rounding rules with concrete examples, edge-case handling, and a closing usage preference. Every clause earns its place; there is 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?

Given the tool's complexity, the description covers domain scope, parameter alternatives, rounding rules, approximate measures, and unquantified lines. An output schema exists, so return-value details are not required. The only notable omission is the fallback or error behavior when no scale parameter is provided, since the schema does not enforce one of factor/from_servings/to_servings.

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 already describes every parameter, so the baseline is 3. The description adds meaning by explaining the relationship between factor and from_servings/to_servings, stating that the factor is computed from the serving pair. It also gives concrete ingredient-line examples. A minor gap is that it does not explicitly state what happens if neither factor nor the from/to pair is supplied, though the schema only requires ingredients.

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

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

States a specific verb and resource: 'Rescale a list of ingredient lines to a different number of servings,' and adds the key constraint 'without contacting any website.' This clearly distinguishes it from sibling recipe browsing and search tools, which focus on finding or retrieving recipes rather than transforming ingredient lines.

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

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

Gives clear context: it works on any French ingredient list, including pasted recipes, and explicitly says 'Prefer this over doing the arithmetic yourself.' It does not name a competing sibling tool or state explicit exclusions, but no sibling targets the same operation, so the guidance is adequate.

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

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

Beyond the readOnlyHint, openWorldHint, and idempotentHint annotations, it discloses non-obvious behaviors: the site counts all matches but serves only one page, the rest cannot be reached, and an over-long ingredient list is refused rather than silently truncated. This is exactly the kind of behavioral context annotations do not capture.

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

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

Three short sentences with the purpose first, then instructions, then boundary behaviors. Every sentence earns its place and there is no filler or repetition of annotation data.

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 rich annotations and output schema, the description covers everything an agent needs to invoke it correctly: ingredient count, language, refusal behavior, and pagination limitations. The only minor gap is not explicitly routing to sibling search_recipes, but the ingredient-based purpose makes that choice obvious.

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 input schema already has 100% coverage, including the French requirement, one-to-five item bounds, and per-string length limits. The description adds helpful cook-friendly examples, but it largely restates the schema rather than adding deeper semantic meaning, so the baseline 3 is appropriate.

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

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

The description opens with a specific verb-resource pair ('Find Ptitchef recipes') and narrows the scope to ingredients a cook already has, which distinguishes it from sibling search_recipes, browse_recipes, and list_categories. It also clarifies the input language and gives examples, making the tool's identity unmistakable.

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

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

It gives actionable usage instructions: one to five ingredients, in French, using natural cook phrasing with examples. It doesn't explicitly say when not to use this tool or name an alternative, so it stops short of a 5, but the context is clear enough for an agent to select it appropriately.

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 a wealth of behavioral detail far beyond what annotations provide. It explains the two distinct response modes (category pages vs. single pages), the meaning of the total (category count vs. row count), the existence of topic_slug, the guide case with no total, and the zero-result case as an explicit absence. This is precisely the kind of non-obvious behavior an agent needs to know before calling the tool.

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

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

While the purpose is front-loaded in the opening sentence, the remainder is a long, winding explanation of response behavior packed into a single run-on paragraph. It lacks clear structure and could be shortened or bullet-pointed. The complexity is high, but the description is not concise; several sentences could be consolidated without losing information. This makes it harder for an agent to quickly extract the key points.

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 search tool with rich behavioral nuances, the description covers all essential aspects: response variants, total semantics, topic_slug usage, guides, and the no-result case. It also routes to browse_recipes for pagination. Since an output schema exists, the description need not explain return values, and it already explains the meaning of fields like rows_seen and total as they appear in responses. No critical missing context is apparent.

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 input schema already covers both parameters with clear descriptions (query in French, limit with default and meaning of rows_seen). The description adds no additional parameter-specific meaning, which is acceptable given 100% schema coverage. Baseline 3 is appropriate; the description does not need to repeat schema content.

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

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

The first sentence clearly states a specific verb and resource: 'Search recipes on Ptitchef by dish or ingredient.' It also distinguishes itself from the sibling 'browse_recipes' by explaining that browse_recipes reads further pages of a category topic. This gives an agent a precise initial understanding of what the tool does and how it differs from a closely related tool.

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

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

The description provides explicit guidance on when to follow up with 'browse_recipes' (when a category answers or a guide is returned), which is a form of usage routing. However, it never mentions the alternative 'search_by_ingredients' or states when to choose this tool over it. It also does not explicitly state when NOT to use search_recipes, so the guidance is partial and relies on inference.

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