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

Only readOnlyHint=false is provided, so the description carries the full behavioral burden. Beyond the word 'additional' (implying additive registration), it does not disclose whether the change is persistent, whether it requires a restart or index refresh, or how duplicates/path errors are handled.

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 efficient sentence with no filler. It is front-loaded with the action, though it is arguably too terse given the undocumented parameters.

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?

An output schema exists so return values need not be explained, but for a mutating registration tool with zero annotation coverage and 0% parameter documentation, the description is insufficient to call 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%: 'name' and 'path' have no descriptions, and the description adds nothing about naming conventions, whether the path must be absolute or pre-existing, or format expectations. The two required parameters are essentially undocumented.

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

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

The description gives a clear verb ('Register') plus resource ('workspace directory') and scopes it to multi-root monorepos/polyrepos. It implicitly contrasts with the base workspace and with list_workspaces, but never names the sibling 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?

The phrase 'for multi-root monorepos or polyrepos' gives an implied usage context, but there is no statement of when not to use it, prerequisites, or a pointer to list_workspaces for inspecting existing workspaces.

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

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

Annotations only declare readOnlyHint=true, so the description carries the rest and does add real operational detail: parallel subquery execution, clustering, and deduplication of merged chunks, which tells the agent the output is a fused result set. It omits cost/latency implications of a multi-hop run, which matter for an expensive operation, so it stops short of full disclosure.

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

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

Two dense sentences with the core capability front-loaded and no filler. The internal-mechanism clause (cluster/merge) is somewhat packed but each part 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?

An output schema exists, so return values need not be described, and the description conveys the overall pipeline. However, with five undocumented parameters and no explicit usage boundary against siblings, it is only minimally 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 coverage is 0% and none of the five parameters (alpha, rerank, sub_queries, top_k_per_subquery) is explained. The mention of 'subquery searches' loosely gestures at the sub_queries parameter but gives no semantics for any field, so 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+resource: multi-hop search that decomposes complex research questions and merges deduplicated chunks. The 'multi-hop' framing implicitly distinguishes it from the plain 'search' sibling, but it never names that alternative explicitly, so the differentiation is left to inference.

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?

'Complex research questions' implies the usage context and contrasts with simple lookups, but there is no explicit when-to-use/when-not-to-use statement and no reference to the sibling 'search' tool. An agent must infer that lighter queries should go elsewhere.

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 readOnlyHint=true already declaring the safe-read profile, the description adds real value: base64 encoding, MIME type return, and the security-relevant note 'Validated against root'. It does not cover size/truncation behavior, which matters given a max_bytes 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?

Three short, front-loaded sentences with no filler; the core verb/return type leads. Slightly fragmented but every clause carries information.

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

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

An output schema exists, so return values need not be spelled out, and annotations cover the safety profile. However, for a two-parameter tool with 0% schema coverage, the unexplained max_bytes leaves a real gap in calling 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% and the description never explains either parameter. 'Validated against root' hints that rel_path is a root-relative path, but max_bytes (its purpose, units, truncation semantics) is 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 and resource (download/read a raw file) plus the return encoding (base64 bytes with MIME type). The phrase 'Suitable for downloading binary files, images, PDFs' implicitly separates it from text-oriented siblings like read_file/read_file_markdown, 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?

Usage is only implied via 'Suitable for downloading binary files, images, PDFs, etc.' There is no explicit when-to-use/when-not or a named alternative, so the agent must infer that text files belong to read_file instead.

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

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

No annotations are provided, so the description carries the full behavioral burden. The verbs 'fetch' and 'extraction' strongly imply a read-only operation, and format-dependent behavior plus offset/limit semantics are given, but there is no explicit non-mutation guarantee, error behavior, or authentication context.

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

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

The description is front-loaded with the core purpose and then structured as four tight, format-specific bullets. Every sentence earns its place and there is no redundant or filler text.

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

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

