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

With no annotations, the description carries full transparency burden. It discloses the requirement for a git checkout, optional line-range blame, and the nature of outputs. It does not mention error cases or performance, but overall provides adequate behavioral context.

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

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

The description is two sentences with no wasted words. The first sentence immediately conveys the tool's purpose and outputs. It is well-structured and front-loaded, making it easy to parse.

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 4 parameters, 100% schema coverage, and the presence of an output schema, the description does not need to detail return values. It covers key behaviors (blame, prerequisite) and mentions churn stats. It is complete enough for the complexity level, though it could briefly mention how to use max_commits.

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%, giving a baseline of 3. The description adds value by explaining that start_line/end_line enable blame on a specific region, which enriches the schema descriptions. It also clarifies the prerequisite (git checkout) implicitly linking to the file 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?

The description uses a specific verb ('explain') and resource ('why code looks the way it does using git'), listing concrete outputs (commits, churn stats, blame). It clearly distinguishes from sibling tools like find_references or search_code, which serve different purposes.

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

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

The description implies when to use (to understand git history of a file) and mentions a prerequisite (git checkout). However, it lacks explicit guidance on when not to use this tool or direct comparisons to siblings, which limits its utility for an AI agent deciding between 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 full burden. It discloses important behavioral traits: resolution is scope/import-aware name matching (not full type inference), very accurate for module-level functions/classes, but methods may include same-named calls on unrelated types. This is good transparency about false positive risks. It does not mention rate limits or auth, but as a read operation, that is acceptable.

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. The first sentence states the core purpose, and subsequent sentences explain resolution details and limitations. Every sentence adds value, and there is no redundant or extraneous text.

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 that the tool has a rich output schema (true in context signals), the description does not need to explain return values. It covers the essential aspects: what is found (calls, attribute access, imports), output format (file:line and source line), and accuracy. It could mention pagination behavior explicitly, but parameters cover limit/offset. Overall, it is sufficiently complete for an agent to use correctly.

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

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

Schema description coverage is 100% (all four parameters have descriptions in the input schema). The tool description does not add additional semantic information beyond what the schema already provides. Baseline is 3 when schema covers parameters well and description adds no extra parameter context.

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 finds every use-site of a symbol (calls, attribute access, imports) with file:line and source line. It distinguishes itself from sibling find_symbol by explicitly noting that find_symbol is for definitions, so the agent knows which tool to use for references vs definitions.

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: 'Use find_symbol to see where it is defined instead.' This tells the agent when not to use this tool. It also explains the resolution approach (scope/import-aware name matching) and accuracy limitations for methods, which helps set appropriate expectations for when to rely on results.

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. It discloses that include_body=True returns full source and costs tokens, which is a behavioral trade-off for agents. It also implies read-only operation by describing a find/locate action. However, it does not explicitly state idempotency or absence of side effects, nor does it mention rate limits or auth requirements, leaving minor gaps.

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 four sentences long, front-loaded with the primary purpose in the first sentence. Every sentence earns its place: purpose, return content, include_body option, and usage exclusions. There is no redundant phrasing, and the text is structured for quick scanning.

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

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

Given the tool has 6 parameters, an output schema (not shown but present), and no annotations, the description provides all essential context: what it does, what it returns, how to paginate (via implicit schema parameters), trade-off of include_body, and error handling ('did you mean'). The output schema likely covers return structure, so the description does not need to. It is complete for effective agent 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 description coverage is 100% (all 6 parameters documented in schema). The tool description adds value beyond schema by explaining name as 'bare name or dotted suffix' and include_body as 'costs tokens' and returns full source. It does not elaborate on limit, offset, or response_format, but the schema sufficiently describes them, so the description incrementally improves 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?

The description clearly states the tool locates definitions of functions/classes/methods/variables. It specifies return content (kind, qualified name, path:line) and distinguishes from siblings by explicitly saying not to use for usages/call sites (use find_references) or free-text search (use search_code). The verb 'locate' paired with resource 'definitions' is precise and 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 provides explicit when-not-to-use scenarios and alternative tools: 'Do NOT use to find usages/call sites — use find_references. Do NOT use for free-text search — use search_code.' It also informs agents that 'did you mean' suggestions are returned when no match is found, setting expectations for nil results. No missing context for usage decisions.

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 bears full responsibility. It explains the bidirectional behavior based on input type, which is transparent. No destructive or performance implications are mentioned, but for a query tool this is adequate.

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 clear structure: first defines purpose, second adds usage context. No redundant words. Highly front-loaded and efficient.

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 only one parameter and an output schema (not shown but indicated as present), the description covers usage and behavior sufficiently. It lacks details on error conditions but is complete for a simple mapping 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 has 100% coverage with a description for 'target'. The tool's description adds value by detailing the output based on target type (e.g., 'test_* functions', 'modules/symbols'), going beyond the schema's brief note.

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 'map' and clearly distinguishes two modes: symbol to tests and test file to symbols. It is not a tautology and effectively communicates the core function.

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 context: 'Use before changing code to know what to run.' This tells when to use it. It does not explicitly mention when not to use or alternatives, but the sibling tools list implies differentiation.

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 the full burden. It discloses that it returns import edges with line numbers and a list of dependent files, and implies a read-only operation. Does not mention rate limits or permissions, but adds value beyond what's given.

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?

Extremely concise: two short sentences. The first sentence states the purpose, the second adds usage context and output. Every sentence is essential and 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?

