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

With no annotations, the description carries the burden and does disclose useful behavior: it includes test files and is intended for pre-test execution. However, it does not state that the operation is read-only, what the return structure looks like, or whether it traverses the full dependency graph (despite max_depth being an input). This is adequate but not rich.

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?

Three tight sentences: the first states the core function, the second adds the test-file detail, and the third gives the operational context. There is no wasted text, and the most identifying information is front-loaded.

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 read-style query tool with fully documented parameters, the description is nearly complete: it explains the tool's purpose, a key behavioral feature (test files), and the practical context. The only missing context is an explicit statement about the return value format and exclusions vs alternatives, but the tool is simple enough that this does not block 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 100%, so each parameter is already documented. The description adds no extra parameter-level meaning beyond implying the main input is a changed file path, which aligns with the schema. Baseline 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 states a specific verb ('Find'), a specific resource ('all files affected by a change to a specific file or symbol'), and a notable inclusion ('test files'). It clearly distinguishes this tool from sibling search tools like get_dependents or get_file_context by emphasizing test-file coverage and its purpose for test execution.

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 an explicit when-to-use context: 'Use this before running tests to know which test files to execute.' This is clear context, though it does not explicitly name alternatives or state when not to use this tool versus impact_analysis or simulate_change.

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 carries the full burden. It discloses that claims are visible to other MCP clients and expire after a configurable TTL, which is useful. It omits details about overlapping claims, idempotency, failure behavior, or any permissions needed, leaving some behavioral ambiguity.

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 tight sentences with the core purpose front-loaded and the TTL lifecycle detail included without filler. Every sentence adds meaningful 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?

The description is enough for an agent to understand the tool's role and select it, but it lacks details about return values, claim conflicts, and the lifecycle interaction with release_files/get_active_claims. Given the absence of an output schema and annotations, some gaps remain.

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 five parameters. The description adds no parameter-level detail, but it also does not need to since the schema handles it 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 names a specific action and object: 'declare intent to modify files,' and explains the coordination goal so other MCP clients see the claim and avoid conflicts. This clearly distinguishes claim_files from siblings like release_files or get_active_claims.

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 when to use the tool: before modifying files in a multi-agent environment. However, it does not explicitly name alternatives like release_files or get_active_claims, nor does it state when not to use it, so it falls short of full routing guidance.

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 disclosure burden. It does disclose two consequential behaviors—automatic cloning for GitHub URLs and replacement of the currently loaded project—which are genuinely important for an agent to know before invoking it. However, it stays silent on failure modes, private-repo/auth requirements, the time cost of cloning, and what 'replaces' implies for any existing analysis 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?

Three sentences, each carrying distinct information: the tool's purpose, the accepted input forms, and the cloning plus replacement behaviors. There is no filler or redundancy, though the critical replacement side effect is tail-positioned rather than flagged up front.

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 2-parameter tool with no annotations and no output schema, the description fully covers how to invoke it and names the key side effect. But it omits any indication of what the tool returns on success or failure, and with no output schema and no annotations that information is not available elsewhere.

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%: both 'source' (with examples of local path and GitHub URL) and 'subdirectory' (with example) are already well documented in the schema. The description adds no new parameter-level meaning beyond the schema, so the baseline of 3 applies.

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 opening phrase 'Connect Depwire to a codebase for analysis' pairs a specific verb with a clear resource and purpose, and the rest of the description pins down the two accepted input forms (local path or GitHub URL). It reads clearly as the project-loading/setup tool among siblings that all operate on an already-loaded project, though it never explicitly contrasts itself with those siblings.

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 conveys the core usage context: this is the tool to load the codebase under analysis, accepting either a local directory or a GitHub URL. However, it never explicitly states when not to use it, names an alternative, or explains prerequisites such as prior project state, leaving routing decisions largely to the agent's inference.

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 behavioral disclosure burden. It explains what the tool scans, the fact that results are categorized by confidence level, and defines the meaning of high confidence ('definitely unused'). It does not deeply explain detection heuristics or limitations of medium/low confidence, but it is transparent about the core behavior and output categorization.

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 tight sentences with no filler. The core definition is front-loaded, followed by output semantics and a clear use case. Every sentence earns its place.

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 tool with only one optional parameter and no output schema, the description is largely complete: it defines what it does, how results are categorized, and when to use it. It could be slightly more specific about the exact return shape, but that is not critical given the simplicity of the 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?

