repowise

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

Beyond the readOnly/openWorld annotations, the description discloses the confidence-tiering behavior and how medium/low results are presented (leading with evidence to verify), plus that `candidate_files` surfaces files the citations don't name. That is real behavioral context an agent could not infer from annotations alone; it stops short of describing failure modes or latency.

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 action and the confidence contract in the first two lines, then a compact Args block. Every sentence carries operational information; there is no filler or restatement of the title.

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 still adds the interpretive layer (confidence meaning, `candidate_files`, `retrieval_quality`) that the schema alone would not convey. The only real gap is the missing routing guidance among the many sibling retrieval tools.

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

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

Schema coverage is 0%, so the description must carry the burden, and it largely does: `question` is constrained to one question about one subject with an explicit anti-pattern, `scope` is defined as a repository-relative path prefix, `repo` is marked as usually omitted, and `include` gives concrete values with the effect of `diagnostics`. `repo` remains thin (no format guidance) and `include` gives examples rather than the full accepted set.

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 — answering a how/where/why question in one evidence-grounded call — and clarifies the confidence contract. It does not differentiate itself from the sibling `get_why`, which by name appears to answer overlapping 'why' questions, leaving an ambiguity an agent must resolve 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?

Gives useful in-call guidance: split multi-part questions into separate calls, don't paste whole tasks, and treat high confidence as usable vs. medium/low as needing evidence verification. However, it never says when to prefer this over `search_codebase`, `get_context`, or especially `get_why`, so tool selection among siblings 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 establish a safe read-only, closed-world operation, and the description adds real substance on top: it says the response leads with directive/status and health_delta, that risk_percentile and diff_shape measure diff size rather than danger, and that impacted_tests names tests to run. That clarification of misleading-looking metrics is exactly the kind of context annotations cannot convey; only rate limits or cost would add more.

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 front-loaded with the scope and the key output semantics before a tidy Args list, and nearly every line earns its place. The prose section is slightly dense but not padded.

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 an output schema exists, the description need not enumerate return values, yet it usefully explains the two most easily misread ones and covers all nine parameters with their defaults and formats. An agent has everything needed to call this correctly without opening the schema.

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

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

Schema description coverage is 0% across 9 parameters, so the description carries the entire burden, and it documents every one of them in a structured Args block, including defaults (baseline samples with 0 disabling), accepted values for include, and the comma-separated string form of include_paths. This is meaning the schema alone does not provide.

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 states a specific verb (review) and resource/scope (a commit, a base..head range, or uncommitted work), which is concrete and actionable. It does not explicitly contrast with the sibling get_risk, so an agent must infer that this tool is change-scoped while get_risk is presumably broader.

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 clear context on when to omit revspec (uncommitted work, or HEAD when the tree is clean) and when to set per_commit (with a range). It does not name alternatives such as get_risk or get_health, nor state exclusions, so it stops short of full routing 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 only declare readOnlyHint and openWorldHint, so the description carries most of the load and does add real behavioral context: results are body-elided and line-verified, compact=False adds structure/imports/docstrings, and risk cues imply escalation to get_risk. It stops short of covering pagination, result-size limits, or failure behavior for bad targets, 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?

It is front-loaded, fragment-dense, and almost every clause carries routing or semantic information. Minor cost: the long pipe-delimited include enumeration is a wall of terms and 'skeleton+' / 'skeleton' distinction is never clarified, which slightly hurts parseability.

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

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

For a five-parameter, multi-mode tool with an output schema (so return values need not be explained), the description covers the calling patterns, batching, elision behavior and sibling routing well. Remaining shortfall is per-value meaning for most include modes and no note of defaults, which an agent must infer from the schema.

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

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

With schema description coverage at 0%, the description does heavy lifting: it documents target syntax ("path::Symbol", "component:<name>", "change:<id>" as pr/sha, "package:<name>") and explains compact and symptom. The gap is the include list — a long enumeration where only skeleton, references, files and symbols get any meaning, leaving metrics, community, doc_drift, provenance, suspects and 'skeleton+' 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?

Opens with a concrete role — a triage card for files/modules/symbols that returns relationships rather than source bytes — and enumerates the concrete payload (summary, signatures with lines, hotspot, fix_history, decision titles). It explicitly distinguishes itself from get_symbol and get_risk, so an agent can choose between them without opening a 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 routing rules: 'either risk cue means get_risk', 'Batch targets in one call', and 'do not call get_symbol per signature' with the skeleton-or-Read alternative. It also supplies scenario recipes — rename via include=["references"], missing tests via include=["files"] — which is the strongest form of when-to-use 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 openWorldHint=false, so safety and locality are covered structurally. The description adds real behavioral context — confidence tiering, the meaning of safe_only (deletion-ready) and the 25-findings-per-tier cap — but says nothing about scan cost, latency, or how tiering interacts with min_confidence.

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 two-line headline states what it finds and how to think about it, then a dense arg list. No filler sentences, and the most decision-relevant point (sweep vs targeted fix) is front-loaded.

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 all 15 parameters are addressed. What's missing is guidance on how filters compose (e.g., passing kind alongside the no_* toggles, or tier vs min_confidence precedence) and any note on scan scope cost for a 15-parameter repository 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?

