Planejar pesquisa culinária

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered and the "planning only, no live web access" nature is consistent. The description adds the workflow gating condition, but says nothing about what side state is created, what happens if ambiguity_resolved=false, or what the plan looks like — the output schema is left to carry returns.

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?

A single short sentence with the precondition front-loaded, so there is no wasted text. But this is brevity through under-specification rather than economy — nothing is left to trim, yet key contract facts are missing.

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?

The tool has an output schema and read-only annotations, which relieve some burden, but the input contract is a required nested object with five fields and a ten-field Profile. For a workflow-orchestration step in a four-tool pipeline, one sentence of sequencing context is not enough to call it correctly.

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% and the only parameter is a deep nested Request with dish, country (ISO-2 pattern), variant, ambiguity_resolved and a full Profile object. The description contributes zero information about any of these fields — not even the meaning of "variant" or how ambiguity_resolved should relate to the precondition it mentions.

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?

"Planeja a primeira busca do host" gives a verb and an object, but "planejar" is abstract — an agent cannot tell whether this produces search queries, a research outline, or a call to the host. It is close to restating the name (plan_research) plus a precondition, and it does not differentiate itself from sibling validate_research beyond ordering.

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 preconditions "após confirmação alimentar e desambiguação" implicitly tell the agent when this tool is valid (after onboarding confirmation and ambiguity resolution). However, no sibling is named, no when-not condition is given, and the relationship to validate_research / validate_delivery in the pipeline is left to inference.

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