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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuine value by listing what the result contains (matching code, project summary, map, conventions) when task_hint is given, but says nothing about indexing cost, latency, or what happens without a hint — even though indexing_depth is the main behavioral lever.

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?

Purpose is front-loaded in one sentence, followed by a compact return-value note. The trailing 'Args:' block partially restates the schema, which is slightly redundant, but it is short and does not bury the lead.

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

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

With no output schema and 4 parameters, the description does cover the shape of the return value, which is the most important gap to fill. However, it omits the meaning of the indexing modes and gives no signal on how this differs from the crowded set of search/explore siblings, leaving an agent unable to route confidently.

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

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

Schema coverage is only 25%, so description must compensate. It explains task_hint well and enumerates indexing_depth's accepted values with 'auto' as the default, but never explains what eager/lazy/minimal actually do. workspace and max_tokens are entirely undocumented in the description, and workspace only has the schema to lean on.

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 concrete verb+resource: find where a behavior is implemented in an unfamiliar repo. That said, the tool name 'bootstrap' suggests project setup, so the description is doing real disambiguation work. It never contrasts with obvious siblings such as explore_codebase, relevant_context, or semantic_search, which likely overlap.

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?

'In an unfamiliar repository' implies the context for use, and the conditional 'With task_hint...' hints at what changes when a hint is supplied. But there is no explicit when-to-use vs. when-to-pick-an-alternative guidance, and no exclusions against the many similar search/explore siblings.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds the meaningful clarification that 'depth' counts hops, which conveys traversal cost, but it says nothing about traffic/token volume on deep traversals, truncation, or what the result looks like for a recursive graph.

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 purpose sentence is front-loaded and the Args block is tight, with each parameter line adding real information ('qualified or bare', the callees/callers mapping, hops semantics). Minor redundancy with the schema prevents a 5 but nothing is wasteful.

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 5-parameter graph traversal with no output schema, the definition covers inputs adequately but says nothing about the shape of the returned call graph or how results are limited/truncated. An agent knows how to call it but not what to expect back, which is a real gap for a traversal 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 only 20% (just 'workspace'), so the description must carry the load and largely does: it defines 'direction' as callees vs callers and 'depth' as maximum hops with default 1, and clarifies 'symbol' accepts qualified or bare names. It leaves 'max_tokens' (default 2000, max 32000) entirely unexplained, which is the main 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: 'Follow the calls of a function or method,' which is a concrete graph-traversal action an agent can distinguish from listing symbols or references. It does not explicitly differentiate itself from close siblings like cross_references, dependencies, or impact_analysis, which would have been valuable.

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 prefer this over cross_references, dependencies, or impact_analysis, all of which sound adjacent. The only implicit guidance comes from the 'direction' parameter values, which hint at use cases but do not tell the agent when this tool is the right choice versus its siblings.

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

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

readOnlyHint=true already tells the agent this is a safe read. The description adds little beyond that: it does not say whether this is a listing of tool definitions, whether calling with 'workspace' switches the active workspace, or what the output looks like. With no output schema, more behavioral disclosure was needed.

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?

It is a single short sentence with no filler, so it is concise, but the brevity comes at the cost of under-specification rather than efficiency. There is nothing front-loaded because nothing substantive is said.

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 no-required-parameter discovery tool with no output schema and only a readOnlyHint annotation, the description should explain what is enumerated and what the response contains. Instead it names four topic areas without connecting them to behavior or output, leaving real gaps for an agent deciding whether to call it.

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

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

Schema coverage is 50% – 'workspace' is documented as a project path, but 'max_tokens' has no description at all. The phrase 'workspace selection' vaguely gestures at the workspace parameter but doesn't explain its effect (default project vs. switching), and max_tokens (default 2000, max 32000, presumably response truncation) is never addressed.

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 is a noun list ('Available tools, profiles, workspace selection, and optional enhancements') with no verb, so the agent must infer that this returns capability/discovery information. It does convey the resource domain (tooling/capabilities) and is not a pure restatement of the name, but it never says explicitly what the tool does or returns.

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

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