Given the high parameter count (9), 0% schema coverage, and no annotations, the description does a strong job covering format support and parameter mapping; the output schema already handles return values. It is slightly incomplete on usage alternatives and behavioral caveats, but it is sufficient for an agent to call 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% across 9 parameters, so the description must compensate. It maps `query` to SQL and JSON path expressions with concrete examples, `columns`/`row_offset`/`row_limit`/`filter_col`/`filter_value` to CSV/TSV filtering, and `start_line`/`end_line` to text extraction. Only `rel_path` and parameter defaults remain unexplained, so the compensation is substantial.

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 ('fetch') and resource ('targeted data against structured files'), then enumerates the exact file formats supported (SQLite, JSON/JSONL, CSV/TSV, text/code). It does not name any sibling tool to differentiate itself, but the multi-format querying capability is distinctive enough for an agent to recognize it.

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 bullets imply when to use which parameter by mapping them to file types, which is useful implied guidance. However, there is no explicit when-to-use or when-not-to-use statement, and no alternative sibling (e.g., read_file, grep_search, search) is mentioned for comparison.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds the return shape (paths, line numbers, import-vs-reference classification, snippets), but says nothing about truncation/limits tied to max_matches or workspace scoping 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?

Two tight sentences, front-loaded with the action and scope, then the return format. No filler or repetition.

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?

An output schema exists, so return values need not be re-explained, and the read-only annotation covers safety. However, four undocumented optional parameters and the absence of any alternative-tool routing leave meaningful gaps for a 5-parameter search tool.

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

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

Schema description coverage is 0% across 5 parameters, and the description compensates only implicitly via 'across workspace code files'. The optional sub_dir, path_glob, workspace, and max_matches parameters receive no explanation of their effect on the search.

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+resource: 'Find call-sites, imports, and usages of a specific symbol across workspace code files.' This clearly separates it from a symbol-definition lookup, but it never names a sibling (e.g. search_symbols, grep_search) to make the distinction explicit.

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 states scope ('across workspace code files') but gives no when-to-use vs alternatives guidance, despite siblings like search_symbols, grep_search, and deep_search that overlap heavily. An agent must infer the selection rule.

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?

readOnlyHint=true already tells the agent this is a safe, non-mutating read. The description adds essentially nothing beyond that: no error behavior for unknown ids, no partial-failure notes, and its return-value sentence duplicates the output schema that already exists.

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

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

Two short sentences with the operation front-loaded and no padding. The second sentence is arguably redundant against the output schema, but nothing is verbose or buried.

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

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

For a one-parameter read tool with an existing output schema and a readOnlyHint annotation, the description covers the essential contract. The remaining gap is relational: what a chunk is and how it differs from get_chunk_context.

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

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

Schema description coverage is 0% for the single required parameter, so the description must carry the load. "By its id" does establish that chunk_id is the lookup key, but it gives no format, origin, or example of a valid chunk id, leaving the core input under-specified.

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

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

The description gives a specific verb and resource ("Fetch a single chunk by its id") and states the return content, so the operation is unambiguous. It does not differentiate itself from the closely related sibling get_chunk_context, leaving the agent to guess which retrieval tool is appropriate.

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

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

There is no guidance on when to use this versus get_chunk_context, search, or deep_search, and no prerequisites or context about where chunk ids originate. The agent gets a definition but no routing rule.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds that neighbors come from the same file, but says nothing about behavior when a chunk_id is missing/at a file boundary, any cap on neighbor counts, or cost/latency characteristics.

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

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

Two tight sentences with zero filler, and the core operation is front-loaded ahead of the rationale.

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?

An output schema exists, so return values need not be described, and annotations cover read-only safety. The remaining gap is the undocumented neighbor-count parameters, which is minor but real for a 3-parameter tool at 0% schema coverage.

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

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

Schema description coverage is 0%, so the description must carry the burden. It implies before/after expansion, which loosely maps to before_chunks/after_chunks, but never explains their meaning, defaults (1), or upper bounds, and adds nothing for chunk_id's format.

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 ('Fetch') and resource ('contextual neighbor chunks surrounding a chunk_id from the same file'), and scopes it to a single file. It is distinguishable from the sibling get_chunk, though it never names that sibling to make the contrast explicit.

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?

'Expands awareness of the document before and after a search hit' implies the usage context (following up on a search result), but there is no explicit when-to-use/when-not, no mention of get_chunk as the alternative for the single chunk, and no 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?

