LazyVerilog MCP

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

No annotations are provided, so the description carries the full burden. 'Run' implies a mutating operation, and the schema's `preview` flag documents a write-free mode, but the description never states that files on disk are modified by default, nor what happens on an ambiguous prefix match or when no action is available at that line.

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 sentence with the action, the discovery source, and the matching rule all front-loaded; nothing is wasted and there is no preamble.

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 five-parameter mutation tool with no annotations and no output schema, the description omits what comes back (the resulting edit, a diff when previewing, or an error) and whether multiple prefix matches are rejected. It covers the call mechanics adequately but not the outcome.

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 80% and mostly self-documenting, so the baseline is 3. The description earns above that by supplying semantics the schema lacks for an undescribed parameter: `title` is matched by prefix against the `code_actions` output, and its value must be paired with a 1-based line in the file.

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 ('Run') plus resource ('the code action'), and anchors it to a named sibling ('from code_actions'), so the agent knows this is the execution half of a discover-then-apply pair. It does not explicitly distinguish itself from action-applying siblings such as rename_symbol, which is why it stops short of 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?

Gives a clear workflow cue: the `title` value must come from `code_actions`, and prefix matching is acceptable. There is no guidance on when to avoid this tool (e.g. use rename_symbol directly, or format_file for formatting-only actions), so it lacks explicit exclusions.

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

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

With no annotations, the description must carry the full behavioral burden; it does convey the key trait that this only lists actions while apply_code_action performs them. However it says nothing about side effects, failure modes, or whether the listing depends on index/LSP readiness, and the trailing "..." leaves the action set open-ended.

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 dense, front-loaded sentence pair with the core operation first, examples second, and the hand-off to the sibling last. The informal "..." after the action list is the only loose element.

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, yet the description never states what a listed action looks like or how an action is identified when passed to apply_code_action (by name? index?), which is exactly the hand-off the agent needs. It is otherwise adequate for a three-parameter read tool.

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

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

Schema coverage is 100%, so the baseline is 3, and the description adds genuine meaning on top: it tells the agent which line kinds yield which action (instantiation line, module header, always_ff) and that `symbol` disambiguates by placing the cursor, with an example (module name of an instance).

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 ("List RTL code actions") scoped to a line in a file, and its examples (AutoInst, AutoArg, AutoFF) make the resource concrete. It is unambiguously the read/query counterpart to apply_code_action, so an agent can tell it apart from every sibling.

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 routes the follow-up step ("Run one with apply_code_action") and hints at positioning with "Pass `symbol` to place the cursor on it." It gives clear context for use but no exclusions or preconditions (e.g., what happens if no actions exist at that line).

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 disclosure burden, yet it says nothing about read-only nature, output format/structure, size limits, or behavior on unparseable files. It does at least disclose that line numbers accompany each symbol, which is useful return-shape information beyond the schema.

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

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

A single front-loaded sentence that gets to the symbol list quickly with no filler. The trailing 'functions...' ellipsis is slightly vague and hints the list is incomplete, but the overall economy is good.

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 simple one-parameter read tool with no output schema, the description should convey the returned structure more fully. Listing symbol kinds and line numbers helps, but the ellipsis and the absence of any statement about output shape (flat list vs nested hierarchy) leave the agent guessing.

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 one parameter and 100% schema description coverage, the schema already documents that 'file' is a SystemVerilog path absolute or workspace-relative. The description adds nothing about the parameter, so the baseline of 3 applies.

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 the resource (a file) and the specific content returned (modules, ports, signals, parameters, instances, functions) plus line numbers, so the agent knows it is a per-file symbol outline. It does not distinguish itself from sibling workspace_symbols, which appears to cover a similar symbol-listing role.

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 use this tool versus alternatives; the closest sibling, workspace_symbols, is never mentioned. The only implied guidance is that it operates on a single file, which an agent must infer from the phrase 'of a file'.

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 project-wide scope (not file-local), but never states that it is a read-only operation, what the result set looks like, or whether the declaration itself is included by default.

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 zero filler and the scope qualifier placed at the end where it reads naturally. It is tight, though arguably too terse for a 5-parameter tool.

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 and no annotations, so the description is the only source of behavioral context, and it omits return shape and the meaning of `include_declaration`. Adequate to call the tool, but not complete for interpreting results.

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 80%, so the schema largely documents the parameters, and the description merely restates the file/line/symbol mapping. It adds nothing about `occurrence` or the undocumented `include_declaration`, which are the parts an agent would most need explained.

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 and resource ('List every reference to `symbol`') and anchors it to a location. An agent can distinguish it from goto_definition (which finds the declaration) and rename_symbol, though it never states that contrast 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 when-to-use or when-not-to-use guidance and no mention of alternatives such as goto_definition, document_symbols or rename_symbol. The only usable hint is the implicit 'across the project' scope, leaving the agent to infer that this is a find-usages operation.

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 must carry the full behavioral burden. It mentions config-driven formatting and optional line ranges, but does not disclose that formatting writes to the file, does not mention the preview mode, permissions, idempotency, or what happens on failure. These are significant gaps for a mutation tool with zero annotation coverage.

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

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

