Priority — TypeScript Compiler Intelligence

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the description only needs to add context beyond that. It usefully adds 'bounded' and 'exact compiler symbol' semantics, clarifying pagination and match behavior, but it does not contradict the annotations.

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

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

The description is a single sentence with no filler. The core verb, resource, and key qualifiers are front-loaded, and every word contributes to the meaning.

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?

Even with a valid output schema and safety annotations, the description is too thin for a tool with a oneOf input mode and six parameters. An agent cannot infer when to supply files versus snapshot or what compact does. More operational context is needed for reliable invocation.

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

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

Schema description coverage is 0%, so the description must compensate, but it only hints at the symbol and boundedness. It does not explain the semantic difference between files and snapshot, the meaning of compact, or how offset beyond a numeric boundary works. This is insufficient for six parameters.

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 the specific verb 'Return' and identifies a precise resource: bounded reverse-caller impact for one exact compiler symbol. This scope distinguishes it from sibling tools like find_references or get_importers, though it does not explicitly name 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?

The description implies the tool is for exact-symbol reverse-caller impact queries but provides no explicit when-to-use guidance or alternatives. It leaves the agent to infer that this is the appropriate tool for bounded caller analysis rather than stating when not to use 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?

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, lowering the burden on the description. The description adds useful behavioral context with 'semantic static' and 'one exact symbol,' but it does not explain matching behavior, result shape, or pagination implications beyond the schema.

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

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

The description is a single sentence that opens with the action and object, contains no filler, and communicates the core distinction in a short sentence. It is optimally front-loaded for an agent scanning tool descriptions.

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

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

Despite having an output schema and favorable annotations, the description omits the required input-mode choice between files and snapshot and does not explain pagination or compact output. For a six-parameter tool with zero schema descriptions, this is a significant completeness 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 carry parameter meaning, but it only clarifies the 'symbol' parameter. The key files/snapshot one-of contract, limit, offset, and compact are left undocumented; an agent cannot learn their semantics from the description or schema 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 names a specific verb ('return') and resource ('semantic static references to one exact compiler symbol'), so an agent immediately knows this is a reference-lookup tool. It does not explicitly contrast with sibling tools like get_definition or get_importers, but the phrasing is distinct enough to establish core purpose.

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 no guidance on when to choose this tool over siblings such as get_imports, get_definition, or get_symbol_context, and it does not state any exclusions. An agent must infer usage from the name and one-line description alone.

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

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

Annotations already cover the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false), so the bar is lower. The description adds value beyond those: 'deterministic ranked' discloses stable result ordering, and 'safely reports ambiguity' discloses that ambiguous input yields a report rather than a failure. No contradiction with annotations — 'resolve' aligns with read-only and deterministic behavior.

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 14-word sentence carries three distinct pieces of information: the resolution action, deterministic ranked ordering, and safe ambiguity reporting. It is front-loaded with the action and contains zero filler or repetition. 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?