There is no statement of when to call this versus the many siblings (bootstrap, project_summary, explore_codebase), nor any prerequisite or exclusion. The word 'Available tools' hints at a discovery role, but the agent is left to infer it.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds pagination behavior (cursor continuation, page_size range 1-100, default 20), which is genuinely beyond the annotations. It does not describe result ordering, whether the definition is included in the page, or the response shape.

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

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

The purpose sentence is front-loaded and the per-argument notes are terse, one line each. The Args block is slightly more structured than the single-sentence prose it needs to be, but 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?

For a 7-parameter tool with 14% schema coverage and no output schema, the description covers the disambiguation and paging story well but leaves max_tokens (default 2000, max 32000) entirely unexplained and says nothing about what the result contains or how a paged result terminates.

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

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

Schema coverage is only 14%, so the description must compensate, and it largely does: it explains file_path's disambiguation role, line's meaning, cursor as a paging continuation, and page_size's range and default. Three parameters (symbol_name, workspace, max_tokens) are left to the schema, with max_tokens undocumented anywhere.

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

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

The opening sentence gives a specific verb and resource: locate a symbol's definition plus every reference (calls, imports, attribute accesses). That is clearly distinct from siblings like symbols or call_graph. It stops short of naming those siblings, so the differentiation 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?

The Args notes imply when the disambiguation parameters matter ("When names collide..."), which is useful selection logic within the tool. But there is no guidance on when to reach for cross_references versus impact_analysis, call_graph, or search_symbols — an agent must infer that from the sibling names alone.

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 and destructiveHint=false, so safety is covered structurally. The description adds the useful bidirectional nuance (what it imports AND what imports it), but says nothing about max_tokens-driven truncation or the workspace default — behaviorally relevant for a tool that can return unbounded edges.

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

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

A single front-loaded sentence with no filler, and the bidirectional scope is stated up front. It is efficient, though it leaves little room for the clarifications the tool actually needs.

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

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

With no output schema, no parameter descriptions for two of three inputs, and no annotations beyond the safety flags, the description is too thin. It should say whether path is absolute or workspace-relative and what the response shape (edges, list of paths) looks like.

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

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

Schema coverage is only 33%: workspace is documented in-schema while path and max_tokens are bare. The description does not clarify that path is a file (vs directory) or that max_tokens truncates output, so a third of the parameters remain semantically opaque.

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 pair — shows both outgoing imports and incoming importers of a file — which disambiguates the bare name 'dependencies' from package-dependency meaning. It does not, however, distinguish this from close siblings like cross_references or impact_analysis, which likely return overlapping information.

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

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

No when-to-use guidance, no prerequisites, and no named alternatives among the many related siblings (cross_references, impact_analysis, call_graph). The agent must infer the choice entirely from the one-line purpose.

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 establish readOnly/non-destructive safety. The description's real contribution is disclosing the return shape (counts, languages, importance, symbols), which matters because there is no output schema, but it omits pagination/truncation behavior tied to max_items/max_tokens.

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

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

Front-loaded leading sentence states the operation and output, followed by a compact Args block. No filler; every line carries information, though the Args section could be formatted to match schema parameter names more cleanly.

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?

Compensates for the absent output schema by describing return contents, but with 6 parameters, no required fields, and low schema coverage, an agent still lacks guidance on defaults for max_items/max_tokens and on when this tool is the right pick.

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

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

Schema coverage is only 17%, so the description carries extra weight. It adds genuine meaning for path ('relative to project root'), importance_threshold ('0.0 to 1.0'), and task_hint ('orders the files'), but leaves max_items and max_tokens completely unexplained anywhere.

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 scope ('List one directory level') and describes the return shape: subdirectories with counts/languages, files with importance and symbols. This clearly distinguishes it from deeper-search siblings like semantic_search or project_summary, though it never names them explicitly.

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

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

