High confidence is content-grounded and may be used directly. Medium
confidence keeps the smallest verification evidence; low confidence leads
with an actionable local conclusion and ranked evidence. ``candidate_files``
ranks the files worth opening that the citations do not name. Provider keys and
network access are optional: local source, symbols, FTS, rationale, and
data-shape evidence remain usable when embeddings or synthesis fail.

Responses fit 24,000 serialized characters. Pass ``include=["evidence"]``
for the deduplicated expanded projection, capped at 32,000. Reductions carry
totals, emitted counts, reasons, and a recovery: the same call with that include.

Args:
    question: Developer question.
    scope: Optional repository-relative path prefix.
    repo: Usually omitted; a workspace alias when needed.
    include: Optional ``["evidence"]`` expanded projection.

Leads with ``directive`` (what to do) and ``health_delta`` (what this
change newly made worse). Findings are reported only when the diff explains
them, name their ``attribution`` basis, and sort change-written above
pre-existing.

Trust ``health_delta.status``: ``partial`` means files were skipped and the
change is not cleared.

``impacted_tests`` keeps measured coverage and inferred candidates distinct.
``patch_coverage`` is the share of changed executable lines stored coverage
ran; ``hints`` name tests to extend. ``fix_history`` is the changed files'
bug-fix record, ``overlap`` the past fixes on these exact lines,
``branch_overlap`` other branches editing them. ``diff_shape`` is one line
on size, not a danger verdict. An empty diff returns
``status: "nothing_to_score"``.

Args:
    revspec: Commit or ``base..head`` range. Omit to review uncommitted
        work, or ``HEAD`` when the tree is clean.
    repo: Repository alias in workspace mode; omit for the default.
    extensions: File suffixes to count, e.g. ``[".py", ".ts"]``.
    exclude_patterns: Gitignore-style paths to omit, e.g. ``["tests/"]``.
    include_paths: Gitignore-style paths to keep, as a list or one
        comma-separated string, e.g. ``"src/api/,src/db/"``. Omit for all.
    baseline: Recent commits sampled for percentile ranking; 0 disables it.
    include: ``"findings"``, ``"diagnostics"`` (raw score mechanics) or
        ``"scales"`` (units).
    finding_id: Expand one ``health_delta`` finding by its id.

Returns title, summary, signatures with line numbers, hotspot bit, and
decision_record titles. A symbol row without symbol_id is path::name.
fix_history appears only on files with counted bug fixes (count, age,
bug_magnet); hotspot is churn. Either one is a cue to
call get_risk. episodes counts the dated records bound to a target — what
happened here and why — and appears only when there is at least one;
get_why serves the bodies. A symbol target is counted as its file, and a
module aggregates everything beneath it.
Batch targets in one call. No source bytes by default: pass
include=["skeleton"] for the whole file body-elided and line-verified in
ONE call, or Read it. Do not call get_symbol per signature.

Default responses fit 24,000 serialized chars; nonempty ``include`` uses
32,000. Reductions carry counts and ``_meta.omitted`` recovery refs;
``_meta.recovery_unavailable`` names a storage failure.
Include-gated blocks are projections, not omissions.

Args:
    targets: file paths, module paths, or "path::Symbol" ids.
    include: opt-in blocks: full_doc | ownership | last_change | callers
        | callees | metrics | community | decisions | skeleton | health
        | doc_drift (documents naming this file) | symbols (all of a
        file's symbols; the default lists the top 15, classes and
        functions first).
        An unrecognised key is named in ignored_arguments.
    compact: default True; False adds structure+imports+docstrings.
    repo: usually omitted.

Run before a cleanup sprint, not a targeted fix. Findings tier
high/medium/low with per-directory and per-owner rollups; workspace
mode lowers confidence on findings other repos import.

