Search recipes

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.