Recipe Validate

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

Annotations already provide readOnlyHint=true, so the description's job is to add behavioral context beyond that. It discloses the specific validations performed, the return structure ({ok, problems}), and the semantics of 'ok' (True iff problems is empty). It also clarifies the tool does NOT build, which is critical behavioral information given the openWorldHint=false annotation.

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 compact, front-loaded with the core action, and every clause adds value. It explains what it does, when to use it, what it catches, and the return shape, all in three sentences 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?

The tool has only two parameters, no output schema, and annotations cover read-only behavior. The description provides the essential context: the return format, the conditions for success, and the purpose of running it before build/merge. Minor gaps exist around the exact structure of the 'problems' array adaptation, but the description is sufficient for an agent to call 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%, so the description carries the full burden of explaining 'recipe' and 'inputs'. The description provides context by naming the inputs parameterization ({recipe, inputs}) and that it validates inputs for type/range/units, but does not detail the format of the recipe string or the exact structure of inputs object. Given zero coverage, more detail would be expected, but the basic semantics are conveyed.

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 that the tool validates a recipe reference without building it, and explicitly lists the categories of errors it catches (unknown recipe, missing required input, wrong-typed, out-of-range, bad-unit, unknown input). This distinguishes it from build tools and validation of other entities.

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 states to run before building or merging to reject malformed parameterizations before geometry is spent. It also mentions the tool mirrors validate_manifest, which helps route to the correct validation tool. However, explicit when-not-to-use scenarios are not provided.

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