The input schema already documents the confidence parameter fully (enum values, default, description). The tool description adds semantic value by defining what 'high' confidence means, which helps an agent interpret the parameter's effect and the results it will receive.

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 a specific verb ('Find') and a specific resource ('potentially dead code — symbols that are defined but never referenced anywhere in the codebase'). This clearly differentiates the tool from sibling code-analysis tools like get_dependencies or search_symbols, whose purposes are different even though they operate on the same codebase.

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 gives a clear intended use case: 'Use this to identify cleanup opportunities.' It does not explicitly name alternatives or state when not to use the tool, but the cleanup framing provides enough contextual guidance for an agent to select it appropriately among siblings.

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 burden of behavioral disclosure. It clearly signals a read-only operation through 'Query' and states the return type ('active file claims'). It does not detail expired-claim behavior or output structure, but it is not misleading and covers the core behavior.

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: two short sentences with no filler. It front-loads the core query action and immediately states the result type and use case, making every sentence valuable.

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 simple read-only tool with three optional parameters, the description covers purpose, return concept, and usage context. The schema fully documents parameters. It does not describe edge cases like expiration or result ordering, but those are not essential for 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 input schema has 100% description coverage for all three optional parameters, so the schema already documents parameter meaning. The tool description adds no additional parameter-level detail, placing it at the baseline of 3.

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?

