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

The readOnlyHint annotation already covers safety. The description adds behavioral detail by describing the return format, the per-hit fields (line, kind, value, extra, function, confidence), and the truncation flag. It doesn't contradict 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 well-structured: a one-sentence core value proposition, a bulleted list of search targets, and a compact return schema. Each sentence contributes new information, making it concise despite its length.

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 moderately complex with 8 parameters and no output schema, but the description compensates by specifying the JSON return structure and per-hit metadata. It does not cover edge cases like duplicate hits or performance, but the essential information for correct invocation and result interpretation is present.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 100% schema coverage, the baseline is 3. The description adds semantic meaning for each parameter type, especially field_names ('捕获 obj.field / obj['field'] / obj.get('field')') and string_values, and notes that multiple search types can be combined—a behavior not detailed in 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 tool as performing AST-level precise analysis of Python code ('对 Python 代码做 AST 级别精确分析') and differentiates it from grep ('比 grep 更准确'). It enumerates five distinct search targets (symbols, field_names, string_values, call_names, import_names), which distinguishes it from siblings like scan_patterns.

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 states that the tool is suitable for scenarios needing precise context ('适合需要精确上下文的场景') and claims better accuracy than grep, giving an implicit comparison to alternatives. However, it does not name sibling tools or state 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 readOnlyHint=true, the description adds valuable behavioral context beyond the annotation: it describes the aggregated JSON return format, the 'truncated' flag indicating possible result truncation, and the meaning of 'kind' and 'parent'. This goes beyond a simple read-only hint and informs the agent about the exact output structure.

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 compact and front-loaded with the purpose, then pair-usage, then return format. It is a bit dense due to the inlined JSON schema, but every sentence earns its place—no filler or repetition. The structure is logical, though slightly heavier than ideal.

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 fully documents the return format including nested objects, fields, and semantics for 'kind' and 'parent'. It also covers the truncation behavior and file aggregation. For a read-only tool with a clear return contract, this is quite complete, though it doesn't explicitly address not-found cases or pagination parameters.

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 all three parameters (project_path, name, exclude_dirs). The description does not add parameter-specific semantics beyond what the schema provides, but it does reinforce the meaning of 'name' indirectly via the return format. 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?

The description clearly identifies the verb+resource: '找出符号在项目中的定义处' (find where a symbol is defined), and enumerates the kinds of definitions (function, class, module/class-level assignments). It distinguishes itself from siblings by explicitly pairing with trace_callers and outlining a workflow, making it unambiguous what this tool does and how it relates to others.

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 states the primary use case (find definition to see signature) and explicitly recommends pairing with trace_callers ('与 trace_callers 配对使用——先找定义看签名，再追调用链'). It provides clear context on when to use the tool, though it does not explicitly state exclusions or 'when not to use' scenarios.

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 reveals cache-based fallback behavior when scan_results/ast_results are omitted, which goes beyond the readOnlyHint annotation. It does not mention potential errors if the cache is missing, but the annotation covers 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 description is two sentences: the first states the core action, the second covers fallback and recommended workflow. Every clause contributes new information.

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

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

Given no output schema, the description sufficiently explains the tool's role and inputs, including cache fallback and the recommended upstream scan calls. It does not detail report structure, but for a read-only aggregation tool with a well-described workflow, it is adequate.

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 75%, with change_description, scan_results, and ast_results documented. The description adds the cache fallback context and an illustrative change_description example, but most parameter semantics are already in 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 opens with a clear verb-resource pairing: '将扫描结果聚合成结构化 Markdown 影响分析报告' (aggregate scan results into a structured Markdown impact report). It distinguishes itself from sibling scanning tools by being the report-generation step, and the recommended workflow reinforces this role.

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?

