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

No annotations are provided, so the description carries the full behavioral burden and delivers almost none of it: it does not say whether files are read from disk, whether an index must exist first, how large the markdown output can get, or how maxFiles truncation behaves. The only disclosure is the output format (markdown) and the source-file restriction.

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?

One sentence with zero padding and the key noun front-loaded, so it is structurally efficient. However, the brevity is under-specification rather than conciseness, since the sentence omits information the agent needs to call the tool correctly.

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?

This is a complex tool — nested union parameter with two search modes, enum-constrained detail, path list, file cap — with no annotations, no output schema, and 0% parameter documentation. A single nine-word sentence is nowhere near sufficient for an agent to select or invoke it 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% across 4 parameters, including a nested indexedSearch union with two modes (symbols/references), a detail enum, paths, and maxFiles. The description adds no meaning for any of them — no explanation of what "detail" controls, how paths interacts with indexedSearch, or how maxFiles caps results — so an agent must reverse-engineer intent from raw JSON 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 names a verb ("Build") and a resource ("markdown context"), plus a scope restriction ("supported source files"), but "context" is left undefined — it is unclear whether this aggregates file contents, symbols, or index hits. It also offers no differentiation from siblings like summarize_file or search_symbols that plausibly produce similar output.

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 when-to-use guidance at all: nothing says when this beats summarize_file, search_symbols, or find_references, nor what conditions (e.g. needing indexed search results in markdown form) should select it. The only hint is the implicit constraint of "supported source files."

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 the full burden. It does usefully disclose the object being destroyed (the SQLite index file, not source data), but says nothing about reversibility, whether the index rebuilds automatically, or the consequences of a stale/empty index.

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 front-loaded sentence with no filler. Every word earns its place and the action is unambiguous.

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, no-output-schema tool this is minimally viable, but as a destructive operation with no annotations the description should say what state the agent is left in (e.g., index must be rebuilt) to be 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?

The tool takes zero parameters, so there is nothing for the description to clarify beyond what the empty schema already shows. Baseline 4 applies for a no-parameter 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?

States a specific verb+resource: 'Delete the SQLite workspace index file.' An agent can distinguish this from siblings like index_workspace (builds) or get_index_status (reads) without opening the schema, though no sibling is named explicitly.

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 when-to-use guidance is given. It does not say when clearing the index is appropriate versus simply re-running index_workspace, nor whether re-indexing is required afterward. The usage context must be inferred entirely.

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 the full behavioral burden. It does not disclose whether the search is LSP-backed or index-backed, what 'supported source files' includes, how results are formatted, or any performance or scope limitations.

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, front-loaded sentence with no filler or repetition. It is appropriately sized, though its brevity contributes to under-specification elsewhere rather than serving as a standalone strength.

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, no output schema, and 0% parameter coverage, the description is too sparse for reliable invocation. It omits language scope, result shape, and distinctions from sibling definition tools.

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 all three parameters. The description only loosely implies the 'name' and 'paths' parameters ('by name', 'across supported source files') and says nothing about the 'kinds' enum or path semantics, so it does not compensate for the missing schema 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?

States a clear verb and resource ('Find symbol definitions') plus scoping ('by name across supported source files'). However, it does not differentiate itself from sibling tools such as lsp_definition or find_indexed_definition, leaving the agent to guess which definition-finding tool to use.

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 when-to-use or when-not-to-use guidance is given. The description does not mention alternatives (lsp_definition, find_indexed_definition) or any prerequisites, so the agent must infer when this search-based tool is preferable.

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 does disclose two useful traits: results come from a local SQLite index (implying potentially stale, non-live data) and each hit includes a code snippet. However, it omits staleness handling, the existence of refreshIfStale/clear_index flows, and match semantics, so the behavioral picture is only partially painted.

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 front-loaded sentence with no filler; the scope (index source) and payload (snippets) come in the right order. It is arguably too terse for a 7-parameter tool, but nothing in it 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?

Seven parameters, no annotations, no output schema, and no parameter documentation leave substantial gaps for a tool whose behavior depends on index freshness and filtering options. The description is not sufficient on its own for an agent to call it confidently.

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?

