Find and catalog existing Architecture Decision Records (ADRs) in a project, optionally including their content for analysis.
Discover and catalog existing ADRs in the project
| Name | Required | Description | Default |
|---|---|---|---|
| adrDirectory | No | Directory to search for ADRs | docs/adrs |
| includeContent | No | Whether to include ADR content in analysis |
Changes observed during successful MCP inspections.
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile with readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description doesn't need to restate those. However, the description adds no extra behavioral context, and the word 'catalog' could ambiguously suggest a persistent write, though annotations clarify it is read-only and idempotent.
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 a single concise sentence with no filler or redundancy, which is good. However, it is so short that it leaves out useful context, so it sits at the borderline between appropriately concise and under-specified.
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?
There is no output schema and no description of what the tool returns, so an agent may not know what 'catalog' produces or how includeContent alters the result. The tool has low complexity and no required parameters, which mitigates the gap, but for a discovery tool with no structured output the description remains incomplete.
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 input schema fully documents both parameters with defaults and descriptions, and the description adds no additional parameter-level meaning. With 100% schema description coverage, the baseline of 3 is appropriate.
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 uses a specific verb 'Discover and catalog' and a clear resource 'existing ADRs in the project', making the core function understandable. However, it doesn't explicitly distinguish this tool from siblings like review_existing_adrs or analyze_adr_timeline beyond the word 'discover', so it loses a point on differentiation.
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?
There is no guidance on when to use this tool versus alternatives, nor any mention of prerequisites such as project path configuration. The verb 'discover' implies an initial scan, but that is left to inference rather than stated explicitly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.