Two tightly written sentences with no wasted text. The primary action and config source are front-loaded, followed by the optional range behavior.

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

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

The description covers the core action and range formatting, and the schema covers all parameters. But with no annotations and no output schema, it should also explain the write side effect and preview behavior. It is adequate but leaves important behavioral context to the schema 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 100%, so the schema already documents file, preview, start_line, and end_line. The description reinforces that start_line/end_line are 1-based and inclusive, which adds minor value. Baseline 3 is appropriate when the schema does the heavy lifting.

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: formatting a file according to lazyverilog.toml [format] rules. It clearly distinguishes the operation from sibling tools like lint, rename_symbol, or code_actions. No explicit sibling differentiation is needed here, but it is also absent.

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

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

The description explains how to limit formatting to a line range with start_line/end_line, which is useful usage guidance. However, it gives no explicit when-to-use vs when-not-to-use guidance, nor does it mention alternatives for broader formatting or preview workflows.

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. 'Find' implies a read-only lookup, which is correct and useful, but it does not state the return shape (a location? a list?), behavior when the symbol has no declaration, or whether unresolved symbols error or return empty.

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 sentence with zero filler, and the essential qualifier (the symbol's written position) is front-loaded inside the same sentence. Nothing could be removed without losing meaning.

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

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

For a simple read-only lookup with complete schema coverage and no nested objects, the description covers all three required inputs. The main gap is the absent output schema combined with no statement of what the result looks like, which an agent must discover at call time.

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

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

Schema description coverage is 100%, so file/line/symbol/occurrence are already fully documented in the schema, setting the baseline at 3. The description's parenthetical restates the schema's meaning of file/line/symbol without adding detail, and never mentions the optional `occurrence` parameter.

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?

Specific verb (find) with a precise resource (the declaration site of `symbol`) and the exact input framing (as written on `line` of `file`). The word 'declared' implicitly separates it from find_references, but 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?

Usage is implied by the tool's semantics: supply the exact symbol text at a known position and get its declaration. However, there is no stated when-to-use vs. find_references/hover guidance, and no note about prerequisites (e.g., file must be indexed/parseable).

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. 'Show' implies a safe read, but it does not state prerequisites (e.g., an active language server), behavior when no symbol is found at the position, or what the response contains.

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 verb and resource front-loaded and zero filler. It is efficient, though the brevity leaves gaps handled in other dimensions rather than here.

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

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

For a read-only position query with full schema coverage and no output schema, the description is minimally adequate. It hints at the return content ('type/declaration info') but does not cover empty-result behavior or confirm what is returned.

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

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

Schema description coverage is 100%, so file, line, symbol, and occurrence are already fully documented in the schema. The description only restates the three required parameters and adds no format or semantics beyond them, so the baseline 3 applies.

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 ('Show') and resource ('type/declaration info') scoped to a symbol at a line in a file, which an agent can distinguish from goto_definition or find_references. It does not explicitly name the sibling it is not, 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 statement of when to use this tool versus alternatives like goto_definition or document_symbols, nor what it does when the symbol cannot be resolved. The only guidance is implied by 'type/declaration info'.

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 diagnostic categories and the exact output line format with 1-based coordinates, but it does not explicitly confirm the operation is read-only/non-mutating, describe error behavior for missing files, or mention any lint configuration.

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 tightly written sentences: the first front-loads the purpose and scope, the second specifies the output format. Every sentence adds useful information with no waste.

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

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

For a simple one-parameter lint tool with a fully documented input schema, the description is complete enough: it states the scope, diagnostic categories, and the return line format in lieu of an output schema. Nothing essential for correct invocation is missing.

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

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

Schema description coverage is 100%, so the file parameter and its absolute/relative path semantics are already documented. The description's 'one SystemVerilog file' reinforces the parameter's meaning but adds no syntax or format details beyond the schema, making the baseline 3 appropriate.

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 ('Lint') and resource ('one SystemVerilog file'), and its single-file scope implicitly distinguishes it from the sibling lint_all. An agent can identify the action and target without opening the 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?

The phrase 'one SystemVerilog file' gives clear context that this is for a single-file lint operation, contrasting with lint_all. However, it does not explicitly name lint_all as the alternative for multiple files or state when not to use this tool.

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

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

No annotations are provided, so the description carries the full burden. It usefully discloses a latency characteristic ('Can be slow on big projects'), which is real behavioral context, but says nothing about whether files are modified, whether diagnostics are returned as a report, or how failures are surfaced.

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, scope first, caveat second. Every clause earns its place with 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?

There are no parameters and no output schema, so the description needn't document inputs, but with no annotations it should say more about what the caller gets back (diagnostics list? counts?) and whether the operation is side-effect free. The performance warning is the only behavioral disclosure.

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 applies. The description adds useful context by naming the config file and section that determines the file list, which explains the parameter-less 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 specific verb ('Lint') and scope ('every file in the project filelists'), which implicitly distinguishes it from the sibling `lint` (single-file/less broad). The parenthetical naming the config key (lazyverilog.toml [design]) grounds the resource precisely, but it never explicitly contrasts with the sibling 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?

The phrase 'every file in the project' implies project-wide use and the slow-on-big-projects caveat hints at when to prefer the narrower `lint`, but neither the alternative nor an explicit when-not-to-use condition is stated. Usage is inferable rather than directed.

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 the key trait that this is a project-wide rewrite rather than a single-file edit, which is real behavioral value. However, it never states that it writes to disk (a destructive mutation), what happens if the symbol is not found at that line/occurrence, or that a preview mode exists to avoid unintended writes.

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 the symbol/line/file locators, with zero filler. Nothing is padded or repeated.

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 six-parameter, project-wide mutation with no annotations and no output schema, the definition is too thin. The two most safety-relevant facts — that it writes changes across the whole project and that preview=true returns a diff instead of writing — are absent, so an agent could invoke a destructive refactor without knowing the dry-run escape hatch.

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 83%, so the schema already documents file, line, symbol, and occurrence; the description adds no syntax or format detail beyond restating them. Notably it is silent on the preview parameter (default false) and on occurrence disambiguation, leaving the schema to carry those entirely.

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 (rename), resource (symbol), and scope (across the project), with the three required locators inlined. An agent immediately understands the operation, though the description never names a sibling (find_references, workspace_symbols) to differentiate from, which is the main thing separating a 4 from 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 or when-not-to-use guidance and no alternative named. The phrase 'across the project' hints at a project-wide refactor rather than a local edit, but the description never suggests previewing first or reaching for find_references to verify the blast radius before committing.

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 the output format (`instance: module (path:line)`) and the reverse traversal behavior, but doesn't state that the operation is read-only, whether it handles SystemVerilog only, or what happens when no instances are found.

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 compact sentences with zero waste. The primary behavior is front-loaded, and the optional `reverse` semantics follow immediately.

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

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

For a simple two-parameter query tool with no output schema, the description covers the core behavior, output shape, and the non-obvious `reverse` parameter. Minor gaps remain around language scope and empty results, but the essential information is present.

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 50%: `file` is documented, but `reverse` has no schema description. The description compensates by explaining that `reverse=true` shows parents that instantiate the module instead, adding meaning beyond the schema.

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

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

The description states a specific resource (module instance hierarchy) rooted at the module in `file`, which is clear. It doesn't explicitly distinguish itself from siblings like `find_references` or `document_symbols`, but the hierarchy-specific framing is distinct enough.

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 conditional guidance for the `reverse` parameter (parents instead of children), which is useful mode selection. However, it offers no guidance on when to use this tool versus alternatives such as `find_references` or `document_symbols`, leaving selection mostly implied.

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 exist, so the description carries the full disclosure burden, and it says nothing about match semantics (substring, prefix, fuzzy, case sensitivity), result limits, ordering, or whether the operation is read-only. For a search tool where matching behavior determines result quality, these are material gaps.

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

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

A single front-loaded sentence that names the action and scope before the trailing clause. The trailing ellipsis and comma list are slightly untidy but cost little.

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 simple (one required string, no output schema to explain), but the description leaves out what a result contains (symbol kind, location) and how matching works, both of which an agent needs to use results correctly. 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% and the single `query` param has no schema description, but the description does add one meaningful fact: the query is matched against symbol names rather than file contents. It still leaves the match mode unspecified, so the compensation is only partial.

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 a concrete resource covering modules, interfaces, packages and classes, plus the scope 'project-wide'. That scope implicitly separates it from document_symbols, but no sibling is actually named, so an agent must infer 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?

The phrase 'project-wide' implies when this is appropriate (searching across the workspace rather than within one file), but there is no explicit when-to-use, when-not-to-use, or named alternative such as document_symbols. Usage must be inferred.

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