Explicit workflow guidance is provided: '推荐工作流：先调用 scan_patterns 和/或 analyze_python_ast，再调用此工具生成报告'. It also describes the cache fallback when scan_results/ast_results are omitted, making the usage context precise.

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 declare readOnlyHint=true, so the read-only safety is already covered. The description adds behavioral context about the two modes (single vs. batch) and a recommendation, but does not disclose other behavioral traits like error handling, performance, or exact return format. This is adequate given the simple read-only nature.

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 the tool's purpose, and no wasted words. Every phrase adds value: the purpose, the two modes, and the batch recommendation.

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 covers the primary usage and modes, and the annotation provides safety context. There is no output schema, so the description could ideally mention what the response includes, but the tool name and context_lines parameter imply code content around the specified lines. It is complete enough for a straightforward read-only utility.

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 well-documented. The description adds value by clarifying the mode semantics (single vs. batch) and the recommendation to use batch mode, which goes beyond the schema's individual parameter descriptions. It also reinforces relative path handling with project_path.

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

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

The description uses a specific verb (获取) and resource (代码上下文), and clarifies its purpose: helping judge whether a code hit is truly affected by changes. It distinguishes from sibling tools by focusing on context retrieval for impact assessment, though it does not explicitly name 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?

It clearly states when to use the tool (to verify if a hit is affected by changes) and recommends batch mode for multiple hits to reduce round trips. It gives context for both single and batch modes, though it lacks explicit exclusions or when-not-to-use 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?

Beyond the minimal readOnlyHint: true annotation, the description adds valuable behavioral context: it states the tool '只负责机械执行搜索' (only mechanically executes search) and describes the exact JSON return structure aggregated by file. This gives the agent insight into the tool's role and output. It does not contradict the annotation. Slightly more could be said about edge cases or performance, but the disclosure is solid.

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 the core purpose in the first sentence, followed by concise sentences that each add distinct value: generality, usage guidance, tool role, and return format. There is no fluff or repetition, making it appropriately sized for a general-purpose search tool.

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?

Since there is no output schema, the description includes the return JSON structure, which is helpful. It covers the tool's scope, when to use it, its mechanical nature, and return format. While some defaults (e.g., extensions, max_results) are only in the schema, this is acceptable. The description is contextually complete for a complex search tool, though it could briefly mention potential limitations like truncation behavior (which is already in the schema).

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 descriptions for all 5 parameters are detailed, providing examples for patterns and defaults for extensions and max_results, so schema coverage is 100%. The description itself does not add additional parameter-level semantics; it only mentions the return format. Since the schema does the heavy lifting, the baseline 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 opens with a specific verb+resource: '在代码库中搜索任意正则表达式 pattern' (search arbitrary regex patterns in the codebase). It then distinguishes itself as '最通用的搜索工具' (the most general-purpose search tool) and provides concrete examples of what it can search (field access, function calls, string values, etc.), clearly differentiating it from specialized sibling tools like trace_callers or find_definition.

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 the tool: '当用户描述任何类型的代码变更并想知道影响范围时，调用此工具' (call this tool when the user describes any type of code change and wants to know the impact scope). It also clarifies that Claude decides the patterns to search, relieving the tool of interpretation. However, it does not mention alternatives or when not to use this tool, 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?

Beyond the readOnlyHint annotation, the description discloses the BFS algorithm, depth limit of 5, the exact return structure, and the semantics of confidence levels (high vs medium). This is useful behavioral context, though it does not cover edge cases like function-not-found or exit conditions. 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?

The description is concise—just two dense sentences—yet packs in the algorithm, depth bounds, use case, return schema, and confidence interpretation. Every phrase contributes meaning, and the most important action (BFS caller tracing) 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?

In the absence of an output schema, the description fully specifies the return structure with fields like target, max_depth, total_found, truncated, and levels with per-caller details. It also explains confidence granularity. Given the tool's moderate complexity, this is complete enough for an agent to understand what to expect.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema description coverage is 100%, and the description adds little beyond the schema for parameters. It does clarify the depth semantics (depth=1 direct callers, depth=2 indirect callers) but this is also largely present in the schema's depth field. With full schema coverage, a 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?

The description uses a specific verb and resource: 'BFS 逐层找出调用指定函数的函数' (BFS layer-by-layer finds callers of the specified function). It clearly distinguishes itself from siblings like find_definition (which locates definitions) and analyze_python_ast (which analyzes AST), making the tool's unique purpose 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 the tool: '适合回答「改了函数 X，影响会波及到哪里？」' (suitable for answering 'If I change function X, where will the impact spread?'). This provides a clear use case, though it does not mention alternatives or exclusions compared to sibling tools.

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