Has output schema externally, but description explains output contents adequately (import edges, line numbers, dependent files). Covers both forward and reverse dependencies. Missing edge cases or error handling, but sufficient for common 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%, and the description adds little new information about parameters beyond the schema. The path description is identical to schema; response_format is not mentioned in description. Baseline 3 is appropriate as schema does the heavy lifting.

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 shows imports (internal vs external) and reverse dependencies (who imports it), using specific verbs and resource. It distinguishes itself from sibling tools like find_references and trace_call_graph by focusing on import dependencies and blast 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?

Explicitly says 'Use to gauge the impact of changing a module', providing clear context. However, it does not explicitly mention when not to use or compare to alternatives like trace_call_graph, leaving some room for ambiguity.

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

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

No annotations are provided, so the description carries full burden. It discloses that the operation is cheap (cost hint), does not read bodies, and returns a nested outline with line numbers. Could add limits (e.g., only for Python files based on path schema) but is fairly transparent.

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 concise sentences front-load the purpose, with no fluff. The second sentence adds important detail about return content. Every phrase 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?

The description covers what, why, and when to use the tool. Given the simple read-only nature with 2 well-documented parameters and an output schema, it is largely complete. Could mention that it works only for Python files (based on path schema) but otherwise 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?

Schema coverage is 100% with clear parameter descriptions. The description does not add extra semantics beyond what the schema provides, but it reinforces the return context ('outline with line numbers'). 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?

Clearly states the action ('List the symbol skeleton') and resource ('a file or directory'), with the key benefit of NOT reading bodies. Distinguishes itself from reading a whole file, which is a sibling operation.

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 advises to prefer this over reading a whole file when only the shape is needed. Implicitly contrasts with tools like search_code or find_references, but does not enumerate when to avoid 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?

Description discloses return format (two indented trees with 'path:line') and edge cases (external bases marked external/unresolved). This adds behavioral context beyond the schema or annotations, which are absent.

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?

Description is concise (two sentences) and front-loaded with purpose. 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?

With an output schema present, the description adequately explains return values. It could mention error handling or prerequisites, but the core functionality is well-covered.

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 described. The description does not add extra meaning beyond the schema, so 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?

Description clearly states the tool shows a class's type hierarchy, specifying both superclasses and subclasses/implementations. It distinguishes from sibling tools like find_symbol or trace_call_graph by focusing on type hierarchy specifically.

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 explicit guidance on when to use this tool versus alternatives. The purpose is clear, but there's no 'when-to-use' or 'when-not-to-use' information, leaving the agent to infer.

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 full burden. It lists the returned data in detail: project name, counts, package manager, config files, entry points, test setup, frameworks, and per-package size map. It implies a read-only, one-call operation. Could mention potential computational cost, but overall transparent.

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?

Concise and well-structured: front-loaded with the key instruction 'run this FIRST', then a clear bullet list of return values. Every sentence is necessary and no waste.

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 purpose (summarizing entire repo) and the presence of an output schema, the description fully covers usage context, return values, and exclusions. 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?

The tool has zero parameters, so baseline is 4. The description adds no parameter info beyond what schema already provides (nothing to add), which 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's purpose: 'Summarize the entire repository in one call — run this FIRST on an unfamiliar codebase.' It specifies the action (summarize) and resource (repository), and distinguishes from siblings by advising against using for specific symbols/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?

Explicitly says when to use: 'run this FIRST on an unfamiliar codebase.' Provides clear when-not guidance: 'Do NOT use for finding a specific symbol or file — use find_symbol or get_file_outline for that.' This directly addresses 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?

Describes return format (file:line plus matched text/symbol) and pagination. With no annotations, it provides good transparency but misses clarifying interactions between regex and modes, and doesn't mention auth/rate limits, though these are not critical for a search 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?

Four sentences, front-loads primary purpose, then explains modes, results, and usage guidance. No redundancy or fluff.

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 output schema present, the description adequately covers key behaviors (mode difference, pagination, usage guidance) without needing to detail every parameter. It is complete for an agent to select and 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 covers all 7 parameters. Description adds value by explaining lexical vs semantic mode behavior and result differences, going beyond what the schema provides. A solid improvement over baseline 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?

Clearly states it searches the repo with filtering and pagination, and distinguishes two modes. It also contrasts with siblings by noting when to use structural tools instead.

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 tells when to use this tool (when exact symbol name unknown) and when not to (prefer find_symbol/find_references). Also notes semantic mode requires optional extra.

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 full burden. It describes the output format (indented tree with path:line), mentions recursion depth limit marking, and shares precision tradeoff. It could explicitly state it's read-only, but the given details provide good transparency.

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

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

Two concise sentences that front-load the core action and benefit, then add output format and tradeoff. No wasted 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?

Given the tool's complexity (3 params, output schema present), the description covers purpose, output, and a key tradeoff. It could mention error handling or performance, but overall it provides sufficient context.

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

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

Schema coverage is 100%, so baseline is 3. The description adds context like 'callers or callees' and 'N levels' that map to parameters, but does not provide additional details beyond the schema's 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 the tool's purpose: 'Trace the call graph from a function — callers or callees — to N levels'. It distinguishes itself from the sibling tool 'find_references' by noting it does this in one call instead of chaining.

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 context by contrasting with chaining find_references and mentions a precision tradeoff. However, it does not explicitly state when not to use this tool or provide alternative conditions.

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