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

Beyond the readOnly/openWorld annotations, it discloses index-based detection, the in-tree/external split, handling of macro-generated and parser-missed definitions via resolved_via, and the JSON result shape. This is substantial 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 information-dense but well organized: a short defining question, a concise behavior summary, and a compact output schema sketch. Every sentence adds value and there is 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 compensates by giving the JSON return shape and key edge cases. However, it omits semantics for format and project_root, and the default-text vs JSON-message ambiguity leaves a minor but real gap.

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 0%, so the description must compensate, but it only clarifies symbol as the exact name. The format parameter (json/text with text as default) and project_root are not explained, and the 'JSON results' example is not reconciled with the default text format.

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 the exact scope: callees/outgoing calls of a function, and further clarifies what the output contains (in-tree locations vs external names). It clearly distinguishes this from siblings like find_callers and find_references without needing to compare schemas.

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

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

The description gives clear invocation context: pass an exact function symbol, and the tool uses the index rather than reading files. It does not explicitly name alternatives or say when not to use this tool, so it stops 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 declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds valuable behavioral context: deduplication per calling function, mapping references to enclosing functions, showing the source line of the first call site, and the JSON result shape. This goes beyond what 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?

The description is well-structured and front-loaded with the core purpose. It includes a compact JSON result example and an Args section. Slightly verbose in the middle ('so there is nothing to re-grep') but that sentence earns its place by explaining a key benefit. Overall efficient 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 query tool with no output schema, the description covers the main use case, result shape, and key parameter. It lacks explicit guidance on pagination parameters (limit/offset) and the text format option, but the core calling scenario is well covered. The absence of an output schema is partially compensated by the inline JSON example.

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 0%, so the description must compensate. It documents the key parameter 'symbol' ('Exact symbol name whose callers you want') and mentions the JSON result fields. However, it doesn't explain limit, offset, format, or project_root semantics beyond what the schema already provides. The description adds some value for the main parameter but leaves the other four undocumented.

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: find callers of a function, deduplicated per calling function with call counts. It distinguishes itself from siblings by explicitly positioning itself as the 'who uses this?' view for impact analysis and mentions walking the caller graph upward, which differentiates it from find_references and find_callees.

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 explains when to use this tool ('highest signal-to-noise who uses this? view for impact analysis') and how to iterate it ('walk the caller graph upward'). It doesn't explicitly name alternatives or say when not to use it, but the context is clear enough for an agent to select it over siblings like find_references or find_callees.

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 indicate readOnlyHint=true and openWorldHint=false, but the description adds significant behavioral context: it explains how macro-generated symbols resolve, how definitions are recovered from EXPORT_SYMBOL* sites, and the flag 'resolved_via'. It also details the behavior of active_config (drops definitions with false guards, config_filtered count). This goes beyond annotations and is not contradicted.

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 lengthy but information-dense and front-loaded with a summary line. It is well-organized in paragraphs and an Args section. There is some verbosity (e.g., examples inside parentheses), but each sentence adds value. A slightly tighter structure would improve it, but it is not wasteful.

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 (7 params, no output schema), the description is fairly complete. It explains the result structure (envelope fields), the behavior of active_config, and the resolution of macros. However, it does not explain the 'limit', 'offset', and pagination behavior, nor the 'format' parameter, and it omits the meaning of 'guard_variants' in the envelope. These gaps are minor given the schema provides defaults but not semantics.

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 has 0% description coverage for parameters. The description explicitly details 'symbol', 'case_insensitive', and 'active_config' parameters with examples and behaviors. However, 'limit', 'format', 'offset', and 'project_root' are not explained. Since the coverage is very low, the description compensates partially by covering the required parameter and two key optional ones, but leaves some undocumented.

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: go to definition for C/C++ symbols, and distinguishes it from siblings by noting it is 'the best first query.' It lists the symbol kinds (function, struct, macro, typedef, enum) and includes a usage summary. This is a specific and informative purpose statement.

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 indicates when to use it (as a first query) and mentions that case_insensitive skips the usage summary, but it does not explicitly compare with siblings such as find_references or find_callers. It gives context for usage but lacks explicit alternatives 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?

