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

With no annotations, the description takes full responsibility for behavioral disclosure. It honestly states that edges come from static analysis, that 'resolved:false' edges are name-match guesses, and that any edge can be stale or miss dynamic dispatch. It also mentions the token budget and truncation behavior, providing excellent 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?

The description is well-structured and mostly concise, front-loading the core purpose. It includes essential details about usage and limitations without excessive verbosity, though it could be slightly more streamlined.

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 (6 parameters, no output schema), the description covers the essential behavioral aspects, limitations, and integration with sibling tools. It lacks explicit mention of the response shape, but the purpose and limitations are clear enough for an AI agent to use the tool 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?

The description provides high-level context for the tool but does not elaborate on individual parameters like depth, maxNodes, or direction beyond what is in the schema. Since schema coverage is 50%, the description partially compensates by explaining the tool's overall behavior, but it doesn't fully clarify parameter semantics for all 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 clearly states the tool's purpose: exploring the static relationship graph around one node, listing specific edge types (callers/callees, imports, inheritance, containment). It distinguishes itself from the sibling tool nav_references by positioning itself as a cheaper, instant alternative for understanding dependency shape.

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 advises to call this BEFORE nav_references for cheap dependency shape, and to verify specific edges with nav_references or nav_callHierarchy later. This provides clear when-to-use and when-to-avoid guidance, including 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?

Without annotations, the description carries full burden. It discloses that the tool is cheap, uses a static index, has no language-server cost, and is fast. It warns that the index may lag recent edits and advises using other tools for live confirmation. However, it does not explicitly mention what the tool does not do (e.g., provide live line numbers) but implies it via the warning.

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 paragraph of 5 sentences, front-loaded with the purpose. Every sentence adds value, and it is well-structured for quick comprehension.

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 3 parameters, no output schema, and no annotations, the description covers purpose, usage guidelines, limitations, and links to siblings. It provides sufficient context for an overview tool, enabling the agent to decide when and how to use 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?

Schema description coverage is 67% (2 of 3 parameters have descriptions). The description adds some context about token budgeting and speed but does not elaborate on parameter usage beyond what the schema provides. It indirectly adds value by explaining the tool's nature, but parameter semantics are not significantly enhanced.

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 that the tool returns a structural summary from a static index, specifying it as a starting point for unfamiliar codebases. It distinguishes itself from siblings like map_neighbors and resolve by explaining how node IDs are used with those 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?

Explicitly says 'START HERE for any unfamiliar codebase or feature area.' Provides guidance on when to use siblings: 'Use the returned node IDs with map_neighbors to explore relationships and with resolve to jump to exact live locations.' Also warns about index lag and suggests confirming with resolve or nav_definition for live data.

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?

Discloses that the path is 'shortest structural path' and 'static and possibly stale', which are important behavioral traits. Since there are no annotations, these add value. However, it does not describe the response format or error behavior (e.g., no path found), slightly reducing completeness.

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 efficient sentences: first defines purpose, second gives usage guidance and a caution. No fluff, 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?

While purpose and usage are clear, the description omits response structure (e.g., the format of the path, whether it is a list of node IDs) and handling of edge cases like no path. Without an output schema, these gaps reduce completeness.

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

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

Schema coverage is 60%, and the description indirectly maps 'from' and 'to' as symbols but adds no details beyond the schema's own descriptions for maxLen, tokenBudget, or includeReferences. It provides minimal additional context, earning a middle score.

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 specifies the verb 'find shortest structural path' and the resource 'static map', with explicit mention of relations (imports/calls/inheritance/containment). It clearly distinguishes from siblings like map_neighbors or map_overview.

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?

Provides a concrete use case ('understand how two areas connect before reading code') and explicitly warns about staleness, directing to nav_references for confirmation. This tells the agent when and when not to rely on this tool.

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 the burden. It reveals that the rebuild is incremental (only re-parses changed files except on first build), and mentions it's long-running on first build. It does not disclose any destructive side effects or system impacts beyond time, but the description is clear enough for safe invocation.

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

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

Two sentences, front-loaded with the action and key behavior (incremental). Every sentence adds value: first defines the tool, second provides usage guidance and performance context. 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?

Given the tool's complexity (side-effect operation) and lack of output schema, the description adequately covers when to use, performance implications, and distinction from live queries. It could optionally mention return format or completion signal, but the context is sufficient for an agent to decide 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 coverage is 100% with the 'scope' parameter described as 'Subtree to rebuild, e.g. 'src/auth'; omit for the whole repo.' The description repeats 'omit for the whole repo' but adds no new meaning beyond the schema. The baseline is 3 for high-coverage schemas.

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

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

The description clearly identifies the tool's action ('Rebuild the static map index') and resource (map index), and distinguishes it from sibling tools like map_neighbors, map_overview, and the nav_* tools by stating it's not needed for nav_* correctness.

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?

