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

No annotations are provided, so the description carries the burden. It conveys that this is a read-only search across the codebase, but does not disclose whether callers are direct vs transitive, whether results are paginated, or any indexing prerequisites.

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

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

A single front-loaded sentence with no filler; every word contributes to defining the operation and its target.

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 read tool with no output schema, the description adequately covers purpose and target. Minor gaps around indexing prerequisites and direct/transitive scope remain, but nothing essential to correct invocation 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 symbol_name is already documented in the schema. The description adds no syntax, naming, or scoping detail beyond what the schema states, 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?

Clear verb 'find' with a specific resource: functions/methods that invoke a given symbol. It defines a reverse-call lookup, which is distinguishable from find_symbol and get_outline, though it does not explicitly contrast itself with the potentially overlapping get_impact_radius.

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

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

No guidance on when to use this versus siblings like find_symbol or get_impact_radius, and no stated prerequisites (e.g. whether the codebase must be indexed first). Usage is only implied by the verb.

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 the full burden; it partially does by disclosing the return payload (paths, [start_line, end_line] bounds, signatures, docstrings) and implying a read-only lookup. It stays silent on substring vs. exact matching behavior, result limits, and what happens with multiple matches.

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 packed sentences, zero redundancy, with the core action front-loaded and the return values following immediately.

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 output is described in prose, which offsets the absent output schema, but for a tool in an indexed-codebase family the description omits whether indexing is a precondition and how ambiguous matches are resolved, leaving real gaps for an agent deciding how to call it.

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 has 100% schema description coverage including an example, so the baseline is 3. The description adds only the notion of matching 'by name', which is already implied by the schema's 'symbol name or substring' text.

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 ('Locate') with a concrete resource ('classes, functions, or methods by name') and enumerates what comes back (paths, line bounds, signatures, docstrings). It does not explicitly distinguish itself from look-alikes such as get_symbol_slice or get_outline, so it stops 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?

Usage is only implied: 'by name' signals this is a name-based lookup, but the description never states when to prefer it over get_outline, get_symbol_slice, or index_codebase, nor any prerequisite such as requiring an indexed codebase first.

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 the analysis outputs (callers, affected files, risk level) and the cascading nature of the traversal, but never states that it is read-only, how depth affects results, or what the risk level is derived from.

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 no redundant restatement of the tool name. The trailing 'across the codebase' is mild filler but does not undermine the structure.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema and no annotations, the description does useful work by naming the three return elements (callers, affected files, risk level). It remains a bit thin on how risk level is defined and what the traversal produces at each depth, but it covers the essentials for invoking 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?

Schema description coverage is 100%, so both symbol_name and max_depth are already documented in the schema, making 3 the baseline. The description only echoes the cascading concept and adds no new syntax, format, or semantic detail about the depth parameter.

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 ('Analyze cascading downstream blast radius') and enumerates what it identifies (callers, affected files, risk level). It is clear enough to distinguish from find_callers by the word 'cascading,' but it never names that sibling explicitly, so the differentiation is left to inference.

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 'before refactoring' implies the usage context, which is better than nothing. However, there is no explicit when-not guidance and no mention of find_callers as the lighter-weight alternative for direct-caller lookup, so an agent must guess at the boundary between the two.

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

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

No annotations are provided, so the description carries the full burden. It does disclose the return scope (skeleton only, not bodies) and implicitly that this is a non-mutating read, but it says nothing about permissions, error behavior for missing files, or handling of non-code files.

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

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

One sentence, front-loaded with the primary purpose and parenthetically enumerating the returned content. Every clause earns its place with no padding.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description usefully enumerates the return contents (classes, functions, line bounds), which is what an agent needs for a simple single-parameter read tool. Minor gaps around error handling and unsupported file types 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?

