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

No annotations are provided, so the description must fully disclose behavior. It only says 'Create a new ADR' without mentioning side effects, required permissions, whether it overwrites duplicates, or any constraints. This is insufficient for a creation tool.

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 sentence, which is concise. However, it omits necessary details about parameters and usage, so it is not effectively concise—it sacrifices informativeness for brevity.

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 has 6 parameters and multiple siblings, the description is too minimal. It does not explain what an ADR is, the role of parameters, or what the output is (output schema exists but not referenced). It misses critical context for correct 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?

Schema description coverage is 0%. The description only mentions 'title and optional content', but the schema has 6 parameters (title, type, context, decision, deciders, project_path). The description fails to explain the meaning or usage of most parameters, providing no added value over the schema.

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 states it creates a new ADR, which is a specific verb and resource. However, it vaguely says 'optional content' while the schema includes multiple specific fields like type, context, decision, etc. It distinguishes from siblings like adr_update and adr_list, but lacks precision.

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 on when to use this tool vs alternatives such as adr_update or adr_supersede. It does not mention prerequisites like project_path or any context for decision-making.

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 present, so the description must disclose behavior. It only says 'build the dependency graph' without indicating side effects, destructiveness, or performance implications. The read-only vs. write nature is unclear.

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?

Single sentence that is front-loaded with the main purpose and optional filter. No redundancy, efficient word choice.

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 building a dependency graph and 15 sibling tools, the description is adequate but minimal. It doesn't specify output details (though output schema exists), format options, or prerequisites. Leaves gaps for an AI agent to infer.

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 0%. The description indirectly explains the 'number' parameter (filter to transitive deps) but does not explain 'format' (default mermaid) or 'project_path'. The description adds minimal meaning beyond the schema structure.

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 'Build the dependency graph of ADRs' with a specific verb and resource, and mentions optional filtering by transitive deps. This distinguishes it from siblings like adr_diagram (visualization) and adr_list (plain listing). However, it does not explicitly differentiate from adr_impact or adr_link.

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 mentions optional filtering but provides no guidance on when to use this tool vs. siblings like adr_diagram or adr_impact. No when-not-to-use or alternative recommendations.

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 should fully disclose behavioral traits, but it only states the action without explaining what deprecation entails (e.g., status changes, reversibility, side effects).

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 too sparse, consisting of a single short sentence that lacks essential details; it does not earn its place as it fails to convey sufficient 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?

Given the tool has 3 parameters, no schema descriptions, no annotations, and is a mutation operation, the description is severely incomplete, missing information about behavior, return values, and parameter specifics.

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 for parameters, and the description adds no meaning to 'number', 'reason', or 'project_path', leaving an agent without necessary context for correct use.

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 specifies the action 'Deprecate' and the resource 'ADR' with a reason, but it does not distinguish this tool from sibling tools like adr_supersede or adr_update_status, which have similar purposes.

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, such as when to deprecate vs. supersede, nor does it mention any prerequisites or context for using the tool.

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, and the description does not disclose side effects (e.g., file creation), required permissions, rate limits, or whether the operation is read-only or mutating. The description carries the full burden but adds minimal behavioral context.

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 sentence with no redundancy. It is appropriately front-loaded but could benefit from additional details without sacrificing conciseness.

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?

Despite having an output schema, the description is insufficient for a tool with multiple parameters (format, diagram_type, project_path) and an ambiguous generate/retrieve behavior. It lacks explanation of how these parameters affect the output, making the tool incomplete for correct agent 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?

Schema description coverage is 0%, and the description does not explain any parameters. While the schema provides types and defaults, the meaning of 'diagram_type' and 'project_path' remains unclear. The description should compensate for the low coverage but fails to do so.

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 states it generates or retrieves a diagram for an ADR, specifying verb and resource. However, the 'or' creates ambiguity about whether it always generates or can retrieve existing diagrams. Among sibling tools focused on CRUD operations, this one is distinct but the ambiguity reduces clarity.

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 on when to use this tool versus alternatives like adr_read or adr_export. There is no mention of appropriate contexts or when to generate vs retrieve, leaving the agent without decision criteria.

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?

Without annotations, the description should provide behavioral details, but it only states the action. It does not mention if it overwrites existing files, whether network access is required, or any side effects. The presence of an output schema partially compensates but does not cover behavioral traits.

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 very concise at one sentence. It is front-loaded with the action. However, it omits necessary details, making it somewhat under-specified. 'Appropriately sized' for a simple tool but missing parameter guidance.

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 has two optional parameters and a non-trivial export operation, the description is incomplete. It does not address parameter behavior or edge cases. The output schema helps with return values but does not complete the 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?