Args:
    repo: usually omitted.
    kind: unreachable_file | unused_export | unused_internal | zombie_package.
        An unrecognised value is dropped and named in ignored_arguments,
        never applied as a filter that matches nothing.
    min_confidence: floor, default 0.4 (0.7 = cleanup-ready only). Also
        accepts a tier name: "high" | "medium" | "low".
    safe_only: deletion-ready findings only (no runtime-load risk).
    limit: max findings per tier (clamped to 25).
    tier: "high" | "medium" | "low", banded as min_confidence.
    directory: path-prefix filter.
    owner: primary-owner filter.
    group_by: "directory" | "owner" rollup.
    include_internals: also scan private symbols (more false positives).
    include_zombie_packages: monorepo package findings (default true).
    no_unreachable: skip file-level reachability findings.
    no_unused_exports: skip public-export findings.
    finding_id: stable ``id`` emitted by a dead-code finding.

No ``targets``: a dashboard led by ``fix_first``, what to fix first;
targets rank files and findings.
Never recomputes health: commit, then run ``repowise update``.
Every block and accepted value: docs/agent/MCP_TOOLS.md.

Args:
    targets: file paths or ``module:<name>``; misses land in ``unresolved``.
    include: ``biomarkers``|``refactoring``|``trend``|``coverage``|
        ``accuracy``|``signals``|``churn_complexity``|``doc_drift``|
        ``semantics``, or a dimension incl. ``advisory``; ``performance`` and
        ``refactoring`` add queues.
    only: keys to keep; identity, totals, recovery survive.
        ``biomarkers``/``accuracy``/``refactoring`` alias their block key;
        ``performance``/``defect``/``maintainability``/``advisory``
        do not: they filter rows into ``unknown_only_keys``.
    repo: usually omitted.
    limit: max rows per ranked list, ``0`` for none.
    cursor: zero-based offset into a ranked list.
    fix_id/finding_id/plan_id: stable ``id`` of an item, finding or plan.
    opportunity_id: ``perf...``/``refop...``: the unit, its steps or
        plan, evidence paged by ``only=["*_evidence"]``.
    refactoring_view: ``diversified`` (default)|``canonical``|
        ``file_spread``; _type/_confidence/_effort/_scope filter.
    performance_view/_context/_boundary/_confidence/_actionability/_sort:
        queue filters.
    scope / counts: default ``all``/``everything``. ``production`` drops
        test files; ``code_shape`` drops git-derived score and findings.

Returns the overview summary, key modules, entry points, architecture
layers and package dependencies, code health, repo-wide git health, and
``next_actions`` (top work for the week and quarter).
Skip this on subsequent calls — once you have the map, jump straight to
``get_context`` / ``get_answer``.

Compact by default: ``content_md`` carries only the overview essay's summary
section, and the outline, onboarding, ownership and graph blocks ship only
on request. The response's ``more`` field names them.

Defaults fit 24,000 chars; nonempty ``include`` uses 32,000. Reductions
carry counts and recovery status in ``_meta``.
Include-gated blocks are projections, not omissions.

In workspace mode:
- Omit ``repo`` for the default repo's overview plus a workspace footer.
- ``repo="all"`` returns the cross-repo topology (co-changes, package deps,
  API contracts) — no single-repo detail.
- ``repo="<alias>"`` targets one specific repo.

Args:
    repo: Repository alias, path, or ID. Use ``"all"`` for workspace overview.
    include: Opt-in extras, any combination of:
        ``"content"`` — the full overview essay instead of its summary.
        ``"outline"`` — the stored wiki page tree, two rungs deep.
        ``"tour"`` — ``guided_tour`` + ``reading_order`` onboarding walks.
        ``"decisions"`` — ``key_decisions``; ``get_why`` is richer.
        ``"graph"`` — ``community_summary``, code-community clusters.
        ``"ownership"`` — ``knowledge_map``: top 3 owners by files owned.

Fuses git temporal signals (``hotspot_score``/``owner_pct`` are 0-1; trend;
bus factor) with graph topology. ``dependents`` are directed structural
reach (source depends on target), ``consumers`` require typed contract links,
and ``co_change_partners`` are historical correlation only. Those counts
are a floor over the indexed graph. Structural reach is not proof of
runtime breakage. The response also includes security
findings. Pass changed_files for PR mode: the response leads with a
directive block (may_break, missing_cochanges, missing_tests,
tests_to_run) — read it first. Each test_recommendations row carries a
measured or inferred basis, and coverage availability is explicit. To
score a commit or ``base..head`` range instead, use ``get_change_risk``.