No guidance on when to reach for this over relevant_context, project_summary, fast_search, or semantic_search, despite a crowded sibling set. Usage is only implied by the tool name and 'one directory level' phrasing.

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 and destructiveHint=false, so safety is covered. The description adds real behavioral detail the annotations do not: the trigram index preselects candidates and the index is skipped above the selectivity threshold. It says nothing about result truncation or output size limits, which matters for an 8-parameter, no-output-schema 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?

Purpose is front-loaded in one sentence, then a compact Args block. Every line carries information; the only inefficiency is the split between the description's parameter list and the schema's properties.

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 a complex 8-param tool with no output schema, the definition gives an agent enough to formulate calls: the required parameter, the scoping path, index behavior, and diagnostics. It falls short only on the undocumented tuning parameters and on any mention of truncation or result-limit behavior.

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

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

Schema description coverage is only 13%, so the description must compensate and it partially does: pattern, path, selectivity_threshold, and explain all get meaningful prose (selectivity_threshold especially, via the 0.10 default and skip semantics). But workspace, max_tokens, max_results, and case_insensitive get no explanation in the schema or the description, leaving half the surface opaque.

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

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

States a specific verb and resource ("Search file contents with a regular expression") plus a concrete mechanism (trigram index preselection). It is clear what the tool does, but it never distinguishes itself from the sibling semantic_search or search_symbols, so an agent must infer which search tool to prefer.

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 regex framing implies usage (exact/literal pattern matching) and the sibling list contains several overlapping search tools, yet there is no explicit statement of when to use fast_search instead of semantic_search or search_symbols. Usage is only inferable.

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 this is a safe read (readOnlyHint=true, destructiveHint=false), so the description's job is to add semantics — and it does, disclosing that traversal is transitive ('directly or through other files') and directional (importers, not imports). It omits that `max_tokens` can truncate results, which is a behavioral trait an agent should know.

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 verb first and the clarifying clause immediately after; zero filler and nothing 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?

There is no output schema, and the description does tell the agent it returns a list of files, which suffices for the core contract. It says nothing about truncation when `max_tokens` is hit, behavior on nonexistent paths, or whether output ordering is meaningful, leaving real gaps for a 3-parameter analysis 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 only 33% — `workspace` is documented, but `max_tokens` and its 32000 ceiling are undocumented anywhere. The description's 'given files' maps to `changed_files` but adds no format or semantics 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?

States a specific verb and resource ('List the files that a change... can affect') and pins the traversal direction as reverse dependencies ('the files that import them'). It does not explicitly distinguish itself from the sibling `dependencies` or `cross_references`, which an agent could easily confuse it with.

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

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

The phrasing implies usage (assessing blast radius before modifying files), but there is no explicit when-to-use guidance and no mention of when to prefer `dependencies`, `cross_references`, or `review_change` instead. The agent must infer the choice from the tool name alone.

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 this a read-only, non-destructive operation, so the safety profile is covered for free. The description adds genuine behavioral context beyond that: the ambiguity resolution flow, the ordering effect of task_hint, the next_source continuation for long definitions, and the caveat that missing relationships do not prove absence. It still says nothing about result size limits despite a max_tokens parameter with a 32000 ceiling.

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?

Roughly six short sentences, front-loaded with the payload inventory before any procedural detail. Every clause conveys a distinct operational fact, and the closing warning about missing relationships earns its place.

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

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

For an aggregation tool with no output schema, the description covers what the agent needs: what comes back, how to disambiguate, how to order, and how to page. The only notable omissions are the truncated-result behavior implied by max_tokens and any hint about which sibling to use for a narrower query.

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 schema description coverage at only 14%, the description has to carry the parameter burden, and it does for the critical ones: it explains that symbol_name alone works, that file_path and the definition line are the disambiguation pair, that task_hint orders excerpts and tests, and that source_start_line pages into long definitions. workspace and max_tokens are left to the schema, with only workspace documented there, so a small gap remains.

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

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