Beyond the readOnlyHint/openWorldHint annotations, it discloses rich behavior: results only come from the index, each reference carries its #if/#ifdef guard stack, symbols with >200 sites are grouped per-file with counts, active_config drops definitely-false guarded references (config_filtered), and no-definition symbols produce a "fallback": "symbol_usages" flag. No contradiction with annotations — "find" is consistent with readOnlyHint=true, and index-scoped results align with openWorldHint=false.

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?

Well-structured and front-loaded: purpose first, then behavioral caveats, then an Args list. The prose is dense with useful specifics. Minor redundancy — group_by's "auto (default: per-file counts above 200 references)" restates the 200-site grouping already explained in the opening paragraph — but this is arguably a helpful reminder rather than 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?

With 9 parameters, no output schema, and 0% schema description coverage, the description carries heavy burden and mostly succeeds: it conveys the result shape (per-file counts vs individual sites, fallback and config_filtered flags, guard stacks) and explains core parameters. The only notable gaps are the unexplained project_root parameter and no description of limit/offset pagination behavior.

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 0%, so the description must compensate — and it does for the core parameters: group_by value semantics, active_config behavior, path_prefix with a concrete example, and case_insensitive meaning. However, four parameters (limit, format, offset, project_root) are never mentioned in the Args section; project_root in particular is ambiguous for a kernel-tool agent.

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 first sentence states an exact verb+resource: "Find all references / usages of a C/C++ symbol — every call and use site." This clearly delineates the tool's scope from siblings like find_callers/find_callees (directional relationships) and find_definition (definitions) by covering all call and use sites. The phrase "Only real reference sites from the index" further pins down what counts as a reference.

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 operational guidance: narrow widely-used symbols with path_prefix, and notes that symbols without in-tree definitions (libc calls, variables) still work and are flagged as fallback. This implies when the tool is appropriate. However, it never names sibling tools or states when not to use it (e.g., "use find_callers for direct callers only"), leaving some boundary inference to the agent.

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, and the description aligns with that (no contradiction). It adds context that the tool extracts only definition lines, handles macro-generated and parser-missed definitions via 'resolved_via', and returns JSON with {path, line, body}. This is valuable beyond annotations, though it doesn't discuss performance limits or potential edge cases.

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: it leads with a clear summary, then provides efficiency motivation, fallback behavior, and output format, before listing args. Each sentence earns its place, with no fluff. The front-loading of the core benefit (avoiding full file reads) is effective.

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 no output schema, the description covers the essential return structure (JSON with path, line, body) and edge cases (macro-generated, max_definitions). However, it doesn't specify the default format (text vs json) or how 'resolved_via' appears, which might be minor gaps given the JSON structure is mentioned.

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 0%, so the description must elaborate on parameters. It explains 'symbol' as exact symbol name and 'max_definitions' as limiting multiply-defined bodies, which is helpful. However, it omits 'format' and 'project_root' entirely, which are present in the schema; the agent may need to infer their purpose, but the schema's default values and types give some clues.

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 reads a symbol's source body without reading the whole file, differentiating it from file-level tools. It mentions specific resource (function, struct, macro) and exact behavior (extracts definitions), and implicitly distinguishes from siblings like find_definition which likely locates but doesn't read bodies.

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 implicitly indicates when to use it: when you need the body of a symbol without reading the entire file. It notes macro-generated and parser-missed definitions are resolved, suggesting fallback behavior. However, it doesn't explicitly compare to alternatives like find_definition, leaving some ambiguity about when to prefer this over find_definition.

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, so the safety profile is covered. The description adds that the tool returns document symbols only, includes kind/signature/guards, and serves as an API-surface outline. It does not mention pagination or errors, but for a read-only listing tool this is sufficient 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 compact and well organized: what it returns, when to use it, and the key argument. Every sentence adds value, and the most important information is front-loaded with no 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?

