Browse the Cookbook

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

Even with annotations (readOnly, openWorld, idempotent), the description adds significant behavioral context: it explains the underlying search mechanism and its limitations ('neither complete nor ordered, and its length says nothing about how many recipes'), and warns that reference pages rank alongside recipes. This goes beyond annotations and sets correct expectations.

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 efficiently structured: it opens with the core purpose, then states prerequisites, then explains caveats and relationship to siblings. Every sentence earns its place, covering purpose, usage, limitations, and alternatives without redundancy.

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 and the presence of an output schema, the description is remarkably complete. It covers how to use it, what to expect (ranked sample, possible non-recipe pages), and how it relates to other tools. The caveats about incompleteness and ranking are crucial context for proper invocation.

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 covers 75% of parameters with descriptions. The description adds important semantics not in schema: the constraint that at least one of cuisine, dish_type, or main_ingredient should be provided, and that combining several narrows results. This is valuable but not exhaustive per-parameter detail; the schema already handles most parameter meaning.

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 clearly states the tool's function: 'Browse the Wikibooks Cookbook by cuisine, by kind of dish, or by main ingredient.' This is a specific verb+resource+scope that immediately distinguishes it from siblings like search_recipes and get_recipe. It also explicitly differentiates itself by noting when to use search_recipes instead, reinforcing purpose clarity.

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 when-to-use guidance: 'Give at least one of the three; giving several narrows the result.' It also names alternatives: 'Use search_recipes instead when there is a dish name to look up' and instructs to 'Open a row with get_recipe before describing it as a recipe.' This is clear, actionable usage guidance with exclusions.

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