generate_adr

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

With no annotations, the description carries the burden, and it does disclose the key non-obvious behavior: this does not produce a finished ADR, only a structured prompt the host LLM must complete. That is genuinely useful. It does not mention determinism, side effects, or that the output format is MADR-prescribed content.

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?

Two sentences, front-loaded with the verb and format, then immediately the crucial distinction that the return value is a prompt rather than a document. No waste.

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 prompt-emitting generator with no output schema, the description covers the essentials: format, inputs by schema, and output shape. It is silent on how the prompt should be used (templating, tool chaining, expected host LLM behavior) and on edge cases like missing consequences, which for a generation tool aimed at a host LLM is a meaningful gap.

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 coverage is 83%, so the schema describes five of six parameters well, including the enum for status and minItems=2 for options. The description adds only the 'MADR-style' framing and none of the parameters; baseline 3 applies when the schema does the heavy lifting.

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 (Generate) and resource (ADR in MADR style), and adds what it returns: a structured prompt for the host LLM. It doesn't name a sibling, but it is distinguishable from generate_documentation and recommend_architecture by its ADR/MADR framing.

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?

Usage is implied by context ('generate an ADR'), and the two-stage nature (prompt the host LLM completes) hints at a workflow. There is no explicit when-to-use vs generate_documentation, recommend_architecture, or generate_implementation_plan, and no guidance on 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.