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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions the tool 'finds' ADRs, implying a read-only operation, but doesn't specify whether it returns a list, count, or details, or if it has side effects like logging. For a tool with zero annotation coverage, this leaves significant gaps in understanding its behavior and output.

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, efficient sentence that directly states the tool's purpose without unnecessary words. It's front-loaded with the core action ('Find Accepted ADRs') and adds only essential context ('that have not been reviewed in a while and may need revisiting'), making it easy to parse and understand 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?

Given the tool's moderate complexity (1 parameter, no output schema, no annotations), the description is minimally adequate. It covers the purpose but lacks details on behavior, output format, or error handling. Without annotations or an output schema, the description should do more to explain what the tool returns and how it operates, but it meets a basic threshold for clarity.

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 has 1 parameter with 100% description coverage, providing a clear default and type. The description doesn't add any parameter-specific details beyond what the schema already states (e.g., it doesn't explain what 'months' means in context or how the threshold is applied). With high schema coverage, the baseline score of 3 is appropriate as the description doesn't compensate but also doesn't detract.

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's purpose: 'Find Accepted ADRs that have not been reviewed in a while and may need revisiting.' It specifies the verb 'find' and the resource 'Accepted ADRs' with a specific condition (not reviewed in a while). However, it doesn't explicitly differentiate from sibling tools like 'review_adr' or 'update_adr_status' that might also handle ADR review processes.

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 implies usage context ('may need revisiting'), suggesting this tool is for identifying stale ADRs rather than performing reviews or updates. However, it lacks explicit guidance on when to use this versus alternatives like 'review_adr' (for actual review) or 'search_decisions' (for broader searches), and doesn't mention prerequisites or exclusions.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It adds some context: it 'exports a markdown file' (output format) and 'warns about similar past decisions' (a behavioral trait). However, it lacks details on permissions, rate limits, error handling, or whether the operation is read-only or destructive, which are critical for a tool that generates and exports files.

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 concise and front-loaded, stating the core action in the first clause. It uses two sentences efficiently to cover the main function and an additional feature ('warns about similar past decisions'). There's no wasted text, though it could be slightly more structured to separate usage from features.

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 the tool's complexity (generating and exporting an ADR with warnings), lack of annotations, and no output schema, the description is moderately complete. It covers the basic action and a key feature but misses details on output format specifics, error cases, or integration with sibling tools. It's adequate as a minimum viable description but has clear gaps for full contextual understanding.

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 has 100% description coverage, with 'session_id' documented as 'Session ID.' The description does not add any meaning beyond this, as it doesn't explain what a session ID entails or how it relates to ADR generation. Since schema coverage is high, the baseline score of 3 is appropriate, as the description doesn't compensate but also doesn't detract.

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's purpose: 'Analyze a saved session and auto-generate an ADR.' It specifies the verb ('analyze' and 'auto-generate') and resource ('saved session' to 'ADR'), making the action understandable. However, it doesn't explicitly differentiate from sibling tools like 'save_session' or 'review_adr', which might involve similar resources, so it misses full sibling distinction.

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 provides no guidance on when to use this tool versus alternatives. It mentions 'warns about similar past decisions,' but this is a feature, not usage advice. There's no indication of prerequisites, when to choose this over tools like 'check_stale_adrs' or 'save_session', or any exclusions, leaving the agent with minimal context for selection.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool 'visualizes' a graph, implying a read-only operation that likely returns a visual representation, but it doesn't specify output format (e.g., image, text), performance characteristics, or any constraints like rate limits. For a tool with no annotation coverage, this is a significant gap in 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 extremely concise and front-loaded: 'Visualize ADR dependency graph. Optionally scope to a single ADR.' Both sentences earn their place by stating the core purpose and a key usage nuance. There is no wasted text, making it efficient and easy to parse.

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 the complexity of visualizing a dependency graph, the lack of annotations, and no output schema, the description is incomplete. It doesn't explain what the output looks like (e.g., graphical format, data structure), how errors are handled, or any behavioral traits. For a tool that likely involves data processing and visualization, this leaves critical gaps for an agent to use it effectively.

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 has 100% description coverage, with the parameter 'adr_id' documented as 'Focus on a specific ADR (omit for full graph).' The description adds minimal value beyond this, only echoing the optional scoping. Since the schema does the heavy lifting, the baseline score of 3 is appropriate, as the description doesn't provide additional syntax or format details.

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's purpose: 'Visualize ADR dependency graph' with the option to 'scope to a single ADR.' It specifies the verb ('visualize') and resource ('ADR dependency graph'), making it easy to understand what the tool does. However, it doesn't explicitly differentiate from siblings like 'get_timeline' or 'search_decisions,' which might also involve ADR data, so it falls short of a perfect score.

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 implies usage by mentioning 'Optionally scope to a single ADR,' suggesting it can be used for both full and focused views. However, it provides no explicit guidance on when to use this tool versus alternatives like 'get_timeline' or 'search_decisions,' nor does it mention prerequisites or exclusions. This leaves the agent to infer context without clear direction.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states 'Get' but doesn't clarify if this is a read-only operation, what permissions are needed, how data is returned, or any rate limits. For a tool with no annotations, this is a significant gap in 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 a single, efficient sentence with zero waste. It's front-loaded and appropriately sized for the tool's apparent simplicity, making it easy 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?

