repowise

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

Goes well beyond the readOnly/openWorld annotations: it explains confidence tiers and how to treat each, that medium confidence retains verification evidence, that candidate_files ranks files not named in citations, and that the tool degrades gracefully when embeddings or synthesis fail. It also discloses hard output limits (24,000 serialized chars, 32,000 with evidence) and that reductions carry totals, counts, reasons, and a recovery call.

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

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

Front-loads the core purpose, then layers confidence semantics, limits, and a structured Args section. Some sentences are telegraphic to the point of ambiguity ('Reductions carry totals, emitted counts, reasons, and a recovery'), but little is wasted.

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

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

With an output schema present, the description appropriately focuses on behavior, truncation, and degradation rather than return values, and it documents all four parameters. It stops short of stating relationship to sibling tools, which is the main remaining ambiguity for an agent choosing between them.

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 Args block is doing essential work: it defines scope as a repository-relative path prefix, tells the agent repo is usually omitted, and enumerates the meaningful include values (evidence, diagnostics) with their effects. Only gap is no guidance on question phrasing or scope format examples.

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

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

States a concrete verb+resource+scope: answer a how/where/why question over a repository with grounded evidence in one call. It is distinguishable from search_codebase (retrieval) and get_symbol (lookup), though it overlaps noticeably with the sibling get_why without acknowledging 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?

Implies when to use it (how/where/why questions, single-call evidence-grounded answers) but never says when NOT to use it or names an alternative. The existence of a sibling named get_why makes an explicit routing statement the obvious missing piece.

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 and openWorldHint, yet the description adds substantial interpretation context the agent could not otherwise know: risk_percentile and diff_shape measure size not danger, partial health means code files were skipped, findings sort change-written above pre-existing, and an empty diff returns status "nothing_to_score". These are genuine behavioral disclosures beyond the annotation layer, not restatements.

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 and args are front-loaded and the paragraph/Args layout is clean, but roughly half the text explains output fields (directive, health_delta, impacted_tests, patch_coverage, fix_history, overlap, branch_overlap) despite an output schema already existing. Some of that interpretation is valuable, but much of it is redundancy that crowds out the more useful scoping and routing 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?

For an 8-parameter, output-schema-backed read tool, coverage is strong: every param is documented, edge cases (empty diff, clean tree, partial health) are handled, and the read-only nature is clear. The one gap is that it never positions itself against the sibling get_risk, which shares the risk vocabulary and is the most likely source of mis-selection.

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 carries the full burden and does: all eight params are explained, including non-obvious details such as include_paths accepting either a list or a single comma-separated string, baseline's default of 200 and that 0 disables percentile ranking, and what finding_id expands. This is meaning well beyond the bare JSON schema types.

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 first sentence gives a specific verb and resource ("Review a commit, base..head range, or uncommitted work") and the scope is clearly change-level rather than repo-level. It does not, however, name or distinguish itself from the sibling get_risk, leaving the agent to infer how change-scoped risk differs from whatever get_risk reports.

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 through the args ("Omit to review uncommitted work, or HEAD when the tree is clean", "0 disables" baseline), which is real operational guidance for calling it. But there is no explicit statement of when to pick this over get_risk or get_health, and no prerequisites or exclusions, so the agent still has to infer sibling routing.

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

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

Beyond the read-only annotation, the description discloses important operational behavior: no source bytes by default, char budgets of 24,000/32,000, reduction metadata and recovery refs, and storage-failure signaling via _meta.recovery_unavailable. It also clarifies absence semantics (episodes absent at zero), aggregation rules, and how include-gated projections differ from omissions.

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 information-dense and front-loads purpose and behavior before the Args section, with little wasted text. However, the shorthand-heavy, multi-idea lines and long include list make it less scannable than ideal for an agent under time pressure.

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 five parameters, no schema descriptions, and an output schema, the description covers the missing semantic and behavioral pieces needed to call the tool correctly. It explains return-shape cues, include opt-ins, budget behavior, and alternatives, so an agent has enough context to select and invoke it appropriately.

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%, but the description compensates thoroughly with an Args section explaining each parameter. It documents accepted target formats ('path::Symbol', 'component:<name>', 'change:<id>', 'package:<name>'), the include block list, compact=False behavior, repo omission, and symptom usage.

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

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

The description states a specific resource and scope: a 'triage card for files / modules / symbols — relationships, not source bytes.' It further distinguishes itself from siblings by telling the agent not to call get_symbol per signature and by routing source-body needs to Read or get_why.

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 explicit when-to-use and when-not-to-use guidance: fix_history/hotspot is 'a cue to call get_risk,' get_why serves bodies, and symbol signatures should not be fetched one-by-one via get_symbol. It also names task-specific alternatives, such as using include=["references"] for rename or update-all-callers work.

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?

Beyond the readOnlyHint/openWorldHint annotations, the description discloses several non-obvious behaviors: workspace mode withdraws safety on findings other repos may use, an unrecognized kind is dropped and reported in ignored_arguments rather than silently matching nothing, limit is clamped to 25, include_internals raises false positives, and include_unverified corresponds to the summary.gated count. These are exactly the operational details an agent cannot get from structured fields.

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 purpose sentence, then usage, then behavior, then a scannable args block — the structure is easy for an agent to parse. A minor redundancy exists in restating tier-name acceptance under both min_confidence and tier, and the arg list is long, though justified by 15 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?