The input schema has two optional parameters with 0% description coverage. The description does not explain the purpose of 'output_dir' or 'project_path', nor their default behavior (null). An agent would need to guess what these parameters control.

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 ('Export') and the resource ('all ADRs') and the output format ('HTML'), making it easy to understand what the tool does. It implicitly distinguishes from sibling tools like adr_create, adr_read, etc.

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 on when to use this tool versus alternatives. The description does not mention conditions, prerequisites, or exclusions. For example, it doesn't say if this is for full documentation generation or partial export.

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, and the description does not disclose any behavioral traits such as read-only, side effects, or authentication requirements. It implies a read operation but offers no explicit 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 sentence, which is concise but too brief to cover necessary details. It front-loads the core action but omits important contextual 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?

Given the existence of an output schema (not shown) and many sibling tools, the description lacks completeness. It does not explain what an ADR is, how the query works, or how the timeline is structured, making it insufficient for confident agent 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 coverage is 0%, and the description does not explain what the 'query' parameter accepts (e.g., regex, keywords) or the purpose of 'project_path'. The agent gets no additional meaning beyond the plain schema.

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 ADRs matching a query, with a specific output format (timeline sorted by date). It uses a specific verb ('find') and resource ('ADRs'), and the timeline aspect distinguishes it from sibling tools, though not explicitly.

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 like adr_search or adr_list. The description does not specify the query format, scope, or exclusion criteria.

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, the description must fully describe behavior. It only states 'find all ADRs that mention a component' but does not specify whether it searches full text, titles, or metadata, nor does it mention return format, side effects (none expected), or any limitations. This is insufficient for a tool with no annotations.

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 sentence, which is concise and front-loaded with the verb. However, it is somewhat under-specified; a slightly more detailed statement would not harm conciseness.

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 existence of an output schema (which defines return structure), the description still misses contextual details like what constitutes a 'mention' (exact match, substring, case sensitivity) and the scope of search (all ADRs or only recent). This makes the tool harder to use correctly.

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 two parameters (component and project_path) with 0% schema description coverage. The description does not explain what 'component' refers to (e.g., name, path) or the role of project_path, leaving the agent to guess.

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 states 'Find all ADRs that mention a component.' This clearly identifies the verb (find) and resource (ADRs) with a specific scope (mentioning a component), which distinguishes it from siblings like adr_list (lists all ADRs) and adr_search (generic search).

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. For example, it does not clarify when to use adr_impact over adr_search or adr_list, nor does it mention any prerequisites or exclusion criteria.

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 alone must disclose behavioral traits. It only states that a link is added, with no information about permissions, reversibility, duplicate prevention, or side effects. This is insufficient for a write 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, clear sentence with no redundant or extraneous information. It efficiently conveys the core 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?

Given the simplicity of the tool, the description is minimal. However, it lacks context about prerequisites (e.g., ADRs must exist), behavior on linking already linked ADRs, and the return format (despite an output schema existing). This incomplete context may hinder correct agent 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 input schema has three parameters (from_number, to_number, project_path) with no schema descriptions (0% coverage). The tool description adds zero semantic value beyond the parameter names; it does not explain what the numbers represent, what project_path is for, or any constraints.

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 'Add a bidirectional related link between two ADRs' uses a specific verb ('Add') and resource ('bidirectional related link') and clearly identifies the objects (two ADRs). It distinguishes from sibling tools such as adr_create (creates new ADR) and adr_update (updates ADR).

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 for linking two ADRs but provides no explicit guidance on when to use this tool versus alternatives like adr_dependencies (which might handle dependency tracking). No when-not-to-use or alternative information is given.

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 provided, so the description should disclose behavioral traits. It implies a safe read operation by saying 'list', but lacks details on pagination, performance, or what 'all ADRs' means in terms of scope (e.g., current project?).

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 that front-loads the main purpose. However, it could be expanded to cover missing parameters without becoming verbose.

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?

With an output schema present, return value documentation is not needed, but the description omits important context: no sibling differentiation, no parameter explanation for one param, and no usage guidance. This makes the tool underspecified for an AI agent.

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 0%, so the description must explain parameters. It correctly identifies status and type as filters, but the 'project_path' parameter is not mentioned, leaving ambiguity about its role.

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 lists all ADRs with optional filtering by status and type, but does not differentiate it from sibling tools like adr_search or adr_overview.

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 on when to use this tool versus alternatives such as adr_search (for complex queries) or adr_overview (for summaries). The description only mentions filtering but not use cases.

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, description provides minimal behavioral context. States 'generate' but does not explain side effects, output format, or that it likely returns a diagram (implied by format parameter). No mention of data persistence or modifications.

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?

Single sentence with no fluff. Could be slightly expanded for clarity without becoming verbose.

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 14 sibling tools and 3 parameters, the description is too sparse. Does not explain output schema (though exists), usage context, or how it differs from similar diagram tools. Inadequate for accurate selection.

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 0%, so description must explain parameters. It only references the status_filter via 'filtered by status', but does not explain 'format' (default mermaid) or 'project_path' (likely needed for project context). Partial compensation.

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?

