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

Annotations already cover read-only, idempotent, non-destructive behavior. The description adds meaningful execution context: multiple phrasings are tried in order, a quality threshold gates acceptance, and a weakened result set includes a warning. It also mentions the performance cost ('slower than `search`').

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 convey purpose, trigger condition, execution behavior, return behavior, and performance trade-off. The key escalation framing is front-loaded, and every clause 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 10 parameters and no output schema, the description covers the essential call decision, execution behavior, and return outcome. It could be more explicit about the exact return format for the 'warning' case, but the core completeness is strong.

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 input schema already documents all parameters. The description reiterates the '2-4 genuinely different phrasings' concept for `queries`, which is already in the schema, but adds no new parameter-level meaning beyond that.

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 verb and resource: it is an escalation for `search`, runs 2-4 different phrasings, and returns the first set that passes a quality threshold or the strongest weak set with a warning. This clearly differentiates it from the sibling `search` and makes its role unmistakable.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly states when to use it ('when `search` came back weak or empty'), when not to start with it ('do not start here'), and names the alternative (`search`). This leaves no ambiguity about the escalation path.

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?

Annotations already cover read-only and non-destructive behavior; the description adds meaningful context by disclosing the graph-layer dependency for call data and the always-available definition/tests. This is real behavioral insight beyond the 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?

Two efficient sentences deliver the core value, use case, and key limitation without repetition. 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 fully documented schema, clear annotations, and the concise disclosure of the graph-layer dependency, the description is largely complete for an agent to select and call the tool. It does not detail the return format, but the symbol context it promises is clearly enumerated.

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 parameters are already well-documented. The description does not add parameter-specific detail, but the schema's own descriptions suffice.

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 clearly states a specific action: get one-shot context about a symbol, listing exact components (definition, callers, callees, tests). It distinguishes itself from siblings by emphasizing the bundled, single-call 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 clear context: use this as the fastest way to understand a function/class before changing it. It also gives an important usage caveat that call data requires the graph layer while definition and tests do not, though it does not explicitly name sibling 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?

Annotations cover read-only/destructive/idempotent hints; description adds that the output is a self-contained offline HTML file and that the call returns the file path. This aligns with readOnlyHint=false and idempotentHint=true, though overwrite behavior is not detailed.

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, front-loaded sentence with no filler; the parenthetical mode breakdown is compact and informative.

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?

All parameters are schema-documented, annotations cover safety, and the description supplies the return value ('file path') and the artifact's purpose. No critical details are missing for a tool that writes a file.

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 already describes all 5 params at 100% coverage, but the description adds functional meaning: mode=symbol relates to blast radius, mode=module to imports/dependents. This helps select target semantics beyond the schema's terse enum.

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 verb 'Write' and resource 'self-contained offline HTML view', and clarifies two modes: symbol blast radius versus module imports/dependents. This distinguishes it from siblings like find_usages or impact, which presumably return structured data rather than an HTML 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?

Provides clear usage context: produce a human-readable offline HTML report to open or attach to a PR. It does not explicitly name alternatives or when-not conditions, but the 'for a human' phrasing implies a choice over data-returning 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 all annotation hints false, the description carries the full burden and does so well: it discloses the write side effect (appended), the local persistence (local log), the privacy guarantee (never uploaded), and the downstream purpose (owner tunes sources and filters). This exceeds what the annotations provide.

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 tightly written sentences: the first states the core action and timing, the second explains where the data goes and why it matters. No filler or redundant restatement.

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 3-parameter feedback tool with full schema coverage and no output schema, the description provides everything needed: when to call it, what it does, its storage behavior, and its purpose. Nothing critical is missing.

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 tool description adds no additional parameter detail, but the baseline of 3 applies because the schema fully covers semantics.

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 action: report when the index could not answer. It identifies the resource (local log) and distinguishes itself from sibling index-querying tools by marking feedback as a fallback after failed lookups.

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 clearly signals when to use: when the index could not answer, before giving up. It does not explicitly enumerate excluded cases or name alternatives, but the condition and timing are clear enough for an agent to route to it correctly.

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 annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds valuable context about the AST-precise vs. BM25 fallback modes and that each hit indicates its source, which goes beyond the annotations without contradicting them.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise, using two sentences to convey purpose, behavior, and usage guidance. It is well-structured with a clear flow and no unnecessary 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?