The readOnlyHint annotation already establishes that this is a safe read operation. The description adds useful behavioral context by naming the graph's analytical outputs (hubs, dependencies, orphans), but it does not disclose performance characteristics, how max_files affects results, or any workspace-scoping 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?

Two short sentences are front-loaded with the core action and then list the detected graph features. Every clause contributes directly to understanding the tool's purpose, 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?

Although an output schema exists and relieves the description of explaining return values, the definition remains incomplete for a tool with two undocumented parameters at 0% schema coverage. It also omits usage context and any caveats about sub_dir scoping or max_files limits, leaving meaningful gaps 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%, so the description must carry the full burden for sub_dir and max_files. It never mentions either parameter, their defaults, or how they shape the graph, leaving parameter semantics entirely undocumented.

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

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

The description uses a specific verb and resource: it constructs an architectural dependency and reference topology graph of the workspace. It further names the exact outputs detected: central hubs by in-degree, file dependencies, and orphan files. This clearly distinguishes the tool from sibling search, read, and indexing tools.

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

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

The description explains what the tool produces but gives no guidance on when to use it versus alternatives such as search_symbols, find_symbol_references, or get_index_status. There are no stated prerequisites, exclusions, or routing conditions for an agent to follow.

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 discloses that indexing occurs as background quick/thorough tasks and that wait=True blocks synchronously with an optional timeout_seconds – meaningful behavioral context. It does not state whether the call itself is read-only, nor what the timeout does on expiry, leaving minor gaps for a no-annotation tool.

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

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

Two sentences, front-loaded: the first establishes what is inspected, the second explains the wait behavior. Every clause carries information with no redundancy.

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

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

An output schema exists, so return values need not be described, and the description sensibly focuses on what state is inspected. It covers the two parameters and the background-task behavior. The remaining gap is the timeout edge case and the absence of any when-to-use framing, which keeps it from being fully self-sufficient.

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 adds real meaning for wait=True ('synchronously await index completion') and names timeout_seconds, but does not explain the default (30) or what happens when the timeout elapses. It partially compensates but leaves the second parameter's semantics underspecified.

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?

Uses a specific verb ('Inspect') plus the resource ('indexing state') and enumerates exactly what is reported: background task status, chunk counts, and completion timestamps. Clearly distinguishable from siblings like refresh_index (which triggers indexing) and get_chunk (which fetches content).

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 the wait=True mechanism for synchronously awaiting completion, which is implied usage guidance. However, it never states when to prefer this tool over refresh_index or when polling is appropriate, and it gives no exclusions. Usage is only implied rather than explicitly framed.

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?

readOnlyHint=true already tells the agent this is a safe read, and the description reinforces this by framing everything as 'inspect' of git history (logs, diffs, blame). It adds the mode taxonomy but says nothing about auth requirements, rate limits, or why one mode is preferable. With annotations covering safety, a 3 is appropriate.

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 tight sentences with the core capability front-loaded ahead of the mode list. No wasted words, though the mode enumeration could be integrated more cohesively with the semantic description.

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 output schema exists, so return values need not be described, and annotations cover the read-only profile. However, for a 6-parameter, 4-mode tool, the description never clarifies which parameters apply to which mode (e.g., line_start/line_end for blame, query for commits), leaving meaningful 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 description coverage is 0% across 6 parameters, so the description must compensate. It usefully enumerates the valid mode values (which are not formal enums), but leaves query, limit, rel_path, line_start, and line_end unexplained, even though line_start/line_end and rel_path clearly scope the blame/diff modes. Partial compensation only.

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

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

The description uses a specific verb ('Inspect') with concrete resources ('git commit logs, recent changes, commit diffs, line blame') and enumerates the four modes. The git-history domain inherently separates it from sibling text-search tools like grep_search or search. It stops short of naming a sibling explicitly, so a 4 rather than 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?

Listing the modes ('commits', 'recent_changes', 'diff', 'blame') implies the tool's capabilities, but there is no explicit when-to-use statement, no guidance on choosing among the modes, and no routing to alternatives like grep_search or search for working-tree text. Usage is left 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?

