adr

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

No annotations are provided, so the description carries the burden. It discloses that the ADR is stored as a structured capture and can be recalled by any agent on the same project. However, it does not clarify whether the tool creates a new record each time, whether it overwrites existing records, or any side effects like memory isolation when team_id/task_id are used. The description offers some context but not complete behavioral transparency.

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 three sentences, each earning its place: the first names the action, the second provides a usage condition, and the third explains storage and sharing. It is front-loaded and free of redundant wording, making it easy for an agent to parse quickly.

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 a moderate complexity with 11 parameters and 3 required, but the description includes the key context: what the tool does, when to use it, and how the resulting data is used (recallable). It does not explicitly link to related tools like recall or capture, but the phrase 'can be recalled' hints at the ecosystem. The absence of an output schema means no return-value explanation is needed, and the description covers the essential usage scenario.

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 100%, so the schema already documents all 11 parameters. The description does not add additional parameter-level meaning beyond what the schema provides. According to the guidelines, a baseline of 3 is appropriate when the schema covers all parameters.

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 the tool records an Architecture Decision Record (ADR) with a specific verb ('Record') and resource ('Architecture Decision Record'). It also explains the purpose: 'when you make a technical decision that future agents should know about,' which distinguishes it from generic capture tools.

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 explicitly tells the agent when to use the tool: 'Use this tool when you make a technical decision that future agents should know about.' It does not mention alternatives or exclusions, but the condition is clear and actionable. The mention that ADRs are 'recalled by any agent' also sets expectations for use.

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