The description opens with a specific verb and resource plus an explicit inventory of what comes back: definition, source excerpt, references, imports, candidate tests. The phrase 'in one call' signals that it aggregates work that siblings like cross_references, symbols and suggest_tests do individually, but it never names those alternatives outright, so differentiation is only 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?

It gives a concrete usage path: a name alone is sufficient, and an ambiguous name requires file_path plus definition start line to disambiguate. It also explains how to tune results with task_hint and how to continue with next_source or source_start_line. It stops short of saying when to prefer this over the sibling tools that cover pieces of the same ground.

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=false and destructiveHint=false, so the write-but-safe profile is covered. The description adds the useful consequence that the index and search will pick up the new content and that the call is redundant under a file watcher, but it says nothing about error behavior for missing paths, idempotency, or whether unchanged files are re-indexed.

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 put the effect first and the redundancy caveat second, then a minimal Args block. Nearly every line earns its place; the watcher sentence is slightly awkwardly phrased but carries genuine routing value.

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

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

For a 3-parameter mutation with no output schema, the description covers purpose and the primary path argument adequately, but leaves the unexplained `max_tokens` parameter and the behavior on invalid paths unaddressed. It is viable but not complete for an agent to call confidently in all cases.

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

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

Schema coverage is only 33% — only `workspace` is documented in the schema. The Args block usefully clarifies `files` as relative-or-absolute paths, but `max_tokens` (a non-obvious budget parameter with a 512–32000 range) is left entirely unexplained 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 gives a specific verb and object ("Tell the server which files changed") and states the downstream effect (index and search read new content), which is more than a restatement of the name. It does not explicitly contrast with any sibling tool, though the notifier role is distinct enough from the analysis siblings that mis-selection is unlikely.

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?

"A server that watches the project finds edits without this call" supplies an explicit when-not-to-use condition, which is real routing guidance. It lacks an equally explicit when-to-use trigger (e.g. "call after writing or editing files"), leaving the positive case implied by the first sentence.

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 and destructiveHint=false, so the safety profile is covered. The description adds value by enumerating the summary's sections (which partially substitutes for the missing output schema), but says nothing about output size, truncation, or how max_tokens affects the result.

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 the verb first and the covered dimensions as a compact list. No filler, though the long enumeration is denser than it needs to be.

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 overview tool with no output schema, listing the summary's contents is genuinely helpful, but the definition leaves gaps an agent needs: whether this is the recommended first call, what the output looks like structurally, and how max_tokens bounds it.

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

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

Schema coverage is 50%: workspace is documented, but max_tokens (default 2000, max 32000) has no description and the tool description does not explain what it controls or what happens when the summary exceeds it. With half the parameters undocumented and no compensating text, this falls below the baseline.

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

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

Names a specific verb+resource ('Summarize the project') and enumerates the dimensions covered (purpose, size, entry points, architecture, layout, dependency layers, tech stack, tests, build). An agent can distinguish it from narrower siblings like symbols or call_graph, though the description never explicitly says it is the high-level overview entry point.

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 statement of when to use this vs. explore_codebase, bootstrap, capabilities or the individual query tools. The only usage signal is the schema's 'default: this project' for workspace, which is parameter-level, not usage guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered structurally. The description does add real behavioral detail: the breadth expansion (imports and importers), depth as hop count, and that task_hint changes ordering rather than filtering. It omits the truncation behavior implied by max_tokens (default 2000, max 32000) and what happens when include_symbols is false, so it does not fully close the gap.

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

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

