Search recipes

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

The annotation already declares readOnlyHint=true, so the agent knows it's a safe read operation. The description adds behavioral details about filter combination logic and what the summaries omit, which goes beyond the annotation. However, it doesn't disclose pagination behavior (the response is paginated but no mention of how total pages are indicated or cursors), response format, or performance implications. For a read-only tool with 14 parameters, this is decent but not exhaustive.

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 three sentences long, front-loaded with the primary purpose, and includes critical usage guidance. It wastes no words. However, the filter logic information could be slightly rephrased for maximum clarity (e.g., 'All filters are combined with AND; within a single filter, entries match if they match ANY of the specified values unless the corresponding require_all_* flag is set'). It's good but not perfect.

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 14 parameters, 79% schema coverage, readOnlyHint annotation, and no output schema, the description provides a clear summary of the tool's return value and a key behavioral rule about filters. It doesn't explain pagination handling or response structure (which would be needed since there's no output schema), but for a search tool with these features and siblings, it strikes a reasonable balance. It's missing a bit on the response format expectations.

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 79%, so the schema already documents many parameters well. The description adds high-level semantic context about filter combination (AND across, OR within) that is not available from individual schema descriptions. However, it could further explain the exact behavior of require_all_* flags more explicitly (e.g., example: 'if set, the filter is AND instead of OR'). The description's key contribution is the overall filter logic, which enhances parameter understanding.

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 ('Searches') and clearly identifies the resource ('recipe collection'). It further specifies what the result contains (summaries with name, slug, id, etc.) and what it excludes (ingredients or steps, directing to get_recipe for those). This clearly distinguishes it from its siblings like get_recipe, suggest_recipes, and others.

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 ('if you need summaries without ingredients or steps') and when not to ('use get_recipe for those'). It also explains combinational logic (AND across filters, OR within filters unless require_all_* flags are set), which is critical for correct usage. However, it doesn't explicitly exclude other sibling tools like suggest_recipes or the various list functions, though the context of summaries vs. details is clear enough.

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