There is no output schema, so the description need not fully explain return values, but it does mention that 'each hit says which' mechanism was used. This gives a reasonable hint about the output. The description sufficiently covers the tool's context and edge cases (AST vs. BM25).

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 covers 100% of the parameters, and the descriptions are present but minimal (e.g., 'Max results', 'Source name', 'Identifier'). They clarify the data type and purpose but do not add much beyond the schema definitions. This is at the baseline expected for full coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Jump to a symbol definition' and specifies the exact resource (symbol definitions) and the action (jump). It also distinguishes itself from sibling tools by naming 'search' and 'describe_symbol' 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?

The description provides explicit guidance on when to use this tool versus alternatives: 'Use `search` instead when you can only describe what the code does, and describe_symbol when you also want the callers and the tests in the same call.' This gives clear conditions for selection.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior. The description adds meaningful behavioral constraints: this is a dense-search-only operation and snippets over 2000 chars are truncated. This goes beyond the safety annotations, though it does not describe result shape or pagination.

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 deliver the core purpose, the usage context, and a key input limitation. Every sentence earns its place and critical constraints are 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-only search tool, the description plus schema and annotations provide enough to select and invoke it correctly. It could be more explicit about the return format since there is no output schema, but the intended behavior is clear.

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 repeats the snippet truncation behavior already present in the schema and adds no new semantics for top_k or source.

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 and resource: it finds code semantically similar to a given snippet. The phrase 'dense search only' narrows the mechanism and differentiates this tool from lexical search siblings like search or deep_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?

