lint_recipe

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

With no annotations present, the description carries the full burden and does well: it states the tool is LOCAL, pure-Python, token-free for the path form, and lists specific checks and the return shape. It does not disclose error behavior or explicitly confirm no side effects, but 'static-analysis' implies no mutation.

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 dense but well-structured: purpose, input modes, rule list, return shape. The long rule enumeration is justified as it tells the agent exactly what checks are performed, but it could be slightly trimmed for brevity without losing value.

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 zero annotations, zero schema descriptions, and no output schema, the description is remarkably self-sufficient. It explains what the tool does, the two input modes with their semantics, the specific lint rules, and the return value structure. No critical information is missing for an agent to decide when and how to invoke it.

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?

The schema has 0% description coverage, but the description compensates by defining 'path' as a local *.recipe.json file and 'recipe_id' as fetched live via the Developer API. It also clarifies the OR relationship between the two. It does not specify constraints like file existence or integer validity, but the core semantics are clear.

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 opens with 'LOCAL static-analysis of a SINGLE recipe,' a specific verb+resource combination that clearly differentiates it from sibling tools like get_recipe or list_recipes. It enumerates dozens of concrete lint rules, making its scope unambiguous.

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?

It provides clear guidance on the two mutually exclusive input modes: 'Provide EITHER path (a local *.recipe.json) OR recipe_id (pulled live via the Developer API).' It also notes 'no token needed for the path form,' which is useful context. However, it does not explicitly contrast this tool with alternatives or state when not to use it.

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