Clearly states it generates an overview diagram of ADRs with optional status filter. However, sibling 'adr_diagram' also produces diagrams, and the description does not differentiate them.

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 on when to use this tool versus alternatives like adr_diagram or adr_list. Does not specify exclusions or prerequisites.

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?

Read operation is implied but not explicitly stated as non-destructive. No mention of error handling, rate limits, or special permissions. Minimal disclosure beyond the obvious.

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, no wasted words. Front-loaded with main 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?

Adequate for a simple read tool with output schema, but misses explanation of optional 'project_path' parameter. Could be improved by describing the structure of returned content.

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?

Description explains 'query' parameter as number or title substring, but does not describe 'project_path' at all. With 0% schema coverage, this is insufficient.

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?

Verb 'Read' and resource 'ADR' are clear. Specifies lookup by number or title substring. However, it doesn't explicitly differentiate from sibling tool 'adr_search' which may also retrieve ADRs.

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 on when to use this tool vs alternatives (e.g., adr_search for more complex queries). No when-not or conditions.

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 full burden. It only says 'full-text search' without disclosing behavior like result format, limits, or side effects. Output schema exists but description does not reference it.

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?

A single sentence, front-loaded with the key action. No extra words.

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?

With 14 sibling tools and no annotations, the description is too brief. It lacks details on scope, filtering, or output, making it insufficient for a search tool.

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 0%, and the description does not explain the 'query' or 'project_path' parameters. The agent gains no additional meaning beyond the schema's field names.

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 'Full-text search across all ADRs', specifying the verb (search) and resource (ADRs). This distinguishes it from siblings like adr_list or adr_read.

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 on when to use this tool versus alternatives like adr_list or adr_read. The description does not mention exclusions or prerequisites.

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?

The description indicates that the tool modifies the old ADR (marks as superseded) and links it to the new ADR. However, it does not disclose side effects, permission requirements, or reversibility. With no annotations, this minimal transparency is acceptable but not comprehensive, earning a middle score.

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 that front-loads the core purpose. It is efficiently written without wasted words, though it could include slightly more detail without becoming verbose.

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 has three parameters (two required), no annotations, and an output schema (which may cover return values), the description lacks context on prerequisites, side effects, and usage scenarios. It is minimally complete for a simple mutation tool but could better address potential user questions.

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 0% description coverage, and the tool description does not explain the parameters. While parameter names ('old_number', 'new_number', 'project_path') are somewhat intuitive, the description adds no additional semantics or constraints. For a tool with undocumented parameters, this is insufficient.

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 ('Mark an ADR as superseded') and the resource ('ADR'), with specific detail about linking to another ADR. This distinguishes it from siblings like adr_deprecate (which likely only deprecates without a successor) and adr_update_status (which changes status generally).

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 does not mention situations where this tool is appropriate, such as when an ADR is replaced by another, nor does it warn about misuse or mention when not to use it (e.g., when simply deprecating without a successor).

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 provided. Description states 'overwrite' implying destructive action (replaces content), but does not disclose whether history is preserved, if permissions are needed, or if the operation is reversible. For a mutation tool without annotations, more behavioral context is needed.

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 sentence, front-loading the core action. It is concise, but could be expanded to cover behavioral notes without being verbose.

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, the description is inadequate. It does not mention return values (despite having an output schema), error conditions, or the effect on linked ADRs. Sibling tools exist (e.g., adr_history) that could be referenced.

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?

With 0% schema description coverage, the description adds no parameter-level meaning. The three parameters (number, content, project_path) are not explained beyond their names. The agent has no context on valid formats for content, or the role of project_path.

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 'overwrite' and the resource 'existing ADR', and specifies the action is with 'new markdown content'. It distinguishes from siblings like adr_create (creates new) and adr_update_status (only updates status), but could be more explicit about the scope of overwrite (e.g., replaces entire content).

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 on when to use this tool vs alternatives (e.g., adr_supersede, adr_update_status). No prerequisites or context provided. The agent must infer from the name and description.

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 present, so the description must carry the full burden. It only states the action (change status) but does not disclose behavioral traits like permissions, side effects, or what the output schema contains.

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 sentence, which is under-specified for a tool with four parameters. It does not earn its place because it provides no useful information beyond the name.

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 (4 parameters, no schema descriptions, output schema present but undescribed), the description is entirely inadequate. It does not cover parameter meanings, return behavior, or usage 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 0%, and the tool description does not add any meaning to the parameters. It fails to explain what values status accepts, what number refers to, or the purpose of reason and project_path.

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 'Change the status of an existing ADR.' is a tautology that simply restates the tool name adr_update_status without adding specificity or distinguishing it from siblings like adr_deprecate or adr_supersede.

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 vs. alternatives such as adr_deprecate, adr_supersede, or adr_update. The description does not mention use cases or exclusions.

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