'Use before writing a function to check whether something like it already exists' gives a clear, concrete trigger for calling the tool. It does not explicitly name alternatives or state when not to use it, so it falls short of a 5.

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 annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description is consistent with these. The description adds valuable behavioral context beyond the annotations: the default search paths (tests/, spec/, __tests__/, etc.) and the fact that test_path_pattern replaces those defaults. The lower bar for annotations is met, with only minor extra behavioral detail (e.g., no-results behavior) omitted.

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 dense but efficient: two sentences cover the action, the resource, the path defaults, the replacement mechanism, the usage trigger, and the sibling contrasts. No redundant words or filler. It could be split into slightly clearer sentences, but every clause 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, idempotent tool with 4 simple parameters and no output schema, the description covers: the purpose, the default path behavior, the replacement semantics, when to use it, and the distinction from two siblings. It omits the output format, but given no output schema and the simple 'list' nature, the coverage is strong. The main gap is edge-case behavior (e.g., no tests found), but this is minor for the tool's complexity.

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% (all 4 parameters have descriptions), which sets a baseline of 3. The description adds meaning beyond the schema by explaining the conventional-path default behavior and how test_path_pattern substitutes for it, giving each parameter operational context (e.g., 'Omit when only one source applies' is reinforced by the tool's purpose). This pushes it above the baseline.

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 ('List') and a specific resource ('tests that mention a symbol') with a clear scope (conventional test paths). It explicitly distinguishes the tool from siblings: 'describe_symbol returns the same tests bundled with the definition and the callers, and impact returns them for a whole blast radius.' This leaves no ambiguity about what the tool does and how it differs from the 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 explicitly states when to use it: 'Use it when the tests are all you want, before or after a change,' and contrasts it with describe_symbol and impact for the when-not cases. It also explains the test_path_pattern parameter's role ('replaces them for another layout'), giving concrete guidance on usage 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?

Annotations already mark the tool as read-only and idempotent. The description adds valuable behavioral context: results depend on whether the graph is 'on', includes specific reference types, and excludes the definition. This goes beyond the annotations and clarifies exactly what the tool computes.

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 tightly worded sentences deliver a high density of information without redundancy. The key question ('who uses X') is front-loaded, and the parenthetical enumeration is compact and readable.

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 tool with full parameter schema coverage and no output schema, the description covers the core semantic well. It explains what uses are included/excluded but does not specify the output format. This is a minor gap given the tool's moderate complexity.

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 minimal parameter-level detail beyond the schema, though the phrase 'Every use of a symbol' reinforces the meaning of the symbol parameter. It does not specifically elaborate on limit or source semantics beyond 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 clearly identifies the action ('find uses of a symbol') and enumerates exactly what counts ('calls... plus textual references'), while explicitly excluding the definition. This strongly differentiates it from the sibling tool find_definition and makes its purpose unambiguous.

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 a clear usage context: when you need to answer 'who uses X'. It also provides an implicit when-not by stating 'definition excluded', signaling that this tool is not for retrieving definitions. However, it does not explicitly name sibling alternatives or broader exclusion 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context by naming exactly what the status report includes: freshness, chunk count, last update, and drift. This goes beyond the annotations without contradicting them.

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 tool's purpose and output fields; the second sentence gives the key use-case. Every word earns its place, and the structure is easy to scan.

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 status tool with one optional parameter and no output schema, the description is complete. It tells the agent what data will be returned, that it can target one or all sources, and when to invoke the tool. Nothing essential is missing for correct selection and 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%, and the single 'source' parameter is already well documented as 'Source to inspect; omit for all.' The tool description's 'one or all sources' phrasing mirrors the schema rather than adding new parameter-level meaning. Baseline 3 is appropriate because the schema carries the semantic weight.

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 reports index state for one or all sources, listing the specific data points it returns (freshness, chunk count, last update, drift). It also distinguishes itself from rebuild tools by explicitly framing itself as a pre-rebuild check, making it easy to tell apart from siblings like update_source_index.

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 when-to-use guidance: 'Check it before considering a rebuild.' It does not list alternative tools by name, but the rebuild context clearly implies this is the inspection tool rather than the mutation tool. It could be stronger with an explicit exclusion or sibling reference, but the guidance is clear and useful.

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?

Beyond the read-only/idempotent annotations, the description adds useful behavioral details: symbol matching is case-insensitive substring, results carry file:line, and the operation set includes status and overview. It does not claim any side effects (consistent with annotations), and the 'raw access' phrasing signals lower-level output. This adds meaningful context beyond the 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 compact two-sentence paragraph. The first sentence explains purpose and relationship to siblings; the second lists operations and key behaviors. No redundant words, and the most important scoping information (dedicated tools) is front-loaded. It is dense but every clause contributes.

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 many operations and no output schema, the description gives enough context to understand its role, limit usage, and know that results include file:line. It does not enumerate return shapes for each operation, but that is largely unnecessary for an agent to select and call the tool; the parameter schema fills in the rest. Minor gaps like per-operation output details are acceptable.

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?

Although schema coverage is 100%, the description enriches parameter understanding by enumerating the allowed operation values (callers, callees, etc.) and clarifying that symbol is matched as a case-insensitive substring. These details are not fully captured in the schema, which only says 'One of the operations listed in the tool description' for operation. Thus it adds value beyond the 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 clearly states it provides raw access to the code knowledge graph and explicitly names the dedicated sibling tools (find_usages, impact, describe_symbol) that cover common cases, distinguishing itself as the fallback for other graph operations. It lists the supported operations with concrete verbs (callers, callees, subclasses, etc.), making the purpose unambiguous.

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 explicit when-to-use guidance: 'for the questions the dedicated tools do not cover' and names the alternatives (find_usages, impact, describe_symbol). This tells the agent exactly when to prefer this tool over siblings, which is the core of usage guidelines.

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?

Annotations already cover read-only, idempotent, non-destructive. Description adds useful context about the algorithm (transitive call graph traversal) and result format (hop distances, tests), going beyond annotations without contradicting them.

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 that front-load the core purpose and immediately differentiate from the sibling. Every phrase adds value; no filler or repetition.

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 lacking an output schema, the description adequately explains what will be returned (reachable symbols with hop counts and associated tests). Combined with full schema coverage of parameters, an agent has enough context to call 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 already describes all four parameters with full coverage. Description adds practical nuance for max_depth (tradeoff) and implies source disambiguation, slightly enhancing parameter understanding.

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 verb ('answer what breaks'), a resource (call graph of symbols), and output (transitive reachability with hop distance plus tests). Clearly distinguishes from sibling find_usages.

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?

Explicitly names when to use (before a risky edit) and when to use find_usages instead (direct one-hop). Also explains max_depth tradeoff between reach and noise.

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 states 'Read from config and metadata, no index opened', which transparently explains that the operation is read-only and does not affect the index. This aligns with the annotations (readOnlyHint, idempotentHint, non-destructive) and provides extra context beyond the 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 concise and well-structured. It lists the returned fields in a compact list and provides usage guidance without unnecessary verbosity.

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 what the tool does, what information it returns, and when to use it. It also references the related tool get_rag_status to guide the agent to alternative actions when needed, making the context 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?

There are no parameters, and the description makes it clear that the tool simply lists all sources without needing any input. No explanation of parameters is required.

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 existing sources and details what each source contains (name, type, path, chunk count, drift flag). It is unambiguous about the resource and the action.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly tells when to use this tool: 'Call it first when you do not know the source names a `source` argument expects'. It also distinguishes it from get_rag_status, which should be used for freshness/rebuild checks.

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?

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds behavioral context beyond that: the tool summarizes a file's defined symbols, imports, and dependents as computed via the call graph. This clarifies what the agent should expect without repeating annotation data.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, no filler. The definition is front-loaded and the usage guidance is actionable. Every word contributes to either clarifying the tool's output or telling the agent when to invoke it.

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 summary tool with fully documented parameters and safety annotations, the description provides sufficient context. It states what the output covers (symbols, imports, dependents) even without an output schema, though it could more explicitly mention how the optional 'source' parameter affects results.

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 covers all parameters with descriptions at 100% coverage, so the baseline is 3. The tool description does not add parameter-level details, but it does contextualize the primary 'file' parameter by describing the file-as-a-unit scope. No additional compensation is needed.

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 defines a clear scope: one file as a unit, covering the symbols it defines, imports, and dependent files via the call graph. It also supplies a direct action ('Read it before editing a file you don't know'), which makes the purpose unmistakable and distinguishes it from symbol-level tools like describe_symbol and impact.

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 an explicit use case: read this before editing an unfamiliar file. It does not explicitly enumerate when not to use it or name alternative tools, but the context is clear enough for an agent to decide when module_summary is the right starting point.

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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds useful behavioral context: it performs a filesystem scan, requires no index, and should only be called once per session. This goes beyond the structured annotations without contradicting them.

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 dense, front-loaded sentences cover purpose, scope, outputs, mode of operation, and usage frequency. Every clause adds value, and there is no filler or repetition of schema 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 tool with a single optional parameter, no output schema, and safety annotations already present, the description is complete. It tells the agent what results to expect, how the tool operates, and how often to use it. 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?

Schema description coverage is 100% and the single optional parameter 'source' is already explained well in the schema, including when to omit it. The description does not add parameter-specific detail, but it does not need to because the schema carries the meaning. 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 the tool provides orientation for an unfamiliar codebase and enumerates specific outputs: languages by file count, frameworks, manifests, entry points, and build/test/run commands. This resource and scope are specific enough to distinguish repo_overview from sibling tools like module_summary or list_sources.

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 explicitly says 'Call once per session,' which gives clear usage frequency guidance. It also indicates the tool is for unfamiliar codebases and does not need an index, implying it suits initial exploration rather than repeated targeted queries. It does not explicitly name alternatives or exclusion conditions, so it falls short of a 5.

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?

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint false), so the bar is lower, and the description clears it by adding genuinely useful behavior: return format (ranked chunks with file:line, symbol, score), score interpretation (0.03 ≈ strong match), and mode behavior for outline. No contradiction with 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?

Four sentences, each earning its place: scope, query phrasing, return format plus score calibration, then two parameter tips. The most important usage constraint (plain-words query) is front-loaded in the second sentence. Zero 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 7-parameter tool with no output schema and 15 siblings, this description covers the critical gaps: what the tool returns, how to judge result quality, how to phrase input, and how two key parameters change behavior. Filtering params (file_glob, extensions, path_contains) are self-explanatory from the schema, so nothing an agent needs to call it correctly is missing.

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 baseline is 3. The description adds value on top by specifying how to phrase `query`, the fusion behavior when `source` is omitted, and the triage use of `outline=true` — going beyond the schema's terse descriptions rather than simply repeating them.

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 verb and resource — 'Hybrid semantic + lexical search over the indexed code and docs' — plus the distinct query contract ('describe what the code does in plain words, not an identifier'). This differentiates it from sibling symbol-oriented tools like find_definition, find_usages, and describe_symbol, and from deep_search, without needing to inspect any of 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?

Gives strong practical context: query phrasing rules, omitting `source` to search everything, and outline=true for cheap broad triage. However, it never names sibling alternatives or states explicit when-not-to-use conditions, so an agent must infer the boundary with find_similar/deep_search from the plain-words contract alone.

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

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

The description warns that the operation is 'expensive and blocking,' which goes beyond the annotations. It also clarifies the trigger condition. It does not contradict the annotations, and the annotations already cover the safety profile.

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 focused sentence that front-loads the core purpose, then adds cost and usage guidance. No filler or repetition of schema 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 two-parameter tool with clear annotations, the description provides enough to select and invoke the tool correctly. It covers purpose, cost, and trigger conditions; the only minor omission is an explicit statement about the return value, but that is not critical for this operation.

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 input schema documents both parameters fully. The description adds contextual meaning around rebuilding and when force is relevant, but it does not add significant parameter-level detail beyond 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 a specific action and resource: 'Force a full rebuild of a source's index.' This clearly distinguishes the tool from read-only siblings like list_sources and search, and from analysis tools like find_usages and impact.

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 explicitly says when to use the tool: 'use it only after a big merge or a drift warning.' It also explains the default state—'the watcher keeps the index current'—which tells the agent not to call this routinely.

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