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

Annotations already declare readOnly, idempotent, non-destructive, closed-world behaviour, so the safety profile is covered. The description usefully adds one non-obvious behavioural trait — the zero-argument call enumerates the colour families and plates, effectively acting as a discovery call — but says nothing about the shape or volume of the pairing results.

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?

One compact sentence covering both directions plus the empty-call escape hatch, front-loaded with the core value proposition. The semicolon-chained phrasing is slightly dense but every clause carries information.

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?

A low-complexity lookup tool with two enum parameters, no output schema, and full annotation coverage — the description covers both query modes and the discovery mode. Missing only the behaviour when both parameters are given, which is a minor gap at this complexity level.

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%, but both parameters are closed enums whose values are self-explanatory (plate names, colour families). The description adds real meaning by mapping each parameter to a use case and clarifying that food_color means the food's *dominant* colour. It does not clarify optionality or the combined-parameter case.

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, dual-direction resource: given a food's dominant colour it says which plate flatters or kills the dish, and given a plate it says which foods suit it. No sibling tool (recipes, calculators) does anything similar, so the agent can route here unambiguously.

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?

Explicitly tells the agent to "call with neither to see the colour families and plates," which is the critical guidance for a tool whose parameters are both optional. It also implies two usage modes (food-colour-first vs plate-first). It stops short of saying what happens when both parameters are supplied at once.

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