Description uses a specific verb ('Query') and names the resource ('active file claims'), while explaining the intended use for orchestrator delegation. It is distinguishable from sibling mutation tools like claim_files and release_files because it is explicitly a read-only lookup, though it does not name those 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 gives clear context for when to use it: 'useful for orchestrator agents deciding what to delegate.' It does not explicitly state when not to use it or name alternative tools, but the context is sufficient for a simple read query.

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 carries the transparency burden. It clearly discloses what the tool returns (file count, symbol count, connectivity metrics, hotspots, orphans), which is the core behavioral expectation. It does not discuss cost or performance, but for a simple read-only overview tool this is a minor gap.

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 entire description is one carefully constructed sentence that leads with the main purpose and then efficiently enumerates the specific summary elements. Every phrase adds value and there is no redundancy or filler.

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 zero-parameter tool with no output schema, the description provides a solid list of what the agent will receive, which is enough to set expectations. It does not define the exact return format, but the itemization is sufficiently complete for an overview tool and no additional context seems essential.

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 tool has zero parameters and the schema coverage is 100%, so there is no parameter information for the description to add. The description appropriately says nothing about parameters, matching the baseline of 4 for parameterless tools.

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 identifies the action ('Get') and resource ('project's architecture'), then lists concrete outputs: file count, symbol count, most connected files, dependency hotspots, and orphan files. This distinguishes it from sibling tools like list_files, get_dependencies, and find_dead_code, whose scopes are narrower or differently focused.

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 phrase 'high-level overview' implies the tool is for architecture-level understanding rather than detailed file-level queries, but the description does not explicitly state when to prefer it over alternatives or mention any prerequisites or exclusions. Usage context is only implied, not stated.

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 carries the behavioral burden. 'Retrieve' and 'see what previous agents decided' clearly signal a non-mutating read operation and add cross-session context. It does not discuss auth, rate limits, or output format, but for a simple getter those omissions are minor.

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 with no filler: the first states exactly what the tool does, and the second explains why it matters. Information is front-loaded and every sentence earns its place.

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 read-only query tool with six optional, fully documented parameters, this description is nearly sufficient. It would be slightly more complete with an explicit note about the returned decision records, since there is no output schema, but 'Retrieve past decisions' adequately covers the core expectation.

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 parameters are already fully documented. The description adds no additional meaning beyond naming the query concept, so the baseline 3 applies.

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 opens with a specific verb and resource ('Retrieve past decisions matching a query') and clarifies the intent: seeing what previous agents or earlier sessions decided. This clearly distinguishes it from sibling tools like record_decision, which writes decisions rather than reading 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?

The second sentence implies when to use the tool: when an agent wants to learn from similar past decisions. However, it does not explicitly state when not to use it or name alternatives such as record_decision, so usage guidance is implied rather than explicit.

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 description carries burden. Describes disambiguation for duplicate names, but omits output format, safety, or auth requirements. Adequate but not comprehensive.

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 purpose, no redundancy. Every sentence earns its place.

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 output schema, the description should hint at the return format (e.g., list of symbol IDs). It is adequate for a simple query tool but could be more complete.

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 has 100% coverage with description. The tool description adds concrete examples ('Router', 'src/router.ts::Router') and explains matching behavior, adding value beyond 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?

Clearly states the tool retrieves symbols that a given symbol depends on, with a parenthetical clarifying imports/calls. Distinguishes from sibling 'get_dependents' which would be the inverse.

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?

Provides clear input format (name or full ID) and disambiguation behavior. Lacks explicit when-not or alternatives, but context makes usage clear.

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 carries the behavioral disclosure burden. It does disclose an important behavior: if multiple symbols share a name, all matches are returned for disambiguation. It also mentions exact-matching behavior for fully qualified IDs. However, it does not describe what happens when a symbol is not found, whether the result is grouped, or how matches are structured.

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 concise sentences with no filler. The core purpose is front-loaded, followed by parameter usage guidance, and then the disambiguation behavior. Every sentence contributes useful 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 simple one-parameter tool with no annotations and no output schema, the description provides the key input semantics, matching behavior, and disambiguation policy. It does not describe the exact return format or error behavior, but the tool's purpose is simple enough that the description is largely complete.

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 100%, so the schema already documents the single 'symbol' parameter. The description adds examples and clarifies the difference between a simple name and a fully qualified ID, which adds some value. Still, it mostly restates the schema meaning, so the baseline 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 clearly states a specific action and resource: 'Get all symbols that depend on a given symbol.' The parenthetical 'what uses this symbol?' reinforces the direction of the relationship. It does not explicitly differentiate from sibling tools like get_dependencies, though the direction is clear enough to avoid major confusion.

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 when to use this tool: whenever you need to find dependents of a symbol. It explains how to pass either a simple symbol name or a fully qualified ID for exact matching, which is useful context. However, it does not explicitly contrast this with similar sibling tools such as get_dependencies or search_symbols, nor does it state 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.

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

With no annotations, the description carries the behavioral disclosure burden. It clearly explains what the tool returns and also discloses the line-range slicing behavior for large files. It does not mention read-only status explicitly, but the verb 'Get' and the content described strongly signal a non-mutating analysis 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?

Two sentences with no filler. The main purpose is front-loaded, and the subsequent details are organized by scope of returned context, followed by parameter use-case. Every sentence earns its place.

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 read-only context retrieval tool with no output schema, the description is complete: it specifies input file path and optional line slicing, enumerates the returned content categories, and even mentions cross-language connections. An agent has enough information to select and invoke the tool 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?

Schema description coverage is 100%, so the parameters are already well-documented. The description adds value by explaining that startLine/endLine exist for chunked reading of large files, which gives practical context beyond the schema's 'return only a slice' wording.

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 ('Get') with a clear resource ('complete context about a file') and enumerates distinctive components: symbols, imports, exports, dependents, and cross-language connections. This allows an agent to distinguish it from narrower siblings like get_symbol_info, get_dependencies, and get_dependents.

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 when to use the tool—when complete file context is needed—but it does not explicitly state when to prefer alternatives or when not to use it. There are no exclusion criteria or named sibling comparisons, so the guidance is implied rather than explicit.

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 carries the burden of behavioral disclosure. It clearly explains what the tool computes, the output format (overall score, per-dimension breakdown, recommendations), and the dimensions analyzed. It does not explicitly state whether the operation is read-only or has side effects, but the verb 'Get' and the tool name strongly imply a non-mutating analysis.

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 with no filler. The first sentence front-loads the core purpose (0-100 health score for dependency architecture), and the second efficiently enumerates the scoring dimensions and the return format. Every sentence contributes valuable 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?

The description fully explains the return value (overall score, dimensions, recommendations) given that no output schema exists. It clearly scopes the analysis to dependency architecture, which is sufficient for tool selection. It could slightly improve by hinting at what not to use it for or naming a sibling, but nothing critical is missing 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?

The tool has zero parameters, and the input schema is an empty object, so there are no parameter descriptions to supplement. With 0 params, a baseline of 4 is appropriate; the description confirms that the tool operates on 'the project' without needing further input specification.

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 ('Get') and resource ('health score for the project's dependency architecture'), clearly distinguishing it from siblings by emphasizing a numeric 0-100 score and actionable recommendations. The listed evaluation dimensions (coupling, cohesion, circular dependencies, etc.) further make the tool's purpose concrete and distinct from other analysis 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 implies when to use it (when you need a health score of dependency architecture) but gives no explicit exclusions or alternative tools. Sibling tools like get_architecture_summary or get_dependencies serve different purposes, but the description doesn't state when NOT to use this tool or point to an alternative.

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 carries the behavioral burden. It does add useful context by stating the tool only retrieves pre-generated docs and listing the returned categories, but it does not disclose failure behavior when docs are missing, authentication needs, or response shape. Useful but not comprehensive.

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 deliver the core action, output contents, and the prerequisite without filler. The most important information is front-loaded.

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 simple read-style tool with one optional parameter and no output schema, the description covers what is returned and the precondition. It is slightly incomplete in not stating behavior when docs have not been generated and in not routing among overlapping siblings, but it is largely sufficient.

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 single parameter doc_type is fully documented in the input schema (100% coverage), so the description doesn't need to add much. It aligns with the listed content types but provides no additional meaning beyond the schema's enum values and default.

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 opens with a clear verb and resource ('Retrieve auto-generated codebase documentation') and enumerates the content types returned. It doesn't explicitly differentiate from get_architecture_summary, a sibling that overlaps on 'architecture overview', so it falls just short of full sibling separation.

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?

It gives a concrete prerequisite ('Documentation must be generated first with `depwire docs` command'), which helps an agent know when calling is valid. However, it provides no guidance on when to prefer this over siblings like get_architecture_summary or get_dependencies, so selection guidance is incomplete.

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 behavioral burden. It discloses two meaningful behaviors: exact matching via name or fully qualified ID, and returning all matches when names collide. It does not state what happens when no symbol is found, whether the operation is read-only, or what fields of 'detailed information' will be returned.

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?

Three sentences with no filler: purpose, input format, and collision behavior. The most important information is front-loaded, and every sentence earns its place.

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 one-parameter lookup with no output schema and no annotations, the description covers the main selection and invocation needs but leaves gaps: no return shape, no not-found behavior, and no explicit side-effect declaration. It is adequate but not fully complete.

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 already documents the name parameter fully (100% coverage), setting a baseline of 3. The description adds value by clarifying that the parameter can be a simple name or a qualified ID, that matching is exact, and that ambiguity triggers multiple results — semantics beyond the schema's examples.

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 a specific action ('Look up') and a resource ('detailed information about a symbol') with examples of both simple names and fully qualified IDs. It differentiates from sibling search_symbols by emphasizing exact matching and disambiguation for multiple matches, though it doesn't explicitly name the sibling.

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 gives clear usage context: it is for retrieving detailed info about a known symbol and specifies how to format the input for exact matching. It does not explicitly state when alternatives like search_symbols or get_file_context should be used, so it lacks explicit when-not guidance.

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 carries the behavioral disclosure burden. It explicitly states the tool 'Returns snapshots at sampled commits showing file counts, symbol counts, edge counts, and structural changes over time,' which discloses the read-only, sampling-based nature and gives a concrete picture of the output. This is sufficient for a read-style analytical 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 two sentences with the primary purpose front-loaded and no filler. The second sentence efficiently summarizes the return content without unnecessary detail.

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?

Without an output schema, the description does explain what is returned (snapshots with file/symbol/edge counts and structural changes). It lacks an explicit output shape or detail on how sampling strategies affect results, but for a tool with two optional parameters this is largely sufficient.

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 already fully describes both parameters with defaults and an enum, so the description adds no additional meaning beyond what is in the schema. With 100% schema coverage, baseline 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 ('Show how...evolved') and names a precise resource ('dependency graph over git history'), clearly distinguishing this from static-analysis siblings like visualize_graph or get_architecture_summary. The temporal evolution focus is unique among the sibling list.

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 the tool is for historical evolution of the dependency graph but never explicitly states when to prefer it over alternatives or mentions any exclusions. Context makes the use case clear, but no explicit routing or contrast with siblings is provided.

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 carry behavioral disclosure. It clarifies matching semantics ('fully qualified ID ... for exact matching'), disambiguation behavior ('returns all matches'), and cross-language span, while 'Analyze' signals a non-mutating operation. It does not explicitly state read-only behavior, but the analysis framing plus the 'before making changes' context make it reasonably clear.

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 front-loaded with purpose and packs six sentences of relevant detail: output scope, cross-language reach, input syntax, disambiguation, and usage timing. It is slightly longer than necessary, but every sentence adds information an agent needs.

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 output schema, the description summarizes what will be returned (dependents, transitive dependents, affected files) and how to request it. It could be more explicit about the exact return shape or any side effects/limits, but it provides enough context for an agent to select and invoke the tool 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?

Schema coverage is 100%, so parameters are already documented. The description adds value by detailing the symbol input format ('src/router.ts::Router') and the behavior when names collide ('returns all matches for disambiguation'), which goes beyond the schema field descriptions.

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 opens with a specific verb and target: 'Analyze what would break if a symbol is changed, renamed, or removed.' It enumerates the outputs (direct dependents, transitive dependents, affected files) and highlights cross-language edges, distinguishing it from sibling tools like get_dependents or affected_files.

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 final sentence explicitly tells an agent when to use the tool: 'Use this before making changes to understand the blast radius.' It does not name alternatives or list when not to use it, so it stops short of full exclusion guidance.

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 carries the burden of disclosing behavior. It conveys that this is a read-only listing operation and allows optional subdirectory filtering, but it does not explain traversal behavior (recursive or not), what 'basic stats' actually includes, or whether hidden files are included.

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, front-loaded sentence that conveys the core purpose without any filler. Every word contributes meaning.

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 description is adequate for a simple listing tool with one optional parameter and no output schema, but it leaves important context unspecified, such as the exact nature of 'basic stats' and whether the listing is recursive. An agent could invoke it correctly but might misinterpret the response shape.

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 only parameter, 'directory', is fully described in the schema as an optional subdirectory filter. The tool description adds no additional semantic detail beyond the schema, so the baseline score of 3 applies.

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 ('List'), the resource ('all files in the project'), and the output scope ('with basic stats'). It is distinguishable from siblings like get_file_context or impact_analysis by its broad, project-wide listing scope, though it does not explicitly name any alternative.

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 intended use is implied by the name and description: to enumerate files in the project with basic statistics. However, there is no explicit guidance about when to choose this over alternatives, when not to use it, or what scenarios warrant the optional directory filter.

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 explicitly states that the tool persists data to .depwire/decisions.jsonl and that the record will be visible to future clients, which goes beyond the basic 'save' semantics. It does not mention append vs. overwrite behavior or return values, but the storage location is a meaningful disclosure.

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, both earning their place. The first states the action and purpose; the second gives the concrete storage location. No filler or redundant restatement of the tool 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?

The schema richly documents all eight parameters, and the description explains the core persistence behavior and location. It does not describe the return value or success/failure semantics, and there is no output schema to fill that gap, but an agent has enough to invoke the tool 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?

Schema description coverage is 100%, so the input schema already documents every parameter. The description adds only the general notion of a 'structured decision' and does not explain parameter relationships or provide usage examples, keeping this at the baseline for fully-covered schemas.

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 ('Save') and clearly identifies the resource ('a structured decision') and the reason for existence (visibility for future clients/sessions). It is easily distinguished from the sibling get_decisions, which is for reading decisions, and from update_project_docs, which targets different 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?

The description provides clear context: use this when a decision needs to be persisted for future clients or sessions. It does not explicitly name alternatives or state when not to use it, but the use case is unambiguous and naturally separated from retrieval-oriented siblings.

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 carries the behavioral burden. It discloses a meaningful side effect—the release is recorded as an append-only event—which signals non-destructive audit behavior. It does not state whether the claim becomes available again, idempotency, or error conditions, so transparency is partial.

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 short sentences with no filler. The core action is front-loaded, and the append-only side effect earns its place as essential behavioral context.

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 two-parameter tool with fully documented schema and no output schema, the description plus schema cover the essential invocation context. Some behavioral outcomes, such as whether the claim becomes reclaimable, are left implicit, but nothing critical blocks a correct call.

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 baseline is 3. The description adds no additional parameter detail, but the schema already explains claim_id and the session_id matching requirement.

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 ('release') and a concrete resource ('previously made file claim'), immediately distinguishing this from sibling tools like claim_files and get_active_claims. The inverse relationship to claiming is clear without needing to inspect other tool schemas.

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 through 'previously made file claim' and the schema's session_id constraint, suggesting this tool applies only to existing claims. However, there is no explicit when-to-use or when-not-to-use guidance, and sibling alternatives are not named.

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 carries the burden of behavioral disclosure. It does add useful semantics: searching across the whole codebase and supporting partial matches. However, it does not mention whether the operation is read-only, whether results are limited by the limit parameter, or what kind of result entries are returned, so some behavioral context is missing.

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 two short, purposeful sentences with no filler. The core operation, scope, and matching behavior are front-loaded, and the schema handles parameter details.

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 simple search tool with only two parameters and full schema coverage, the description is mostly adequate. However, with no output schema and no annotations, it would be stronger if it stated what the search results contain (e.g., symbol names, file locations) and that the operation is non-destructive.

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 explains both 'query' and 'limit' clearly, including the case-insensitive substring behavior and default limit. The description's 'partial matching' aligns with the schema but does not add additional parameter-level meaning beyond it.

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 a clear verb ('Search') and resource ('symbols by name') with an explicit scope ('across the entire codebase') and matching behavior ('partial matching'). It is distinguishable from sibling tools like get_symbol_info because it is a discovery/search operation rather than a detail lookup, though it does not explicitly call out the 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 implies the use case: searching for symbols by name across the codebase. However, it does not explicitly state when to use this tool instead of more specific siblings such as get_symbol_info, get_dependencies, or get_dependents, nor does it mention any 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?

With no annotations provided, the description carries the full burden and covers key behaviors: deterministic checks, graph-aware severity elevation with a concrete example, and a return format of ranked findings with attack scenarios and suggested fixes. It does not explicitly state whether the scan is read-only or mention limitations, but the language strongly implies a non-mutating analysis.

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 well-structured and front-loaded: lead purpose sentence, checks overview, graph-aware severity explanation, and return/usage guidance. It is slightly longer than necessary and slightly repeats the schema's target description, but each section earns its place.

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 no-required-param scan tool with no output schema, the description provides enough to invoke it correctly: whole-repo vs single-file behavior, types of checks performed, severity elevation logic, and output shape. It does not specify the exact response format or performance constraints, but nothing essential is missing for basic use.

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 100%, so the baseline is 3; the description adds value by explaining --target usage, the effect of graph-aware severity elevation, and a human-readable list of vulnerability classes. It does not perfectly map to the classes enum—code-injection and supply-chain are not mentioned in the description—but it still enriches the schema's terse parameter docs.

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 opens with a specific verb and resource—'Scan the codebase for security vulnerabilities'—and adds distinctive method details ('deterministic checks + graph-aware severity scoring'). It also states the output ('ranked findings (Critical → Low)'), which clearly separates it from sibling tools like get_health_score or find_dead_code.

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 gives clear usage context: scan the whole repo by default, use --target for a single-file scan, no API key required. It does not explicitly name alternatives or exclusion conditions, but its use case is clear enough for an agent to select it appropriately among the listed tools.

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 behavioral burden and does so well. It discloses zero file I/O, pure in-memory simulation, cross-language edge handling, and even operation-specific behavior like failing fast on symbol name collisions in merge.

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 structured with a front-loaded overview followed by a scannable operations list. Every sentence and bullet adds operational value; there is no filler or repetition of schema content.

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, five parameters, and no output schema, the description is remarkably complete. It explains what the tool returns, when to run it, what each operation does, and important constraints like in-memory execution and cross-language impact.

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 already has 100% description coverage, and the tool description adds significant meaning on top: which parameters are required for each operation (split, move, rename, merge) and the merge collision behavior. This is exactly the kind of operational parameter context that helps an agent invoke the tool correctly.

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 a clear verb and resource: simulate an architectural change before code is touched, and names concrete outputs (health score delta, broken imports, affected nodes). It does not explicitly differentiate itself from the closely related sibling impact_analysis, so it falls short of a 5.

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 gives explicit guidance: 'Always run this before any refactor that touches file structure.' This provides clear context for when to use the tool. However, it does not discuss when not to use it or name alternatives.

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 burden. It clearly discloses the main effects (regenerating docs and creating docs on first run), but it does not mention whether existing docs are overwritten, whether a repo connection is required, or any other side effects. This is adequate but not rich.

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?

Three short sentences, each earning its place: what it does, the first-time behavior, and when to use it. No fluff or redundant restating of the tool 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?

For a simple one-parameter tool with no output schema, the description covers action, first-run behavior, and usage timing. It is slightly incomplete only in that it does not describe post-call result or prerequisites, but those are not critical for selecting and invoking this 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 100% for the single optional doc_type parameter, so the schema already fully explains accepted values and the default. The description adds no parameter-specific meaning, matching the baseline of 3.

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 action (regenerate) on a clear resource (codebase documentation), including the first-time generation case. It does not explicitly name sibling tools, but the update-vs-get distinction against get_project_docs is implied by the verb and resource.

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?

Gives a clear trigger: use after significant code changes to keep docs current. It does not explicitly list exclusions or alternatives such as get_project_docs for read-only access, so it is clear context but not a full routing guide.

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 exist, so the description must carry the behavioral burden. It does disclose determinism, the categories of checks, and that it returns a report rather than applying the change. However, it does not explicitly state whether the tool is read-only or has side effects, nor does it describe the report's format or any prerequisites (e.g., connected repository).

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?

Three sentences with the core purpose front-loaded. The second sentence enumerates checks efficiently. The final audience sentence is minor extraneous context but does not bloat the description.

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 description lists what the report checks but not what the report contains structurally or how a caller should interpret the result. With no output schema and no annotations, this is a notable gap. It also does not specify that a change must be supplied as either file_path+new_content or unified_diff, though the schema covers this.

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 parameter descriptions already define file_path, new_content, unified_diff, and depwire_action_token. The tool description adds no parameter-level detail, but that is acceptable because the schema is self-sufficient. It does not clarify the mutually exclusive input modes, but the schema comments already explain the alternatives.

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 action: 'return a deterministic safety report' before applying a code change, and enumerates specific checks (broken imports, circular dependencies, health score impact, targeted scan). This differentiates it from siblings like impact_analysis or security_scan through the temporal qualifier 'Before applying' and the deterministic nature.

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?

Provides a clear trigger condition: 'Before applying a code change.' It does not explicitly name alternative tools or exclusions, so agents must infer when not to use it. The audience note ('Used by AI coding assistants and autonomous agents') is context, not a usage criterion.

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 behavioral disclosure burden. It explains that the tool renders an interactive diagram, shows files as bars, draws dependency arcs, colors them by distance, and outputs inline in the conversation. This clearly frames the operation as non-mutating and tells the agent where the output appears, which is meaningful beyond the schema.

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 two sentences with no filler. The primary action and resource come first, followed by a compact explanation of the visual output and where it appears. Every sentence adds necessary context and the structure makes the tool's behavior immediately clear.

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 is simple, has only optional parameters, and no output schema, so the description covers the essential call context: what is rendered, what it looks like, and that the result appears inline. It could add a note about whether the codebase needs to be connected first, and the 'interactive' behavior is not elaborated, but overall the description is sufficient for an agent to invoke the tool 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?

Schema coverage for parameters is 100%, so the schema already describes maxFiles and highlight. The description does not add extra semantic detail about either parameter, such as how highlighting works or what 'top N most connected' means in practice. Under the coverage baseline, a score 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 clearly states a specific verb ('Render') and a specific resource ('interactive arc diagram visualization of the current codebase's cross-reference graph'). It also gives concrete visual details (bars, arcs, coloring by distance), which makes the tool's purpose unmistakable. The phrasing differentiates it from data-returning siblings like get_dependencies and get_temporal_graph by focusing on an inline visual artifact.

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 conveys that this tool is for producing a visual representation of cross-references, so an agent can infer when it is appropriate. However, it does not explicitly state when to prefer this over related tools like get_dependencies, get_dependents, or impact_analysis, nor does it mention any exclusions or prerequisites such as requiring a connected repository.

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