Assess a multi-file changeset against a git baseline and roll the per-file verdicts into a project before/after (read-only). Use for a module split or any edit spanning several files. Each file is compared to baseline_ref (new files have no baseline). Flags complexity_relocated_within_file and project_regression. Returns a ChangesetResult.

Compare a baseline to a side-by-side proposed variant (read-only). For normal edit-in-place loops, use topos_assess_worktree_change or snapshot first with topos_begin_refactor then topos_assess_snapshot. This tool is for variants supplied as proposed_code or proposed_filepath. Returns an AssessmentResult with status and score/metric deltas.

Assess the current file against a baseline captured by topos_begin_refactor. Loads the stored baseline by snapshot_id and compares it to the current on-disk file, with the same status semantics as topos_assess_improvement. A missing or expired snapshot is reported via blocked_by.

Assess an in-place edit against a git revision — the common refactor loop. Stateless: the baseline is read from git (git show <baseline_ref>:<path>, default HEAD) and compared to the current working-tree file. No prior call required. For untracked/new files or an uncommitted pre-edit baseline, use topos_begin_refactor + topos_assess_snapshot. Do not call if you have not edited the file. A no-change result on a passing file has no next_tool.

Persist the file's current source as a baseline snapshot before you edit it (writes a snapshot record — its only side effect). Returns a snapshot_id; edit the file in place, then call topos_assess_snapshot(snapshot_id, filepath). Use this when the baseline is not a committed git revision.

Measure how well a test suite exercises its program-under-test, via structural (UAST) coverage (read-only). A standalone signal, separate from the four-pillar quality lattice; for a quality verdict use topos_evaluate_* instead. Computes UAST bipartite declaration matching and k-gram path recall. Returns a CoverageResult.

Compute the AST (tree-edit) distance between two source-code strings. Read-only and idempotent; parses both snippets in memory, never writes or scores. Use for clone detection or to measure refactor impact; the topos_assess_* tools already fold this in as an anti-gaming check, so call it directly only for the raw number. Returns a ComparisonResult: normalized_distance in [0, 1], similarity (= 1 - it), raw_distance, an operations edit-count map, and source_valid/target_valid (error set if either fails to parse).

Compute the AST (tree-edit) distance between two source files on disk. Read-only; parses both files, never writes or scores. Both files are parsed in the language their suffix names, the same way topos compare does; an unsupported suffix or two different languages is an error. Use for clone detection or refactor impact; use topos_assess_* for a quality verdict. Returns a ComparisonResult (see topos_compare_code).

Report .gitnexus availability and freshness (read-only). Distinguishes a missing graph from a stale one and from a load/schema failure, so an agent knows whether COMPOSABLE can be trusted and what to do next. Never shells out and never mutates state.

Score a raw code string on the SIMPLE / SECURE / NAVIGABLE quality lattice (read-only; never writes or runs the code). Use for a snippet not yet on disk. SIMPLE, SECURE, and NAVIGABLE are reachable here (CFG/CPG/UAST); COMPOSABLE needs a module dependency graph, so for it use topos_evaluate_file with gitnexus_dir, or topos_evaluate_project for a whole tree. Returns an EvaluationResult: the lattice verdict (SLOP…IDEAL), per-generator scores, and a next-step agent contract.

Score a file on disk on the SIMPLE / COMPOSABLE / SECURE / NAVIGABLE lattice — the only evaluate tool that can reach COMPOSABLE (side-effecting). Unless no_composable is set, this generates/refreshes .gitnexus (given by gitnexus_dir or auto-detected at <root>/.gitnexus) when it's missing or stale, then attaches the resulting ModuleDependencyGraph — the same default behavior as the CLI's topos evaluate. SIMPLE/SECURE/NAVIGABLE always run. When GitNexus isn't installed or generation fails, coupling_available is false and warnings explains why; the rest of the evaluation still succeeds. Do not call again when agent_contract.next_tool is absent: the file already passes, or this call already returned the edit span.

Recursively score every supported source file in a directory on the SIMPLE / COMPOSABLE / SECURE / NAVIGABLE lattice, with a project rollup (side-effecting). Autodetects all supported languages in one walk. Returns a summary by default: the rollup (aggregate_floor_verdict is the pillars every scored file holds), the five worst files with absolute paths and the metric behind each, counts, and warnings. detail: "full" returns per-file rows (limit / offset) and the named lists. Unless no_composable is set, generates/refreshes .gitnexus when missing or stale before scoring, same as topos_evaluate_file and the CLI's topos evaluate — coupling_available/warnings explain it when that isn't possible, without failing the evaluation. Do not call this for one file, or after a file already passed. It walks the tree. A person asks for the project rollup; an agent editing one file does not.

Generate the .gitnexus dependency graph via GitNexus (side-effecting). Ensures the graph by default: no-ops when current, otherwise runs gitnexus analyze. force=true always regenerates.

Return a Topos documentation page as Markdown. Use when your MCP client does not expose resource fetching to the agent. Clients that do surface resources should prefer the equivalent resource URI for efficiency: topos://docs/{topic}. Topics: agent-contract (compact loop contract, read first for refactors), lattice (the 16-element H(G_qual) over four generators), metrics (every metric key, thresholds, interpretation), preferences (strict generator rankings and preference walks), priority (priority profiles), workflows (the expanded refactor loop guide).

Full metric breakdown for a single code unit (inline string or file). Provide exactly one of code or filepath. Use when you need the per-function detail behind a verdict; use topos_evaluate_* when the medal alone is enough. Returns an InspectionResult: the lattice evaluation, a top-N function complexity table (top_n_functions, default 10), total_functions, and entropy details. With filepath, the verdict is scored on all four generators and agrees with topos_evaluate_file: unless no_composable is set, this generates/refreshes .gitnexus (given by gitnexus_dir or auto-detected at <root>/.gitnexus) when missing or stale, then attaches the ModuleDependencyGraph — so this tool is side-effecting. With inline code there is no module to place in the graph, so only SIMPLE/SECURE/NAVIGABLE are reachable, as in topos_evaluate_code. Do not call after topos_evaluate_file already returned a passing verdict or a refactor_targets span. This is the detail view, not the next step.

Structural PR or commit-range recap: gate readiness, blocking findings, files needing attention. Summary by default; detail: "full" for topos.pr_recap.v3.

Turn a generator ranking into a preference-ordered relaxation walk. Pure and read-only (lattice math only; no files, no scoring). Call after an evaluation to pick the next verdict to aim for, or to relax the goal gracefully under a token/time budget. Returns a PreferenceWalkResult: walk (steps from target down to just above current), next_step, progress in [0, 1], aspirational_target/fallback_target, and induced_order (all 16 verdicts ranked).

Rank structural refactor hotspots for one file (read-only, advisory). Does not score the four pillars — use topos_evaluate_* for medals and topos_assess_* to verify edits afterward. target selects the engine: cycles (CFG loop/branch bodies), dependencies (MDG Forman curvature on imports; needs .gitnexus), or process (execution choke points; needs .gitnexus). Returns a RefactorResult with ranked hotspots (kind, label, score, suggestion, optional lines).