Given no annotations, no output schema, and a simple input schema, the description is incomplete. It doesn't explain what a 'decision timeline' entails, how results are structured, or any behavioral traits, leaving the agent with insufficient context to use the tool effectively beyond basic invocation.

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 description coverage is 100%, with the parameter 'project' documented as 'Project name (omit for all projects)'. The description adds no additional meaning beyond this, such as format examples or constraints, so it meets the baseline for high schema coverage without compensating further.

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 action ('Get') and resource ('decision timeline for a project'), making the purpose understandable. However, it doesn't differentiate from sibling tools like 'search_decisions' or 'get_adr_graph', which might also retrieve decision-related information, so it lacks sibling distinction.

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?

No guidance is provided on when to use this tool versus alternatives. The description doesn't mention prerequisites, context, or exclusions, leaving the agent to infer usage based on the name alone, which is insufficient for effective tool selection.

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

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

With no annotations provided, the description carries full burden for behavioral disclosure. It states 'Create a relationship,' implying a write/mutation operation, but doesn't specify permissions needed, whether the operation is idempotent, error handling (e.g., if ADRs don't exist), or side effects. This leaves significant gaps for a tool that modifies data.

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, efficient sentence that front-loads the purpose ('Create a relationship between two ADRs') and includes essential details (relationship types). There is no wasted language, making it easy 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?

For a mutation tool with 3 parameters, 100% schema coverage, no annotations, and no output schema, the description is minimally adequate. It covers the basic action but lacks details on behavioral aspects like permissions, idempotency, or error cases. Without annotations or output schema, more context would be helpful for safe usage.

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%, with clear parameter descriptions in the schema (e.g., 'Source ADR ID,' 'Target ADR ID,' 'Relationship type'). The description adds minimal value beyond the schema by listing the enum values for 'relation,' but doesn't explain the semantics of relationship types (e.g., what 'conflicts_with' means). Baseline 3 is appropriate as the schema does most of the work.

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 action ('Create a relationship') and the resource ('between two ADRs'), with specific relationship types listed. It distinguishes itself from siblings like 'check_stale_adrs' or 'update_adr_status' by focusing on linking ADRs rather than status management or review. However, it doesn't explicitly differentiate from potential similar tools like 'get_adr_graph' which might retrieve relationships.

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 provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., ADRs must exist), exclusions, or compare to siblings like 'get_adr_graph' for viewing relationships or 'update_adr_status' for status changes. Usage is implied but not explicitly defined.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions the tool performs an 'AI quality review' and lists evaluation criteria, but doesn't describe the output format, potential side effects, permissions required, or any limitations like rate limits. This leaves significant gaps for a tool that likely returns structured feedback.

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, efficient sentence that front-loads the core purpose ('AI quality review of an ADR') and then specifies the evaluation aspects. There's no wasted verbiage, and every phrase adds value to understanding the tool's function.

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 the tool's complexity (AI-based quality assessment) and lack of annotations or output schema, the description is incomplete. It doesn't explain what the review output looks like (e.g., scores, flags, recommendations), how results are structured, or any behavioral nuances, which are critical for an agent to use this tool effectively.

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 input schema already documents the 'adr_id' parameter. The description doesn't add any parameter-specific details beyond what the schema provides, such as format constraints or examples. Baseline 3 is appropriate as the schema handles parameter documentation adequately.

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 specific action ('AI quality review') and resource ('ADR'), and distinguishes its purpose from siblings by focusing on quality assessment rather than generation, retrieval, or linking. It specifies what the review evaluates: completeness, missing context, unconsidered alternatives, and optimistic consequences.

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?