readOnlyHint=true already establishes the safe-read profile, so the description's contribution is the return shape (matching lines, context, line numbers, paths) and the feature set (path_glob, case sensitivity). Since an output schema exists, the return-value description is partly redundant, and it omits throttling/truncation behavior for high-match queries.

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

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

Three tight sentences, front-loaded with purpose then return shape then supported features. Every sentence carries information, though the return-format sentence loses some value against the existing output schema.

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

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

For a 7-parameter tool with zero schema documentation, the description covers the search semantics and two flags but leaves workspace, sub_dir, and max_matches unexplained. An agent can call it on defaults, but cannot reason about workspace scoping or result caps from the definition.

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

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

With 0% schema description coverage the description must carry the params, and it only explains path_glob (with a concrete glob example) and case sensitivity. sub_dir, workspace, and max_matches remain undocumented in both places, so the compensation is 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 resource (files in the workspace) and pins the mode as 'exact regex or substring', which implicitly contrasts with semantic/fuzzy siblings like deep_search or search. It does not explicitly name any sibling alternative, so an agent must still infer the boundary, keeping it 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?

Usage is implied by 'exact regex or substring' — use it when you know the pattern — but there is no explicit when-to-use, when-not-to-use, or named alternative among the many search siblings (deep_search, git_search, search_symbols). The contrast is left for the agent to construct.

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

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

Annotations declare readOnlyHint=true, which is consistent with listing. The description adds that it returns metadata including MIME/type, conversion support, and relative path, and that depth and glob filtering are supported. However, it doesn't disclose the default limits (limit=150, max_depth=2), the sandboxing behavior, or whether pattern matches are case-sensitive. Some behavioral context is present but not rich.

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

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

Two sentences, front-loaded with the main purpose. It's concise and avoids repetition. The second sentence lists return details and capabilities efficiently.

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?

An output schema exists, so return values needn't be explained, but the description already spends a sentence on them. More critically, with 7 undocumented parameters and no usage guidance, the description is insufficient for correct invocation. It does not cover the default workspace or how to filter, which are essential for correct use.

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% – none of the 7 parameters are described in the schema. The description mentions 'depth' (max_depth) and 'glob filtering' (pattern), but leaves rel_path, workspace, limit, include_dirs, and include_files completely undocumented. The description fails to compensate for the low schema coverage, which is critical for a tool with 7 parameters.

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

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

States a specific verb (Explore/List) and resource (sandboxed filesystem tree), and clarifies the return content. The scope 'sandboxed filesystem tree' distinguishes it somewhat from read_file/read_file_markdown, but the description does not explicitly differentiate from siblings like grep_search or read_files_batch.

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. It doesn't say whether to use this instead of read_file/grep_search to discover paths, nor does it mention prerequisites like needing a valid workspace. The mention of 'depth and glob filtering' implies use cases but provides no selection criteria.

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

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

The readOnlyHint annotation already declares this as a safe read operation. The description adds that it returns registered workspace roots and their status, but does not disclose other behavioral details such as pagination or permissions, which is acceptable given the output schema and simple nature of the 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?

The description is a single, front-loaded sentence with no redundant or filler content. It states exactly what the tool does and what it returns.

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

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

Given the zero-parameter input schema, readOnlyHint annotation, and existing output schema, the description is complete enough. It tells the agent what resource is listed and that status information is included, with no missing prerequisites.

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 no parameters, so there is no parameter semantics to document. Per the rubric, zero-parameter tools receive a baseline of 4 when the schema and description are otherwise consistent.

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 precise verb ('List'), resource ('registered workspace roots'), and scope ('all registered') plus the returned status. An agent can immediately distinguish this from sibling tools such as add_workspace or get_index_status.

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 does not explicitly say when to use this tool versus related tools like add_workspace or get_index_status. However, for a zero-parameter listing tool, the intended use is largely self-evident 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?

With readOnlyHint=true already covering safety, the description adds genuine behavioral detail: it groups contiguous chunks by file, dedupes, and trims to strict token budgets. This discloses the transformation logic an agent needs to predict the output, though it says nothing about ordering or failure/shortfall 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?

