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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive, so the safety profile is covered. The description still adds operational context the annotations don't: paging behavior, the one-recipe-per-generation constraint, and when model_id should be applied. Return format is not described, but an output schema exists, so that is a minor gap.

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?

Purpose and the 'search before choosing' instruction are front-loaded, and the trailing sentence routes to list_presets efficiently. It is dense with parenthetical definitions (arm/reprompt/run) that are helpful but push it toward the long side for a list tool.

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 7-param, 0%-coverage list tool with an output schema, the description covers routing, filtering logic, and the enum fields, so an agent can call it correctly in most cases. The unexplained tags/line/limit parameters keep it short of fully 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 0% across 7 parameters, so the description must carry the load. It explains the two enums (model_id, model_kind) and the conditional logic for model_id, plus paging via 'page through'. However, tags, line, and limit are completely unexplained, leaving a substantial portion of the parameter surface 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?

States a specific verb and resource (search/page the RECIPE catalog) and defines what a recipe is conceptually ('templates that ask you questions and then make something'). It explicitly separates recipes from styles/presets, so an agent can distinguish it from list_presets and list_models without opening a schema.

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 explicit when-to-use ('Search it before choosing a model'), the constraints for the model_id filter, and routes three downstream actions (generate_with_recipe for arm/reprompt, start_recipe_run for run, list_presets for styles). Alternatives and exclusions are both named.

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