With 15 optional parameters and 0% schema coverage, this description is complete enough to call the tool correctly on the first attempt, including output-shape hints (per-directory/per-owner rollups, summary.gated) even though an output schema already exists. No parameter or major behavior is left unexplained.

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 carries the full burden and does: every one of the 15 parameters is explained with defaults, accepted values, and edge semantics (min_confidence takes both a numeric floor and a tier name; tier bands as min_confidence; repo is usually omitted; finding_id is the stable emitted id). This is well beyond what the bare schema conveys.

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 line names the concrete resource class — unused exports, unreachable files, zombie packages — and adds the confidence-tiering angle, so the tool's function is unmistakable. It does not name any sibling tool to contrast against, so an agent must infer the boundary with get_health or get_risk on its own.

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?

"Run before a cleanup sprint, not a targeted fix" gives a clear when-to-use and an explicit when-not-to-use condition, which is unusually direct for a codebase-analysis tool. It stops short of naming the sibling (e.g. get_symbol or get_why) that should handle a targeted lookup 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?

Annotations already cover read-only and closed-world, so the bar is lower, and the description still adds real behavior: it never recomputes, requires a prior update run, returns a fix_first-led dashboard absent targets, routes misses into unresolved, and explains that only-keys like performance/defect get filtered into unknown_only_keys. That is meaningful beyond the annotations.

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 front-loading is correct — purpose, then workflow, then args — and there is little outright filler for 23 parameters. However the Args block is a compressed wall of double-backtick fragments, and it defers the authoritative detail ('Every block and accepted value') to an external doc file the agent may not be able to read, which undercuts the description's self-sufficiency.

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 no prose, and the description covers the mutation-free behavior, the freshness prerequisite, and most parameters of a 23-arg tool. The remaining shortfall is the vague filter families, acceptable given the tool's breadth but not 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 0% across 23 parameters, so the description carries the full burden and largely does: targets, include (with the full enumerated list), only, limit/cursor semantics, the three id types, opportunity_id, and scope/counts defaults are all explained. Gaps remain for the queue filter params, which are dismissed collectively as 'queue filters' without listing accepted values.

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?

Opens with a concrete statement of the resource: code-health scores and findings from stored analysis, plus the key constraint that it never recomputes. This separates it from write/index siblings, though it never explicitly contrasts itself with get_overview, get_risk, or get_dead_code, so the agent must infer the boundary.

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 does explain two usage modes (no targets = dashboard led by fix_first; with targets = ranked files/findings) and states the stale-data workflow (commit, then run repowise update). But there is no guidance on when to pick this over sibling tools like get_overview or get_risk, and exclusions are absent.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, and the description adds real operational context: default 24,000-char budget rising to 32,000 with a nonempty include, plus reduction counts and recovery status reported in _meta, and the note that include-gated blocks are projections rather than omissions. It does not describe error behavior or how long an initial index takes, 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?

Front-loaded with purpose, then cadence, then budget, then parameter detail — a sensible ordering. The Args block restates the schema parameters, which is defensible given 0% schema coverage, but the budget/reduction sentences are dense and slightly repetitive with the 'compact by default' framing.

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 the description still covers what each include block adds, what the defaults return, token budgets, and _meta reporting. Nothing needed to call it correctly is missing.

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

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

Schema coverage is 0%, so the description carries the full burden and does: repo is documented as alias/path/ID/'all' with default-repo semantics, and include is enumerated with a one-line meaning for each of the ten block names and pointers to richer siblings (get_why for decisions). This is exactly what the schema lacks.

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?

Opening line states the specific job — orientation for an unfamiliar repo — and enumerates the concrete payload (packages, entry points, riskiest files, top actions). It explicitly differs from siblings by naming get_context and get_answer as the follow-on 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?

"Once per session; then use get_context or get_answer" gives an explicit when and names the alternatives with their selection condition. It also covers the workspace/no-repo case (omit repo, use an alias, or 'all'), so an agent knows which invocation mode applies.

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 and closed-world, but the description adds substantial context: response size budgets (24k default, 32k with include), reduction counters with _meta.omitted, _meta.recovery_unavailable on storage failure, and that structural reach is not proof of runtime breakage. The only shortfall is that include-gated versus omitted blocks are described abstractly rather than operationally.

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 first line front-loads the core purpose and the key sibling routing appears early, which is good. The middle is dense with parenthetical jargon and near-duplicative caveats (counts are a floor; structural reach is not proof; blocks are projections not omissions), which cost readability without adding much.

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 spelled out, yet the description still explains the directive fields and tests_to_run_basis, which is necessary for correct invocation. Coverage is strong; the main gap is that repo's role and the interplay between include values remain under-specified.

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

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