Two dense sentences with zero filler, front-loading the primary action and packing the grouping/dedupe/trimming behavior efficiently.

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?

An output schema exists, so return values need not be described. However, with six parameters at 0% schema coverage and no parameter explanations, the definition is incomplete for correct invocation despite a solid behavioral summary.

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 six parameters exist, so the description carries the full burden. It only hints at max_tokens via the 'e.g. 4000 tokens' example; alpha, rerank, path_glob, include_line_numbers, and query are entirely unexplained, leaving most parameters 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?

The description states a specific verb ('Assemble') and resource ('Markdown prompt context pack from search hits'), and its output nature (packed context) is distinct from the search/retrieval siblings. It stops short of naming a sibling to differentiate against, but the purpose is unambiguous.

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

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

Usage is implied by 'from search hits', suggesting it operates downstream of search, but there is no explicit when/when-not guidance or named alternative among the many search-related siblings. The agent must infer the workflow position.

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

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

Annotations only declare the safety profile (readOnlyHint=false, destructiveHint=false); the description adds genuinely new behavioral facts: the edit is atomic, it operates on a sandboxed file, and it triggers incremental re-indexing in under 50ms on success. It still omits failure semantics (what happens if old_string is absent or ambiguous) and whether edits are reversible.

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 tight sentences, no filler, with the core action stated first and the side effect (re-indexing) second. Every clause earns its place.

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

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

An output schema exists, so return values need not be explained, and annotations cover the safety profile. However, for a 6-parameter mutating tool with 0% schema coverage, the description leaves dry_run, replace_all, and workspace completely unexplained, which is a real completeness gap.

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

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

Schema description coverage is 0% across 6 parameters, so the description carries the full burden, yet it only indirectly clarifies old_string/new_string. Nothing explains dry_run, replace_all, or workspace, leaving half the parameters undocumented in both places.

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 (patch) and resource (sandboxed file in the workspace) plus the exact mechanism (replace an exact substring with new content). That mechanism implicitly separates it from read-only siblings like read_file or grep_search, 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?

The 'exact substring' framing implies when this tool is appropriate (targeted edits at a known location), but there is no explicit when-to-use/when-not guidance, no mention of alternatives (e.g., write_file or refresh_file), and no prerequisites such as the file already existing in the index.

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

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

The readOnlyHint=true annotation already tells the agent this is a safe, non-mutating call. The description adds useful context that it verifies both connectivity and 'runtime readiness', which is more than a bare ping. It still doesn't say what a negative result means (timeout, error shape), so the added value is moderate.

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 that is front-loaded with the primary concept ('Health check and liveness probe') and closes with the scope of verification. No filler or redundant restatement of the name.

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

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

The tool is a zero-parameter, read-only probe and an output schema exists, so return values need not be described. The description covers what is checked, leaving only usage routing unaddressed, which is a minor gap for a tool this simple.

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 per the rubric this defaults to a baseline of 4. There is no parameter semantics to add or omit.

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: 'Health check and liveness probe verifying server connectivity and runtime readiness.' An agent can immediately tell this is a connectivity check rather than a data operation. It does not name a sibling it differs from, though none of the siblings are health checks, so differentiation is implicit.

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 or when-not-to-use guidance is given. The description never mentions when an agent should call this versus a status-like sibling such as get_index_status, nor any preconditions. Usage must be inferred entirely 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?

Annotations already mark this as read-only, so safety is covered. The description adds substantive behavior beyond annotations: path validation against the root and refusal of escaping symlinks. It does not mention max_bytes truncation behavior, permissions, or return format, but the added security constraint is meaningful.

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

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

Two short sentences with zero waste; the core action is front-loaded and the security constraint follows immediately. Nothing extraneous is present.

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 two-parameter read tool with an output schema (so return format need not be explained) and readOnlyHint, the description covers the operation and path-safety model. However, with 0% schema coverage it should clarify the two parameters, especially max_bytes truncation, which is an invisible behavioral choice.

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

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