With 0% schema description coverage across 15 parameters, the description carries the entire burden and largely discharges it: kind's four values, min_confidence accepting either a number or a tier name with its 0.4 default, limit's ceiling, filter semantics for directory/owner, and explicit meaning for finding_id and repo. The bundled boolean toggles are described collectively rather than individually, which is a minor compression but still understandable.

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 exact finding types the tool produces (unused exports, unreachable files, zombie packages) and frames them as confidence-tiered, which is far more specific than the name alone. It does not name a sibling tool to contrast with (get_health or get_risk could plausibly overlap), 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?

"For a cleanup sweep, not a targeted fix" plus the min_confidence hint (0.7 = cleanup-ready) and safe_only as deletion-ready give a clear picture of when this tool applies. It never names an alternative tool for the targeted-fix case, so the exclusion half of the guidance is left implicit.

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, so safety is covered. The description adds genuinely non-obvious behavior: it never recomputes and requires an external `repowise update` to refresh, scope='production' drops non-production code, and counts='code_shape' removes the git-derived half of the score. Those are exactly the side effects and data caveats an agent needs.

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 key statement about dashboard-vs-targets and the never-recomputes caveat are front-loaded, and the Args block is terse with one line per parameter group. Some density is unavoidable at 23 parameters, though the repeated rST double-backtick noise and the pointer to docs/agent/MCP_TOOLS.md for 'every block and accepted value' push explanation out of the definition.

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 shapes need not be described, and the description covers the remaining essentials: freshness workflow, scoping options, default list size, and item-expansion IDs. It is only incomplete for the enumerated queue-filter values, which are deferred to an external document.

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: it enumerates the accepted include values, explains aliasing nuances for only (biomarkers/accuracy/refactoring alias their block, performance/defect/maintainability do not), and states limit defaults and cursor offset. The refactoring_*/performance_* filters are lumped together as 'queue filters' with no per-parameter meaning, 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?

The opening line states a specific resource and source: 'Code-health scores and findings from stored analysis.' The 'No targets: a dashboard led by fix_first' clause clarifies what the tool returns in its default shape. It does not name siblings like get_overview or get_risk, so the boundary with them is left 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 real usage context: omit targets for a dashboard view, and the data is stale unless you commit and run `repowise update`. However it never says when to prefer this over get_overview, get_risk, or get_dead_code in the sibling set, so routing between tools is inferred rather than stated.

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

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

Beyond readOnlyHint=true and openWorldHint=false, the description discloses output shape behavior: results are 'compact by default' with additional blocks available on request and discoverable via a `more` field. That is real behavioral context an agent cannot get from annotations. It stops short of saying anything about size, latency, or whether requesting many blocks is expensive.

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 routing rule, then parameter detail — every sentence carries information. Slightly clipped prose ('named in ``more``') and the double-backtick markup make a couple of lines harder to parse than necessary.

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

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

For a zero-required-parameter orientation tool with an output schema, the essentials are present: what it returns, how to expand it, when to call it, and how to scope by repo. The remaining gap is that the mechanics of requesting extra blocks (via `include` versus via `more`) and the meaning of each block are left implicit.

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 largely meets it: `repo` accepts an alias, path, or ID, and the special value 'all' for cross-repo links; `include` enumerates eleven valid block names. What it does not do is explain what each block contains or confirm these are the only accepted values, so the agent must guess at the cost of requesting each one.

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 the resource (a repo) and enumerates the concrete payload — packages, entry points, riskiest files, top actions — so the agent knows exactly what it gets. It also explicitly contrasts itself with get_context and get_answer, making it separable from siblings 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?

'Orientation for an unfamiliar repo' plus 'Once per session; then use get_context or get_answer' gives both the triggering condition and the named follow-up alternatives. The recursion/frequency limit (once per session) is stated outright, which is unusually strong 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 only declare readOnlyHint and openWorldHint, so the interpretive burden is on the description — and it delivers: dependents/co_change_partners are 'a floor and correlation, not proof of runtime breakage', and directive.reach is 'never a breakage probability'. These are exactly the misinterpretation traps an agent would otherwise fall into.

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 punchy first line front-loads the purpose, and the caveats follow in a logical order (signals → caveats → PR mode → alternatives → args). It is dense but not padded, though the docstring-style Args block and reST literals make it read more like source documentation than agent-facing prose.

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 needn't enumerate return fields, and it wisely spends its words on mode selection, directive field names, and interpretation caveats instead. The only thin spot is default behavior when both targets and changed_files are omitted.

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, and it largely does: targets defaults to changed_files, include enumerates valid values ('graph', 'churn', 'owners', 'scales', 'changes') plus mode-gated ones ('tests', 'blast') with brief meanings, and repo is 'usually omitted'. It stops short of stating path format (repo-relative vs. absolute) or what each include value returns in detail.

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 ('What history says about touching these files — bug fixes, churn, owners') plus the git-signal list makes the resource clear: a history-based risk read for a set of files. It explicitly distinguishes itself from the sibling get_change_risk ('For a commit or range use get_change_risk'), though the verb is implied by the name rather than stated outright.

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 names the two operating modes (targets-only vs. PR mode via changed_files) and the exact conditions that select them, and routes commit/range lookups to get_change_risk by name. It also tells the agent what to read first in PR mode ('the response leads with directive ... read it first').

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, but the description still adds real behavior: results are "verified, line-numbered source" and a truncated result carries a continuation to pass back. That truncation/continuation contract is not derivable from annotations. It stops short of the full picture (e.g. what happens when the id is stale or ambiguous), so not 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?