Seven parameters with 0% schema description coverage, and the description explains none of them. 'Exact' hints that name matching is literal and 'with snippets' loosely maps to includePreview, but kinds, limit, contextBefore/After, and refreshIfStale are entirely undocumented anywhere, so the agent must infer their behavior.

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 and resource (find exact symbol definitions) plus the data source (SQLite workspace index) and a return trait (snippets). It is clear in isolation, but it never differentiates itself from close siblings like find_definition, lsp_definition, or lsp_workspace_symbols, leaving the agent to guess why the indexed variant should be chosen.

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 when-to-use guidance, no prerequisites (e.g. that the index must first be built via index_workspace or refreshed), and no mention of the many alternative lookup tools in the sibling list. The agent receives no routing signal beyond the word '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 discloses that results come from a SQLite index and include snippets, but says nothing about index staleness (even though a refreshIfStale parameter exists), pagination, or what happens when no index is built — significant gaps for a search tool.

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

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

A single tight sentence with no waste, front-loading the verb and resource. It is well-structured, though it is concise at the cost of the missing behavioral and parameter detail.

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 6-parameter tool with no annotations, no output schema, and zero parameter documentation, the description is far too thin. An agent cannot know how to bound results or control snippet context without opening the raw 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 description coverage is 0% across 6 parameters. The description only implies the 'name' input and the presence of 'snippets', leaving limit, contextBefore, contextAfter, and refreshIfStale completely undocumented in both schema and description.

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 (Find) and resource (identifier references), and adds the source ('SQLite workspace index') plus that results include snippets. This distinguishes it from the LSP-based siblings, but it never explicitly names find_references or lsp_references as the alternatives an agent should choose between.

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 when-to-use or when-not guidance. The phrase 'from the SQLite workspace index' hints that this is the indexed counterpart to the LSP tools, but nothing tells the agent when to prefer the index over live LSP references, nor mentions index prerequisites.

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 the full behavioral burden, and it omits essentials: whether the operation is read-only, whether it requires a pre-built index, how results are returned or paginated, and how unresolved names are handled. 'Across supported source files' hints at scope but nothing about 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 tight sentence with no filler and the key constraint (by name) front-loaded. It is efficient, though the brevity is partly under-specification rather than disciplined concision.

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 lookup tool with two undocumented required parameters, no output schema, no annotations, and several near-identical siblings, the description leaves too much open: result shape, index prerequisites, and why this tool over the alternatives are all 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 both required parameters, so the description must compensate but does not. 'By name' loosely maps to the name param and 'source files' loosely to paths, but there is no format guidance (plain identifier vs qualified name, single file vs directory) for either.

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 ('Find identifier references') plus scope ('by name across supported source files'), so the core action is unambiguous. However, it never distinguishes itself from close siblings like lsp_references or find_indexed_references, leaving the agent to guess which reference-finder to pick.

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 when-to-use guidance and no alternative named, despite four other reference/definition siblings in the toolset. The agent gets no signal about whether this is the indexed variant or the live-LSP variant, or when this is preferred.

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, yet it only discloses that output is 'depth-limited' and applies to 'one supported source file'. It does not say which languages are supported, what happens on an unsupported file, or whether large files 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?

A single front-loaded sentence with no filler; the key artifact and constraint lead. It is arguably too sparse rather than bloated, but the sentence itself 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 3-parameter tool with 0% schema coverage, no annotations, and no output schema, the description leaves too much unspecified. An agent lacks the supported-language list, default depth, and the meaning of includeText needed to call it reliably.

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 all three parameters. 'Depth-limited' loosely gestures at maxDepth and 'one source file' at path, but includeText is never mentioned, and no defaults, units, or formats are given.

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'), a specific artifact ('tree-sitter AST'), and a scope ('one supported source file'). No sibling tool returns a raw AST, so the agent can distinguish it, though it never explicitly contrasts itself with the symbol/summary tools it could be confused with.

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 statement of when to reach for this tool versus siblings like summarize_file, list_symbols, or lsp_document_symbols, nor any prerequisites. The agent must infer usage entirely 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?

No annotations are provided, so the description carries the full burden. It implies a non-destructive read by describing counts returned, but says nothing about behavior when no index exists, error modes, or the cost of the call, and it never explains the stale-reason parameter.

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 front-loaded sentence with no filler; the returned fields are listed compactly. Slightly list-like, but nothing 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?