The leading sentence front-loads the behavior and the Args block maps cleanly to parameters, with no filler prose. Slight redundancy with the schema in restating defaults, but it is short and structurally clear.

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 read-only graph traversal with no output schema, the definition covers the core semantic levers: direction of traversal, hop depth, ordering, and workspace scope. Missing notes on truncation and symbol suppression are minor against annotations that already establish the non-destructive read profile.

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 only 17% (workspace alone), so the description must compensate, and it partially does: it explains files as center paths, constrains depth to 1 or 2 with a default of 1, and clarifies that task_hint orders rather than filters. However max_tokens, include_symbols, and workspace are left entirely to the schema, half the parameter surface is undocumented anywhere meaningful.

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?

A specific verb-plus-resource statement: it shows the files around the given files, both what they import and what imports them, plus top symbols. That pins down the traversal direction and payload better than a generic 'get context' name would. It never names or distinguishes itself from closely overlapping siblings such as dependencies, impact_analysis, or cross_references, which keeps it out of 5 territory.

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

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

There is no statement of when to reach for this tool versus dependencies, impact_analysis, or cross_references, all of which sound like they operate on the same import graph. The only hint at usage is the optional task_hint parameter, which implies 'gather context around files for a task', but that is inference rather than guidance. No exclusions or prerequisites are given.

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 and destructiveHint=false, so the safety profile is covered structurally. The description adds that results come back as one consolidated report, but says nothing about cost, depth of analysis, or what 'rule violations' and 'conventions' are measured against.

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 purpose sentence is front-loaded and the Args list is compact with no filler. Slightly under-specified rather than verbose, which costs nothing in structure terms.

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 four optional parameters, no output schema, and a report-producing behavior, the definition leaves open what the report contains, whether findings are per-file or aggregated, and what max_tokens bounds. Annotations cover safety, but the operational picture is only partially filled in.

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 25%, so the description must compensate; it does for files (default = git changed files) and mode (quick = security only, full), which the schema leaves bare. It is silent on max_tokens (what it bounds — report size or analysis effort) and workspace, so half the parameters remain undocumented.

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

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

States a specific verb+resource ('Review changed files') and enumerates the three dimensions checked (security, rule violations, conventions) plus the single-report output. An agent can distinguish it from suggest_tests or impact_analysis, 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 Args block implies usage context: files default to git-reported changes and mode selects security-only vs full review. However, it never says when to pick this over sibling tools like suggest_tests or relevant_context, nor when 'quick' is preferable beyond the parenthetical.

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 and destructiveHint=false, so safety is covered. The description earns credit for disclosing ranking behavior ("best match first: exact, prefix, substring...") which the annotations cannot convey. It does not mention result-set bounds (limit default 30, max_tokens truncation) or what the results contain, which matter for a search tool with no output 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?

The purpose is front-loaded in one sentence followed by a compact args list; nothing is padded. The args block does useful work (enumerating kind values, explaining task_hint) rather than merely echoing types, so its length is justified.

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

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

There is no output schema, and the description never indicates what a match looks like or that results may be truncated by max_tokens/limit, which an agent needs to interpret an empty or short result list. For a 6-parameter tool with one-third of parameters undocumented and no return-value guidance, it is adequate but leaves real 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 only 17% (only `workspace` is described), so the description must compensate; it documents 3 of 6 params (name, kind, task_hint) and helpfully enumerates the `kind` values even though the schema declares no enum. `limit`, `max_tokens` and `workspace` are left entirely to the schema, 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 and resource ("Find symbol definitions by name") and adds the matching strategy (exact, prefix, substring, camelCase/snake_case parts). It does not name the closely related siblings (symbols, inspect_symbol, fast_search, semantic_search), so an agent still has to infer which lookup tool to pick.

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

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

The matching-strategy sentence implicitly frames this as the tool for name-based lookup, and 'best match first' suggests it is the right first stop when a name is known. But there is no explicit when-to-use/when-not statement and no mention of alternatives such as inspect_symbol (for details on a found symbol) or semantic_search (for description-based lookup).

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 cover the read-only safety profile, and the description adds genuinely new behavioral context: the ranked return format ('best first'), the latency implication that vector mode waits for embeddings, and the constraint that branch only applies to remote service while local search reads the working tree. It does not mention limits on result size or how top_k/max_tokens interact, which is a minor gap.

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

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