Provides explicit usage conditions: 'Use when map responses flag staleness or after large refactors.' Also states when not to use: 'Not needed for nav_* correctness.' The note about long-running first build sets performance expectations.

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 mentions the lookup is name-based and possibly stale, indicating it may not reflect the latest state. However, it does not explicitly state whether the tool is read-only or any other side effects, leaving some 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 two sentences, immediately stating the purpose and usage context. It is front-loaded and every sentence adds value without redundancy.

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

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

Given no output schema, the description explains the return type (node IDs) and how to use them (with map_neighbors and resolve). It also notes the staleness caveat. The sibling list provides further context. It is adequately complete for a simple search tool.

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

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

Schema description coverage is 50% (query and tokenBudget have descriptions; kind and limit do not). The description adds that the search is by name and returns node IDs, which indirectly explains query's purpose but does not elaborate on kind or limit. It adds marginal value beyond the schema for 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 clearly states the tool performs fuzzy symbol lookup over a static map, returning node IDs for use with map_neighbors and resolve. It distinguishes itself from siblings like nav_workspaceSymbols by noting it is name-based, cheap, and possibly stale.

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 says when to use: when you don't have a location yet. It also provides an alternative: for ground truth use nav_workspaceSymbols, which queries the live language server. This gives clear context and exclusions.

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 discloses that the tool is 'cheap' (low cost) and enumerates the data it provides, which implies it is a safe, read-only operation. No hidden behaviors or side effects are indicated.

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 long, no wasted words, and front-loads the key information about what the tool provides. It is optimally concise.

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 no output schema, the description enumerates all relevant status aspects (map age, counts, etc.). For a zero-parameter status check, this is complete and sufficient for an agent to understand the tool's output.

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 zero parameters, so schema description coverage is 100%. The description adds no parameter info because none exist, aligning with the baseline score of 4 for no-parameter tools.

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 explicitly states the tool provides 'Health and freshness of both layers' and lists specific metrics like map age, file/symbol/edge counts, stale files, watcher state, and per-language LSP availability. This clearly distinguishes it from sibling tools like map_neighbors or map_overview.

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 advises using it when 'results look off' or to check language server installation, providing clear usage context. It does not explicitly mention when not to use or alternatives, but the guidance is sufficient.

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 discloses fallback to static map call edges with source tag and warning, and the need for cursor on symbol name.

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 well-structured sentences with no redundancy; every part adds value relative to the schema.

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?

Covers main behavior, fallback, and response hints (source tag, warning) even without output schema. Slightly lacking on detailed use cases.

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 67%; description adds context about positioning requirement but does not detail parameter semantics beyond schema defaults.

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 provides 'live call hierarchy' with direction (incoming/outgoing), and distinguishes from siblings like nav_references and resolve(nodeld).

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?

Explains positioning requirement ('must be on the symbol name') and fallback behavior, but does not explicitly exclude cases like non-symbol positions or when to prefer siblings.

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 description carries full burden. Discloses that results are 'ground-truth' and current, and mentions tokenBudget truncation behavior. However, lacks details on auth, rate limits, or error 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?

Two concise sentences with no redundant information. Front-loaded with purpose and usage guidance. Every sentence adds value.

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?

Parameters are fully described in schema, but output schema is absent. Description partially compensates by mentioning list truncation with tokenBudget, but does not specify return format or what the tool returns (e.g., location or list). Adequate but not 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 covers 100% of parameters with descriptions. The description adds context about resolve(nodeId) for obtaining file:line:col, but does not substantially enhance understanding beyond the schema.

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

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

Clearly states it performs 'go to definition' from the live language server, reflecting current on-disk contents. Distinguishes from sibling nav tools like nav_references and nav_callHierarchy.

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 to use after map_search/map_neighbors or directly with exact file:line:col, and mentions resolve(nodeId) for obtaining that. Provides clear context but does not explicitly state when not to use.

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 mentions 'language-server ground truth' and 'Live', but fails to disclose behavioral traits like destructive potential, authentication requirements, rate limits, or return format. This is insufficient for a tool with zero annotation coverage.

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-loaded with the core purpose and usage pattern. No unnecessary words, making it efficient for an agent 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?

For a navigation tool with no output schema and no annotations, the description is reasonably complete. It covers what the tool does and how to use it. Missing some behavioral details, but for this type of tool it suffices.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description adds minimal extra meaning (only references usage pattern). Baseline 3 is appropriate as the description does not significantly enhance understanding beyond the schema.

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

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

The description clearly states the tool navigates to implementations of an interface or abstract method, using language-server ground truth. It specifies the exact resource and action, and distinguishes itself from siblings like nav_definition by targeting implementations.

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 provides usage pattern: same as nav_definition, requiring a position from resolve or map_search+resolve. It does not explicitly state when not to use it, but the guidance on prerequisite steps is clear and actionable, earning a 4.

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, but description discloses that it is live language server, reflects current on-disk contents, costs real latency, and results may be truncated. Implies read-only, though not explicit.

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?

Three sentences with no redundancy. Front-loaded with core purpose, followed by usage guidance and optimization tip.

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?

Covers purpose, usage, and behavioral traits well. Lacks description of return structure, but mentions truncation behavior. Sufficient for a tool with many siblings and no output schema.

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

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

