recipe_validate

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

No annotations are provided, so the description carries the full burden and does well: it discloses that the operation is cheap/non-building, is a pre-check, and enumerates the exact failure classes it catches (unknown recipe, missing required input, wrong-typed/out-of-range/bad-unit/unknown input). It also states the return shape {ok, problems} and the ok-if-empty semantics. It does not state whether it requires an open document/workspace or any auth context, which on a mutation-free validator is the main residual gap.

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?

Three sentences, front-loaded with the verb+resource and the key differentiator ('WITHOUT building it — the cheap front door'). Every clause earns its place: failure modes, return contract, and call-site recommendation. No 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?

For a 2-param, no-annotation, no-output-schema validator, the description supplies the missing behavioral and return-shape context, so an agent knows what it checks and what it returns. The only omission is the execution prerequisite (does it need an open document/workspace?), which matters in this large stateful tool family.

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% for both parameters, so the description must compensate — and it does partially by naming the two fields as {recipe, inputs} and implying inputs is the parameterization to check. But it doesn't say what shape inputs must take (the schema's anyOf object/null gives no guidance either) or what a valid input looks like, so the compensation is thin.

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 verb (validate) and resource (a recipe reference {recipe, inputs}), and explicitly distinguishes itself from the build step ('WITHOUT building it — the cheap front door'). It also names a mirror sibling (validate_manifest), aligning it with a family of validate_* tools. An agent can tell it apart from recipe, items_validate, and merge_assembly without opening schemas.

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?

Gives explicit when-to-use ('Run before building or merging to reject a malformed parameterization before geometry is spent') and effectively a when-not (don't use it to build — that's the build tool). It also names the analogous tool validate_manifest for pattern recognition. This is exactly the routing the agent needs across 200+ siblings.

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