Schema coverage is 0%, so the description must compensate for two undocumented parameters. It does not explain rel_path (relative to the configured root) or max_bytes (truncation limit) at all, leaving the agent to infer semantics from names alone.

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

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

The description states a specific verb and resource (read a file's contents) and adds scope ('from the configured root'). This distinguishes it from siblings like read_file_markdown, read_files_batch, and get_chunk, which have different output formats or scopes.

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 a clear boundary ('configured root') but does not explicitly say when to prefer this tool over read_file_markdown, read_files_batch, or get_chunk. Usage is implied by the purpose, but alternative selection is left to the agent.

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?

readOnlyHint=true already tells the agent this is a safe read, so the bar is lower. The description usefully adds the supported input formats and the 'validated against root' security constraint, but says nothing about unsupported formats, size limits, or failure 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?

Two tightly packed sentences with zero filler; the format enumeration and the Markdown outcome are both front-loaded and no sentence 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?

An output schema exists so return values need no explanation, and both the input formats and the root-validation behavior are covered. The only real gap is behavior on unsupported or oversized inputs, which is minor for a simple read-only converter.

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

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

With 0% schema description coverage, the burden is on the description, and 'Validated against root' does hint that rel_path is resolved relative to a workspace root. However, it does not clarify expected path syntax, leading separators, or extension handling, leaving real ambiguity for the single required 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?

States a specific verb (convert) and resource (documents of many formats) with the concrete output (clean Markdown), and the enumerated format list makes the scope unmistakable. It does not explicitly distinguish itself from the sibling read_file, which is the obvious adjacent tool, so it falls short of a full 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 implies you reach for this when you need Markdown output, but it never states when to prefer it over read_file, read_files_batch, or download_file_raw, nor any when-not condition. No alternative routing is provided.

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

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

Annotations already declare readOnlyHint=true, so safety is covered. The description adds real value beyond that: it discloses concurrent execution, the per-file return mapping, and that failures surface as structured error objects rather than aborting the batch. The one gap is that truncation behavior for max_bytes_per_file is never described.

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

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

Three short sentences, zero filler, and the core capability (batch concurrent read) is front-loaded before the return-shape and option details. Every sentence 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?

An output schema exists and annotations cover safety, so the description does not need to explain returns. Still, max_bytes_per_file is ambiguous everywhere (does it truncate, skip, or error?), and there is no routing guidance among the many sibling read/search tools, leaving meaningful gaps for a 3-parameter tool.

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

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

Schema description coverage is 0%, so the description must carry the burden. It does explain as_markdown (Markdown vs raw text) with the exact keyword form, but max_bytes_per_file and the rel_paths format are left entirely unexplained in both the description and 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?

States a specific verb (inspect), resource (multiple files), and a distinguishing scope (concurrently, single roundtrip). It is clearly differentiable from read_file/read_file_markdown by the batch semantics, though it never names those siblings 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?

Batch usage is implied by 'multiple files concurrently in a single roundtrip', which tells an agent the general situation this fits. However, there is no explicit when-to-use versus read_file or read_file_markdown, no batch-size guidance, and no stated 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?

Annotations declare readOnlyHint=false and destructiveHint=false, so the agent knows this is a non-destructive mutation. The description adds useful behavioral context (incremental, avoids walking the workspace, <50ms), which is real value beyond annotations, but it omits auth requirements and what happens when the file is missing or unchanged.

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, and the operation and its performance scope are front-loaded. Acceptable, though the parenthetical '(re-)chunk' is slightly awkward.

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 an output schema present, return values need not be explained. However, the 0%-covered parameter and the absence of usage/exclusion guidance leave the description only minimally adequate for a mutation tool.

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

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

Schema description coverage is 0% and the sole parameter rel_path is undocumented in both schema and description. The description does not clarify that the path is relative or how it is resolved, so it 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 (re-chunk and re-index) applied to a specific resource (a single file), and the incremental scope distinguishes it from the sibling refresh_index. It does not explicitly name refresh_index as the workspace-wide alternative, 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?

The incremental, single-file scope implies when to use it (after editing one file) versus refresh_index, but this is left implicit. There is no explicit when/when-not statement or named alternative.

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

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

Annotations only declare readOnlyHint=false and destructiveHint=false, so the description carries extra weight: it discloses idempotency ('safe to call repeatedly'), eviction of stale chunks, and a performance caveat on large corpora. That is meaningful behavior beyond the annotation set, though it omits auth/permission requirements.

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

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

Three tight sentences: the operation is front-loaded, then idempotency, then the performance caveat. No filler and nothing redundant.

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

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

An output schema exists, so return values need not be explained, and the description covers the core mutation semantics and safety. It is only slightly incomplete in leaving the full_rebuild flag entirely undocumented, which matters for a rebuild tool.

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

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

Schema description coverage is 0% and the single parameter full_rebuild is never mentioned in the description. An agent cannot tell what a full rebuild changes versus the default incremental (false) behavior, nor what the tradeoff is, so 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 and resource chain ('walk the configured root directory', 'chunk every text file', 'embed + index all chunks'), which clearly distinguishes a whole-index rebuild from the per-file sibling refresh_file. It stops short of explicitly naming that sibling or the index-status tool, so routing is inferred rather than stated.

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 operational guidance ('safe to call repeatedly', 'may be slow on large corpora') but never says when to prefer this over refresh_file or to check get_index_status first. Usage context is implied through scope rather than explicit alternatives or 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?

Annotations only declare readOnlyHint=true and openWorldHint=false, so the description carries the interesting behavior and does so well: non-blocking default, immediate search over currently available content, index-completeness reporting, and the two flags that alter that behavior. It does not mention performance cost of rerank/fuzzy or staleness implications of an incomplete index, which keeps it below a 5.

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

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

Four sentences, front-loaded with purpose then behavior then the two tuning flags; there is little filler. The middle clauses are slightly dense but each sentence carries distinct information.

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

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

With an output schema present, the description need not detail return values, and its coverage of async indexing and context-budget behavior is genuinely useful for a hybrid search tool. It is complete enough to invoke correctly, though the undocumented parameters leave an agent guessing on ranking controls.

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 8 parameters, so the description must compensate — and it only explains wait_for_indexing and compact (plus an implicit nod to top_k via 'top-k'). The hybrid-weight parameter alpha, fuzzy, rerank, and path_glob are left entirely opaque, which is a large gap for a search tool where alpha and rerank materially change results.

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 and resource — 'Hybrid full-text + vector search over the indexed filesystem' — and even summarizes the return shape (top-k chunks with file path, offset range, snippet). That is far more specific than a generic 'search', and the 'hybrid' qualifier implicitly separates it from keyword-only siblings like grep_search. It stops short of naming an alternative tool the way a 5 would.

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 operational guidance around indexing ('Does NOT block... Set wait_for_indexing=True to explicitly wait') and context-budget guidance ('Set compact=True'), which is real usage direction. However it never states when to choose this tool over siblings such as grep_search, deep_search, or search_symbols, so selection guidance is only 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?

Annotations already declare readOnlyHint=true, so the safe-read profile is covered. The description adds real context by disclosing the return contents and the efficiency trait (no full text scan), but says nothing about indexing prerequisites, staleness, or result limits even though max_matches exists.

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

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

Two sentences, front-loaded with the action and immediately followed by the return shape and the efficiency differentiator. No filler and no restatement of the tool name.

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?

An output schema exists, so return-value explanation is not needed and the description correctly skips it. But with six undocumented parameters at 0% schema coverage, an agent has no basis for setting sub_dir, path_glob, or max_matches, leaving a meaningful gap.

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

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

Schema description coverage is 0% across 6 parameters, so the description carries the full compensating burden and largely fails. Only the symbol_type dimension is loosely hinted at via 'function and class declarations'; name, sub_dir, path_glob, workspace, and max_matches are never mentioned.

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 function/class declarations and definitions) and scopes it to named languages, which distinguishes it from the generic `search`/`grep_search` siblings. It does not name a specific sibling, 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?

The clause 'without full text scanning' implies this is the cheaper alternative to a text-search tool, which is an implied when-to-use. However, it never names grep_search, deep_search, or find_symbol_references, nor does it state exclusions or prerequisites for choosing between them.

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