Schema coverage is 0%, so the description must carry all parameter meaning; it defines targets (defaults to changed_files), changed_files for blast mode, and enumerates the include blocks (graph, churn, owners, tests, blast, scales, changes). However repo is dismissed as 'usually omitted' with no explanation of what supplying it does, and the blast/scales coupling is only partially explained.

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

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

States a concrete resource and verb: it reports history (bug fixes, churn, owners) fused with graph topology for given files. It explicitly distinguishes itself from the sibling get_change_risk, so an agent can route without opening either schema.

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

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

Gives explicit mode selection: pass changed_files for PR mode, and use get_change_risk instead to score a commit or base..head range. It also warns that directive.reach is uncalibrated and not a breakage probability, which is a usage constraint.

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 this as a safe, closed read (readOnlyHint=true, openWorldHint=false), so the description is not obligated to cover safety. It nonetheless discloses beyond-annotation behavior an agent must plan around: ambiguity returns every candidate, index misses fall back to live lines, truncated results carry the exact continuation to pass straight back, and depth 2-3 populates callee_bodies.

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

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

Front-loaded with the routing constraint before any mechanics, and the Args block is long but earns its length given 0% schema coverage. Minor redundancy in re-explaining the reference parameter's purpose in two places keeps it from a perfect score.

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 the description still usefully characterizes return shape (verified line-numbered source, candidate lists on ambiguity, live fallback on index miss, continuation on truncation), which is more than required. Combined with full parameter documentation and explicit sibling routing, an agent has everything needed to invoke it correctly.

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

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

Schema description coverage is 0%, so the description carries the full burden, and the Args block documents all seven parameters including the accepted id/symbol_id alias, the 0-50 bound on context_lines, the depth 1-vs-2-3 distinction, the omission-ref-only restriction on query, and the fallback rule that query is read as symbol_id when no id is given.

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

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

States a specific verb and resource ('follow-up read of one symbol whose id another response already gave you') and immediately demarcates it from siblings by declaring 'Not an entry point' and naming get_answer, get_context, and plain Read as the entry paths. An agent can distinguish this from the nine sibling tools without opening any schema.

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

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

Gives explicit when-to-use ('Reach here for a body that was elided, or for a continuation / omission ref') and explicit when-not ('Not an entry point', 'Never walk a file symbol by symbol'), each paired with the named alternative that should be used instead. There is no inference required to route correctly.

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 safety profile, but the description adds real behavior: a git-archaeology fallback that is 'never empty', and interpretation rules for `authority`, `answer_basis`, and `provenance` (matching ids are shared evidence, not corroboration). That epistemic caveat is genuinely useful context an agent could not infer from the schema.

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

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

Front-loaded with the purpose and the call trigger, then progressively more detailed semantics. The authority/answer_basis paragraph is dense and slightly repetitive ('candidate is the weakest' restated), and the reStructuredText double-backtick markup is noise, but almost every sentence carries information.

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

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

An output schema exists, so return values need not be spelled out, yet the description still explains how to read the key fields and what the weakest answer basis means — covering a five-parameter tool with no documented params. Minor gap: no guidance on combining id/reference with query or targets.

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 load, and it does: query, targets, repo ('usually omitted'), id (decision or ev_ id), and reference are each explained in behavioral terms. The `reference` entry stays abstract — 'structured evidence reference' with no shape given — which keeps it from a 5.

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 first line names the specific resource — decision records plus evidence commits — and the retrieval intent (explaining why code is shaped as it is), which separates it from peers like get_symbol or search_codebase. It never names a sibling directly, so the differentiation is inferred rather than 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?

Gives a clear trigger ('Call before refactors or pattern divergences') and enumerates four concrete query modes, including the no-query dashboard case, so the agent knows how to start. It stops short of stating when to prefer a different tool or when this tool is unnecessary.

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 and openWorldHint; the description goes well beyond, disclosing ranking behavior (decision records rank below file pages unless why-shaped), which row fields appear under which conditions (`path`, `symbols`, `matched_lines`, `candidates`, `lines`), and the important `complete` flag meaning no further grep is 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?

Front-loaded with purpose and the get_answer exclusion, then progressively deeper detail. The returns paragraph is dense but nearly every clause carries actionable information; a sentence or two could be tightened, but nothing is padding for its complexity level.

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 8-parameter, 5-mode hybrid search tool with 0% schema coverage, the description covers purpose, routing, per-mode behavior, parameter semantics, and return shape. An agent has everything needed to choose a mode and call it correctly despite an output schema and annotations that alone would be insufficient.

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 all eight parameters are documented in the Args block with meaning the schema lacks: limit counted as distinct files except in symbol mode, page_type values, kind enum values, repo='all', the mode enum with its dispatch semantics, and pattern as an alias for query.

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?

Opens with a specific verb and resource ('Find code by concept, symbol, or path — hybrid codebase search') and immediately contrasts itself with get_answer ('runs this retrieval internally and returns a cited answer'). An agent can distinguish this from every sibling without reading the schema.

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

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

Explicitly states when to route elsewhere (question-shaped queries → get_answer) and when to use this tool (enumerating matches, resolving an identifier to a symbol_id, scoping get_context). It even explains how mode='auto' dispatches by query shape, which is the core routing decision an agent must make.

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