Single parameter at 100% schema coverage, so the schema already documents file_path and its workspace-relative format. The description adds only that it targets 'a file', which is the baseline expectation.

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 ('get') and resource ('outline') and immediately defines what the outline contains: classes, functions, line bounds. An agent knows exactly what artifact it receives, though it does not explicitly contrast itself with siblings like get_symbol_slice or find_symbol.

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 'without reading its entire contents into context' implies the token-efficiency motivation for choosing this over a full file read, but no alternative tool is named and no when-not condition is given. Usage is inferable rather than 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?

No annotations are provided, so the description must carry the behavioral load. It does disclose the key behavior that only the exact symbol block is returned, not the surrounding file, which is useful. However, it omits whether the operation is read-only, how ambiguities (e.g., overloaded methods) are resolved, or what happens when the symbol is not found.

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

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

A single sentence with zero waste, front-loading the action and the differentiator (exact block, no surrounding file). Every word 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?

No output schema exists, so the description must clarify return values; it does so adequately by stating 'exact source code block'. Yet for a tool with no annotations and no output schema, it leaves gaps around error handling, ambiguity resolution, and whether the block includes line numbers or metadata. The slight mismatch between 'function or class' in the description and 'function, class, or method' in the schema also reduces completeness.

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 both parameters are fully documented in the schema. The description adds only 'by symbol name' and implies file_path, but does not provide additional syntax or format guidance beyond what the schema already offers, so the baseline of 3 is appropriate.

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

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

States a specific verb (extract) and resource (exact source code block of a single function or class by symbol name) and implicitly contrasts with reading the whole file. It distinguishes itself from siblings like find_symbol and get_outline by focusing on the code block itself, though it never names those alternatives 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?

Offers no explicit when-to-use guidance or comparison to alternatives such as find_symbol, get_outline, or find_callers. The phrase 'without reading the surrounding file' hints at efficiency but leaves the agent to infer the appropriate context.

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, yet it omits the key facts: that it writes/refreshes an on-disk index, that it can be slow on large workspaces, and how the cache behaves. The caching detail appears only in the schema's 'force' parameter, not in the description.

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

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

A single front-loaded sentence with no filler, stating action and benefit. It is efficient, though arguably too terse given the tool's side effects and prerequisite role.

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 an indexing tool with no annotations and no output schema, the description covers what it produces but not the state it mutates, the cost of the operation, or its prerequisite relationship to the symbol-retrieval siblings. Adequate but leaves real gaps.

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 both parameters (force, workspace_path) are already fully documented in the schema. The description adds no parameter detail beyond what is there, which is the expected 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?

States a specific verb (scan and index) and concrete resources (classes, functions, methods) with scope (workspace) and a payoff (sub-millisecond symbol search). It is distinguishable from the read-only siblings (find_symbol, get_outline) as the index-building prerequisite, though it never names them 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?

Usage is only implied: the agent must infer that this is the setup step that makes symbol search fast. There is no statement of when to call it (first run, after edits), when not to call it, or how it relates to find_symbol/get_outline.

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 does disclose meaningful behavior beyond structured data: automatic AST syntax validation and automatic rollback on invalid input. It does not state overwrite/destructive semantics, permission requirements, or how indentation/formatting is preserved.

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 no filler, front-loading the core action before the safety guarantee. 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 mutation tool with no annotations and no output schema, the description covers the essential action and the key safety behavior (validation + rollback). What remains missing is destructive/overwrite framing and any error or return behavior, but the core is complete enough to invoke 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 all three parameters are already documented, giving a baseline of 3. The description's 'function or class block by symbol name' adds marginal color (the schema also mentions methods) but no new syntax, format, or constraint detail.

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 and resource: 'replace a function or class block by symbol name.' It is clearly distinguishable from the read-only siblings (find_symbol, get_symbol_slice, get_outline) because it is the only mutation tool, but it never explicitly names or contrasts 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?

Usage is only implied: an agent can infer you call this when you want to overwrite a symbol's source. There is no explicit when-to-use/when-not guidance and no mention of alternatives (e.g., whole-file rewrite vs. symbol patch).

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