No explicit guidance is provided on when to use this tool versus alternatives like 'check_stale_adrs' or 'search_decisions'. The description implies usage for quality assessment but doesn't specify prerequisites, timing, or exclusions, leaving the agent to infer context from tool names alone.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It states this is a save operation to a database, implying a write/mutation, but doesn't mention permission requirements, whether the operation is idempotent, what happens on conflicts, or any rate limits. This leaves significant gaps for a tool that modifies persistent state.

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, focused sentence that efficiently communicates the core purpose without unnecessary words. It's appropriately sized and front-loaded with the essential information.

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 database write operation with no annotations and no output schema, the description is insufficient. It doesn't explain what happens after saving (success/failure responses), whether the operation creates or updates records, or any behavioral characteristics. The combination of mutation tool + zero annotation coverage requires more comprehensive description.

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 description provides no additional parameter information beyond what's already documented in the schema (which has 100% coverage). It doesn't explain relationships between parameters, format expectations, or usage examples. The baseline score of 3 reflects adequate but minimal value added given the comprehensive schema documentation.

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 action ('Save') and resource ('Claude Code development session to the database'), providing a specific verb+resource combination. However, it doesn't distinguish this tool from any potential sibling tools that might also save data, though none of the listed siblings appear to be direct alternatives.

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 provides no guidance on when to use this tool versus alternatives, prerequisites, or contextual constraints. It simply states what the tool does without indicating appropriate usage scenarios or exclusions.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool searches 'past architectural decisions by keyword' but doesn't reveal critical behaviors such as whether it's read-only, how results are returned (e.g., pagination, format), error conditions, or any rate limits. This leaves significant gaps for an agent to understand the tool's operation.

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, efficient sentence that front-loads the core functionality ('Search past architectural decisions by keyword'). There is no wasted text, making it highly concise and well-structured for quick understanding.

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 the lack of annotations and output schema, the description is incomplete. It doesn't address behavioral aspects like safety (read vs. write), result format, or error handling. For a search tool with no structured metadata, more context is needed to guide an agent effectively, such as what the search returns or any limitations.

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 has 100% description coverage, with the 'query' parameter fully documented as a 'Search term (e.g. Redis, PostgreSQL, JWT)'. The description adds minimal value beyond this, only implying keyword-based search without providing additional syntax, format details, or constraints. This meets the baseline for high schema coverage.

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's purpose with a specific verb ('search') and resource ('past architectural decisions'), and specifies the search mechanism ('by keyword'). However, it doesn't explicitly differentiate from sibling tools like 'check_stale_adrs' or 'get_adr_graph', which might also involve decision retrieval.

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 provides no guidance on when to use this tool versus alternatives. With siblings like 'check_stale_adrs' (likely for stale decisions) and 'get_adr_graph' (likely for relationships), there's no indication of when keyword search is preferred over other retrieval methods, nor any prerequisites or exclusions mentioned.

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

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

With no annotations provided, the description carries full burden for behavioral disclosure. It implies a mutation operation ('Update') but doesn't state permission requirements, whether changes are reversible, or what happens on success/failure. The status transition list is helpful but doesn't cover behavioral traits like validation rules or side effects (e.g., notifications).

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, efficient sentence that front-loads the core action ('Update the status of an ADR') followed by specific status values. There's zero wasted text, and every word contributes directly to understanding the tool's purpose.

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 mutation tool with no annotations and no output schema, the description is incomplete. It doesn't address what the tool returns, error conditions, or important behavioral aspects like whether 'superseded_by' is validated. The status transition list is useful but insufficient for safe invocation without additional context.

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 three parameters thoroughly. The description adds no parameter-specific information beyond implying status transitions, which the schema's enum already covers. This meets the baseline for high schema coverage but doesn't provide additional semantic context.

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 verb ('Update') and resource ('status of an ADR') with specific status transitions listed. It distinguishes this tool from siblings like 'check_stale_adrs', 'generate_adr', or 'link_adrs' by focusing on status updates rather than creation, review, or linking. However, it doesn't explicitly mention what ADR stands for (Architectural Decision Record), which could help further differentiate it.

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 provides no guidance on when to use this tool versus alternatives like 'review_adr' or 'link_adrs'. It lists status transitions but doesn't specify prerequisites (e.g., needing review before acceptance) or exclusions (e.g., not for initial creation). This leaves the agent to infer usage from the tool name alone.

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