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

With no annotations, the description carries the full burden and does well: it discloses the return content (calling function plus call-site lines), the symbol-resolution rules, and the JS/TS-only limitation. It does not cover failure modes (e.g. unresolved names) or whether results are paginated, but for a read-only query tool the disclosure is strong.

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?

Front-loaded with the core question and an example before any elaboration, and every subsequent sentence adds a distinct fact (scope vs references, resolution rules, alias, language limit). It is dense but not padded, though the mid-paragraph resolution detail is slightly heavy for a first read.

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 annotations and no output schema, the description supplies the return shape, the scoping semantics, the alias, and the language constraint, which is enough to call it correctly. Minor gaps remain around result limits and behavior when a symbol cannot be resolved.

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 compensate and largely does: it explains that `name` accepts dotted `Class.method` with inherited members, that `file_path` disambiguates a common name, and that `query` is an alias for `name`. Only the exact error/empty behavior of an unresolved `name` is left unexplained.

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 direct question-and-verb statement ('Who calls this function?') plus a concrete invocation example, and explicitly distinguishes itself from the sibling `references` tool by scope. An agent can tell instantly what resource it operates on and how it differs from the nearest alternative.

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 names the alternative (`references`) and the exact condition that separates them: callers omits imports and type-only usages and lists only actual call sites. It also states the language restriction ('JS/TS only'), which is a hard when-not-to-use boundary.

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 full burden and does well: it discloses the scan scope (`.css` files plus HTML style blocks/attributes), that definitions and usages are reported separately per configured root, and references the `WEBNAV_MCP_ROOTS` config with a single unnamed root default. It stops short of noting scanning cost, limits, or ignored files.

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 core question is front-loaded with an inline example (`css_var(name="--bg")`), and the remaining sentences each add distinct detail (cross-file rationale, scan scope, output grouping, roots, alias). It is dense and slightly long but no sentence is redundant.

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?

There is no output schema, so the description must describe returns, and it does: definitions include value plus enclosing context (e.g. `@media (...) › :root`) and usages are grouped by file with line numbers, per root. For a 2-param, no-annotation tool this is nearly complete, missing only error/empty-result 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 coverage is 0%, so the description must compensate, and it does: it states `name` may be supplied with or without the leading `--`, and that `query` is an accepted alias for `name`. Both parameters are addressed, though neither is marked optional despite required count being zero.

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 opening question states a specific resource (a `--custom-property`) and the exact action (finding where it is defined and used). It also draws an explicit boundary against sibling language-server tools like `references`/`definition` by noting those only see one file at a time, so an agent can route correctly without opening a schema.

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

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

It clearly implies when to use this over the file-scoped language servers: cross-file `var(--x)` lookups across `.css` files and HTML `<style>`/`style=` blocks. There is no explicit 'do not use when' clause, but the alternative and its limitation are spelled out, which is strong routing guidance.

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

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

With no annotations, the description carries the burden and does well: it discloses the 1-indexed, UTF-16 offset convention, tab handling, and that CSS tokens are answered from a cross-file index scoped per WEBNAV_MCP_ROOTS root. It does not describe the return shape or a 'no definition found' behavior, keeping it short of a 5.

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?

Front-loaded with the core action, then supporting detail. The CSS parenthetical is long and dense but every clause adds real semantic value, so little is wasted.

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 3-param positional tool with no annotations and no output schema, the description covers position semantics and the CSS special case well, but omits what is returned (a definition location list) and what happens on failure. Adequate but with clear gaps.

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 compensate, and it does for the two non-obvious parameters: line/column are 1-indexed with column being a UTF-16 character offset where a tab is one character. Only file_path's meaning is left implicit, which is acceptable given its obviousness.

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?

States a specific verb and resource ('Go to the definition of the symbol at a position') that an agent can distinguish from siblings like references, hover, and symbol_info. It even clarifies the difference from references in the CSS special case, so the purpose is 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 gives rich context for the CSS/custom-property case, but it never explicitly says when to choose this over siblings like hover, symbol_info, or implementations. Usage is implied by the tool name rather than stated as guidance.

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

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