In PR mode ``structural_impact_score`` is an uncalibrated 0-10 structural
heuristic, never a runtime-breakage probability; ``overall_risk_score`` is
its deprecated exact alias.

Default responses fit 24,000 serialized chars; nonempty ``include`` uses
32,000. Reductions carry counts and ``_meta.omitted`` recovery refs;
``_meta.recovery_unavailable`` names a storage failure.
Include-gated blocks are projections, not omissions.

Args:
    targets: file paths to assess; defaults to changed_files.
    repo: usually omitted.
    changed_files: PR-changed files for blast-radius mode.
    include: opt-in blocks - "graph", "churn", "scales" (units and
        calibration for every scalar; identical per call, so ask once).

**Not an entry point.** ``get_answer`` already ships ``symbol_bodies``, and
for a whole file ``get_context(include=["skeleton"])`` or a plain Read is
one call instead of many. Reach here for a body that was elided, or for a
``continuation`` / omission ref. Never walk a file symbol by symbol.

Returns verified, line-numbered source for one indexed symbol, live range,
or omission ref. Ambiguity returns every candidate; an index miss returns
live fallback lines. A truncated result carries the exact continuation to
pass straight back.

Args:
    symbol_id: "path/to/file.py::Name", "path/to/file.py:140-180" for a
        live range, or an omission ref.
    context_lines: extra lines before/after (0-50).
    repo: usually omitted.
    query: omission refs only, regex/substring filter on lines.
    id: accepted alias for ``symbol_id``.
    depth: 1 (default) is this symbol alone; 2-3 also returns the bodies
        it calls, transitively, in ``callee_bodies``.
    reference: structured source reference emitted by this tool. Its id
        and repository are accepted together without caller translation.

Call before refactors or pattern divergences. Query modes: a question
("why is auth using JWT?"), a file path (governing decisions + origin
story + alignment score), a question anchored to targets, or no query
(decision health dashboard). Falls back to git archaeology when no
decisions exist for a path — never empty. Evidence-bearing rows carry an
explicit ``provenance`` and self-contained ``evidence_refs``; matching ids
mean shared evidence, not independent corroboration. Every decision row
carries ``authority``: ``accepted`` means somebody signed it, ``candidate``
means nobody has yet. ``answer_basis`` names the strongest lane the response
rests on (decision, episode, rationale, archaeology, documentation,
candidate); only ``decision`` is a ruling, and ``candidate`` is the weakest
-- it means nothing cleared that bar.

Args:
    query: question, file/module path, or omit for the dashboard.
    targets: optional file paths to anchor the search, or to ask about on
        their own when there is no query.
    repo: usually omitted.
    id: decision or ``ev_...`` evidence id emitted by this or another tool.
    reference: structured evidence reference. Its id and repository are
        accepted together without caller translation.

For QUESTIONS ("how does X work", "where is Y handled", "why is Z like
this"), call get_answer instead: it runs this same hybrid retrieval
internally and synthesizes a cited answer, so searching first is a wasted
round-trip. Use this tool for the raw ranked hits: enumerating matches,
resolving an identifier to a symbol_id, or scoping get_context.

mode="auto" (default) routes the query: identifier-shaped queries search
the indexed symbols (returns symbol_id/path/line bounds — pipe into
get_symbol), path-shaped queries resolve files (pipe into get_context),
and conceptual queries run wiki-semantic search. Mixed queries run hybrid:
symbol hits first, then file-backed pages only. Decision records rank
below file pages unless the query is why-shaped.

Rows naming a file carry `path`; `candidates` is up to `limit`
distinct files to Read, best first.

Args:
    query: identifier, path, or natural language.
    limit: max results (default 5); distinct files outside
        mode="symbol" (same-file symbols in `symbols`).
    page_type: restrict to one page type. Common: file_page (per-file
        docs, always present) or module_page (subsystem/concept pages).
        Any stored type filters (repo_overview, layer_page, scc_page,
        api_contract, infra_page, symbol_spotlight).
    kind: implementation | test | config | doc (concept/symbol modes).
    repo: alias, or "all" for workspace-wide.
    mode: auto | concept | symbol | path | hybrid.
    symbol_kind: filter symbol hits by kind (function|class|method|...).