Despite a rich annotation set and an output schema (which lighten the return-value and safety burden), the tool is moderately complex: 7 params, a oneOf files/snapshot branching mode, and 11 siblings with overlapping symbol tools. The description is too thin to let an agent correctly choose an input mode or construct a well-formed call. The input contract and sibling-routing gaps are significant.

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% across 7 parameters, so the description carries the burden of explaining inputs. It only implicitly maps to 'name' via 'a symbol name' and says nothing about kind, path, files, limit, compact, or snapshot. Critically, the oneOf files-or-snapshot input contract — a core decision for callers — is entirely unexplained. The description fails to compensate for the schema's lack of documentation.

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 ('Resolve'), a resource ('a symbol name'), and an outcome ('deterministic ranked compiler symbol candidates'). It clearly conveys what the tool does and implies a multi-candidate result rather than a single lookup. However, it does not explicitly contrast with overlapping siblings like get_definition or get_type, so it stops short of full sibling differentiation.

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 offers no guidance on when to use this tool versus the 11 siblings, several of which overlap in symbol resolution (get_definition, get_type, get_symbol_context, query_code). There are no when-to-use conditions, exclusions, or alternative routing. 'Safely reports ambiguity' hints at a niche (ambiguous names don't error), but that is behavioral, not usage direction.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so safety is covered. The description adds no extra behavioral context such as authentication, rate limits, or data freshness, but for a read-only capability query this 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?

Single sentence, front-loaded with the verb 'Return', and every word conveys meaning. There is no redundancy or filler.

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

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

Given zero parameters, an output schema, and annotations covering safety, the description is sufficient. It names the categories of information returned, which is all an agent needs to decide 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 tool has zero parameters, so there are no parameter semantics for the description to add. The baseline of 4 applies here, and the description does not need to compensate for any schema gaps.

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: 'Return Semantic Reader capabilities, limits, billing and discovery facts.' This clearly distinguishes it from sibling tools that focus on code symbols (find_symbol, get_type, etc.), so an agent can easily tell this is a system-level capability query.

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 the tool is for retrieving capability and billing information, but it does not explicitly state when to use it or mention alternatives. Since it is a simple zero-parameter query, the gap is minor but still present.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the 'compiler-resolved' nuance, implying resolution across definitions, but does not disclose behavior for missing symbols or ambiguous definitions. This is adequate given the annotations.

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

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

The description is a single, concise sentence with no redundant wording. It front-loads the core action and resource, making it easy to parse quickly.

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 five parameters, a oneOf requirement, and zero schema descriptions, the description is too sparse. It does not explain the input options, the output structure, or any constraints. While an output schema exists, the input semantics remain unclear, leaving a significant gap for the agent.

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 hints at 'supplied-file symbol' without explaining parameters like kind, path, or the oneOf relationship between files and snapshot. The agent cannot infer parameter meanings from the description alone.

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 returns the compiler-resolved declaration for a symbol in a supplied file. It implies a specific verb ('Return') and resource ('declaration'), distinguishing it from siblings like find_symbol or get_type, which serve different lookup 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?

No explicit guidance on when to use this tool versus alternatives. It does not mention when to prefer get_definition over find_symbol, get_type, or get_symbol_context, nor any exclusions or prerequisites beyond the need for a supplied file and symbol name.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the note that diagnostics are 'syntactic and semantic' and that they apply to 'supplied files,' implying no whole-project scanning. However, it does not disclose details like pagination behavior or that it may require a snapshot or tsconfig for accurate results. Given the annotations, a 3 is fair—some added context but not rich behavioral disclosure.

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

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

The description is a single sentence, concise and front-loaded with the core action and object. Every word contributes to the primary purpose, and there is no redundancy or filler. It is appropriately brief for a tool whose purpose is straightforward, even if the parameter semantics are lacking.

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—8 parameters, nested objects, a oneOf constraint, and an output schema—the description is far too sparse. It does not explain when to use it, what the parameters mean, or how to handle the oneOf alternatives. While the output schema clarifies return values, the description leaves critical context, such as the need for either files or snapshot, entirely to the schema, which has no descriptions. This is incomplete for an agent to call correctly without additional inference.

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%, meaning none of the 8 parameters (files, snapshot, limit, offset, compact, packages, tsconfig, path) have descriptions. The tool description does not compensate: it only mentions 'supplied files,' which maps to the 'files' parameter, but says nothing about the oneOf requirement, the meaning of limit/offset, or the purpose of packages, tsconfig, or snapshot. The agent would have to guess or rely on schema structure, which is insufficient.

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 clear action ('Return'), a specific resource ('TypeScript syntactic and semantic diagnostics'), and a scope ('for supplied files'). This distinguishes it from sibling tools like find_references or get_type, which focus on code navigation rather than diagnostics. The word 'bounded' hints at a limited result set, which aligns with the pagination parameters, though it is not fully explained.

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 no guidance on when to use this tool versus its siblings. It does not mention alternatives or conditions for selection. For example, it does not say 'Use this when you need type errors' or 'for cross-file analysis, use query_code.' The lack of context leaves the agent to infer usage from the tool name alone.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds no additional behavioral context such as pagination behavior, limits, or the meaning of 'snapshot' vs 'files'. With annotations covering safety, the description adds minimal extra value.

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

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

The description is a single, efficient sentence with no unnecessary words. It is appropriately front-loaded, stating the core function 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 tool has 6 parameters, a oneOf constraint, and an output schema, yet the description explains none of these. It does not clarify the difference between 'files' and 'snapshot' inputs, how pagination works, or what the output format is. Given the complexity, the description is severely under-specified.

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% and the description does not explain any of the 6 parameters. It does not clarify the roles of 'files', 'snapshot', 'symbol', 'limit', 'offset', or 'compact'. The description's mention of 'supplied files' and 'target file' vaguely maps to 'files' and 'symbol', but this is insufficient given the oneOf requirement and pagination parameters.

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 ('Return') and resource ('supplied files') with a clear condition ('statically import one target file'). It distinguishes from siblings like find_references by focusing on file-to-file import relationships. However, the required parameter is named 'symbol' while the description refers to a 'target file', creating ambiguity about whether 'symbol' is a file path or a code 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?

No guidance is provided on when to use this tool versus alternatives like get_imports or find_references. The description does not mention any exclusions, prerequisites, or typical scenarios. The agent is left to infer usage from the name and description.

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 idempotentHint=true, so the safety profile is covered. The description adds the 'static' qualifier, indicating dynamic imports are excluded, and 'one supplied file' clarifies the input scope. However, it does not discuss output format, pagination behavior, or the implications of the oneOf between files and snapshot, which would add further 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 a single sentence that front-loads the action and resource. There is no filler or redundant information. It is appropriately concise for a tool with a straightforward purpose.

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 six parameters and zero schema descriptions, the description is severely incomplete. It fails to mention the required symbol parameter, the oneOf requirement (files or snapshot), pagination controls, or the compact flag. An agent would not know how to construct a valid request without opening the schema, and even then the semantics of snapshot and symbol are unexplained. The description is far from sufficient for a tool of this complexity.

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

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

Schema description coverage is 0%, so the description must compensate. It only hints at a file input but does not explain the required 'symbol' parameter, the alternative 'snapshot' input, or the meaning of limit, offset, and compact. The phrase 'one supplied file' even conflicts with the schema's files array (up to 96 items), adding confusion rather than clarity.

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 verb 'Return' and the resource 'static imports', and specifies the scope as 'made by one supplied file'. This distinguishes it from sibling get_importers, which would return files that import a given symbol. The purpose is unambiguous and well differentiated.

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 no guidance on when to use this tool versus alternatives like get_importers or find_references. It does not mention any conditions, exclusions, or fallback tools, leaving the agent to infer usage context from the name alone.

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

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

Annotations already establish readOnly, idempotentHint, and non-destructive behavior, so the description's safety burden is low. It does add 'bounded' context and a depth/cost hint, but 'paid depth' is unclear and there is no explanation of how depth limits, offsets, or section limits behave, leaving a significant behavior gap.

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 short, which is good for conciseness, but it is cryptic rather than compact. The semicolon-separated second clause is not self-explanatory and appears to compress important detail into an unclear phrase, so the structure does not earn its place.

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

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

For a tool with 8 parameters, a nested files/snapshot oneOf, and a large output schema, a single ambiguous sentence is not enough for an agent to correctly select and invoke it. Even though an output schema exists, the description leaves the invocation modes, selection criteria, and depth semantics unresolved.

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 0% schema description coverage, the description must explain the parameters, but it only loosely maps to the include categories (definition, callers, callees, references, impact). It does not clarify the files-vs-snapshot oneOf, required name, kind/path behavior, offsets, or per_section_limit, so most of the 8 parameters remain semantically uncovered.

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 clause, 'Return bounded definition/callers/callees context', does name a clear verb and resource, which is helpful. But the second clause, 'references or impact request paid depth', is ambiguous about whether references/impact are included, cost extra, or require a depth parameter, and no distinction from sibling tools like get_definition or find_references is drawn.

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?

There is no guidance on when to use this composite tool rather than get_definition, find_references, analyze_impact, or query_code. The phrase 'request paid depth' hints at some trade-off or precondition, but it is not actionable and no alternatives or exclusions are 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description need not repeat those. However, it adds no additional behavioral context—no mention of how it resolves types (e.g., via files or snapshot), any failure modes, or constraints like requiring a TypeScript project. It doesn't contradict annotations, but it also doesn't enrich them, so it falls short of adding value beyond the structured fields.

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

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

The description is a single sentence with no wasted words, which is concise. However, given the tool's complexity (7 parameters, nested objects, output schema), this brevity is under-specification rather than efficient conciseness. It's front-loaded with the core purpose but lacks the structural guidance an agent needs.

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 has 7 parameters including complex nested objects (files, packages, tsconfig), an output schema, and multiple sibling tools. The description only states the output, not how to invoke it correctly—no explanation of the oneOf between files and snapshot, no guidance on required 'name', and no mention of how the output is structured. This is severely incomplete for a tool of this complexity.

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

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

Schema coverage is 0% (no parameter descriptions in the schema), and the description offers no explanation of the 7 parameters (name, kind, path, files, snapshot, packages, tsconfig). It doesn't clarify what 'name' refers to (e.g., declaration name), how 'files' vs 'snapshot' are alternatives, or what 'kind' and 'path' mean. With zero compensation for missing schema documentation, this is a critical gap.

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: returning TypeScript type facts and call/construct signatures for a single declaration. It uses a specific verb ('Return') and resource ('type facts and call/construct signatures'), which differentiates it from siblings like get_definition (likely returns location) or find_symbol (likely returns symbol references). However, it doesn't explicitly contrast with those siblings, so it's clear but not fully distinguished.

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 no guidance on when to use this tool versus alternatives. It doesn't mention conditions like 'when you need type details' or 'use find_symbol for locating symbols instead'. Given the rich set of sibling tools, this lack of routing leaves the agent to guess, which is a significant gap.

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

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

The description states the tool 'store[s] supplied source files,' implying a write operation, while annotations declare readOnlyHint=true, indicating the tool should not modify state. This is a direct contradiction. The description also fails to disclose any other behavioral traits (e.g., lifecycle of the snapshot, side effects, or how the handle is used).

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

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

The description is a single, concise sentence with no filler. It front-loads the core action ('store') and purpose ('return handle for reuse'). However, it lacks any structured breakdown (e.g., sections or examples) that could improve clarity, though its brevity is not a flaw per se.

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 a stateful operation that returns a handle for later use, but the description does not explain the expected workflow, the nature of the snapshot, or how the handle should be consumed. Although an output schema exists, the description itself is too sparse to guide correct invocation, especially given the nested parameter structure.

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 explain the 'files' parameter. It only says 'supplied source files' without describing the array-of-objects structure (path/content) or constraints. This provides minimal semantic value beyond the schema's raw type definitions.

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 ('store') and resource ('supplied source files') with a clear purpose ('return an opaque snapshot handle for reuse'). It clearly distinguishes from sibling analysis tools (e.g., find_references, query_code) which do not store files, making the purpose unambiguous.

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

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

The description offers no guidance on when to use this tool versus alternatives. It does not mention any prerequisites, exclusions, or conditions under which another tool would be more appropriate. The only hint is 'for reuse,' which is vague and does not clarify the workflow with sibling 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?

Annotations already declare readOnlyHint=true and idempotentHint=true, so the description adds no new behavioral information. It does not mention pagination, result size, or any other runtime characteristics beyond what the schema's limit/offset parameters imply.

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

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

The description is a single short sentence, which is concise in word count but not appropriately sized for a tool with seven parameters and complex query semantics. It is under-specified rather than efficiently 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?

Given the complexity (seven params, many siblings, and an output schema), the description is grossly incomplete. It does not explain the query types, the input modes (files vs snapshot), or the meaning of symbol, making it inadequate for an agent to call correctly.

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

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

Schema description coverage is 0%, so the description must compensate, but it fails to explain any of the seven parameters. It does not clarify what files vs snapshot means, what symbol refers to, or how compact and limit/offset work, leaving the agent entirely dependent on guessing from names and enums.

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 tool provides 'free navigation for symbols, callers, callees or function facts,' which maps to the query enum values. However, it is vague about what 'navigation' entails and does not differentiate it from siblings like find_symbol, get_definition, or find_references, which have more specific 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?

There is no guidance on when to use this tool versus the many siblings. The description does not mention any exclusions, conditions, or alternatives, leaving the agent to infer use cases from the vague 'free navigation' phrasing.

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