The one-sentence purpose statement is front-loaded and the args list is compact with no filler. Each line adds information, though the args block could have absorbed the two undocumented parameters instead of stopping at four.

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 seven-parameter tool with no output schema, the description does cover return shape and the trickier parameters (mode, branch, file_filter). It falls short on the token-budget parameters (top_k, max_tokens) and does not explain the workspace default beyond what the schema already says, so an agent cannot fully predict result size.

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

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

Schema coverage is only 14% (workspace alone is documented), so the description must carry the load and it does document four of seven parameters with concrete examples for query, file_filter, and mode defaults. However, top_k and max_tokens — the two parameters that control result volume and token budget — are left completely unexplained, leaving meaningful gaps.

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

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

States a specific verb and resource — 'search the code by meaning with a natural-language query' — and describes the return shape ('files, functions and classes, best first'). The 'by meaning' phrasing implicitly separates it from keyword-oriented siblings like fast_search and search_symbols, but no sibling is named explicitly, and the presence of a 'keyword' mode slightly blurs 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?

Usage context is implied through the mode options and the note that 'vector' mode 'waits for embeddings', which tells the agent when a mode is slow. It never says when to prefer this tool over fast_search, search_symbols, or explore_codebase, so the agent must infer routing from the sibling names.

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 and destructiveHint=false, so the safety profile is covered. The description adds only that suggestions are derived from imports and syntax and are 'candidate' (i.e., advisory, not written), but says nothing about how many suggestions come back, cost, or how max_tokens constrains output.

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 compact sentence with the core action front-loaded and the optional modifiers trailing, which matches the required-vs-optional split. It is efficient, though the terseness borders on under-specification.

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 5 parameters, 20% schema coverage, and no output schema, the description carries the burden of explaining the files input and the token budget but does neither. An agent cannot confidently assemble a call from this definition 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 coverage is only 20% — just 'workspace' is documented. The description hints at symbol_name and task_hint, but files (what paths? source files? test files?), the 2000-default/32000-max max_tokens budget, and workspace's meaning beyond the schema line are all left unexplained.

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

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

States a specific verb and resource ('suggest candidate tests') plus the basis for suggestions (imports and syntax) and the optional narrowing axes (symbol, task). An agent can tell this apart from all listed siblings, none of which deal with test generation, though the description never explicitly contrasts with them.

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

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

'optionally focus on a symbol and task' implies when symbol_name and task_hint are worth supplying, but there is no explicit when-to-use/when-not guidance, no prerequisites, and no mention of what to do when the caller has no symbol in mind.

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 and destructiveHint=false, so the safety profile is covered. The description adds that results are limited to symbols the file itself defines, which is useful scope information, but says nothing about output ordering, truncation via max_tokens, or behavior on unparseable files.

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

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

A single front-loaded sentence with no filler. Every word contributes to defining the resource and its file scope.

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

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

The tool is simple and the annotations cover read safety, but the description leaves the two optional parameters and result shape unexplained. For a three-parameter tool with low schema coverage, it is adequate rather than complete.

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

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

Schema description coverage is only 33%, with workspace documented in the schema and path required but unannotated. The description mentions the file implicitly but does not explain path, workspace, or the max_tokens budget, so it does not compensate for the low coverage.

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

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

States a specific verb+resource: listing functions, classes and methods, with the scope narrowed to what a given file defines. This distinguishes it from siblings like search_symbols or inspect_symbol, though it does not name an alternative explicitly.

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

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

There is no guidance on when to use this versus search_symbols, inspect_symbol, or cross_references. The agent must infer that this is a file-scoped listing tool rather than a search or detail tool.

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