With no output schema, no annotations, and an undocumented boolean parameter, the description partially compensates by enumerating the return fields. It leaves the parameter and failure behavior unexplained, so it is adequate but incomplete.

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?

There is one parameter (includeStaleReasons) with 0% schema description coverage, and the description never mentions it. The phrase 'stale file count' hints at staleness but does not explain what the flag does or what it changes in the response.

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 ('Return') and resource ('SQLite index'), then enumerates the exact payload (index path, indexed file count, symbol count, stale file count). This clearly separates it from mutating siblings like index_workspace and clear_index, though it never names an alternative explicitly.

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 statement of when to call this tool versus alternatives such as index_workspace (to build) or clear_index (to reset), and no prerequisites or exclusions. Usage is only inferable from the 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?

With no annotations, the description carries the full behavioral burden. It does disclose two useful traits: the operation is idempotent-ish ('build or refresh') and it is workspace-wide, not per-file. However, it says nothing about cost/duration for a potentially long-running whole-workspace index, nor whether it blocks or what the caller should expect afterward.

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?

One sentence, front-loaded with the action, with no filler. Every clause adds information (build vs refresh, index type, 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?

For a zero-parameter tool this is close to sufficient, but with no annotations and no output schema there is nothing telling the agent how long it runs, whether it is safe to repeat, or what (if anything) it returns. A brief note on duration or the resulting index state would close the 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?

The tool takes zero parameters, so the baseline is 4. The description correctly implies there is nothing to configure and that the scope is fixed to 'all supported source files'.

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 pair (build/refresh) and a concrete resource (the SQLite symbol index), plus scope (all supported source files). An agent can distinguish it from siblings like get_index_status or clear_index by action, though the description never names an alternative to reinforce that contrast.

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 when-to-use guidance, no prerequisites, and no routing to the obvious siblings (get_index_status to check state, clear_index to reset). The agent must infer that this is the 'do the indexing' step purely from the 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?

No annotations are provided, so the description carries the full behavioral burden. It hints at scope ('top-level' rather than nested, one file) but says nothing about return format, error behavior for unsupported file types, or what 'supported' languages are.

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 front-loaded sentence with no filler, appropriately sized for a one-parameter tool. It is efficient, though so terse that the brevity borders on under-specification rather than tightness.

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, no output schema, and an undocumented parameter, the description is too thin. It leaves unclear what a 'symbol' is, how results are ordered/shaped, or how it differs from the numerous sibling symbol-listing tools.

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 single 'path' parameter has no schema description. The phrase 'one supported source file' loosely implies path targets a source file, but format (absolute vs relative), language constraints, or expected inputs are never clarified.

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 (List) and resource (top-level symbols) with a clear scope constraint (one supported source file). However, it does nothing to distinguish itself from siblings like lsp_document_symbols or search_symbols, which an agent would reasonably confuse it with.

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 on when to use this versus the many sibling symbol tools (lsp_document_symbols, search_symbols, lsp_workspace_symbols). The only hint is the implicit 'one file' scope, with no conditions, alternatives, or prerequisites 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?

With no annotations, the description carries the full behavioral burden. It usefully discloses one trait — that positions are zero-based LSP coordinates and completion is scoped to the prefix before the cursor — but says nothing about indexing requirements, whether the result is ranked/fuzzy, how limit truncates, or why 'workspace' symbol completion differs from document completion. That is a thin disclosure for an unannotated 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?

One sentence, front-loaded with the verb and resource, no filler or redundancy. It is efficiently written, though its brevity reflects under-specification rather than tight editing, so it does not merit 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 6-parameter, 0%-schema-coverage tool with no annotations and no output schema, the single sentence leaves major gaps: what completion items contain, how kinds/paths/limit behave, and any index prerequisites. An agent could call it, but only by guessing at half the 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 description coverage is 0% across 6 parameters, and the description only illuminates the three required ones implicitly (path + zero-based line/character). The optional kinds, limit, and paths parameters are completely undocumented anywhere — no filter semantics, no default, no cap rationale for limit's 500 maximum. The description fails to compensate for the coverage 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?

States a specific verb (Return) and resource (workspace symbol completion items) and pins the trigger to the prefix before a zero-based LSP position. It is distinguishable from siblings like lsp_hover or lsp_definition by the word 'completion', but it never explicitly contrasts itself with lsp_signature_help or lsp_workspace_symbols, which are the nearest 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?

No when-to-use guidance at all. The description does not say when an agent should prefer completion over lsp_workspace_symbols, lsp_document_symbols, or lsp_signature_help, nor does it state any prerequisite such as the file being indexed or open. The caller has to infer the intent entirely.

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 supplied, so the description carries the full behavioral burden, and it does almost none of it. It implies a read operation via 'Return', but says nothing about whether an LSP server must be running, what happens when no definition exists, or what the returned locations contain.

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 front-loaded sentence with no filler; the essential information (verb, result, coordinate convention) comes first and nothing 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?

With no output schema and no annotations, the description should explain the shape of returned locations (URI + range) and the live-LSP requirement, and it should disambiguate against find_definition/find_indexed_definition. It also leaves one of four parameters (paths) undocumented, so it is not sufficient for correct 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% for 4 parameters, yet the sentence does add real meaning: it clarifies that line/character are a zero-based position and that they locate an identifier in a file. It does not explain the 'paths' array parameter or its relationship to the singular 'path', leaving a genuine gap at low coverage.

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 ('Return definition locations') and resource ('identifier') and even pins down the coordinate semantics ('zero-based LSP position'). However, it does not differentiate itself from the closely related siblings find_definition and find_indexed_definition, so an agent cannot tell from the text alone which lookup path this one uses.

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 when-to-use or when-not-to-use statement, and the crowded sibling list (find_definition, find_indexed_definition, lsp_references) makes routing ambiguous. The 'zero-based LSP position' phrasing only faintly implies live-server usage; no prerequisite (e.g. an initialized LSP session) is 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?

With no annotations, the description carries the full burden, but it does disclose one genuinely useful behavioral trait: results come from tree-sitter parse errors and are 'lightweight,' implying no type or semantic diagnostics. It stops short of stating prerequisites (must the file be open/indexed?), whether it reads from disk, or the return shape.

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 tight sentence with the key qualifier ('lightweight', 'tree-sitter parse errors') front-loaded and no filler. Nothing is wasted, though there is very little content to structure.

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 annotations, no output schema, and an undocumented parameter leave real gaps: the agent does not know the diagnostic format (line/column/severity), whether it is limited to parse errors versus lint or type errors, or any path constraints. For a diagnostics tool this is 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 single 'path' parameter is never mentioned in the description. It does not say whether the path is absolute or relative, whether it must point to an indexed file, or whether directories are accepted, so the description does not compensate for the coverage 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?

States a specific verb ('Return') and resource ('syntax diagnostics'), and qualifies the source as tree-sitter parse errors rather than full LSP analysis. This is clear and self-contained, but it never names or contrasts with any sibling tool, so an agent gets no explicit differentiation signal beyond the name.

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 when-to-use or when-not-to-use guidance. The agent must infer that this is the syntax-error tool and guess how it relates to siblings like get_ast_tree, run_query, or lsp_document_symbols; nothing in the text routes 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?

No annotations are provided, so the description carries the full behavioral disclosure burden. It mentions the return shape ('ranges and kinds') but omits whether this is a read-only operation, whether it touches disk or an LSP server, error behavior for missing/invalid paths, and any performance or caching characteristics. This is a significant gap 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?

The description is a single, front-loaded sentence with no filler. It is appropriately sized for the limited information it conveys, though its brevity comes at the cost of completeness rather than being an intentional structural choice.

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, no output schema, and no parameter documentation, the description is too thin for correct invocation. It does not explain how the path parameter is used, how results relate to the LSP protocol, or how to choose this tool over the many symbol-related siblings.

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?

There is one required parameter ('path') with 0% schema description coverage. The description does not mention the path parameter at all or explain what it should point to (file? workspace? language-specific path?). The tool name implies a document, but the description fails to compensate for the schema coverage 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 gives a specific operation: return tree-sitter symbols converted to LSP DocumentSymbol ranges and kinds. However, it does not distinguish this tool from siblings like lsp_workspace_symbols, list_symbols, or search_symbols, nor does it state that it operates on a single document/file. An agent can infer the general purpose but not exactly when this tool is the right choice.

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 guidance, no alternatives mentioned, and no prerequisites or exclusions. The description only states what is returned, leaving the agent to infer the appropriate context from the tool name and other 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?

With no annotations, the description carries the full behavioral burden, but it does disclose the two most useful traits: the return payload is markdown hover content and positions are zero-based. It says nothing about what happens when no hover exists at that position, whether the file must be open/indexed, or error conditions.

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 tight sentence with the action and the coordinate semantics front-loaded. Every word earns its place and there is no 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?

For a 4-parameter tool with 0% schema coverage, no annotations, and no output schema, the description is too thin: it omits the path/paths semantics and any failure behavior. The agent cannot confidently construct a correct call from this alone.

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 clarifies that line/character are zero-based LSP coordinates, which is genuinely useful, but it completely ignores the path vs. paths distinction — path is required while paths is optional and undocumented, leaving a real ambiguity unresolved.

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 markdown hover contents") and pins the target down to "the identifier at a zero-based LSP position". That is enough for an agent to tell it apart from lsp_definition or lsp_references, though it never names a sibling explicitly to sharpen the distinction.

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 when-to-use guidance, no condition that selects hover over lsp_definition/lsp_signature_help, and no mention of prerequisites. The agent must infer usage purely from the tool 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?

With no annotations, the description carries the full behavioral burden. It conveys the positional convention (zero-based LSP position) but says nothing about what is returned (declarations included? cross-file?), whether an LSP server must be running, or how the optional paths parameter changes 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 tight sentence with no filler, and the key scoping detail (position-based lookup) is front-loaded. Efficient, though minimal.

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 annotations, no output schema, and 0% parameter documentation leave the description too thin for a 4-parameter tool with several near-duplicate siblings. An agent lacks enough information to call it correctly or route to it over find_references.

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 4 parameters. The description alludes to an identifier position (implying line/character/path) but never explains the required path/line/character semantics or the purpose of the extra optional 'paths' array, which is undocumented everywhere.

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 (return) and resource (reference locations) scoped to an identifier at a position, so the core operation is unambiguous. However, it gives no signal distinguishing it from close siblings like find_references and find_indexed_references, nor does it explicitly contrast with lsp_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?

There is no guidance on when to choose this tool over find_references, find_indexed_references, or lsp_definition. No prerequisites (e.g., LSP server availability, file open state) are mentioned.

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 notes the zero-based LSP position convention, which is useful, but says nothing about required LSP server state, what happens when the cursor is not inside a call (likely empty result), or whether this is a pure read with no side effects.

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 front-loaded sentence with no filler or redundancy. It is efficient, though its brevity is partly a symptom of under-specification rather than disciplined editing.

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 4-parameter tool with 0% schema coverage, no annotations and no output schema, one sentence is not enough. Missing: path vs paths semantics, LSP server prerequisites, and expected behavior when no call is at the position.

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 4 parameters, so the description must compensate. It only clarifies that the position is zero-based (helping line/character) and never explains the crucial ambiguity between the required 'path' and the optional 'paths' array, leaving a real risk of incorrect invocation.

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+resource ('Return signature help') and scopes it to 'the active call', which is more precise than a generic hover. It does not, however, differentiate itself from the very similar siblings lsp_hover and lsp_completion, so an agent must infer which to pick.

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 when-to-use guidance, no stated prerequisites (e.g. a running LSP server), and no mention of alternatives despite a crowded sibling set (lsp_hover, lsp_completion, lsp_definition). The phrase 'active call' hints at context but does not tell the agent when this beats lsp_hover.

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 the full burden. It adds one behavioral detail (case-insensitive matching) but omits whether the operation is read-only, how results are returned, whether it searches the entire workspace, or any performance or permission considerations.

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, front-loaded sentence with no filler. Every word contributes to the stated purpose, and nothing is repeated unnecessarily.

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-parameter tool with no annotations and no output schema, the description is far too thin. It omits what the 'kinds' and 'paths' filters do, what the returned symbols look like, and any behavioral caveats an agent would need to invoke 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?

Schema description coverage is 0%, so the description must compensate. It explains only the 'query' parameter's case-insensitive nature; the 'kinds' and 'paths' parameters receive no explanation at all, leaving most parameter semantics 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 specific verb ('Return'), resource ('workspace symbols'), and scope ('workspace'), plus query semantics ('case-insensitive'). It does not explicitly distinguish itself from siblings like list_symbols or search_symbols, so it stops short of a 5.

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 when-to-use, when-not-to-use, or alternative guidance. It does not tell the agent when to prefer this over lsp_document_symbols or search_symbols. There is only an implied usage, with no contextual 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 provided, the description carries the full behavioral burden. It discloses only the single-file constraint; it says nothing about return format, error behavior when the file is unsupported, or what 'supported' means. For a tool with zero annotation coverage this is a substantial 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?

A single, front-loaded sentence with no filler or repetition. It is appropriately sized, though its terseness is part of why other dimensions are thin.

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 0% parameter documentation, no annotations, and no output schema, the description should carry more context. It omits query syntax, supported languages, and return format, so an agent cannot reliably call this tool without prior knowledge.

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 neither parameter is described in the schema. The description adds only that the query runs against 'one supported source file' for the path, and gives no syntax or semantics for the tree-sitter query itself. It does not compensate for the coverage 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?

States a specific verb and resource ('Run a tree-sitter query') and scopes it to 'one supported source file', which is clear enough for an agent to know what the tool does. However, it offers no differentiation from the closest sibling get_ast_tree, which also operates on tree-sitter output, so it doesn't fully earn a 5.

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 when-to-use guidance, no alternatives, and no exclusions. It implies a single-file constraint via 'one supported source file' but never tells the agent how this differs from get_ast_tree or the LSP siblings, leaving selection 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 burden. It implies a read-only search against an index, but says nothing about index staleness, whether a refresh occurs, rate limits, or the shape/size of results. The existence of a refreshIfStale parameter hints at staleness handling, but the description never explains it.

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 tight sentence with no filler, which is structurally clean and front-loaded. But it is terse to the point of under-specification rather than genuinely economical given the tool's complexity.

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 7-parameter search tool with no annotations, no output schema, and full schema-description gaps, this one-liner is inadequate. It gives no return-value expectations, no pagination/limit behavior, and no guidance on index freshness, leaving significant gaps an agent must fill by trial and error.

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?

Seven parameters with 0% schema description coverage, and the description adds no semantics for any of them. The query matching behavior, the meaning of the kinds enum, limit bounds, contextBefore/After, includePreview, and refreshIfStale are all 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?

States a specific verb (search) and resource (symbols) scoped to the 'SQLite workspace index', which does gesture toward the indexed-vs-LSP distinction among siblings. However, it never names or differentiates itself from close siblings like lsp_workspace_symbols, list_symbols, or find_indexed_definition, so an agent cannot pick confidently 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?

There is no when-to-use guidance, no prerequisites, and no mention of the many available alternatives (lsp_workspace_symbols, list_symbols, get_index_status). The agent is left to infer usage entirely.

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 the full behavioral burden. It implies a read-only summarization but never states that nothing is mutated, what happens on a missing or binary file, whether results are cached, or anything about error behavior, leaving key behavioral traits undisclosed.

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 tight sentence that front-loads the verb and enumerates the output fields with no filler. It is appropriately sized for a simple tool, though the enumeration could have been used to also convey usage or path semantics.

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 low-complexity (one param, no nested objects) and the description does enumerate the returned summary fields, which partially substitutes for the absent output schema. However, with no annotations and no path semantics, it leaves real gaps an agent would need filled.

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 1 parameter at 0% schema description coverage, the description must compensate but does not. It says "one file" but gives no meaning to the path argument (relative vs absolute, project-root resolution, file-type expectations), so an agent gets no more than the parameter name implies.

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 ("Summarize") and resource ("one file") and enumerates what is summarized (language, line count, imports, exports, symbols). This distinguishes it somewhat from pure symbol-listing siblings like list_symbols or lsp_document_symbols, but it never explicitly names or contrasts those siblings, so it falls short of a 5.

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 when-to-use guidance, no prerequisites, and no named alternatives. The phrase "for one file" hints at per-file scope versus workspace-level siblings, but this is left implicit rather than stated as a usage condition.

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