Search Fitatu Recipes

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, giving a safety profile. The description adds meaningful behavior beyond that: trimming of query, case-insensitivity, returning raw recipeId values, empty/whitespace query listing all recipes, and the partial-results-with-warnings behavior for scope=all. No contradictions with annotations; the description enhances the behavioral understanding.

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 efficient and front-loaded with the core search behavior, then adds optional flags and edge cases. It covers a lot in a compact text without redundancy. Slightly dense, but each sentence adds information. It doesn't waste words, though it could be split into clearer paragraphs.

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 clarifying the return structure, the description focuses on behavior. It covers all key edge cases: empty queries, scope combinations, warnings, and the optional details flag. Given the tool's moderate complexity and the presence of a rich schema, the description is complete for an agent to correctly 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 100%, but the description adds crucial semantics: 'trimmed' for the query, the raw recipeId return, and the warning behavior for scope=all. These details are not present in the schema and directly inform parameter usage. The description also clarifies the purpose of includeDetails in the day-plan context, which is not captured in the schema's parameter description.

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 ('searches') and resource ('active recipes'), and defines the matching semantics (trimmed, case-insensitive name substring) and the output (raw recipeId values). This is unambiguous and distinct from sibling tools like search_food or search_food_by_barcodes, which target food items rather than recipes. No confusion about what is being searched.

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 practical guidance: it notes that includeDetails=true provides details useful for adding a recipe to a day plan, and explains the distinction of scope=all (combines catalogs, returns partial results with warnings). While it doesn't explicitly name alternatives like get_recipe or search_food, it provides enough contextual cues for an agent to decide when this tool is appropriate, especially with the sibling list available.

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