Front-loaded and well organized: the core statement comes first, routing second, then an Args block, which is easy to scan. Minor overhead from backtick-heavy markup and the "Args:" label on a description that is already structured, but 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?

For a 7-parameter read tool with an output schema and safety annotations, everything an agent needs to call it correctly is present: purpose, routing, id format, depth semantics, and truncation handling. Return-value detail is correctly left to the output schema rather than duplicated.

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: it gives accepted symbol_id formats (path::Name, path:140-180 range, omission ref), rules out bare file paths, explains depth=1 vs 2-3 returning transitive callee_bodies, bounds context_lines to 0-50, describes query as a regex/substring filter on omission refs, and flags id/reference as aliases and repo as usually omitted.

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 states a specific verb and resource ("Follow-up read of one symbol") and pins the input to an id obtained elsewhere. It explicitly contrasts itself with get_answer and get_context, so an agent can distinguish it from siblings 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?

Strongest part of the definition: "Not an entry point" plus concrete routing to get_answer (for symbol_bodies), get_context with include=["skeleton"], or a plain Read, and an explicit anti-pattern ("Never walk a file symbol by symbol"). That is when-to-use, when-not-to-use, and named alternatives all at once.

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 (readOnlyHint=true, openWorldHint=false), yet the description adds real behavioral context: it falls back to git archaeology rather than returning empty, and it explains how to read results via ``authority: accepted`` and ``answer_basis``. That is genuine disclosure beyond structured fields, though it stops short of describing result shape or latency/cost.

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 and activation trigger are front-loaded, and the Args block is compact. The doubled-backtick markup is noisy and the query/shape guidance is repeated between the body and Args, but nothing is badly padded.

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

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

For a five-parameter, all-optional tool with zero schema descriptions and an output schema, the description supplies the missing decision rules (which input combos are legal, what the fallback is, how to interpret authority). The gap is the undocumented ``reference`` object and how ``id`` interacts with ``query`` when both are supplied.

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 burden and does document all five args at a surface level, including the useful ``ev_...`` id hint and the "omit for the dashboard" default. However, ``reference`` is dismissed as "structured evidence reference" with no shape at all despite being a free-form object, and ``repo: usually omitted`` gives no guidance on when it is not.

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 both the resource (decision records + evidence commits) and the question it answers ("why this code is shaped this way"), which is a distinct job from siblings like get_health or get_dead_code. It doesn't explicitly name a sibling it is not, so it falls short of a 5, but the purpose is unmistakable.

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?

"Call before a refactor or pattern divergence" gives a concrete activation trigger, and the description enumerates the accepted input shapes (question, path, question+targets, or nothing for the dashboard). It never states when to prefer get_answer or get_context instead, so it stops short of full alternative 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?

Annotations only declare readOnlyHint and openWorldHint, so the description carries the rest: it discloses that identifier/literal queries return `lines` read from live files with definitions first, that `complete=true` means no grep is needed, and that `candidates` is ordered best-first. That is real behavioral context beyond the annotations, though the existence of an output schema means some of it is reinforcement rather than new information.

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 exclusion before any detail, then a compact behavior sentence, then a structured Args block. Every clause adds routing or invocation value; nothing is repeated from the annotations or 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?

Eight optional parameters, zero schema descriptions, and an output schema — the description covers all parameters, the return-shape routing (`lines` vs `candidates`), and the completeness guarantee. An agent has everything needed to choose the right mode and interpret the result.

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 schema declares no enums, so the description does all the work — and it does it: every one of the eight parameters gets meaning, including the mode enum (auto/symbol/path/concept/hybrid), kind values, symbol_kind, page_type, `repo` accepting "all" for workspace-wide, and `pattern` as an alias for query. This fully compensates for the empty schema.

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

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

The opening sentence names a concrete verb (find) and resource (code) and scopes it three ways: concept, symbol, path, plus 'hybrid codebase search'. It immediately distinguishes itself from the sibling get_answer, so an agent can pick between them without opening a 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?

Explicit routing: 'For a how/where/why question call get_answer' states when NOT to use this tool, and the three named use cases (enumerate matches, resolve identifier to symbol_id, find files for get_context) cover when to use it. Both alternatives are named directly.

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