The core purpose and read-only nature are clear, and annotations cover safety. However, with no output schema and 0% parameter coverage, the agent is left to infer pagination (limit/offset), the meaning of project_root, and how format changes the result. Acceptable for a simple list tool but not fully complete.

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

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

Schema description coverage is 0%, so the description must compensate. It only explains file_path ('relative to project root or absolute'); limit, offset, format, and project_root are left to their schema titles/defaults. project_root in particular is ambiguous in relation to relative paths, and no guidance is given for pagination or output format selection.

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 ('Outline') and resource ('one source file'), then enumerates exactly what is included: functions, structs, macros, with kind, signature, and #ifdef guards. This clearly distinguishes it from sibling tools like find_definition or get_symbol_body, which target individual symbols rather than a whole file's API surface.

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 'Use this INSTEAD of reading a file when you only need its API surface,' giving a clear trigger condition and an alternative. It does not enumerate sibling tools as alternatives, but the boundary against reading the whole file is enough to guide 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?

The description adds substantial behavior beyond the annotations: BFS over the caller graph, shortest-chain semantics, per-hop call-site file:line details, result fields, hop direction, and the limitation that function pointers cannot be followed. This is exactly the kind of context an agent needs.

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 efficient and front-loaded, opening with the core question and then adding usage, behavior, limitations, and parameter details. No sentence is wasted, and the argument explanations are compact and meaningful.

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

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

The description is largely complete: it covers purpose, alternative usage, output shape, direction of hops, depth limits, and a key limitation. It does not mention the text output format or project_root, but the required behavior and main arguments are fully specified, so the gaps are minor.

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 0%, so the description carries the burden. It usefully explains from_symbol, to_symbol, and max_depth, but it does not explain format or project_root, both of which appear in the schema. The main parameters are well covered, but the full parameter set is not.

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

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

The description clearly states a specific verb and resource: it determines whether FROM transitively calls TO and identifies the chain of functions. It also explicitly differentiates itself from find_callers, and the 'shortest chain' detail sharpens the scope.

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 guidance: use this instead of chaining find_callers rounds when the question is whether one function can end up in another. This directly routes the agent to the correct sibling and explains the intended use case.

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 indicate that this operation is not read-only, is idempotent, and is not destructive. The description adds context that the refresh is synchronous and can be a performance barrier, which is useful. However, it does not disclose any side effects on the index or the specific behavior when 'full' is true beyond a brief note. Since annotations already cover the safety profile (not read-only, idempotent, not destructive), a 3 is appropriate – the description adds some behavioral context but not extensive detail.

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 opens with a clear purpose, provides usage context, and then details the 'full' parameter in a list format. It avoids unnecessary fluff and stays focused on guiding the agent. The only minor inefficiency is that the parameter explanation is slightly repetitive with the schema default, but overall it earns a high score.

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 index refresh tool with three parameters and no output schema, the description covers the primary use case well but leaves gaps. The tool's side effects on the index are not deeply described, and two parameters ('format' and 'project_root') are not explained. Given that the tool is relatively simple and annotations provide safety info, the description is adequate but not fully complete. A 3 reflects that there are improvement opportunities, but it is not severely lacking.

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 0%, so the description must carry the burden of explaining parameters. The description explains the 'full' parameter's purpose ('rebuild from scratch... rarely needed') and gives scenarios like 'large branch switch, suspected corruption.' However, 'format' and 'project_root' are not mentioned in the description; their purpose is not covered. Since schema also lacks descriptions, this leaves a gap. While the main parameter is well-handled, the others are undocumented.

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: to refresh the code index synchronously after editing files. It uses a specific verb ('refresh') and a specific resource ('code index'), making it distinct from the sibling query tools listed. It also highlights its role as a 'guaranteed-freshness barrier', which distinguishes it from the background-refresh behavior of query tools.

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

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

The description explicitly states when to use this tool: 'right after editing files when the very next query must see the changes.' It also contrasts with query tools that refresh automatically in the background, implying that the agent should use this tool instead of relying on automatic refreshes when immediacy is critical. It does not list alternatives by name but provides clear context for when to choose this tool.

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