With no annotations, the description carries the full behavioral burden. It does disclose one genuinely non-obvious trait — that CSS/HTML results include index-derived warnings the single-file language server cannot see — but says nothing about read-only nature, latency/freshness, whether the file must be open, or the shape of results.

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 short paragraphs, front-loaded with the core purpose, and the second paragraph is dense with information that is not available anywhere else in the definition. No filler sentences.

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 one-parameter, low-complexity query tool this is nearly sufficient, and the tricky CSS/HTML case is covered. Since no output schema exists, the description could have said more about the returned diagnostics, and the absence of annotations leaves the read-only/safety profile unstated.

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% for the single required parameter, so the description has to compensate. 'For a single file' usefully implies file_path takes one path (no globs or multi-file input), but path format (absolute vs relative vs URI) is left unstated.

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?

States a specific verb and resource ('Get the relevant language server's diagnostics (errors/warnings)') plus an explicit scope ('for a single file'), which is enough to separate it from the workspace-level sibling without opening either schema. The CSS/HTML addendum further pins down what 'diagnostics' means for those file types.

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 'single file' scoping implies the contrast with the `workspace` sibling, and the CSS/HTML clause frames when the extra index-derived warnings appear, but usage is only implied. There is no explicit statement of when to prefer this over `workspace`, nor any exclusion or precondition (e.g., file must be open/indexed).

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 full burden. It usefully discloses coordinate behavior (1-indexed lines, UTF-16 offsets on columns, tab handling), which is real behavioral context rather than restated name. However, it says nothing about what is returned when no symbol exists, whether results are plain text or markdown, or any auth/latency characteristics.

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

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

Two sentences with zero filler, and the core purpose is front-loaded ahead of the coordinate caveats. Every clause, including the tab note, earns its place by preventing an off-by-one or encoding error.

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 three-parameter read tool with no output schema and no annotations, the description should do more: it never describes the shape of the returned hover content (type signature vs. docstring vs. both) or `file_path` semantics. The coordinate explanation is a genuine strength, but the picture is only minimum-viable.

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 explain the two tricky parameters (`line`, `column`) with indexing and encoding rules. It says nothing about `file_path`, leaving open whether it is absolute or relative, and nothing about valid ranges.

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 gives a specific verb and resource: "Get type/documentation info for the symbol at a position." This clearly separates it from a location-returning sibling like `definition`, but it never names or contrasts with the closest siblings (`symbol_info`, `definition`), so an agent must infer the boundary itself.

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 explicit when-to-use or when-not-to-use guidance, and no alternative is named despite a crowded sibling set (`definition`, `symbol_info`, `references`, `implementations`). Usage is only implied by the tool name and the phrase "at a position."

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 and does well: it discloses the underlying mechanism (LSP textDocument/implementation), that results are transitive, that it follows type-checker semantics, and that it is JS/TS only. It does not mention result limits or truncation, but the operational profile is otherwise clear.

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?

Front-loads the purpose as a question, then an example, then the precise semantics. Slightly redundant (the question and the following sentence cover similar ground) but every sentence carries information.

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

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

No output schema or annotations exist, yet the description conveys what the return contains (implementing/extending classes or methods), the language restriction, and the resolution behavior for arguments. Adequate for an agent to call it correctly, with only minor gaps around result limits.

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 compensate, and it does: `name` resolves like symbol_info, `file_path` disambiguates, and `query` is an accepted alias. All three parameters are given meaning beyond the bare schema, though it never states which is required.

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?

States a precise verb+resource: lists classes that implement/extend an interface or class, or methods implementing an abstract method, and gives a concrete invocation example. It is clearly distinguishable from siblings like references, callers, and definition.

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

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

Explains the context in which it applies (interfaces, classes, abstract methods) and notes it follows the type checker rather than naming, which implicitly separates it from text-search siblings. It stops short of explicitly naming when to prefer references/callers instead.

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 full burden and does well: it discloses the scope (JS/TS files only), ordering (source order), and exactly what is excluded (locals, callbacks, object-literal keys) unless detailed=true. It does not mention error handling for non-JS/TS or missing files, and read-only status is only implied.

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?

Front-loads purpose with a question, then the definition, exclusions, flag, and follow-up path, in that order. The inline example earns its place by showing exact call syntax; phrasing is dense but not padded.

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?

No output schema exists, so the description accurately describes the return shape (indented outline with :start-end spans) and the effect of detailed on that output. Combined with explicit follow-up tools, an agent has everything needed to call it and use the result.

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% for 2 params, so the description must compensate. It explains detailed=true and its concrete effect, and the inline example demonstrates file_path usage; file_path's own semantics (path to the file to outline) are conveyed only implicitly.

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?

Names a specific verb+resource: an indented outline (functions, classes, interfaces with line spans) of a JS/TS file. It distinguishes itself from siblings like symbol_info and search_symbol by describing a whole-file structural view rather than a named-symbol lookup.

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?

Gives clear context for use ('so you can navigate without reading it in full') and routes to follow-ups (hover/definition/references at a listed line, or symbol_info by name). It does not state an explicit when-not-to-use case, but the alternative-tool routing is concrete.

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 full burden. It adds genuine behavioral detail: the cross-file index path for CSS custom-properties/id/class tokens and the per-root scoping limit with a same-root fallback. But it omits general behavioral facts such as read-only nature, whether declarations are included by default, or result/ordering behavior, so it is only partially complete.

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 core action is front-loaded in the first sentence, and the dense second paragraph is devoted to non-obvious positional and routing details rather than filler. It is somewhat information-packed but each clause 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?

For a position-based query tool with no annotations and no output schema, the description covers the risky part (coordinate semantics and special-case routing) but leaves the include_declaration flag unexplained even though it directly affects the result set. Adequate but with a clear visible 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 coverage is 0%, so the description must compensate. It does this well for line/column (1-indexed, UTF-16 offset, tab counts as one character), which is high-value semantics absent from the schema. However include_declaration and file_path receive no explanation, leaving two of four parameters 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?

States a concrete verb+resource+scope: "Find all usages of the symbol at a position across the workspace." An agent can distinguish this from definition or hover. It does not, however, contrast itself against close siblings like callers or implementations, which also report usage-like relationships.

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 usage (find usages when you have a position) but never states explicit when-to-use/when-not versus callers, implementations, or definition. It does give one routing rule — CSS/HTML tokens resolve via the cross-file index rather than the single-file language server — but general selection guidance is absent.

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 full burden and does disclose non-obvious traits: results are capped, production code ranks before tests, fuzzy non-containing hits are collapsed to a count unless `fuzzy=true`, and positions use the shared character-offset column convention. It stops short of stating the cap size or the read-only/safety profile, so it is strong but not exhaustive.

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?

Dense but front-loaded: purpose and language scope come first, then alternatives, then parameter behavior. Every sentence carries information, though the middle is packed with several distinct concerns in a row.

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 5 undocumented parameters, no annotations, and no output schema, the description supplies enough for correct invocation and even describes the return shape (identifier positions, SymbolKind label, caps). The absence of an explicit cap value or safety statement is the only 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, and it largely does: `name` is documented as an alias for `query`, `kind` takes comma-separated SymbolKind labels with examples, `path` accepts a workspace-relative prefix or glob, and `fuzzy` controls listing of loose hits. Only the exact cap/semantics of an unbounded `query` remain unspecified.

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?

States a specific verb and resource ('Search JS/TS files for a symbol by name') and enumerates the symbol kinds it matches. It clearly delimits itself from the sibling symbol_info, which an agent would otherwise confuse with this search tool.

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 'Prefer `symbol_info` for a one-call summary', declares the JS/TS-only restriction and why (HTML/CSS language servers lack workspace-wide search), and tells the agent how to narrow queries with `kind` and `path`. When-to-use, when-not-to-use, and the alternative are all 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?

With no annotations, the description carries the full disclosure burden and does so well: it enumerates exactly what is scanned, how special cases are labeled ('[generated]', 'string literal', 'dynamic partial match'), and how env vars (WEBNAV_MCP_EXCLUDE, WEBNAV_MCP_ROOTS) affect coverage. It never explicitly states the operation is read-only or describes result ordering beyond 'grouped by file', leaving a small gap for a no-annotation tool.

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

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

Front-loaded with the one-line answer and example before the detail, and every sentence is information-dense rather than filler. The two trailing sentences on dynamic partial matching are heavy relative to their importance, but they describe genuine edge-case behavior an agent would otherwise misread.

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 no annotations and no output schema, the description is nearly self-sufficient: it explains what is searched, how hits are labeled, and how they are grouped. The one thing left open is the concrete response shape (field names/structure of the returned hits), which it only describes prose-wise.

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 compensate, and it does: it mandates the leading '#' or '.', gives a worked example, and explains that 'query' is an alias for 'name'. It does not clarify that one of the two must actually be supplied (required count is 0), so the requiredness question remains ambiguous.

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 opening sentence states a specific verb and resource ('Who uses this #id or .class?') and immediately clarifies scope by listing what it cross-references (CSS rules, HTML id/class attrs, JS usages). It also explicitly carves itself out from the sibling single-file CSS/HTML language servers, so an agent can tell it apart without opening a schema.

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 clear context: workspace-wide lookup that the single-file CSS/HTML language servers cannot perform, which implies when to reach for it. However, it never names its actual siblings (references, css_var, search_symbol) or states an explicit when-not condition, so the guidance stops short of full routing.

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 full burden and does disclose the composite nature of the call (it fuses hover, definition, and references into one response and groups references by file), which is genuinely useful behavioral context. It stops short of saying whether the lookup is strictly read-only, how ambiguity or zero-match cases are handled, or whether results are truncated.

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, front-loaded with the core purpose and a concrete call example before the routing advice. The "What is X and where is it used?" framing and the example are mildly redundant with the following sentence, but nothing is wasted overall.

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?

There is no output schema, so the description appropriately enumerates the return contents (header, hover, definition, references grouped by file), and it covers the sibling routing an agent needs. It is only slightly thin on ambiguity behavior and the undocumented include_references flag.

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 for four bare parameters. It explains that query is an alias for name and that file_path disambiguates a match, but it never mentions include_references (or its default true) or the expected string form of name beyond the example, so half the parameters remain 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 gives a specific verb-and-resource framing ("One-call summary for a JS/TS name") and enumerates exactly what is returned: header, hover text, definition, and references grouped by file. It explicitly contrasts itself with the sibling chain search_symbol → hover → definition → references and with css_var/selector, so an agent can place it without opening any schema.

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 states when to use it ("the usual first lookup") and what it replaces, and gives explicit when-not guidance by routing CSS/HTML cross-file lookups to css_var / selector. It also names the disambiguation condition for file_path, leaving nothing to inference.

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 full behavioral burden. It does disclose the conceptual output (which directory, plus a reason), which is useful, but says nothing about safety, determinism, or whether it inspects git worktrees versus plain directories. Zero-parameter and clearly read-only by nature, yet that is inferred rather than stated.

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 short sentences with no filler, and the 'which directory' framing is front-loaded ahead of the usage trigger. The rhetorical-question style is slightly indirect for a tool definition, which keeps it from a 5.

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 zero-param read tool with no output schema, the description should clarify the shape of the answer. It gestures at 'which directory ... and why' but never specifies what 'why' means (git worktree, symlink resolution, config), leaving the agent to discover the return semantics by calling 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 takes zero parameters and schema description coverage is reported at 100%, so there is nothing for the description to compensate for. Baseline 4 applies for a parameterless tool.

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 gets at the resource (the directory webnav is operating in) and hints at an explanatory payload ('and why'), but it is phrased as a rhetorical question rather than a statement of a verb+resource. The noun-only name 'workspace' does not disambiguate against code-navigation siblings like outline or diagnostics. An agent can infer it reports the active workspace root, but only with effort.

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 a concrete trigger: 'Use when results look like they come from the wrong checkout/worktree.' That is a clear when-to-use condition tied to a real failure mode of the sibling navigation tools. It names no alternative (e.g., diagnostics) and gives no when-not-to-use, so it falls short of a 5.

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