Schema has 100% parameter descriptions, so baseline is 3. Description adds minimal extra guidance (use fileFilter instead of raising tokenBudget).

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 verb 'find all references' and the resource (symbol at file:line:col). Distinguishes from siblings by mentioning map_neighbors and resolve as alternatives.

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

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

Explicitly states when to use (confirm impact before editing) and when not to (costs latency, narrow first with map_neighbors/resolve). Provides refinement strategy for truncated 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?

No annotations are provided, so the description bears full responsibility for behavioral disclosure. It only states 'always current' and 'live outline', implying a read-only operation, but fails to mention side effects, required permissions, error behavior, or the fact that it returns a hierarchical list of symbols. Critical behavioral traits are missing.

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 only two sentences, with no wasted words. It front-loads the core functionality ('Live outline of one file') and immediately follows with a usage suggestion. Every sentence adds value and fits within a concise scope.

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 there is no output schema, the description does not explain the return format (e.g., symbol kind, name, location), which is relevant for an agent to interpret results. It also does not compare with sibling tools beyond the one alternative (reading whole file). For a two-parameter tool with full schema coverage, it is minimally adequate but leaves gaps in output format and sibling differentiation.

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 no extra meaning beyond what the schema provides. It implies the 'file' parameter through 'one file' but does not elaborate on tokenBudget or its truncation behavior. Baseline 3 is appropriate as the schema already documents both parameters sufficiently.

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 provides a 'live outline of one file (document symbols, hierarchical)', specifying the verb (outline), resource (one file), and structure (hierarchical). It distinguishes from reading a whole file but does not explicitly differentiate from sibling tools like nav_callHierarchy or nav_definition, which also deal with symbols.

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 advises to 'prefer this over reading a whole file to learn its structure', giving a clear when-to-use context. However, it lacks explicit when-not-to-use guidance or mention of alternative tools among the siblings, leaving the agent to infer exclusion criteria.

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 discloses that the tool uses the language server's type checker for live hover, and clarifies limitations of map tools. Does not discuss side effects (likely none) or response structure, but is sufficient for a read-only query.

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: first defines core functionality, second differentiates from siblings. No wasted words, front-loaded with the key action 'Live hover: resolved type signature and docs'.

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

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

Given no output schema and 4 documented parameters, the description explains the tool's authority and data source. It does not specify return format, but for a type-query tool this is acceptable; a minor gap is the lack of verbosity on what 'docs' includes.

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 has 100% parameter coverage with descriptions for all 4 parameters, so baseline is 3. The description adds no additional parameter-level context beyond what the schema provides.

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 provides 'resolved type signature and docs at a position' from the language server's type checker, and distinguishes itself from sibling 'map' tools by noting they only have parse-time signatures.

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 implies use when needing type information at a cursor position ('authoritative answer to what type is this?'), contrasting with map tools. Lacks explicit when-not-to-use or alternatives, but the sibling list and context make it clear.

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?

Since no annotations are provided, the description carries full burden. It discloses the tool is authoritative, slower, and enforces a minimum query length. However, it does not mention error handling, authorization needs, or confirm read-only nature, which is a minor 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 two sentences, front-loaded with the purpose, and every sentence adds essential information. 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?

With no output schema, the description should explain return values. It only says 'symbol search', leaving the result format ambiguous. It also does not mention the truncation behavior implied by the tokenBudget parameter's schema description, which is a gap. However, the tool is relatively simple, so the description is adequate 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 coverage is only 33% (only tokenBudget has a description). The description adds rationale for query minLength ('to avoid result floods') but does not describe the limit parameter or provide additional context for tokenBudget beyond the schema's own description. The added value is minimal.

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 does 'Live workspace-wide symbol search from the language server' and distinguishes it from the sibling map_search by noting it is authoritative but slower, and provides explicit use cases: 'use when the map is stale or missing, or to confirm a map_search hit.'

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?

Provides explicit when-to-use guidance vs alternative map_search, and specifies a constraint ('Query must be ≥3 chars to avoid result floods'), making it clear for an agent to decide.

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 both input modes (nodeId vs file:line:col), explains the mapStale flag indicating drift, and details what happens when map hasn't caught up (inMap:false with nearest container). Also explains tokenBudget behavior (truncation with note). No annotations present, so description carries full burden and succeeds.

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?

Sentence 2 is long but packs essential information. Could be slightly more structured (e.g., bullet points), but still efficient with 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?

Completely covers both directions of resolution, explains stale detection and fallback behavior, and provides usage context relative to sibling tools. No output schema exists, but description gives enough to understand return 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?

Adds significant meaning beyond schema: explains the nodeId pattern, the dual use of file/line/col, and the tokenBudget behavior. At 60% schema coverage, description compensates fully.

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 tool bridges static map and live language server, resolving nodeId to file:line:col and vice versa. Distinguishes from sibling map_* and nav_* tools by positioning it as a bridge between 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?

Explicitly says 'call it whenever you switch layers', and provides specific guidance: 'Use before nav_* calls that need exact positions, and after nav_* results to re-enter the map graph.' This tells the agent exactly when and how to use it.

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