Topos MCP is a structural code-quality server that scores code/files/projects, verifies refactors, and exposes dependency, security, coverage, and PR insights to coding agents.
Evaluate code quality on the SIMPLE / COMPOSABLE / SECURE / NAVIGABLE lattice, returning medals from SLOP to IDEAL with scores, metrics, and next-step guidance.
Evaluate inline code, files, or entire projects across Python, Rust, JavaScript, TypeScript, C++, and Go; project rollups include gate failures and paginated per-file results.
Assess refactors and changesets against git baselines or saved snapshots, including multi-file changesets, worktree edits, and side-by-side proposed variants.
Begin refactor workflows by snapshotting a file before edits, then verifying the edited file against that snapshot.
Compare structural similarity between two code strings or files using AST tree-edit distance for clone detection or refactor impact.
Inspect detailed metrics for a code unit, including top complex functions and per-function breakdowns.
Measure structural test coverage via UAST coverage and k-gram path recall.
Manage dependency graphs by checking .gitnexus freshness/status and generating or refreshing the dependency graph for COMPOSABLE scoring.
Get refactor hotspots for cycles, dependency curvature, or process bottlenecks.
Produce PR/commit-range recaps with gate readiness, findings, splits, and rollups.
Use preference/lattice tools to rank generators and plan a preference-ordered relaxation walk toward a target verdict.
Read built-in documentation on agent contracts, lattice semantics, metrics, preferences, priority, and workflows.
Coding agents produce working code quickly. The harder question is whether the result is still easy to understand, safe to change, and well-fitted to the rest of the repository. Quality is the new currency.
Topos computes that signal from program structure—not from an LLM review or a style opinion—and returns concrete failure locations and next actions. It is fast enough to sit inside the agent loop: measure, edit, verify, repeat.
Tests check behavior. Topos checks whether the implementation is built to keep changing.
Grounded in category theory, written in Rust.
Related MCP server: sourcebook
One binary. Every supported agent harness. A clean way back out.
Use the verified release installer:
curl -fsSL https://docs.krv.ai/topos/install.sh | bashOr install with Homebrew:
brew install krv-labs/tap/toposOn Homebrew 6+, that fully qualified one-liner auto-taps and trusts only this formula. If you brew tap krv-labs/tap first, run brew trust --formula krv-labs/tap/topos before brew install topos.
Prefer an editor-managed install? In VS Code or Cursor, search @mcp topos in the Extensions view or choose Install MCP server. This is an alternative to topos install: your editor installs and manages the Topos MCP server for you.
topos install detects every supported MCP harness and lets you configure any—or all—of them from one interactive checklist:
topos install┌ Which agent integrations do you want to configure?
│
│ ↑↓ move · space toggle · a all · enter confirm · esc cancel
│
│ ❯ ○ Claude Code (detected)
│ ○ Claude Desktop (detected)
│ ● Codex CLI (✓ active)
│ ● Gemini CLI (✓ active)
│ ○ GitHub Copilot CLI (detected)
│ ○ Cursor (detected)
│ ○ VS Code (detected)
│ ○ Google Antigravity (detected)
│ ○ pi (detected)
│ ○ OpenCode (detected)
└Restart the agents you configured, then ask:
"Use Topos to find this repository's worst structural problem, make one focused improvement, and verify the result."
Too many tools spray MCP servers across agent JSON files, scatter symlinks around your machine, then leave you to burn half a Claude session untangling the mess—or pull your own hair out doing it. Topos does not play that game. We follow a leave-no-trace policy for harness installation state:topos status shows every registration, while topos uninstall opens the same selector, previews exactly what will change, and removes everything it added to your harness configs. Shared cache bookkeeping and repository-scoped cache leases are not installation state, so uninstall leaves them alone and reports any shared bookkeeping it keeps; generated PR caches are removed only by an explicit topos cache clean or topos cache prune. If Topos makes it easy to do, it should be just as easy to undo.
topos status
topos uninstallSee the agent setup guide for permissions, manual configuration, and troubleshooting.
topos evaluate . -rTopos discovers Python, Rust, JavaScript, TypeScript, C++, and Go automatically. Pass --language only when you want to narrow the run.
Reviewing a pull request instead? topos pr-recap 5 gives a structural before/after card and debt ledger for the PR's changed files — no LLM, fully reproducible, with presets calibrated across 1,609 open-source pull requests (PR Recap calibration · lab notes).
See Installation for platform support and alternative install paths.
Every file gets four independent verdicts:
SIMPLE — avoids unnecessary complexity using AST entropy and control-flow complexity.
COMPOSABLE — limits a file's outward dependency burden; broader coupling and stability metrics remain available for diagnosis.
SECURE — avoids dangerous API reachability and taint paths in the code property graph.
NAVIGABLE — stays shallow enough for an agent to read and change in one pass, using depth-weighted nesting divergence over the AST scope tree.
Those verdicts roll up into one memorable quality medal without hiding which pillar failed:
Medal | Criteria |
🏆 PLATINUM | Passes all 4 |
🥇 GOLD | Passes 3 of 4 |
🥈 SILVER | Passes 2 of 4 |
🥉 BRONZE | Passes 1 of 4 |
❌ SLOP | Passes 0, or fails to parse |
See the full metrics reference. Refactor guidance also surfaces control-flow cycles, load-bearing dependency edges, and process bottlenecks.
The four pillars are pairwise incomparable and form a sixteen-element evaluation lattice (a 4-cube); PLATINUM is their intersection. Labels below abbreviate the pillars as Simple, Composable, Sc = Secure, Navigable.
Measures · Category-theory foundations
Topos is a self-contained Rust CLI and MCP server. Analysis runs locally; your source code is not sent to an external model or hosted analysis service.
Component | Role |
Parses six languages and powers the native AST, CFG, CPG, PDG, and UAST representations. | |
Supplies the repository dependency graph scored by COMPOSABLE ( | |
Embedded in the MCP server for supplementary security findings; native CPG probes remain the SECURE scoring source. |
The result is one agent-facing contract over several structural lenses: one score to optimize, explicit evidence for each failure, and a verification loop that can tell a real improvement from cosmetic churn.
OpenClaw / ClawHub: openclaw skills install @Krv-Labs/topos
Hermes: hermes skills tap add Krv-Labs/topos then hermes skills install Krv-Labs/topos/topos
Agent Plugins: point a compatible client at agent-plugin/ (spec)
MCP Registry name: io.github.Krv-Labs/topos
CLI reference: docs.krv.ai/topos/cli
Topos ships four ways:
GitHub Releases — the topos CLI binary (macOS/Linux), via install.sh or a direct release download.
PyPI — topos-mcp, a thin bin-wheel bundling the MCP server binary (pip install topos-mcp / uvx topos-mcp), zero Python runtime.
VS Code Marketplace — the Topos extension, bundling platform binaries.
Docker — a container image for Glama and other MCP-registry hosting.
Crate layout and adapter details: docs.krv.ai/topos/architecture.
Topos is used internally at Krv Labs to manage AI-agent code output. We welcome bugs, ideas, and contributions.
Bug? Open an issue
Idea? Start a discussion or open a PR
Collaborate? team@krv.ai
Full documentation · Measures and metrics · Engineering notes
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.
| Name | Required | Description | Default |
|---|---|---|---|
| allow | No | One-off acknowledged dangerous-call patterns. | |
| files | Yes | Edited file paths (working tree) that make up the changeset. | |
| preferences | No | Optional generator ranking. | |
| baseline_ref | No | Git baseline ref each file is compared against. | HEAD |
| gitnexus_dir | No | .gitnexus directory. | |
| include_security_findings | No | Include SECURE findings. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only, idempotent, non-destructive, so the safety profile is covered. The description adds genuine behavioral context beyond that: per-file comparison against baseline_ref, the special case that new files have no baseline, and the two named flags it emits (complexity_relocated_within_file, project_regression). It stops short of explaining the ChangesetResult payload.
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, then usage, then mechanics, with no filler sentences. The phrasing is slightly choppy across lines but every sentence carries information; minor tightening would help.
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, the description names the return type and the key flags, and the schema fully documents all parameters, so the core picture is complete for a 6-parameter tool. The main residual gap is that 'ChangesetResult' is not described, leaving the returned structure opaque.
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 100%, so all six parameters are already documented in the schema; per the rubric this establishes a baseline of 3. The description reinforces baseline_ref semantics ('new files have no baseline') but adds nothing about allow, preferences, gitnexus_dir, or include_security_findings.
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 ('Assess a multi-file changeset against a git baseline') plus the aggregation behavior ('roll the per-file verdicts into a project before/after'). The multi-file scope distinguishes it from single-file siblings like topos_evaluate_file or topos_assess_worktree_change.
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?
'Use for a module split or any edit spanning several files' gives a concrete when-to-use condition. It does not, however, explicitly name the nearest alternative (topos_assess_worktree_change / topos_assess_snapshot) or state when not to use it, so an agent must still infer the boundary.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| allow | No | One-off acknowledged dangerous-call patterns. | |
| filepath | No | Baseline file path for side-by-side assessment. | |
| language | No | Language for inline code. | python |
| preferences | No | Optional generator ranking. | |
| current_code | No | Inline baseline source; COMPOSABLE is unavailable. | |
| gitnexus_dir | No | .gitnexus directory. | |
| proposed_code | No | Proposed source. | |
| proposed_filepath | No | Proposed file path. | |
| include_security_findings | No | Include SECURE findings. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint/idempotentHint/destructiveHint, so the '(read-only)' note is largely redundant. However, it compensates for the missing output schema by stating the return shape ('AssessmentResult with status and score/metric deltas'), and clarifies the variant-based execution model. It does not mention the COMPOSABLE-unavailable constraint noted in the schema, 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?
Front-loaded with the purpose, then routing guidance, then input clarification, then return shape. Four tight sentences with no filler; every sentence 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?
With no output schema, the description usefully names the returned status and deltas, and annotations cover the safety profile. It leaves the baseline-side inputs (filepath vs current_code) and the inline COMPOSABLE limitation to the schema, which handles them, so coverage is nearly 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 100% with 9 self-documenting parameters, so the baseline is 3. The description reinforces which inputs carry the variant ('proposed_code or proposed_filepath') but adds little syntax or meaning beyond what the schema already provides.
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 ('Compare a baseline to a side-by-side proposed variant') and explicitly differentiates itself from siblings such as topos_assess_worktree_change and topos_assess_snapshot. An agent can pick this tool over the many other assess_* siblings 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?
Gives explicit when-to-use and when-not-to-use guidance: 'For normal edit-in-place loops, use topos_assess_worktree_change or snapshot first with topos_begin_refactor then topos_assess_snapshot.' It also names the condition that selects this tool instead ('variants supplied as proposed_code or proposed_filepath').
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| allow | No | One-off acknowledged dangerous-call patterns. | |
| filepath | Yes | Edited file path. | |
| snapshot_id | Yes | Snapshot id from topos_begin_refactor. | |
| include_security_findings | No | Include SECURE findings. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds context about blocked_by behavior for missing/expired snapshots, which is useful but not extensive. No contradictions with 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 description is two sentences, front-loaded with the primary action, and contains no extraneous information. Every word contributes to understanding.
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 description covers the main action, the comparison baseline, and error case (blocked_by). However, it does not describe the output or the status semantics referenced from topos_assess_improvement, which would be helpful for a complete picture.
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 100%; each parameter is described adequately in the schema. The description does not add further parameter-level detail, but that is not necessary given the schema's completeness.
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 clearly states that the tool assesses a file against a baseline snapshot, referencing topos_begin_refactor for the baseline and topos_assess_improvement for status semantics. This uniquely identifies its role among siblings.
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 description implies usage after topos_begin_refactor and mentions blocking for missing/expired snapshots, but does not explicitly state when to use this tool versus alternatives like topos_assess_worktree_change or topos_assess_changeset. No when-not-to guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| allow | No | One-off acknowledged dangerous-call patterns. | |
| filepath | Yes | Edited file path. | |
| preferences | No | Optional generator ranking. | |
| baseline_ref | No | Git baseline ref. | HEAD |
| gitnexus_dir | No | .gitnexus directory. | |
| include_security_findings | No | Include SECURE findings. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower, but the description adds real behavioral context: the tool is stateless, the baseline is read via 'git show <baseline_ref>:<path>' defaulting to HEAD, no prior call is needed, and a no-change result on a passing file yields no next_tool. It stops short of describing return shape or how findings are structured.
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?
Four tight sentences, front-loaded with the core purpose, then the stateless mechanism, then the alternative path, then the guardrail. Every sentence carries distinct information with no repetition of the name or 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?
For a read-only, parameter-heavy assessment tool with no output schema, the description covers invocation prerequisites, baseline resolution, and the empty-result case. The main residual gap is what an assessment result contains (findings, verdict shape, next_tool semantics), though the mention of next_tool partially mitigates this.
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 100%, so the baseline is 3, but the description genuinely enriches the most consequential parameter: it explains that baseline_ref is resolved via git show against the working-tree file and defaults to HEAD, and that filepath must refer to an already-edited file. That is more than the schema's terse 'Git baseline ref.'
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+scope: 'Assess an in-place edit against a git revision — the common refactor loop.' It distinguishes itself from siblings by naming topos_begin_refactor and topos_assess_snapshot as the tools for untracked/new-file or pre-edit-baseline cases, so an agent can route correctly without opening schemas.
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 when-to-use (in-place edit vs git revision), when-not ('Do not call if you have not edited the file'), and the exact alternative path for untracked/new files or an uncommitted pre-edit baseline. It also sets expectations for the no-change case.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| filepath | Yes | File path to snapshot. Prefer an absolute path. | |
| preferences | No | Optional generator ranking. | |
| gitnexus_dir | No | .gitnexus directory. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false and destructiveHint=false, but the description adds valuable context beyond them: it discloses the exact side effect ('writes a snapshot record — its only side effect') and the return value ('snapshot_id'). This clarifies the mutation scope precisely, which is more than the annotations convey.
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 action and its side effect are front-loaded, followed by the return value and the workflow guidance. It is efficient and well-ordered, with only minor redundancy in restating the snapshot concept across clauses.
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 workflow-initiating tool with no output schema, the description carries the burden well: it explains the side effect, the returned snapshot_id, the subsequent edit step, and the follow-up call to topos_assess_snapshot. Nothing an agent needs to invoke 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 description coverage is 100%, so the schema already documents filepath, preferences, and gitnexus_dir thoroughly. The description references 'the file' and the snapshot workflow but adds no syntax or format detail beyond what the schema provides. Baseline 3 is appropriate.
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 ('Persist the file's current source as a baseline snapshot before you edit it') and clearly distinguishes its role from siblings by naming the follow-up tool 'topos_assess_snapshot'. An agent can immediately tell what this does without opening 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 the triggering condition: 'Use this when the baseline is not a committed git revision,' and names the companion tool to call afterward. It gives clear context for use, though it stops short of an explicit when-not/alternative comparison for the case where the baseline IS a committed revision.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| k | No | Length of kind n-grams for path recall. | |
| language | No | Programming language (for parsing). | python |
| put_files | Yes | Paths to the program-under-test files (relative to project root). | |
| test_files | No | Paths to the test suite files (relative to project root). Optional: inline tests in `put_files` (Rust `#[cfg(test)]`, Go `Test*`, Python `test_*`) are counted on the test side. | |
| include_unknown | No | Whether to include Unknown UAST nodes in the analysis. | |
| coverage_threshold | No | Minimum threshold for the declaration coverage policy. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and non-destructive, so the safety profile is covered; the description adds the method (UAST bipartite declaration matching and k-gram path recall) and the return type (CoverageResult). It doesn't describe error conditions or how partial inputs are handled, but for a pure read-only analysis tool that is a minor omission.
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?
Three short sentences, front-loading the core action and then the sibling differentiation, with no filler. The phrasing is jargon-dense ('four-pillar quality lattice', 'UAST bipartite declaration matching') but each clause 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 read-only, fully schema-documented tool with eight sibling evaluate/assess tools, the description covers purpose, method, and the routing decision away from quality verdicts. With no output schema it names the return type, which is the minimum needed; more detail on result shape or behavior on missing test files would round it out.
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 100%, so the schema already documents all six parameters, making 3 the baseline. The description's mention of 'k-gram path recall' loosely connects to the `k` parameter but adds no syntax or format detail 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: 'Measure how well a test suite exercises its program-under-test, via structural (UAST) coverage.' It also differentiates itself from siblings by declaring it is 'a standalone signal, separate from the four-pillar quality lattice' and pointing to `topos_evaluate_*` for quality verdicts, so an agent can tell it apart from the evaluate family.
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 (use this to measure test-suite exercise of a program) and an explicit exclusion with an alternative route ('for a quality verdict use `topos_evaluate_*` instead'). The gap is that the alternative is named as a wildcard family rather than a specific sibling, so the agent must still choose among several evaluate tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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).
| Name | Required | Description | Default |
|---|---|---|---|
| language | No | python, rust, javascript, typescript, cpp, or go. | python |
| source_code | Yes | Baseline code. | |
| target_code | Yes | Proposed/target code. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnly, idempotent, non-destructive hints. Description adds 'parses both snippets in memory, never writes or scores,' which goes beyond annotations but is not extremely rich.
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?
Three sentences: purpose, behavior+usage, return value. All front-loaded, no wasted words.
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 tool with 3 simple and well-documented parameters and no output schema, the description covers purpose, usage, behavior, and return value completely.
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 100%, so baseline is 3. The description repeats schema descriptions ('Baseline code.' and 'Proposed/target code.') without adding extra syntax or format details.
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 verb+resource clearly: 'Compute the AST distance between two source-code strings.' Distinguishes from siblings by noting that assess tools already fold it in, and this tool provides raw numbers for clone detection or refactor impact.
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 says 'call it directly only for the raw number' and names alternatives (topos_assess_*), giving clear context on when to use vs. not use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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).
| Name | Required | Description | Default |
|---|---|---|---|
| source | Yes | Baseline file path (prefer absolute). | |
| target | Yes | Comparison file path (prefer absolute). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds meaningful behavior beyond them: both files are parsed in the language their suffix names, the same way `topos compare` does, and mismatched languages or unsupported suffixes are errors. It also states it never writes or scores, which is non-obvious for a comparison 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?
Front-loaded with the core operation, then usage, then return type. Slightly dense with the parenthetical and cross-references, but nearly every clause adds routing or behavioral information rather than filler.
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 two-param read-only tool with no output schema, the description covers operation, language inference, error conditions, and usage routing. The one gap is that the return shape is delegated entirely to `topos_compare_code` rather than described, which is acceptable but requires a cross-reference.
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 100%, so both parameters are documented in the schema as baseline/target paths. The description adds only the behavioral note that language is inferred from the file suffix, which is useful but not parameter-specific; baseline 3 is appropriate when the schema carries the load.
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: 'Compute the AST (tree-edit) distance between two source files on disk.' It goes further by naming the sibling it is not (topos_assess_* for quality verdict) and the related return type (topos_compare_code), so an agent can distinguish it without opening schemas.
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 names use cases ('clone detection or refactor impact') and the alternative with its own domain ('use topos_assess_* for a quality verdict'). It also states error conditions (unsupported suffix, two different languages) that constrain when the tool will succeed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| directory | No | Repo root to inspect (default: MCP file root / process project root). | |
| gitnexus_dir | No | `.gitnexus` store under the project root (default: `<project root>/.gitnexus`). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description still adds value by enumerating the diagnostic outcomes it can report (missing vs stale vs load/schema failure) and confirming it "never shells out," which tells the agent there are no external side effects or shell dependencies.
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 core action and kept to three short sentences with no filler. The closing "never shells out and never mutates state" is partly redundant with readOnlyHint, but it is brief and reinforces an important guarantee.
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, so the description must convey what the agent learns from the call; it does so by naming the three diagnostic states it distinguishes. Coverage is good for a two-optional-parameter read-only probe, though the actual response shape and any remediation steps remain unspecified.
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 100%: both `directory` and `gitnexus_dir` are documented with their defaults and fallback behavior. The description adds no parameter-level detail, which is the expected baseline when the schema carries the full burden.
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 ("Report `.gitnexus` availability and freshness") and enumerates the states it distinguishes (missing, stale, load/schema failure), so the agent knows exactly what it inspects. It does not explicitly name the sibling `topos_generate_depgraph` as the counterpart action, so sibling differentiation is only implied.
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 usage context: run it to determine "whether COMPOSABLE can be trusted and what to do next." There are no explicit exclusions or named alternative tools, and "what to do next" is left unstated, which keeps it short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| code | Yes | Source code to evaluate. | |
| allow | No | One-off acknowledged dangerous-call patterns. | |
| verbose | No | Include raw metrics. | |
| language | No | Language: python, rust, javascript, typescript, cpp, or go. | python |
| preferences | No | Optional generator ranking. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnlyHint, idempotentHint, destructiveHint), the description adds key behavioral context: 'never writes or runs the code' and details what the return value is: 'an EvaluationResult: the lattice verdict (SLOP…IDEAL), per-generator scores, and a next-step agent contract.' It also explains the analytical scope (CFG/CPG/UAST) and the COMPOSABLE limitation.
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 compact and front-loaded: starts with the primary action, then usage context, limitations with alternatives, and return value—all in three sentences with no redundancy.
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, the description explains the return contract. It covers when to use, what it does, what it cannot do (COMPOSABLE), and that it is read-only. For a 5-parameter tool, this is thorough and gives sufficient context for correct invocation.
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 100%, so baseline is 3. The description does not add parameter-specific details beyond the schema; it only mentions 'raw code string' which corresponds to `code`. No additional semantics for `allow`, `verbose`, `language`, or `preferences` are provided, though the schema covers them.
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 verb and resource: 'Score a raw code string on the SIMPLE / SECURE / NAVIGABLE quality lattice.' It clearly distinguishes from siblings by noting 'a snippet not yet on disk' and explicitly stating COMPOSABLE is not reachable here, directing to `topos_evaluate_file` or `topos_evaluate_project`.
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 description provides explicit when-to-use guidance: 'Use for a snippet not yet on disk.' It also names alternatives for cases it cannot handle: 'for [COMPOSABLE] use `topos_evaluate_file` with `gitnexus_dir`, or `topos_evaluate_project` for a whole tree.'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| allow | No | One-off acknowledged dangerous-call patterns. | |
| verbose | No | Include raw metrics. | |
| filepath | Yes | Source file path. Prefer an absolute path. | |
| preferences | No | Optional generator ranking. | |
| gitnexus_dir | No | `.gitnexus` store under the file root (default: `<file root>/.gitnexus`); generated/refreshed when missing or stale (see `no_composable`). | |
| no_composable | No | Use no dependency graph, even an existing `.gitnexus`; score SIMPLE/SECURE/NAVIGABLE only. | |
| security_scan | No | Run Sighthound even if SECURE passed; report-only. | |
| refactor_targets | No | Ranked edit targets to return, gate failures first (default 3; 0 = off; capped at 25). | |
| include_security_findings | No | Include SECURE findings. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond annotations: it discloses the side effect (generating/refreshing .gitnexus), the condition under which it happens (missing or stale), the default CLI-equivalent behavior, and a graceful failure mode (coupling_available=false with warnings). This is consistent with readOnlyHint=false and non-idempotent, adding real context about what changes on disk and what happens when it fails.
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 purpose and unique differentiator before the side-effect details, and every sentence carries information. It is dense and slightly heavy with parentheticals, but nothing is padded or redundant.
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 9-parameter mutation tool with no output schema, it covers the essentials: side effects, failure handling, and terminology that maps to output fields (coupling_available, warnings, agent_contract.next_tool). Return-shape detail is partial, but the safety-relevant behavior an agent needs is present.
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 100%, so the baseline is 3, but the description adds value the schema does not: it explains the interplay between no_composable and gitnexus_dir (auto-detection path, gating of generation) and the always-on pillars. It clarifies behavior of specific parameters beyond their individual field descriptions.
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 (score) and resource (a file on disk) plus the lattice dimensions it evaluates against. It explicitly differentiates itself from siblings by claiming to be 'the only evaluate tool that can reach COMPOSABLE', so an agent can distinguish it from topos_evaluate_project, topos_evaluate_code, and topos_assess_snapshot 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?
Names the distinguishing condition ('the only evaluate tool that can reach COMPOSABLE') and gives an explicit when-not rule ('Do not call again when agent_contract.next_tool is absent'). It stops short of routing to specific sibling tools by name (e.g. when to prefer topos_evaluate_project instead), so it is clear context but not a full when/when-not/alternative map.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Directory to evaluate, walked recursively. Prefer an absolute path. Must resolve inside the trusted file root. Languages are autodetected. | |
| allow | No | Dangerous-call patterns to acknowledge for this run only. | |
| limit | No | Per-file rows to return per page (1–500, default 25). | |
| detail | No | `summary` (default): rollups and worst files. `full`: per-file rows. | |
| offset | No | Zero-based row offset for pagination; pass the response's `next_offset` to fetch the next page. | |
| verbose | No | When true, include each file's raw metric values alongside scores. | |
| preferences | No | Optional ranking of simple/composable/secure/navigable (best first). Top-ranked sets scorer priority (default SIMPLE). | |
| gitnexus_dir | No | `.gitnexus` store under the file root (default: `<file root>/.gitnexus`); generated/refreshed when missing or stale (see `no_composable`), or COMPOSABLE is reported unavailable if generation fails. | |
| no_composable | No | Use no dependency graph, even an existing `.gitnexus`; score SIMPLE/SECURE/NAVIGABLE only. | |
| include_security_findings | No | When true, attach per-file SECURE findings to each entry; off by default to keep responses compact. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, idempotentHint=false, destructiveHint=false, and the description is consistent ('side-effecting'). It adds real context beyond them: .gitnexus is generated/refreshed when missing or stale, and failure to do so degrades gracefully via coupling_available/warnings rather than failing the evaluation. It leaves unstated what refreshing a stale .gitnexus overwrites, which is the one remaining behavioral 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?
Front-loaded with the core action and scope, then return shape, then the .gitnexus side effect, then the don't-use rule. It is dense but every sentence carries information, though the no_composable/gitnexus caveat is restated enough to feel slightly repetitive.
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 10-parameter tool with no output schema, the description covers what a summary contains (aggregate_floor_verdict, five worst files with paths and metrics, counts, warnings) and how full mode differs. That is nearly complete; a few secondary flags are left entirely to 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 coverage is 100%, so the baseline is 3, but the description goes further by explaining the summary-vs-'full' return shapes, pagination via limit/offset, and the no_composable skip path with its fallback. It leaves verbose, include_security_findings, allow, and preferences to 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 scope — recursively score every supported source file in a directory on the SIMPLE/COMPOSABLE/SECURE/NAVIGABLE lattice — plus the project rollup and side-effecting nature. It explicitly distinguishes itself from the file-level sibling (topos_evaluate_file) and the CLI. An agent can identify the tool without opening 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?
Gives explicit exclusions: 'Do not call this for one file, or after a file already passed. It walks the tree.' It also draws the intent boundary — a person asks for the project rollup, an agent editing one file does not — which routes the agent to the right sibling.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| force | No | Regenerate even when current. | |
| directory | No | Repo root to analyze (default: MCP file root / process project root). | |
| gitnexus_dir | No | `.gitnexus` store under the project root. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false and destructiveHint=false; the description adds the important context that the tool is side-effecting, that it no-ops when the graph is current, and that force=true always regenerates. That is genuine value beyond the structured hints. It stops short of describing failure behavior or what the graph write touches on disk.
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?
Three tight sentences with the side-effecting warning and the core action front-loaded, followed by the default and force semantics. No filler, though the parenthetical '(side-effecting)' is slightly awkwardly detached from the main clause.
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 mutating tool with no output schema, the description covers the key agent questions: what it writes, that it is side-effecting, when it skips work, and how to force a rebuild. Remaining gaps (failure modes, whether it modifies tracked repo files) are minor.
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 100%, so `force`, `directory`, and `gitnexus_dir` are already fully documented in the schema. The description's restatement of `force=true` behavior adds nothing beyond the schema's 'Regenerate even when current.' Baseline 3 is appropriate.
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 ('Generate the `.gitnexus` dependency graph') plus the underlying mechanism (`gitnexus analyze`), which is far more than a restatement of the name. It does not, however, mention the closely related sibling `topos_depgraph_status`, which an agent could easily confuse with this read/write pair.
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 description explains the default call semantics ('no-ops when current, otherwise runs gitnexus analyze') and the force condition, which implicitly tells the agent it is safe to invoke without checking state first. But it never names an alternative tool (e.g. `topos_depgraph_status`) or states when-not to use this one, so usage guidance is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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).
| Name | Required | Description | Default |
|---|---|---|---|
| topic | Yes | agent-contract | lattice | metrics | preferences | priority | workflows |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds that the output is Markdown and that the tool is a fallback for clients without resource fetching. It does not contradict annotations and provides useful behavioral context beyond the structured hints.
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 sentences plus a compact topic list. First sentence states purpose, second gives usage rationale, and the list is scannable with parenthetical explanations. No wasted words.
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 a simple read-only doc fetch with one parameter. The description covers the return format (Markdown), the precise when-to-use scenario, and enumerates all topics. Annotations handle the safety profile, so nothing 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 covers the single 'topic' parameter 100% with enum definitions, but the description strengthens the semantics by explaining what each topic contains, e.g., 'agent-contract (compact loop contract, read first for refactors)'. This is meaningful enrichment beyond the enum 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?
The description opens with 'Return a Topos documentation page as Markdown,' a specific verb+resource statement that immediately disambiguates it from sibling tools (all focused on code analysis/refactoring). It clearly names the tool's function as documentation retrieval.
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 guidance: '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.' This directly states when to use the tool and when to prefer an alternative, which is exactly what usage guidelines should do.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| code | No | Inline source code. | |
| allow | No | One-off acknowledged dangerous-call patterns for this inspection. | |
| verbose | No | Include raw probe metric floats under each file in the response. | |
| filepath | No | Source file path inside the project root (prefer for large files). | |
| language | No | Language for inline `code`; ignored for `filepath`, which is autodetected from the file extension. | python |
| preferences | No | Strict total order on the four generators; see `topos://docs/preferences`. | |
| gitnexus_dir | No | `.gitnexus` store under the file root (default: `<file root>/.gitnexus`); only used with `filepath`. | |
| no_composable | No | Use no dependency graph, even an existing `.gitnexus`; score SIMPLE/SECURE/NAVIGABLE only. | |
| top_n_functions | No | Return at most this many functions, sorted by descending cyclomatic complexity. Keeps agent context lean on large files. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only say readOnlyHint=false/idempotentHint=false; the description adds the crucial behavioral detail beyond them — that filepath mode generates/refreshes `.gitnexus` and attaches a ModuleDependencyGraph, so the call is side-effecting, and that inline code can only reach SIMPLE/SECURE/NAVIGABLE. It also sketches the return shape (InspectionResult, lattice evaluation, top-N table, total_functions, entropy).
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?
Long but dense and front-loaded: the core purpose and the code/filepath rule come first, and the alternatives/exclusion come next. Nearly every sentence carries a distinct fact (generator reachability, side-effect, sibling routing); a little could be tightened but nothing is padding.
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 9-param, no-output-schema tool this covers the essentials: input exclusivity, side effects, which generators apply per mode, and the return payload. Nothing an agent needs to invoke it correctly or avoid misusing it 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 100%, so baseline is 3, but the description adds real meaning: the code-vs-filepath exclusivity, top_n_functions' default of 10 as a context-lean measure, gitnexus_dir's auto-detection path, and no_composable's effect on scoring. It stops short of documenting allow/language/verbose/preferences 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+resource ('Full metric breakdown for a single code unit') and explicitly contrasts itself with the sibling family: detail view vs. the medal-only topos_evaluate_*. An agent can tell it apart from topos_evaluate_file and topos_evaluate_code 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 selection criteria ('use when you need the per-function detail behind a verdict; use topos_evaluate_* when the medal alone is enough') and a hard exclusion ('Do not call after topos_evaluate_file already returned a passing verdict or a refactor_targets span'). Also states the code/filepath mutual-exclusivity constraint.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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).
| Name | Required | Description | Default |
|---|---|---|---|
| target | No | Optional aspirational-target override; defaults to IDEAL. | |
| current | No | Optional current verdict; truncates the walk to steps strictly above it and sets `next_step`. Defaults to the full walk. | |
| ranking | Yes | Permutation of {simple, composable, secure, navigable}, most-preferred first. | |
| gate_scores | No | Pillar gate scores in `[0, 1]`. Enables `next_pillar`. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description still adds real value by scoping it as 'lattice math only; no files, no scoring' and by enumerating the return fields, which matters because no output schema exists.
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 three sentences, front-loaded with the core action before the guidance and return shape. Dense but each clause earns its place; no preamble or filler.
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, the description compensates by listing the PreferenceWalkResult fields (walk, next_step, progress, targets, induced_order), and annotations cover safety. For a pure lattice-math tool this is nearly everything an agent needs, though it could note the fixed 16-verdict domain more explicitly.
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 100%, so the baseline is 3, but the description adds relationship semantics beyond the schema: the walk runs 'from target down to just above current' and truncates accordingly, clarifying how target and current interact rather than merely restating them.
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 (turns a generator ranking into a preference-ordered relaxation walk) and further clarifies with 'pick the next verdict to aim for, or to relax the goal.' It is jargon-heavy ('relaxation walk', 'Heyting algebra'), but a reader can tell it apart from the assess/evaluate/refactor siblings since it computes a walk rather than a score.
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 clear sequencing context: 'Call after an evaluation to pick the next verdict to aim for, or to relax the goal gracefully under a token/time budget.' This tells the agent when to reach for it, though it names no explicit alternatives and states no when-not-to-use condition.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Structural PR or commit-range recap: gate readiness, blocking findings, files needing attention. Summary by default; detail: "full" for topos.pr_recap.v3.
| Name | Required | Description | Default |
|---|---|---|---|
| pr | No | Pull request number (mutually exclusive with `base`/`head`). | |
| base | No | Base commit ref (default `HEAD`). | |
| head | No | Head commit ref or `:worktree` (default `:worktree` or `HEAD`). | |
| paths | No | Absolute or repo-relative paths of files whose full records to include. | |
| detail | No | `summary` (default) or `full` v3 document. | |
| preset | No | Built-in gate preset (`relaxed`, `recommended`, or `strict`). | |
| strict | No | Fail readiness check on `warn` as well as `block`. | |
| priority | No | Priority pillar or comma-separated ranking. | |
| directory | No | Repository directory (default: MCP file root). | |
| max_files | No | Max scored files by churn (default 0 = all). | |
| no_coupling | No | Skip coupling graph preparation. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds the default output mode and the versioned document emitted at full detail, but says nothing about cost, repo scoping (directory/paths), or result size behavior for a tool with 11 parameters.
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, zero filler, and the highest-value content (what the recap shows) is front-loaded before the verbosity default. Nothing is repeated from structured fields unnecessarily.
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 annotations carry the safety profile and the schema covers all parameters, the description is adequate: it names the three output sections and the full-detail document variant. It doesn't clarify how PR mode versus base/head mode is chosen or what scoping via directory/paths does, leaving some interpretation to 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 100%, so all 11 parameters are already documented in the schema, including the detail enum. The description's note about `detail: "full"` and `topos.pr_recap.v3` largely restates the schema's own wording, adding no format or interaction detail (e.g. how preset/strict/priority combine).
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 ('Structural PR or commit-range recap') and enumerates what the recap contains: gate readiness, blocking findings, files needing attention. It doesn't distinguish itself from adjacent evaluate/assess siblings (topos_assess_changeset, topos_assess_worktree_change), so an agent can't fully rule those out from the description alone.
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 exclusion criteria, and no named alternative among the many topos_assess_*/topos_evaluate_* siblings. The only routing hint is about output verbosity ('Summary by default; detail: full'), which is a parameter default rather than a tool-selection rule.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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).
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum hotspots to return (default 5). | |
| target | Yes | Which analysis engine to run: `cycles` (CFG), or `dependencies` / `process` (need `.gitnexus`). | |
| filepath | Yes | Source file path relative to the MCP file root. | |
| gitnexus_dir | No | Override `.gitnexus` directory (`dependencies` / `process` targets). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds genuinely useful context beyond that: the advisory (non-scoring) nature and the `.gitnexus` prerequisite for two of three engines, though it says nothing about cost, rate limits, or failure modes when the prerequisite is absent.
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 core action, then alternatives, then engine selection, then return shape — a logical order. It is dense with backticks and parentheticals but every sentence carries information; only the engine descriptions slightly duplicate the 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?
With no output schema, the description helpfully describes the return shape (RefactorResult with ranked hotspots containing kind, label, score, suggestion, optional lines). Combined with prerequisite notes and sibling routing, an agent has everything needed to call 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 100% and the enum `$defs` already document each target engine in detail. The description largely paraphrases those same engine meanings ('cycles (CFG loop/branch bodies)', 'dependencies (MDG Forman curvature...)'), adding little beyond what the schema provides, so the baseline 3 applies.
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 ('Rank structural refactor hotspots for one file') plus scope ('read-only, advisory'). It explicitly names what it is NOT, routing agents to `topos_evaluate_*` and `topos_assess_*`, so it is distinguishable from siblings without opening schemas.
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/when-not: use topos_evaluate_* for pillar scoring and topos_assess_* to verify edits afterward, implying refactor is the pre-edit step. It also states per-target prerequisites ('needs `.gitnexus`' for dependencies and process), which is actionable routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.15.0topos_evaluate_project2 fields changedInput schema / $defs / DetailAdded value: +{
+ "enum": [
+ "summary",
+ "full"
+ ],
+ "type": "string"
+}Input schema / properties / detailAdded value: +{
+ "$ref": "#/$defs/Detail",
+ "description": "`summary` (default): rollups and worst files. `full`: per-file rows."
+}topos_pr_recap5 fields changedInput schema / $defsAdded value: +{
+ "Detail": {
+ "enum": [
+ "summary",
+ "full"
+ ],
+ "type": "string"
+ }
+}Input schema / properties / detailAdded value: +{
+ "$ref": "#/$defs/Detail",
+ "description": "`summary` (default) or `full` v3 document."
+}Input schema / properties / max_files / defaultPrevious value: -40New value: +0Input schema / properties / max_files / descriptionPrevious value: -"Max scored files by churn (default 40)."New value: +"Max scored files by churn (default 0 = all)."Input schema / properties / pathsAdded value: +{
+ "default": [],
+ "description": "Absolute or repo-relative paths of files whose full records to include.",
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+}v0.12.0topos_pr_recapv0.11.0topos_assess_changeset4 fields changedInput schema / properties / gitnexus_dir / anyOfAdded value: +[
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+]Input schema / properties / gitnexus_dir / descriptionAdded value: +".gitnexus directory."Input schema / properties / gitnexus_dir / typeRemoved value: -[
- "string",
- "null"
-]Input schema / properties / include_security_findings / descriptionAdded value: +"Include SECURE findings."topos_assess_improvement12 fields changedInput schema / properties / current_code / anyOfAdded value: +[
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+]Input schema / properties / current_code / typeRemoved value: -[
- "string",
- "null"
-]Input schema / properties / filepath / anyOfAdded value: +[
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+]Input schema / properties / filepath / typeRemoved value: -[
- "string",
- "null"
-]Input schema / properties / gitnexus_dir / anyOfAdded value: +[
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+]Input schema / properties / gitnexus_dir / descriptionAdded value: +".gitnexus directory."Input schema / properties / gitnexus_dir / typeRemoved value: -[
- "string",
- "null"
-]Input schema / properties / language / descriptionAdded value: +"Language for inline code."Input schema / properties / proposed_code / anyOfAdded value: +[
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+]Input schema / properties / proposed_code / typeRemoved value: -[
- "string",
- "null"
-]Input schema / properties / proposed_filepath / anyOfAdded value: +[
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+]Input schema / properties / proposed_filepath / typeRemoved value: -[
- "string",
- "null"
-]topos_assess_worktree_change3 fields changedInput schema / properties / gitnexus_dir / anyOfAdded value: +[
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+]Input schema / properties / gitnexus_dir / descriptionAdded value: +".gitnexus directory."Input schema / properties / gitnexus_dir / typeRemoved value: -[
- "string",
- "null"
-]topos_begin_refactor3 fields changedInput schema / properties / filepath / descriptionPrevious value: -"File path to snapshot."New value: +"File path to snapshot. Prefer an absolute path."Input schema / properties / gitnexus_dir / anyOfAdded value: +[
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+]Input schema / properties / gitnexus_dir / typeRemoved value: -[
- "string",
- "null"
-]topos_calculate_coverage3 fields changedInput schema / properties / test_files / defaultAdded value: +[]Input schema / properties / test_files / descriptionPrevious value: -"Paths to the test suite files (relative to project root)."New value: +"Paths to the test suite files (relative to project root). Optional:\ninline tests in `put_files` (Rust `#[cfg(test)]`, Go `Test*`,\nPython `test_*`) are counted on the test side."Input schema / requiredPrevious value: -[
- "put_files",
- "test_files"
-]New value: +[
+ "put_files"
+]topos_compare_files2 fields changedInput schema / properties / source / descriptionPrevious value: -"Baseline file path."New value: +"Baseline file path (prefer absolute)."Input schema / properties / target / descriptionPrevious value: -"Comparison file path."New value: +"Comparison file path (prefer absolute)."topos_depgraph_status4 fields changedInput schema / properties / directory / anyOfAdded value: +[
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+]Input schema / properties / directory / typeRemoved value: -[
- "string",
- "null"
-]Input schema / properties / gitnexus_dir / anyOfAdded value: +[
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+]Input schema / properties / gitnexus_dir / typeRemoved value: -[
- "string",
- "null"
-]topos_evaluate_file6 fields changedInput schema / properties / filepath / descriptionPrevious value: -"Source file path."New value: +"Source file path. Prefer an absolute path."Input schema / properties / gitnexus_dir / anyOfAdded value: +[
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+]Input schema / properties / gitnexus_dir / descriptionPrevious value: -"`.gitnexus` store under the MCP file root (default:\n`<file root>/.gitnexus`). Freshness and regeneration always use the\nfile root as the project root; this only selects the store path\ninside it. If missing or stale, this tool generates/refreshes first\n(see `no_composable`)."New value: +"`.gitnexus` store under the file root (default: `<file root>/.gitnexus`);\ngenerated/refreshed when missing or stale (see `no_composable`)."Input schema / properties / gitnexus_dir / typeRemoved value: -[
- "string",
- "null"
-]Input schema / properties / no_composable / descriptionPrevious value: -"Skip GitNexus detection/generation; score SIMPLE/SECURE/NAVIGABLE\nonly, exactly like a missing `.gitnexus` did before this tool\nstarted generating it automatically."New value: +"Use no dependency graph, even an existing `.gitnexus`; score\nSIMPLE/SECURE/NAVIGABLE only."Input schema / properties / security_scanAdded value: +{
+ "default": false,
+ "description": "Run Sighthound even if SECURE passed; report-only.",
+ "type": "boolean"
+}topos_evaluate_project6 fields changedInput schema / properties / gitnexus_dir / anyOfAdded value: +[
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+]Input schema / properties / gitnexus_dir / descriptionPrevious value: -"`.gitnexus` store under the MCP file root (default:\n`<file root>/.gitnexus`). Freshness and regeneration always use the\nfile root as the project root; this only selects the store path\ninside it. If missing or stale, this tool generates/refreshes first\n(see `no_composable`). If generation isn't possible, COMPOSABLE is\nreported as unavailable rather than failing the whole evaluation."New value: +"`.gitnexus` store under the file root (default: `<file root>/.gitnexus`);\ngenerated/refreshed when missing or stale (see `no_composable`), or\nCOMPOSABLE is reported unavailable if generation fails."Input schema / properties / gitnexus_dir / typeRemoved value: -[
- "string",
- "null"
-]Input schema / properties / no_composable / descriptionPrevious value: -"Skip GitNexus detection/generation; score SIMPLE/SECURE/NAVIGABLE\nonly, exactly like a missing `.gitnexus` did before this tool\nstarted generating it automatically."New value: +"Use no dependency graph, even an existing `.gitnexus`; score\nSIMPLE/SECURE/NAVIGABLE only."Input schema / properties / path / descriptionPrevious value: -"Directory to evaluate, walked recursively. Must resolve inside the\ntrusted file root; paths outside it are refused. All supported\nlanguages are autodetected — no language argument is needed."New value: +"Directory to evaluate, walked recursively. Prefer an absolute path. Must\nresolve inside the trusted file root. Languages are autodetected."Input schema / properties / preferences / descriptionPrevious value: -"Optional ranking of simple/composable/secure (best first). The\ntop-ranked generator sets scorer priority; omit to default to\nSIMPLE priority."New value: +"Optional ranking of simple/composable/secure/navigable (best first).\nTop-ranked sets scorer priority (default SIMPLE)."topos_generate_depgraph4 fields changedInput schema / properties / directory / anyOfAdded value: +[
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+]Input schema / properties / directory / typeRemoved value: -[
- "string",
- "null"
-]Input schema / properties / gitnexus_dir / anyOfAdded value: +[
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+]Input schema / properties / gitnexus_dir / typeRemoved value: -[
- "string",
- "null"
-]topos_inspect_code10 fields changedInput schema / properties / code / anyOfAdded value: +[
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+]Input schema / properties / code / descriptionAdded value: +"Inline source code."Input schema / properties / code / typeRemoved value: -[
- "string",
- "null"
-]Input schema / properties / filepath / anyOfAdded value: +[
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+]Input schema / properties / filepath / descriptionPrevious value: -"Path to the source file inside the project root. Prefer this for\nlarge files."New value: +"Source file path inside the project root (prefer for large files)."Input schema / properties / filepath / typeRemoved value: -[
- "string",
- "null"
-]Input schema / properties / gitnexus_dir / anyOfAdded value: +[
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+]Input schema / properties / gitnexus_dir / descriptionPrevious value: -"`.gitnexus` store under the MCP file root (default:\n`<file root>/.gitnexus`). Freshness/regeneration use the file root\nas the project root; this only selects the store path. Only used\nwith `filepath` — inline `code` has no module to place in the graph."New value: +"`.gitnexus` store under the file root (default: `<file root>/.gitnexus`);\nonly used with `filepath`."Input schema / properties / gitnexus_dir / typeRemoved value: -[
- "string",
- "null"
-]Input schema / properties / no_composable / descriptionPrevious value: -"Skip GitNexus generation; score whatever `.gitnexus` is already\nthere, or SIMPLE/SECURE/NAVIGABLE only when there is none."New value: +"Use no dependency graph, even an existing `.gitnexus`; score\nSIMPLE/SECURE/NAVIGABLE only."topos_preference_walk2 fields changedInput schema / properties / gate_scoresAdded value: +{
+ "additionalProperties": {
+ "format": "double",
+ "type": "number"
+ },
+ "default": {},
+ "description": "Pillar gate scores in `[0, 1]`. Enables `next_pillar`.",
+ "type": "object"
+}Input schema / properties / ranking / descriptionPrevious value: -"Permutation of {simple, composable, secure}, most-preferred first."New value: +"Permutation of {simple, composable, secure, navigable}, most-preferred first."topos_refactor2 fields changedInput schema / properties / gitnexus_dir / anyOfAdded value: +[
+ {
+ "type": "string"
+ },
+ {
+ "type": "null"
+ }
+]Input schema / properties / gitnexus_dir / typeRemoved value: -[
- "string",
- "null"
-]v0.6.0topos_generate_graphify_graphtopos_refactor3 fields changedInput schema / $defs / RefactorTargetKind / oneOfPrevious value: -[
- {
- "const": "cycles",
- "description": "CFG cycle-basis: loop/branch bodies driving cyclomatic complexity.",
- "type": "string"
- },
- {
- "const": "dependencies",
- "description": "MDG Forman curvature: load-bearing import edges (needs `.gitnexus`).",
- "type": "string"
- },
- {
- "const": "process",
- "description": "Process-graph choke points (needs `.gitnexus`).",
- "type": "string"
- },
- {
- "const": "graphify",
- "description": "Graphify orphan nodes / fragile inferred edges.",
- "type": "string"
- }
-]New value: +[
+ {
+ "const": "cycles",
+ "description": "CFG cycle-basis: loop/branch bodies driving cyclomatic complexity.",
+ "type": "string"
+ },
+ {
+ "const": "dependencies",
+ "description": "MDG Forman curvature: load-bearing import edges (needs `.gitnexus`).",
+ "type": "string"
+ },
+ {
+ "const": "process",
+ "description": "Process-graph choke points (needs `.gitnexus`).",
+ "type": "string"
+ }
+]Input schema / properties / graphify_dirRemoved value: -{
- "default": null,
- "description": "Override Graphify output directory (`target=graphify` only).",
- "type": [
- "string",
- "null"
- ]
-}Input schema / properties / target / descriptionPrevious value: -"Which analysis engine to run: `cycles` (CFG), `dependencies` /\n`process` (need `.gitnexus`), or `graphify` (need Graphify graph)."New value: +"Which analysis engine to run: `cycles` (CFG), or `dependencies` /\n`process` (need `.gitnexus`)."v0.5.0topos_assess_changeset5 fields changedInput schema / $defs / GeneratorInput / enumPrevious value: -[
- "simple",
- "composable",
- "secure"
-]New value: +[
+ "simple",
+ "composable",
+ "secure",
+ "navigable"
+]Input schema / $defs / LatticeElement / descriptionPrevious value: -"The 8 elements of the free Heyting algebra H(G_qual) on the three\ngenerators SIMPLE, COMPOSABLE, SECURE, mirroring `EvaluationValue` on\nthe MCP wire."New value: +"The 16 elements of the free Heyting algebra H(G_qual) on the four\ngenerators SIMPLE, COMPOSABLE, SECURE, NAVIGABLE, mirroring\n`EvaluationValue` on the MCP wire.\n\nNote for clients pinned to the pre-v0.5.0 shape: `IDEAL` now requires\nall four pillars. The verdict that used to be `IDEAL` — the top of the\nthree-generator algebra — serializes as `SIMPLE_COMPOSABLE_SECURE`.\nVariants are declared in **bitmask order**, matching\n`EvaluationValue::ALL`, so the two enums convert by position. Serde\nkeys on variant names, so this ordering is an implementation detail\nand not part of the wire contract."Input schema / $defs / LatticeElement / enumPrevious value: -[
- "SLOP",
- "SIMPLE",
- "COMPOSABLE",
- "SECURE",
- "SIMPLE_COMPOSABLE",
- "SIMPLE_SECURE",
- "COMPOSABLE_SECURE",
- "IDEAL"
-]New value: +[
+ "SLOP",
+ "SIMPLE",
+ "COMPOSABLE",
+ "SIMPLE_COMPOSABLE",
+ "SECURE",
+ "SIMPLE_SECURE",
+ "COMPOSABLE_SECURE",
+ "SIMPLE_COMPOSABLE_SECURE",
+ "NAVIGABLE",
+ "SIMPLE_NAVIGABLE",
+ "COMPOSABLE_NAVIGABLE",
+ "SIMPLE_COMPOSABLE_NAVIGABLE",
+ "SECURE_NAVIGABLE",
+ "SIMPLE_SECURE_NAVIGABLE",
+ "COMPOSABLE_SECURE_NAVIGABLE",
+ "IDEAL"
+]Input schema / $defs / UserPreferencesInput / descriptionPrevious value: -"Strict ranking over simple, composable, and secure."New value: +"Strict ranking over simple, composable, secure, and navigable."Input schema / $defs / UserPreferencesInput / properties / ranking / descriptionPrevious value: -"Permutation of simple/composable/secure, best first."New value: +"Permutation of simple/composable/secure/navigable, best first."topos_assess_improvement5 fields changedInput schema / $defs / GeneratorInput / enumPrevious value: -[
- "simple",
- "composable",
- "secure"
-]New value: +[
+ "simple",
+ "composable",
+ "secure",
+ "navigable"
+]Input schema / $defs / LatticeElement / descriptionPrevious value: -"The 8 elements of the free Heyting algebra H(G_qual) on the three\ngenerators SIMPLE, COMPOSABLE, SECURE, mirroring `EvaluationValue` on\nthe MCP wire."New value: +"The 16 elements of the free Heyting algebra H(G_qual) on the four\ngenerators SIMPLE, COMPOSABLE, SECURE, NAVIGABLE, mirroring\n`EvaluationValue` on the MCP wire.\n\nNote for clients pinned to the pre-v0.5.0 shape: `IDEAL` now requires\nall four pillars. The verdict that used to be `IDEAL` — the top of the\nthree-generator algebra — serializes as `SIMPLE_COMPOSABLE_SECURE`.\nVariants are declared in **bitmask order**, matching\n`EvaluationValue::ALL`, so the two enums convert by position. Serde\nkeys on variant names, so this ordering is an implementation detail\nand not part of the wire contract."Input schema / $defs / LatticeElement / enumPrevious value: -[
- "SLOP",
- "SIMPLE",
- "COMPOSABLE",
- "SECURE",
- "SIMPLE_COMPOSABLE",
- "SIMPLE_SECURE",
- "COMPOSABLE_SECURE",
- "IDEAL"
-]New value: +[
+ "SLOP",
+ "SIMPLE",
+ "COMPOSABLE",
+ "SIMPLE_COMPOSABLE",
+ "SECURE",
+ "SIMPLE_SECURE",
+ "COMPOSABLE_SECURE",
+ "SIMPLE_COMPOSABLE_SECURE",
+ "NAVIGABLE",
+ "SIMPLE_NAVIGABLE",
+ "COMPOSABLE_NAVIGABLE",
+ "SIMPLE_COMPOSABLE_NAVIGABLE",
+ "SECURE_NAVIGABLE",
+ "SIMPLE_SECURE_NAVIGABLE",
+ "COMPOSABLE_SECURE_NAVIGABLE",
+ "IDEAL"
+]Input schema / $defs / UserPreferencesInput / descriptionPrevious value: -"Strict ranking over simple, composable, and secure."New value: +"Strict ranking over simple, composable, secure, and navigable."Input schema / $defs / UserPreferencesInput / properties / ranking / descriptionPrevious value: -"Permutation of simple/composable/secure, best first."New value: +"Permutation of simple/composable/secure/navigable, best first."topos_assess_worktree_change5 fields changedInput schema / $defs / GeneratorInput / enumPrevious value: -[
- "simple",
- "composable",
- "secure"
-]New value: +[
+ "simple",
+ "composable",
+ "secure",
+ "navigable"
+]Input schema / $defs / LatticeElement / descriptionPrevious value: -"The 8 elements of the free Heyting algebra H(G_qual) on the three\ngenerators SIMPLE, COMPOSABLE, SECURE, mirroring `EvaluationValue` on\nthe MCP wire."New value: +"The 16 elements of the free Heyting algebra H(G_qual) on the four\ngenerators SIMPLE, COMPOSABLE, SECURE, NAVIGABLE, mirroring\n`EvaluationValue` on the MCP wire.\n\nNote for clients pinned to the pre-v0.5.0 shape: `IDEAL` now requires\nall four pillars. The verdict that used to be `IDEAL` — the top of the\nthree-generator algebra — serializes as `SIMPLE_COMPOSABLE_SECURE`.\nVariants are declared in **bitmask order**, matching\n`EvaluationValue::ALL`, so the two enums convert by position. Serde\nkeys on variant names, so this ordering is an implementation detail\nand not part of the wire contract."Input schema / $defs / LatticeElement / enumPrevious value: -[
- "SLOP",
- "SIMPLE",
- "COMPOSABLE",
- "SECURE",
- "SIMPLE_COMPOSABLE",
- "SIMPLE_SECURE",
- "COMPOSABLE_SECURE",
- "IDEAL"
-]New value: +[
+ "SLOP",
+ "SIMPLE",
+ "COMPOSABLE",
+ "SIMPLE_COMPOSABLE",
+ "SECURE",
+ "SIMPLE_SECURE",
+ "COMPOSABLE_SECURE",
+ "SIMPLE_COMPOSABLE_SECURE",
+ "NAVIGABLE",
+ "SIMPLE_NAVIGABLE",
+ "COMPOSABLE_NAVIGABLE",
+ "SIMPLE_COMPOSABLE_NAVIGABLE",
+ "SECURE_NAVIGABLE",
+ "SIMPLE_SECURE_NAVIGABLE",
+ "COMPOSABLE_SECURE_NAVIGABLE",
+ "IDEAL"
+]Input schema / $defs / UserPreferencesInput / descriptionPrevious value: -"Strict ranking over simple, composable, and secure."New value: +"Strict ranking over simple, composable, secure, and navigable."Input schema / $defs / UserPreferencesInput / properties / ranking / descriptionPrevious value: -"Permutation of simple/composable/secure, best first."New value: +"Permutation of simple/composable/secure/navigable, best first."topos_begin_refactor5 fields changedInput schema / $defs / GeneratorInput / enumPrevious value: -[
- "simple",
- "composable",
- "secure"
-]New value: +[
+ "simple",
+ "composable",
+ "secure",
+ "navigable"
+]Input schema / $defs / LatticeElement / descriptionPrevious value: -"The 8 elements of the free Heyting algebra H(G_qual) on the three\ngenerators SIMPLE, COMPOSABLE, SECURE, mirroring `EvaluationValue` on\nthe MCP wire."New value: +"The 16 elements of the free Heyting algebra H(G_qual) on the four\ngenerators SIMPLE, COMPOSABLE, SECURE, NAVIGABLE, mirroring\n`EvaluationValue` on the MCP wire.\n\nNote for clients pinned to the pre-v0.5.0 shape: `IDEAL` now requires\nall four pillars. The verdict that used to be `IDEAL` — the top of the\nthree-generator algebra — serializes as `SIMPLE_COMPOSABLE_SECURE`.\nVariants are declared in **bitmask order**, matching\n`EvaluationValue::ALL`, so the two enums convert by position. Serde\nkeys on variant names, so this ordering is an implementation detail\nand not part of the wire contract."Input schema / $defs / LatticeElement / enumPrevious value: -[
- "SLOP",
- "SIMPLE",
- "COMPOSABLE",
- "SECURE",
- "SIMPLE_COMPOSABLE",
- "SIMPLE_SECURE",
- "COMPOSABLE_SECURE",
- "IDEAL"
-]New value: +[
+ "SLOP",
+ "SIMPLE",
+ "COMPOSABLE",
+ "SIMPLE_COMPOSABLE",
+ "SECURE",
+ "SIMPLE_SECURE",
+ "COMPOSABLE_SECURE",
+ "SIMPLE_COMPOSABLE_SECURE",
+ "NAVIGABLE",
+ "SIMPLE_NAVIGABLE",
+ "COMPOSABLE_NAVIGABLE",
+ "SIMPLE_COMPOSABLE_NAVIGABLE",
+ "SECURE_NAVIGABLE",
+ "SIMPLE_SECURE_NAVIGABLE",
+ "COMPOSABLE_SECURE_NAVIGABLE",
+ "IDEAL"
+]Input schema / $defs / UserPreferencesInput / descriptionPrevious value: -"Strict ranking over simple, composable, and secure."New value: +"Strict ranking over simple, composable, secure, and navigable."Input schema / $defs / UserPreferencesInput / properties / ranking / descriptionPrevious value: -"Permutation of simple/composable/secure, best first."New value: +"Permutation of simple/composable/secure/navigable, best first."topos_depgraph_status2 fields changedInput schema / properties / directoryAdded value: +{
+ "default": null,
+ "description": "Repo root to inspect (default: MCP file root / process project root).",
+ "type": [
+ "string",
+ "null"
+ ]
+}Input schema / properties / gitnexus_dir / descriptionPrevious value: -"`.gitnexus` store under the MCP file root (default:\n`<file root>/.gitnexus`). Does not change the file root."New value: +"`.gitnexus` store under the project root (default:\n`<project root>/.gitnexus`)."topos_evaluate_code5 fields changedInput schema / $defs / GeneratorInput / enumPrevious value: -[
- "simple",
- "composable",
- "secure"
-]New value: +[
+ "simple",
+ "composable",
+ "secure",
+ "navigable"
+]Input schema / $defs / LatticeElement / descriptionPrevious value: -"The 8 elements of the free Heyting algebra H(G_qual) on the three\ngenerators SIMPLE, COMPOSABLE, SECURE, mirroring `EvaluationValue` on\nthe MCP wire."New value: +"The 16 elements of the free Heyting algebra H(G_qual) on the four\ngenerators SIMPLE, COMPOSABLE, SECURE, NAVIGABLE, mirroring\n`EvaluationValue` on the MCP wire.\n\nNote for clients pinned to the pre-v0.5.0 shape: `IDEAL` now requires\nall four pillars. The verdict that used to be `IDEAL` — the top of the\nthree-generator algebra — serializes as `SIMPLE_COMPOSABLE_SECURE`.\nVariants are declared in **bitmask order**, matching\n`EvaluationValue::ALL`, so the two enums convert by position. Serde\nkeys on variant names, so this ordering is an implementation detail\nand not part of the wire contract."Input schema / $defs / LatticeElement / enumPrevious value: -[
- "SLOP",
- "SIMPLE",
- "COMPOSABLE",
- "SECURE",
- "SIMPLE_COMPOSABLE",
- "SIMPLE_SECURE",
- "COMPOSABLE_SECURE",
- "IDEAL"
-]New value: +[
+ "SLOP",
+ "SIMPLE",
+ "COMPOSABLE",
+ "SIMPLE_COMPOSABLE",
+ "SECURE",
+ "SIMPLE_SECURE",
+ "COMPOSABLE_SECURE",
+ "SIMPLE_COMPOSABLE_SECURE",
+ "NAVIGABLE",
+ "SIMPLE_NAVIGABLE",
+ "COMPOSABLE_NAVIGABLE",
+ "SIMPLE_COMPOSABLE_NAVIGABLE",
+ "SECURE_NAVIGABLE",
+ "SIMPLE_SECURE_NAVIGABLE",
+ "COMPOSABLE_SECURE_NAVIGABLE",
+ "IDEAL"
+]Input schema / $defs / UserPreferencesInput / descriptionPrevious value: -"Strict ranking over simple, composable, and secure."New value: +"Strict ranking over simple, composable, secure, and navigable."Input schema / $defs / UserPreferencesInput / properties / ranking / descriptionPrevious value: -"Permutation of simple/composable/secure, best first."New value: +"Permutation of simple/composable/secure/navigable, best first."topos_evaluate_file6 fields changedInput schema / $defs / GeneratorInput / enumPrevious value: -[
- "simple",
- "composable",
- "secure"
-]New value: +[
+ "simple",
+ "composable",
+ "secure",
+ "navigable"
+]Input schema / $defs / LatticeElement / descriptionPrevious value: -"The 8 elements of the free Heyting algebra H(G_qual) on the three\ngenerators SIMPLE, COMPOSABLE, SECURE, mirroring `EvaluationValue` on\nthe MCP wire."New value: +"The 16 elements of the free Heyting algebra H(G_qual) on the four\ngenerators SIMPLE, COMPOSABLE, SECURE, NAVIGABLE, mirroring\n`EvaluationValue` on the MCP wire.\n\nNote for clients pinned to the pre-v0.5.0 shape: `IDEAL` now requires\nall four pillars. The verdict that used to be `IDEAL` — the top of the\nthree-generator algebra — serializes as `SIMPLE_COMPOSABLE_SECURE`.\nVariants are declared in **bitmask order**, matching\n`EvaluationValue::ALL`, so the two enums convert by position. Serde\nkeys on variant names, so this ordering is an implementation detail\nand not part of the wire contract."Input schema / $defs / LatticeElement / enumPrevious value: -[
- "SLOP",
- "SIMPLE",
- "COMPOSABLE",
- "SECURE",
- "SIMPLE_COMPOSABLE",
- "SIMPLE_SECURE",
- "COMPOSABLE_SECURE",
- "IDEAL"
-]New value: +[
+ "SLOP",
+ "SIMPLE",
+ "COMPOSABLE",
+ "SIMPLE_COMPOSABLE",
+ "SECURE",
+ "SIMPLE_SECURE",
+ "COMPOSABLE_SECURE",
+ "SIMPLE_COMPOSABLE_SECURE",
+ "NAVIGABLE",
+ "SIMPLE_NAVIGABLE",
+ "COMPOSABLE_NAVIGABLE",
+ "SIMPLE_COMPOSABLE_NAVIGABLE",
+ "SECURE_NAVIGABLE",
+ "SIMPLE_SECURE_NAVIGABLE",
+ "COMPOSABLE_SECURE_NAVIGABLE",
+ "IDEAL"
+]Input schema / $defs / UserPreferencesInput / descriptionPrevious value: -"Strict ranking over simple, composable, and secure."New value: +"Strict ranking over simple, composable, secure, and navigable."Input schema / $defs / UserPreferencesInput / properties / ranking / descriptionPrevious value: -"Permutation of simple/composable/secure, best first."New value: +"Permutation of simple/composable/secure/navigable, best first."Input schema / properties / no_composable / descriptionPrevious value: -"Skip GitNexus detection/generation; score SIMPLE/SECURE only,\nexactly like a missing `.gitnexus` did before this tool started\ngenerating it automatically."New value: +"Skip GitNexus detection/generation; score SIMPLE/SECURE/NAVIGABLE\nonly, exactly like a missing `.gitnexus` did before this tool\nstarted generating it automatically."topos_evaluate_project6 fields changedInput schema / $defs / GeneratorInput / enumPrevious value: -[
- "simple",
- "composable",
- "secure"
-]New value: +[
+ "simple",
+ "composable",
+ "secure",
+ "navigable"
+]Input schema / $defs / LatticeElement / descriptionPrevious value: -"The 8 elements of the free Heyting algebra H(G_qual) on the three\ngenerators SIMPLE, COMPOSABLE, SECURE, mirroring `EvaluationValue` on\nthe MCP wire."New value: +"The 16 elements of the free Heyting algebra H(G_qual) on the four\ngenerators SIMPLE, COMPOSABLE, SECURE, NAVIGABLE, mirroring\n`EvaluationValue` on the MCP wire.\n\nNote for clients pinned to the pre-v0.5.0 shape: `IDEAL` now requires\nall four pillars. The verdict that used to be `IDEAL` — the top of the\nthree-generator algebra — serializes as `SIMPLE_COMPOSABLE_SECURE`.\nVariants are declared in **bitmask order**, matching\n`EvaluationValue::ALL`, so the two enums convert by position. Serde\nkeys on variant names, so this ordering is an implementation detail\nand not part of the wire contract."Input schema / $defs / LatticeElement / enumPrevious value: -[
- "SLOP",
- "SIMPLE",
- "COMPOSABLE",
- "SECURE",
- "SIMPLE_COMPOSABLE",
- "SIMPLE_SECURE",
- "COMPOSABLE_SECURE",
- "IDEAL"
-]New value: +[
+ "SLOP",
+ "SIMPLE",
+ "COMPOSABLE",
+ "SIMPLE_COMPOSABLE",
+ "SECURE",
+ "SIMPLE_SECURE",
+ "COMPOSABLE_SECURE",
+ "SIMPLE_COMPOSABLE_SECURE",
+ "NAVIGABLE",
+ "SIMPLE_NAVIGABLE",
+ "COMPOSABLE_NAVIGABLE",
+ "SIMPLE_COMPOSABLE_NAVIGABLE",
+ "SECURE_NAVIGABLE",
+ "SIMPLE_SECURE_NAVIGABLE",
+ "COMPOSABLE_SECURE_NAVIGABLE",
+ "IDEAL"
+]Input schema / $defs / UserPreferencesInput / descriptionPrevious value: -"Strict ranking over simple, composable, and secure."New value: +"Strict ranking over simple, composable, secure, and navigable."Input schema / $defs / UserPreferencesInput / properties / ranking / descriptionPrevious value: -"Permutation of simple/composable/secure, best first."New value: +"Permutation of simple/composable/secure/navigable, best first."Input schema / properties / no_composable / descriptionPrevious value: -"Skip GitNexus detection/generation; score SIMPLE/SECURE only,\nexactly like a missing `.gitnexus` did before this tool started\ngenerating it automatically."New value: +"Skip GitNexus detection/generation; score SIMPLE/SECURE/NAVIGABLE\nonly, exactly like a missing `.gitnexus` did before this tool\nstarted generating it automatically."topos_generate_depgraph2 fields changedInput schema / properties / directory / descriptionPrevious value: -"Repo root to analyze (default: derived from `gitnexus_dir` when set,\notherwise the MCP file root). Explicit `directory` wins over derivation."New value: +"Repo root to analyze (default: MCP file root / process project root)."Input schema / properties / gitnexus_dir / descriptionPrevious value: -"`.gitnexus` store under the MCP file root. When `directory` is omitted,\nthe analyze root is the parent of this path — same derivation\n`topos_depgraph_status` uses — so status → generate stay aligned."New value: +"`.gitnexus` store under the project root."topos_generate_graphify_graph4 fields changedInput schema / properties / directory / defaultRemoved value: -nullInput schema / properties / directory / descriptionPrevious value: -"Directory to analyze (default: MCP file root)."New value: +"Absolute directory in the project to analyze."Input schema / properties / directory / typePrevious value: -[
- "string",
- "null"
-]New value: +"string"Input schema / requiredAdded value: +[
+ "directory"
+]topos_inspect_code7 fields changedInput schema / $defs / GeneratorInput / enumPrevious value: -[
- "simple",
- "composable",
- "secure"
-]New value: +[
+ "simple",
+ "composable",
+ "secure",
+ "navigable"
+]Input schema / $defs / LatticeElement / descriptionPrevious value: -"The 8 elements of the free Heyting algebra H(G_qual) on the three\ngenerators SIMPLE, COMPOSABLE, SECURE, mirroring `EvaluationValue` on\nthe MCP wire."New value: +"The 16 elements of the free Heyting algebra H(G_qual) on the four\ngenerators SIMPLE, COMPOSABLE, SECURE, NAVIGABLE, mirroring\n`EvaluationValue` on the MCP wire.\n\nNote for clients pinned to the pre-v0.5.0 shape: `IDEAL` now requires\nall four pillars. The verdict that used to be `IDEAL` — the top of the\nthree-generator algebra — serializes as `SIMPLE_COMPOSABLE_SECURE`.\nVariants are declared in **bitmask order**, matching\n`EvaluationValue::ALL`, so the two enums convert by position. Serde\nkeys on variant names, so this ordering is an implementation detail\nand not part of the wire contract."Input schema / $defs / LatticeElement / enumPrevious value: -[
- "SLOP",
- "SIMPLE",
- "COMPOSABLE",
- "SECURE",
- "SIMPLE_COMPOSABLE",
- "SIMPLE_SECURE",
- "COMPOSABLE_SECURE",
- "IDEAL"
-]New value: +[
+ "SLOP",
+ "SIMPLE",
+ "COMPOSABLE",
+ "SIMPLE_COMPOSABLE",
+ "SECURE",
+ "SIMPLE_SECURE",
+ "COMPOSABLE_SECURE",
+ "SIMPLE_COMPOSABLE_SECURE",
+ "NAVIGABLE",
+ "SIMPLE_NAVIGABLE",
+ "COMPOSABLE_NAVIGABLE",
+ "SIMPLE_COMPOSABLE_NAVIGABLE",
+ "SECURE_NAVIGABLE",
+ "SIMPLE_SECURE_NAVIGABLE",
+ "COMPOSABLE_SECURE_NAVIGABLE",
+ "IDEAL"
+]Input schema / $defs / UserPreferencesInput / descriptionPrevious value: -"Strict ranking over simple, composable, and secure."New value: +"Strict ranking over simple, composable, secure, and navigable."Input schema / $defs / UserPreferencesInput / properties / ranking / descriptionPrevious value: -"Permutation of simple/composable/secure, best first."New value: +"Permutation of simple/composable/secure/navigable, best first."Input schema / properties / no_composable / descriptionPrevious value: -"Skip GitNexus generation; score whatever `.gitnexus` is already\nthere, or SIMPLE/SECURE only when there is none."New value: +"Skip GitNexus generation; score whatever `.gitnexus` is already\nthere, or SIMPLE/SECURE/NAVIGABLE only when there is none."Input schema / properties / preferences / descriptionPrevious value: -"Strict total order on the three generators; see\n`topos://docs/preferences`."New value: +"Strict total order on the four generators; see\n`topos://docs/preferences`."topos_preference_walk3 fields changedInput schema / $defs / GeneratorInput / enumPrevious value: -[
- "simple",
- "composable",
- "secure"
-]New value: +[
+ "simple",
+ "composable",
+ "secure",
+ "navigable"
+]Input schema / $defs / LatticeElement / descriptionPrevious value: -"The 8 elements of the free Heyting algebra H(G_qual) on the three\ngenerators SIMPLE, COMPOSABLE, SECURE, mirroring `EvaluationValue` on\nthe MCP wire."New value: +"The 16 elements of the free Heyting algebra H(G_qual) on the four\ngenerators SIMPLE, COMPOSABLE, SECURE, NAVIGABLE, mirroring\n`EvaluationValue` on the MCP wire.\n\nNote for clients pinned to the pre-v0.5.0 shape: `IDEAL` now requires\nall four pillars. The verdict that used to be `IDEAL` — the top of the\nthree-generator algebra — serializes as `SIMPLE_COMPOSABLE_SECURE`.\nVariants are declared in **bitmask order**, matching\n`EvaluationValue::ALL`, so the two enums convert by position. Serde\nkeys on variant names, so this ordering is an implementation detail\nand not part of the wire contract."Input schema / $defs / LatticeElement / enumPrevious value: -[
- "SLOP",
- "SIMPLE",
- "COMPOSABLE",
- "SECURE",
- "SIMPLE_COMPOSABLE",
- "SIMPLE_SECURE",
- "COMPOSABLE_SECURE",
- "IDEAL"
-]New value: +[
+ "SLOP",
+ "SIMPLE",
+ "COMPOSABLE",
+ "SIMPLE_COMPOSABLE",
+ "SECURE",
+ "SIMPLE_SECURE",
+ "COMPOSABLE_SECURE",
+ "SIMPLE_COMPOSABLE_SECURE",
+ "NAVIGABLE",
+ "SIMPLE_NAVIGABLE",
+ "COMPOSABLE_NAVIGABLE",
+ "SIMPLE_COMPOSABLE_NAVIGABLE",
+ "SECURE_NAVIGABLE",
+ "SIMPLE_SECURE_NAVIGABLE",
+ "COMPOSABLE_SECURE_NAVIGABLE",
+ "IDEAL"
+]v0.4.4topos_depgraph_status1 field changedInput schema / properties / gitnexus_dir / descriptionPrevious value: -"Override .gitnexus directory (default: <root>/.gitnexus)."New value: +"`.gitnexus` store under the MCP file root (default:\n`<file root>/.gitnexus`). Does not change the file root."topos_evaluate_file1 field changedInput schema / properties / gitnexus_dir / descriptionPrevious value: -".gitnexus directory for COMPOSABLE scoring. When omitted, it is\nauto-detected at `<file root>/.gitnexus`; if missing or stale, this\ntool generates/refreshes it first (see `no_composable`)."New value: +"`.gitnexus` store under the MCP file root (default:\n`<file root>/.gitnexus`). Freshness and regeneration always use the\nfile root as the project root; this only selects the store path\ninside it. If missing or stale, this tool generates/refreshes first\n(see `no_composable`)."topos_evaluate_project1 field changedInput schema / properties / gitnexus_dir / descriptionPrevious value: -"Path to a `.gitnexus` dependency-graph directory, for COMPOSABLE\nscoring. When omitted, it is auto-detected from the project root;\nif missing or stale, this tool generates/refreshes it first (see\n`no_composable`). If generation isn't possible (GitNexus not\ninstalled, generation failure), COMPOSABLE is reported as\nunavailable rather than failing the whole evaluation."New value: +"`.gitnexus` store under the MCP file root (default:\n`<file root>/.gitnexus`). Freshness and regeneration always use the\nfile root as the project root; this only selects the store path\ninside it. If missing or stale, this tool generates/refreshes first\n(see `no_composable`). If generation isn't possible, COMPOSABLE is\nreported as unavailable rather than failing the whole evaluation."topos_generate_depgraph2 fields changedInput schema / properties / directory / descriptionPrevious value: -"Repo root (default: MCP file root)."New value: +"Repo root to analyze (default: derived from `gitnexus_dir` when set,\notherwise the MCP file root). Explicit `directory` wins over derivation."Input schema / properties / gitnexus_dirAdded value: +{
+ "default": null,
+ "description": "`.gitnexus` store under the MCP file root. When `directory` is omitted,\nthe analyze root is the parent of this path — same derivation\n`topos_depgraph_status` uses — so status → generate stay aligned.",
+ "type": [
+ "string",
+ "null"
+ ]
+}topos_inspect_code1 field changedInput schema / properties / gitnexus_dir / descriptionPrevious value: -".gitnexus directory for COMPOSABLE scoring. When omitted, it is\nauto-detected at `<file root>/.gitnexus`; if missing or stale, this\ntool generates/refreshes it first (see `no_composable`). Only used\nwith `filepath` — inline `code` has no module to place in the graph."New value: +"`.gitnexus` store under the MCP file root (default:\n`<file root>/.gitnexus`). Freshness/regeneration use the file root\nas the project root; this only selects the store path. Only used\nwith `filepath` — inline `code` has no module to place in the graph."v0.4.0topos_assess_changeset10 fields changedInput schema / $defsAdded value: +{
+ "GeneratorInput": {
+ "description": "Wire form of a generator name.",
+ "enum": [
+ "simple",
+ "composable",
+ "secure"
+ ],
+ "type": "string"
+ },
+ "LatticeElement": {
+ "description": "The 8 elements of the free Heyting algebra H(G_qual) on the three\ngenerators SIMPLE, COMPOSABLE, SECURE, mirroring `EvaluationValue` on\nthe MCP wire.",
+ "enum": [
+ "SLOP",
+ "SIMPLE",
+ "COMPOSABLE",
+ "SECURE",
+ "SIMPLE_COMPOSABLE",
+ "SIMPLE_SECURE",
+ "COMPOSABLE_SECURE",
+ "IDEAL"
+ ],
+ "type": "string"
+ },
+ "UserPreferencesInput": {
+ "additionalProperties": false,
+ "description": "Strict ranking over simple, composable, and secure.",
+ "properties": {
+ "ranking": {
+ "description": "Permutation of simple/composable/secure, best first.",
+ "items": {
+ "$ref": "#/$defs/GeneratorInput"
+ },
+ "type": "array"
+ },
+ "target": {
+ "anyOf": [
+ {
+ "$ref": "#/$defs/LatticeElement"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "Optional explicit target verdict."
+ }
+ },
+ "required": [
+ "ranking"
+ ],
+ "type": "object"
+ }
+}Input schema / $schemaAdded value: +"https://json-schema.org/draft/2020-12/schema"Input schema / properties / allowAdded value: +{
+ "default": [],
+ "description": "One-off acknowledged dangerous-call patterns.",
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+}Input schema / properties / baseline_refAdded value: +{
+ "default": "HEAD",
+ "description": "Git baseline ref each file is compared against.",
+ "type": "string"
+}Input schema / properties / filesAdded value: +{
+ "description": "Edited file paths (working tree) that make up the changeset.",
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+}Input schema / properties / gitnexus_dirAdded value: +{
+ "default": null,
+ "type": [
+ "string",
+ "null"
+ ]
+}Input schema / properties / include_security_findingsAdded value: +{
+ "default": true,
+ "type": "boolean"
+}Input schema / properties / paramsRemoved value: -{
- "additionalProperties": false,
- "description": "Arguments for ``topos_assess_changeset`` (multi-file refactor).",
- "properties": {
- "allow": {
- "description": "One-off acknowledged dangerous-call patterns.",
- "items": {
- "type": "string"
- },
- "type": "array"
- },
- "baseline_ref": {
- "default": "HEAD",
- "description": "Git baseline ref each file is compared against.",
- "minLength": 1,
- "type": "string"
- },
- "files": {
- "description": "Edited file paths (working tree) that make up the changeset.",
- "items": {
- "type": "string"
- },
- "minItems": 1,
- "type": "array"
- },
- "gitnexus_dir": {
- "anyOf": [
- {
- "type": "string"
- },
- {
- "type": "null"
- }
- ],
- "default": null
- },
- "include_security_findings": {
- "default": true,
- "type": "boolean"
- },
- "preferences": {
- "anyOf": [
- {
- "additionalProperties": false,
- "description": "Strict ranking over simple, composable, and secure.",
- "properties": {
- "ranking": {
- "description": "Permutation of simple/composable/secure, best first.",
- "items": {
- "description": "The three quality generators of ``G_qual``.",
- "enum": [
- "simple",
- "composable",
- "secure"
- ],
- "type": "string"
- },
- "maxItems": 3,
- "minItems": 3,
- "type": "array"
- },
- "target": {
- "anyOf": [
- {
- "description": "The 8 quality verdicts, from SLOP (none) to IDEAL (simple+composable+secure).",
- "enum": [
- "SLOP",
- "SIMPLE",
- "COMPOSABLE",
- "SECURE",
- "SIMPLE_COMPOSABLE",
- "SIMPLE_SECURE",
- "COMPOSABLE_SECURE",
- "IDEAL"
- ],
- "type": "string"
- },
- {
- "type": "null"
- }
- ],
- "default": null,
- "description": "Optional explicit target verdict."
- }
- },
- "required": [
- "ranking"
- ],
- "type": "object"
- },
- {
- "type": "null"
- }
- ],
- "default": null,
- "description": "Optional generator ranking."
- }
- },
- "required": [
- "files"
- ],
- "type": "object"
-}Input schema / properties / preferencesAdded value: +{
+ "anyOf": [
+ {
+ "$ref": "#/$defs/UserPreferencesInput"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "Optional generator ranking."
+}Input schema / requiredPrevious value: -[
- "params"
-]New value: +[
+ "files"
+]topos_assess_improvement13 fields changedInput schema / $defsAdded value: +{
+ "GeneratorInput": {
+ "description": "Wire form of a generator name.",
+ "enum": [
+ "simple",
+ "composable",
+ "secure"
+ ],
+ "type": "string"
+ },
+ "LatticeElement": {
+ "description": "The 8 elements of the free Heyting algebra H(G_qual) on the three\ngenerators SIMPLE, COMPOSABLE, SECURE, mirroring `EvaluationValue` on\nthe MCP wire.",
+ "enum": [
+ "SLOP",
+ "SIMPLE",
+ "COMPOSABLE",
+ "SECURE",
+ "SIMPLE_COMPOSABLE",
+ "SIMPLE_SECURE",
+ "COMPOSABLE_SECURE",
+ "IDEAL"
+ ],
+ "type": "string"
+ },
+ "UserPreferencesInput": {
+ "additionalProperties": false,
+ "description": "Strict ranking over simple, composable, and secure.",
+ "properties": {
+ "ranking": {
+ "description": "Permutation of simple/composable/secure, best first.",
+ "items": {
+ "$ref": "#/$defs/GeneratorInput"
+ },
+ "type": "array"
+ },
+ "target": {
+ "anyOf": [
+ {
+ "$ref": "#/$defs/LatticeElement"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "Optional explicit target verdict."
+ }
+ },
+ "required": [
+ "ranking"
+ ],
+ "type": "object"
+ }
+}Input schema / $schemaAdded value: +"https://json-schema.org/draft/2020-12/schema"Input schema / properties / allowAdded value: +{
+ "default": [],
+ "description": "One-off acknowledged dangerous-call patterns.",
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+}Input schema / properties / current_codeAdded value: +{
+ "default": null,
+ "description": "Inline baseline source; COMPOSABLE is unavailable.",
+ "type": [
+ "string",
+ "null"
+ ]
+}Input schema / properties / filepathAdded value: +{
+ "default": null,
+ "description": "Baseline file path for side-by-side assessment.",
+ "type": [
+ "string",
+ "null"
+ ]
+}Input schema / properties / gitnexus_dirAdded value: +{
+ "default": null,
+ "type": [
+ "string",
+ "null"
+ ]
+}Input schema / properties / include_security_findingsAdded value: +{
+ "default": true,
+ "description": "Include SECURE findings.",
+ "type": "boolean"
+}Input schema / properties / languageAdded value: +{
+ "default": "python",
+ "type": "string"
+}Input schema / properties / paramsRemoved value: -{
- "additionalProperties": false,
- "description": "Side-by-side assessment. In-place edits use worktree/snapshot tools.",
- "properties": {
- "allow": {
- "description": "One-off acknowledged dangerous-call patterns.",
- "items": {
- "type": "string"
- },
- "type": "array"
- },
- "current_code": {
- "anyOf": [
- {
- "type": "string"
- },
- {
- "type": "null"
- }
- ],
- "default": null,
- "description": "Inline baseline source; COMPOSABLE is unavailable."
- },
- "filepath": {
- "anyOf": [
- {
- "type": "string"
- },
- {
- "type": "null"
- }
- ],
- "default": null,
- "description": "Baseline file path for side-by-side assessment."
- },
- "gitnexus_dir": {
- "anyOf": [
- {
- "type": "string"
- },
- {
- "type": "null"
- }
- ],
- "default": null
- },
- "include_security_findings": {
- "default": true,
- "description": "Include SECURE findings.",
- "type": "boolean"
- },
- "language": {
- "default": "python",
- "type": "string"
- },
- "preferences": {
- "anyOf": [
- {
- "additionalProperties": false,
- "description": "Strict ranking over simple, composable, and secure.",
- "properties": {
- "ranking": {
- "description": "Permutation of simple/composable/secure, best first.",
- "items": {
- "description": "The three quality generators of ``G_qual``.",
- "enum": [
- "simple",
- "composable",
- "secure"
- ],
- "type": "string"
- },
- "maxItems": 3,
- "minItems": 3,
- "type": "array"
- },
- "target": {
- "anyOf": [
- {
- "description": "The 8 quality verdicts, from SLOP (none) to IDEAL (simple+composable+secure).",
- "enum": [
- "SLOP",
- "SIMPLE",
- "COMPOSABLE",
- "SECURE",
- "SIMPLE_COMPOSABLE",
- "SIMPLE_SECURE",
- "COMPOSABLE_SECURE",
- "IDEAL"
- ],
- "type": "string"
- },
- {
- "type": "null"
- }
- ],
- "default": null,
- "description": "Optional explicit target verdict."
- }
- },
- "required": [
- "ranking"
- ],
- "type": "object"
- },
- {
- "type": "null"
- }
- ],
- "default": null,
- "description": "Optional generator ranking."
- },
- "proposed_code": {
- "anyOf": [
- {
- "minLength": 1,
- "type": "string"
- },
- {
- "type": "null"
- }
- ],
- "default": null,
- "description": "Proposed source."
- },
- "proposed_filepath": {
- "anyOf": [
- {
- "minLength": 1,
- "type": "string"
- },
- {
- "type": "null"
- }
- ],
- "default": null,
- "description": "Proposed file path."
- }
- },
- "type": "object"
-}Input schema / properties / preferencesAdded value: +{
+ "anyOf": [
+ {
+ "$ref": "#/$defs/UserPreferencesInput"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "Optional generator ranking."
+}Input schema / properties / proposed_codeAdded value: +{
+ "default": null,
+ "description": "Proposed source.",
+ "type": [
+ "string",
+ "null"
+ ]
+}Input schema / properties / proposed_filepathAdded value: +{
+ "default": null,
+ "description": "Proposed file path.",
+ "type": [
+ "string",
+ "null"
+ ]
+}Input schema / requiredRemoved value: -[
- "params"
-]topos_assess_snapshottopos_assess_worktree_changetopos_begin_refactor7 fields changedInput schema / $defsAdded value: +{
+ "GeneratorInput": {
+ "description": "Wire form of a generator name.",
+ "enum": [
+ "simple",
+ "composable",
+ "secure"
+ ],
+ "type": "string"
+ },
+ "LatticeElement": {
+ "description": "The 8 elements of the free Heyting algebra H(G_qual) on the three\ngenerators SIMPLE, COMPOSABLE, SECURE, mirroring `EvaluationValue` on\nthe MCP wire.",
+ "enum": [
+ "SLOP",
+ "SIMPLE",
+ "COMPOSABLE",
+ "SECURE",
+ "SIMPLE_COMPOSABLE",
+ "SIMPLE_SECURE",
+ "COMPOSABLE_SECURE",
+ "IDEAL"
+ ],
+ "type": "string"
+ },
+ "UserPreferencesInput": {
+ "additionalProperties": false,
+ "description": "Strict ranking over simple, composable, and secure.",
+ "properties": {
+ "ranking": {
+ "description": "Permutation of simple/composable/secure, best first.",
+ "items": {
+ "$ref": "#/$defs/GeneratorInput"
+ },
+ "type": "array"
+ },
+ "target": {
+ "anyOf": [
+ {
+ "$ref": "#/$defs/LatticeElement"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "Optional explicit target verdict."
+ }
+ },
+ "required": [
+ "ranking"
+ ],
+ "type": "object"
+ }
+}Input schema / $schemaAdded value: +"https://json-schema.org/draft/2020-12/schema"Input schema / properties / filepathAdded value: +{
+ "description": "File path to snapshot.",
+ "type": "string"
+}Input schema / properties / gitnexus_dirAdded value: +{
+ "default": null,
+ "description": ".gitnexus directory.",
+ "type": [
+ "string",
+ "null"
+ ]
+}Input schema / properties / paramsRemoved value: -{
- "additionalProperties": false,
- "description": "Capture a dirty/untracked baseline before editing.",
- "properties": {
- "filepath": {
- "description": "File path to snapshot.",
- "minLength": 1,
- "type": "string"
- },
- "gitnexus_dir": {
- "anyOf": [
- {
- "type": "string"
- },
- {
- "type": "null"
- }
- ],
- "default": null,
- "description": ".gitnexus directory."
- },
- "preferences": {
- "anyOf": [
- {
- "additionalProperties": false,
- "description": "Strict ranking over simple, composable, and secure.",
- "properties": {
- "ranking": {
- "description": "Permutation of simple/composable/secure, best first.",
- "items": {
- "description": "The three quality generators of ``G_qual``.",
- "enum": [
- "simple",
- "composable",
- "secure"
- ],
- "type": "string"
- },
- "maxItems": 3,
- "minItems": 3,
- "type": "array"
- },
- "target": {
- "anyOf": [
- {
- "description": "The 8 quality verdicts, from SLOP (none) to IDEAL (simple+composable+secure).",
- "enum": [
- "SLOP",
- "SIMPLE",
- "COMPOSABLE",
- "SECURE",
- "SIMPLE_COMPOSABLE",
- "SIMPLE_SECURE",
- "COMPOSABLE_SECURE",
- "IDEAL"
- ],
- "type": "string"
- },
- {
- "type": "null"
- }
- ],
- "default": null,
- "description": "Optional explicit target verdict."
- }
- },
- "required": [
- "ranking"
- ],
- "type": "object"
- },
- {
- "type": "null"
- }
- ],
- "default": null,
- "description": "Optional generator ranking."
- }
- },
- "required": [
- "filepath"
- ],
- "type": "object"
-}Input schema / properties / preferencesAdded value: +{
+ "anyOf": [
+ {
+ "$ref": "#/$defs/UserPreferencesInput"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "Optional generator ranking."
+}Input schema / requiredPrevious value: -[
- "params"
-]New value: +[
+ "filepath"
+]topos_calculate_coveragetopos_compare_codetopos_compare_files5 fields changedInput schema / $schemaAdded value: +"https://json-schema.org/draft/2020-12/schema"Input schema / properties / paramsRemoved value: -{
- "additionalProperties": false,
- "description": "Arguments for ``topos_compare_files``.",
- "properties": {
- "source": {
- "description": "Baseline file path.",
- "minLength": 1,
- "type": "string"
- },
- "target": {
- "description": "Comparison file path.",
- "minLength": 1,
- "type": "string"
- }
- },
- "required": [
- "source",
- "target"
- ],
- "type": "object"
-}Input schema / properties / sourceAdded value: +{
+ "description": "Baseline file path.",
+ "type": "string"
+}Input schema / properties / targetAdded value: +{
+ "description": "Comparison file path.",
+ "type": "string"
+}Input schema / requiredPrevious value: -[
- "params"
-]New value: +[
+ "source",
+ "target"
+]topos_depgraph_status4 fields changedInput schema / $schemaAdded value: +"https://json-schema.org/draft/2020-12/schema"Input schema / properties / gitnexus_dirAdded value: +{
+ "default": null,
+ "description": "Override .gitnexus directory (default: <root>/.gitnexus).",
+ "type": [
+ "string",
+ "null"
+ ]
+}Input schema / properties / paramsRemoved value: -{
- "additionalProperties": false,
- "description": "Arguments for ``topos_depgraph_status``.",
- "properties": {
- "gitnexus_dir": {
- "anyOf": [
- {
- "type": "string"
- },
- {
- "type": "null"
- }
- ],
- "default": null,
- "description": "Override .gitnexus directory (default: <root>/.gitnexus)."
- }
- },
- "type": "object"
-}Input schema / requiredRemoved value: -[
- "params"
-]topos_evaluate_code9 fields changedInput schema / $defsAdded value: +{
+ "GeneratorInput": {
+ "description": "Wire form of a generator name.",
+ "enum": [
+ "simple",
+ "composable",
+ "secure"
+ ],
+ "type": "string"
+ },
+ "LatticeElement": {
+ "description": "The 8 elements of the free Heyting algebra H(G_qual) on the three\ngenerators SIMPLE, COMPOSABLE, SECURE, mirroring `EvaluationValue` on\nthe MCP wire.",
+ "enum": [
+ "SLOP",
+ "SIMPLE",
+ "COMPOSABLE",
+ "SECURE",
+ "SIMPLE_COMPOSABLE",
+ "SIMPLE_SECURE",
+ "COMPOSABLE_SECURE",
+ "IDEAL"
+ ],
+ "type": "string"
+ },
+ "UserPreferencesInput": {
+ "additionalProperties": false,
+ "description": "Strict ranking over simple, composable, and secure.",
+ "properties": {
+ "ranking": {
+ "description": "Permutation of simple/composable/secure, best first.",
+ "items": {
+ "$ref": "#/$defs/GeneratorInput"
+ },
+ "type": "array"
+ },
+ "target": {
+ "anyOf": [
+ {
+ "$ref": "#/$defs/LatticeElement"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "Optional explicit target verdict."
+ }
+ },
+ "required": [
+ "ranking"
+ ],
+ "type": "object"
+ }
+}Input schema / $schemaAdded value: +"https://json-schema.org/draft/2020-12/schema"Input schema / properties / allowAdded value: +{
+ "default": [],
+ "description": "One-off acknowledged dangerous-call patterns.",
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+}Input schema / properties / codeAdded value: +{
+ "description": "Source code to evaluate.",
+ "type": "string"
+}Input schema / properties / languageAdded value: +{
+ "default": "python",
+ "description": "Language: python, rust, javascript, typescript, cpp, or go.",
+ "type": "string"
+}Input schema / properties / paramsRemoved value: -{
- "additionalProperties": false,
- "description": "Arguments for ``topos_evaluate_code``.",
- "properties": {
- "allow": {
- "description": "One-off acknowledged dangerous-call patterns.",
- "items": {
- "type": "string"
- },
- "type": "array"
- },
- "code": {
- "description": "Source code to evaluate.",
- "minLength": 1,
- "type": "string"
- },
- "language": {
- "default": "python",
- "description": "Language: python, rust, javascript, typescript, or cpp.",
- "type": "string"
- },
- "preferences": {
- "anyOf": [
- {
- "additionalProperties": false,
- "description": "Strict ranking over simple, composable, and secure.",
- "properties": {
- "ranking": {
- "description": "Permutation of simple/composable/secure, best first.",
- "items": {
- "description": "The three quality generators of ``G_qual``.",
- "enum": [
- "simple",
- "composable",
- "secure"
- ],
- "type": "string"
- },
- "maxItems": 3,
- "minItems": 3,
- "type": "array"
- },
- "target": {
- "anyOf": [
- {
- "description": "The 8 quality verdicts, from SLOP (none) to IDEAL (simple+composable+secure).",
- "enum": [
- "SLOP",
- "SIMPLE",
- "COMPOSABLE",
- "SECURE",
- "SIMPLE_COMPOSABLE",
- "SIMPLE_SECURE",
- "COMPOSABLE_SECURE",
- "IDEAL"
- ],
- "type": "string"
- },
- {
- "type": "null"
- }
- ],
- "default": null,
- "description": "Optional explicit target verdict."
- }
- },
- "required": [
- "ranking"
- ],
- "type": "object"
- },
- {
- "type": "null"
- }
- ],
- "default": null,
- "description": "Optional generator ranking."
- },
- "verbose": {
- "default": false,
- "description": "Include raw metrics.",
- "type": "boolean"
- }
- },
- "required": [
- "code"
- ],
- "type": "object"
-}Input schema / properties / preferencesAdded value: +{
+ "anyOf": [
+ {
+ "$ref": "#/$defs/UserPreferencesInput"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "Optional generator ranking."
+}Input schema / properties / verboseAdded value: +{
+ "default": false,
+ "description": "Include raw metrics.",
+ "type": "boolean"
+}Input schema / requiredPrevious value: -[
- "params"
-]New value: +[
+ "code"
+]topos_evaluate_file12 fields changedInput schema / $defsAdded value: +{
+ "GeneratorInput": {
+ "description": "Wire form of a generator name.",
+ "enum": [
+ "simple",
+ "composable",
+ "secure"
+ ],
+ "type": "string"
+ },
+ "LatticeElement": {
+ "description": "The 8 elements of the free Heyting algebra H(G_qual) on the three\ngenerators SIMPLE, COMPOSABLE, SECURE, mirroring `EvaluationValue` on\nthe MCP wire.",
+ "enum": [
+ "SLOP",
+ "SIMPLE",
+ "COMPOSABLE",
+ "SECURE",
+ "SIMPLE_COMPOSABLE",
+ "SIMPLE_SECURE",
+ "COMPOSABLE_SECURE",
+ "IDEAL"
+ ],
+ "type": "string"
+ },
+ "UserPreferencesInput": {
+ "additionalProperties": false,
+ "description": "Strict ranking over simple, composable, and secure.",
+ "properties": {
+ "ranking": {
+ "description": "Permutation of simple/composable/secure, best first.",
+ "items": {
+ "$ref": "#/$defs/GeneratorInput"
+ },
+ "type": "array"
+ },
+ "target": {
+ "anyOf": [
+ {
+ "$ref": "#/$defs/LatticeElement"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "Optional explicit target verdict."
+ }
+ },
+ "required": [
+ "ranking"
+ ],
+ "type": "object"
+ }
+}Input schema / $schemaAdded value: +"https://json-schema.org/draft/2020-12/schema"Input schema / properties / allowAdded value: +{
+ "default": [],
+ "description": "One-off acknowledged dangerous-call patterns.",
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+}Input schema / properties / filepathAdded value: +{
+ "description": "Source file path.",
+ "type": "string"
+}Input schema / properties / gitnexus_dirAdded value: +{
+ "default": null,
+ "description": ".gitnexus directory for COMPOSABLE scoring. When omitted, it is\nauto-detected at `<file root>/.gitnexus`; if missing or stale, this\ntool generates/refreshes it first (see `no_composable`).",
+ "type": [
+ "string",
+ "null"
+ ]
+}Input schema / properties / include_security_findingsAdded value: +{
+ "default": true,
+ "description": "Include SECURE findings.",
+ "type": "boolean"
+}Input schema / properties / no_composableAdded value: +{
+ "default": false,
+ "description": "Skip GitNexus detection/generation; score SIMPLE/SECURE only,\nexactly like a missing `.gitnexus` did before this tool started\ngenerating it automatically.",
+ "type": "boolean"
+}Input schema / properties / paramsRemoved value: -{
- "additionalProperties": false,
- "description": "Arguments for ``topos_evaluate_file``.",
- "properties": {
- "allow": {
- "description": "One-off acknowledged dangerous-call patterns.",
- "items": {
- "type": "string"
- },
- "type": "array"
- },
- "filepath": {
- "description": "Source file path.",
- "minLength": 1,
- "type": "string"
- },
- "gitnexus_dir": {
- "anyOf": [
- {
- "type": "string"
- },
- {
- "type": "null"
- }
- ],
- "default": null,
- "description": ".gitnexus directory for COMPOSABLE scoring."
- },
- "include_security_findings": {
- "default": true,
- "description": "Include SECURE findings.",
- "type": "boolean"
- },
- "preferences": {
- "anyOf": [
- {
- "additionalProperties": false,
- "description": "Strict ranking over simple, composable, and secure.",
- "properties": {
- "ranking": {
- "description": "Permutation of simple/composable/secure, best first.",
- "items": {
- "description": "The three quality generators of ``G_qual``.",
- "enum": [
- "simple",
- "composable",
- "secure"
- ],
- "type": "string"
- },
- "maxItems": 3,
- "minItems": 3,
- "type": "array"
- },
- "target": {
- "anyOf": [
- {
- "description": "The 8 quality verdicts, from SLOP (none) to IDEAL (simple+composable+secure).",
- "enum": [
- "SLOP",
- "SIMPLE",
- "COMPOSABLE",
- "SECURE",
- "SIMPLE_COMPOSABLE",
- "SIMPLE_SECURE",
- "COMPOSABLE_SECURE",
- "IDEAL"
- ],
- "type": "string"
- },
- {
- "type": "null"
- }
- ],
- "default": null,
- "description": "Optional explicit target verdict."
- }
- },
- "required": [
- "ranking"
- ],
- "type": "object"
- },
- {
- "type": "null"
- }
- ],
- "default": null,
- "description": "Optional generator ranking."
- },
- "refactor_targets": {
- "default": 0,
- "description": "Ranked edit targets to return (0 = off).",
- "maximum": 25,
- "minimum": 0,
- "type": "integer"
- },
- "verbose": {
- "default": false,
- "description": "Include raw metrics.",
- "type": "boolean"
- }
- },
- "required": [
- "filepath"
- ],
- "type": "object"
-}Input schema / properties / preferencesAdded value: +{
+ "anyOf": [
+ {
+ "$ref": "#/$defs/UserPreferencesInput"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "Optional generator ranking."
+}Input schema / properties / refactor_targetsAdded value: +{
+ "default": 3,
+ "description": "Ranked edit targets to return, gate failures first (default 3;\n0 = off; capped at 25).",
+ "format": "uint",
+ "minimum": 0,
+ "type": "integer"
+}Input schema / properties / verboseAdded value: +{
+ "default": false,
+ "description": "Include raw metrics.",
+ "type": "boolean"
+}Input schema / requiredPrevious value: -[
- "params"
-]New value: +[
+ "filepath"
+]topos_evaluate_project13 fields changedInput schema / $defsAdded value: +{
+ "GeneratorInput": {
+ "description": "Wire form of a generator name.",
+ "enum": [
+ "simple",
+ "composable",
+ "secure"
+ ],
+ "type": "string"
+ },
+ "LatticeElement": {
+ "description": "The 8 elements of the free Heyting algebra H(G_qual) on the three\ngenerators SIMPLE, COMPOSABLE, SECURE, mirroring `EvaluationValue` on\nthe MCP wire.",
+ "enum": [
+ "SLOP",
+ "SIMPLE",
+ "COMPOSABLE",
+ "SECURE",
+ "SIMPLE_COMPOSABLE",
+ "SIMPLE_SECURE",
+ "COMPOSABLE_SECURE",
+ "IDEAL"
+ ],
+ "type": "string"
+ },
+ "UserPreferencesInput": {
+ "additionalProperties": false,
+ "description": "Strict ranking over simple, composable, and secure.",
+ "properties": {
+ "ranking": {
+ "description": "Permutation of simple/composable/secure, best first.",
+ "items": {
+ "$ref": "#/$defs/GeneratorInput"
+ },
+ "type": "array"
+ },
+ "target": {
+ "anyOf": [
+ {
+ "$ref": "#/$defs/LatticeElement"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "Optional explicit target verdict."
+ }
+ },
+ "required": [
+ "ranking"
+ ],
+ "type": "object"
+ }
+}Input schema / $schemaAdded value: +"https://json-schema.org/draft/2020-12/schema"Input schema / properties / allowAdded value: +{
+ "default": [],
+ "description": "Dangerous-call patterns to acknowledge for this run only.",
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+}Input schema / properties / gitnexus_dirAdded value: +{
+ "default": null,
+ "description": "Path to a `.gitnexus` dependency-graph directory, for COMPOSABLE\nscoring. When omitted, it is auto-detected from the project root;\nif missing or stale, this tool generates/refreshes it first (see\n`no_composable`). If generation isn't possible (GitNexus not\ninstalled, generation failure), COMPOSABLE is reported as\nunavailable rather than failing the whole evaluation.",
+ "type": [
+ "string",
+ "null"
+ ]
+}Input schema / properties / include_security_findingsAdded value: +{
+ "default": false,
+ "description": "When true, attach per-file SECURE findings to each entry; off by\ndefault to keep responses compact.",
+ "type": "boolean"
+}Input schema / properties / limitAdded value: +{
+ "default": 25,
+ "description": "Per-file rows to return per page (1–500, default 25).",
+ "format": "uint",
+ "minimum": 0,
+ "type": "integer"
+}Input schema / properties / no_composableAdded value: +{
+ "default": false,
+ "description": "Skip GitNexus detection/generation; score SIMPLE/SECURE only,\nexactly like a missing `.gitnexus` did before this tool started\ngenerating it automatically.",
+ "type": "boolean"
+}Input schema / properties / offsetAdded value: +{
+ "default": 0,
+ "description": "Zero-based row offset for pagination; pass the response's\n`next_offset` to fetch the next page.",
+ "format": "uint",
+ "minimum": 0,
+ "type": "integer"
+}Input schema / properties / paramsRemoved value: -{
- "additionalProperties": false,
- "description": "Arguments for ``topos_evaluate_project``.",
- "properties": {
- "allow": {
- "description": "Dangerous-call patterns to acknowledge for this run only (e.g. `subprocess.run`), suppressing their SECURE penalty without changing stored preferences.",
- "items": {
- "type": "string"
- },
- "type": "array"
- },
- "gitnexus_dir": {
- "anyOf": [
- {
- "type": "string"
- },
- {
- "type": "null"
- }
- ],
- "default": null,
- "description": "Path to a `.gitnexus` dependency-graph directory, required for COMPOSABLE scoring. When omitted, it is auto-detected from the project root; if none is found, COMPOSABLE is reported as unavailable rather than failing."
- },
- "include_security_findings": {
- "default": false,
- "description": "When true, attach per-file SECURE findings (dangerous-call locations) to each entry; off by default to keep responses compact.",
- "type": "boolean"
- },
- "limit": {
- "default": 25,
- "description": "Per-file rows to return per page (1–500, default 25).",
- "maximum": 500,
- "minimum": 1,
- "type": "integer"
- },
- "offset": {
- "default": 0,
- "description": "Zero-based row offset for pagination; pass the response's `next_offset` to fetch the next page.",
- "minimum": 0,
- "type": "integer"
- },
- "path": {
- "description": "Directory to evaluate, walked recursively. Must resolve inside the trusted file root; paths outside it are refused. All supported languages are autodetected — no language argument is needed.",
- "minLength": 1,
- "type": "string"
- },
- "preferences": {
- "anyOf": [
- {
- "additionalProperties": false,
- "description": "Strict ranking over simple, composable, and secure.",
- "properties": {
- "ranking": {
- "description": "Permutation of simple/composable/secure, best first.",
- "items": {
- "description": "The three quality generators of ``G_qual``.",
- "enum": [
- "simple",
- "composable",
- "secure"
- ],
- "type": "string"
- },
- "maxItems": 3,
- "minItems": 3,
- "type": "array"
- },
- "target": {
- "anyOf": [
- {
- "description": "The 8 quality verdicts, from SLOP (none) to IDEAL (simple+composable+secure).",
- "enum": [
- "SLOP",
- "SIMPLE",
- "COMPOSABLE",
- "SECURE",
- "SIMPLE_COMPOSABLE",
- "SIMPLE_SECURE",
- "COMPOSABLE_SECURE",
- "IDEAL"
- ],
- "type": "string"
- },
- {
- "type": "null"
- }
- ],
- "default": null,
- "description": "Optional explicit target verdict."
- }
- },
- "required": [
- "ranking"
- ],
- "type": "object"
- },
- {
- "type": "null"
- }
- ],
- "default": null,
- "description": "Optional ranking of simple/composable/secure (best first). The top-ranked generator sets scorer priority; omit to default to SIMPLE priority."
- },
- "verbose": {
- "default": false,
- "description": "When true, include each file's raw metric values (entropy, complexity, instability) alongside the scores.",
- "type": "boolean"
- }
- },
- "required": [
- "path"
- ],
- "type": "object"
-}Input schema / properties / pathAdded value: +{
+ "description": "Directory to evaluate, walked recursively. Must resolve inside the\ntrusted file root; paths outside it are refused. All supported\nlanguages are autodetected — no language argument is needed.",
+ "type": "string"
+}Input schema / properties / preferencesAdded value: +{
+ "anyOf": [
+ {
+ "$ref": "#/$defs/UserPreferencesInput"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "Optional ranking of simple/composable/secure (best first). The\ntop-ranked generator sets scorer priority; omit to default to\nSIMPLE priority."
+}Input schema / properties / verboseAdded value: +{
+ "default": false,
+ "description": "When true, include each file's raw metric values alongside scores.",
+ "type": "boolean"
+}Input schema / requiredPrevious value: -[
- "params"
-]New value: +[
+ "path"
+]topos_generate_depgraph5 fields changedInput schema / $schemaAdded value: +"https://json-schema.org/draft/2020-12/schema"Input schema / properties / directoryAdded value: +{
+ "default": null,
+ "description": "Repo root (default: MCP file root).",
+ "type": [
+ "string",
+ "null"
+ ]
+}Input schema / properties / forceAdded value: +{
+ "default": false,
+ "description": "Regenerate even when current.",
+ "type": "boolean"
+}Input schema / properties / paramsRemoved value: -{
- "additionalProperties": false,
- "description": "Arguments for ``topos_generate_depgraph`` (side-effecting).",
- "properties": {
- "directory": {
- "anyOf": [
- {
- "type": "string"
- },
- {
- "type": "null"
- }
- ],
- "default": null,
- "description": "Repo root (default: MCP file root)."
- },
- "force": {
- "default": false,
- "description": "Regenerate even when current.",
- "type": "boolean"
- }
- },
- "type": "object"
-}Input schema / requiredRemoved value: -[
- "params"
-]topos_generate_graphify_graphtopos_get_doc7 fields changedInput schema / $defsAdded value: +{
+ "DocTopic": {
+ "description": "Topic for `topos_get_doc`.",
+ "enum": [
+ "agent-contract",
+ "lattice",
+ "metrics",
+ "preferences",
+ "priority",
+ "workflows"
+ ],
+ "type": "string"
+ }
+}Input schema / $schemaAdded value: +"https://json-schema.org/draft/2020-12/schema"Input schema / properties / topic / $refAdded value: +"#/$defs/DocTopic"Input schema / properties / topic / descriptionAdded value: +"agent-contract | lattice | metrics | preferences | priority | workflows"Input schema / properties / topic / enumRemoved value: -[
- "agent-contract",
- "lattice",
- "metrics",
- "preferences",
- "priority",
- "workflows"
-]Input schema / properties / topic / typeRemoved value: -"string"Output schema / (root)Previous value: -{
- "properties": {
- "result": {
- "type": "string"
- }
- },
- "required": [
- "result"
- ],
- "type": "object",
- "x-fastmcp-wrap-result": true
-}New value: +nulltopos_inspect_code13 fields changedInput schema / $defsAdded value: +{
+ "GeneratorInput": {
+ "description": "Wire form of a generator name.",
+ "enum": [
+ "simple",
+ "composable",
+ "secure"
+ ],
+ "type": "string"
+ },
+ "LatticeElement": {
+ "description": "The 8 elements of the free Heyting algebra H(G_qual) on the three\ngenerators SIMPLE, COMPOSABLE, SECURE, mirroring `EvaluationValue` on\nthe MCP wire.",
+ "enum": [
+ "SLOP",
+ "SIMPLE",
+ "COMPOSABLE",
+ "SECURE",
+ "SIMPLE_COMPOSABLE",
+ "SIMPLE_SECURE",
+ "COMPOSABLE_SECURE",
+ "IDEAL"
+ ],
+ "type": "string"
+ },
+ "UserPreferencesInput": {
+ "additionalProperties": false,
+ "description": "Strict ranking over simple, composable, and secure.",
+ "properties": {
+ "ranking": {
+ "description": "Permutation of simple/composable/secure, best first.",
+ "items": {
+ "$ref": "#/$defs/GeneratorInput"
+ },
+ "type": "array"
+ },
+ "target": {
+ "anyOf": [
+ {
+ "$ref": "#/$defs/LatticeElement"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "default": null,
+ "description": "Optional explicit target verdict."
+ }
+ },
+ "required": [
+ "ranking"
+ ],
+ "type": "object"
+ }
+}Input schema / $schemaAdded value: +"https://json-schema.org/draft/2020-12/schema"Input schema / properties / allowAdded value: +{
+ "default": [],
+ "description": "One-off acknowledged dangerous-call patterns for this inspection.",
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+}Input schema / properties / codeAdded value: +{
+ "default": null,
+ "type": [
+ "string",
+ "null"
+ ]
+}Input schema / properties / filepathAdded value: +{
+ "default": null,
+ "description": "Path to the source file inside the project root. Prefer this for\nlarge files.",
+ "type": [
+ "string",
+ "null"
+ ]
+}Input schema / properties / gitnexus_dirAdded value: +{
+ "default": null,
+ "description": ".gitnexus directory for COMPOSABLE scoring. When omitted, it is\nauto-detected at `<file root>/.gitnexus`; if missing or stale, this\ntool generates/refreshes it first (see `no_composable`). Only used\nwith `filepath` — inline `code` has no module to place in the graph.",
+ "type": [
+ "string",
+ "null"
+ ]
+}Input schema / properties / languageAdded value: +{
+ "default": "python",
+ "description": "Language for inline `code`; ignored for `filepath`, which is\nautodetected from the file extension.",
+ "type": "string"
+}Input schema / properties / no_composableAdded value: +{
+ "default": false,
+ "description": "Skip GitNexus generation; score whatever `.gitnexus` is already\nthere, or SIMPLE/SECURE only when there is none.",
+ "type": "boolean"
+}Input schema / properties / paramsRemoved value: -{
- "additionalProperties": false,
- "description": "Arguments for ``topos_inspect_code``.",
- "properties": {
- "allow": {
- "description": "One-off acknowledged dangerous-call patterns for this inspection. Mirrors CLI --allow and is fully disclosed in the evaluation.",
- "items": {
- "type": "string"
- },
- "type": "array"
- },
- "code": {
- "anyOf": [
- {
- "minLength": 1,
- "type": "string"
- },
- {
- "type": "null"
- }
- ],
- "default": null
- },
- "filepath": {
- "anyOf": [
- {
- "minLength": 1,
- "type": "string"
- },
- {
- "type": "null"
- }
- ],
- "default": null,
- "description": "Path to the source file inside the project root. Prefer this for large files."
- },
- "language": {
- "default": "python",
- "description": "Language for inline `code`; ignored for `filepath`, which is autodetected from the file extension.",
- "type": "string"
- },
- "preferences": {
- "anyOf": [
- {
- "additionalProperties": false,
- "description": "Strict ranking over simple, composable, and secure.",
- "properties": {
- "ranking": {
- "description": "Permutation of simple/composable/secure, best first.",
- "items": {
- "description": "The three quality generators of ``G_qual``.",
- "enum": [
- "simple",
- "composable",
- "secure"
- ],
- "type": "string"
- },
- "maxItems": 3,
- "minItems": 3,
- "type": "array"
- },
- "target": {
- "anyOf": [
- {
- "description": "The 8 quality verdicts, from SLOP (none) to IDEAL (simple+composable+secure).",
- "enum": [
- "SLOP",
- "SIMPLE",
- "COMPOSABLE",
- "SECURE",
- "SIMPLE_COMPOSABLE",
- "SIMPLE_SECURE",
- "COMPOSABLE_SECURE",
- "IDEAL"
- ],
- "type": "string"
- },
- {
- "type": "null"
- }
- ],
- "default": null,
- "description": "Optional explicit target verdict."
- }
- },
- "required": [
- "ranking"
- ],
- "type": "object"
- },
- {
- "type": "null"
- }
- ],
- "default": null,
- "description": "Strict total order on the three generators; see ``topos://docs/preferences``."
- },
- "top_n_functions": {
- "default": 10,
- "description": "Return at most this many functions, sorted by descending cyclomatic complexity. Keeps agent context lean on large files.",
- "maximum": 200,
- "minimum": 1,
- "type": "integer"
- },
- "verbose": {
- "default": false,
- "description": "Include raw probe metric floats under each file in the response.",
- "type": "boolean"
- }
- },
- "type": "object"
-}Input schema / properties / preferencesAdded value: +{
+ "anyOf": [
+ {
+ "$ref": "#/$defs/UserPreferencesInput"
+ },
+ {
+ "type": "null"
+ }
+ ],
+ "description": "Strict total order on the three generators; see\n`topos://docs/preferences`."
+}Input schema / properties / top_n_functionsAdded value: +{
+ "default": 10,
+ "description": "Return at most this many functions, sorted by descending cyclomatic\ncomplexity. Keeps agent context lean on large files.",
+ "format": "uint",
+ "minimum": 0,
+ "type": "integer"
+}Input schema / properties / verboseAdded value: +{
+ "default": false,
+ "description": "Include raw probe metric floats under each file in the response.",
+ "type": "boolean"
+}Input schema / requiredRemoved value: -[
- "params"
-]topos_preference_walktopos_refactor9 fields changedInput schema / $defsAdded value: +{
+ "RefactorTargetKind": {
+ "description": "Engine selector for `topos_refactor`.",
+ "oneOf": [
+ {
+ "const": "cycles",
+ "description": "CFG cycle-basis: loop/branch bodies driving cyclomatic complexity.",
+ "type": "string"
+ },
+ {
+ "const": "dependencies",
+ "description": "MDG Forman curvature: load-bearing import edges (needs `.gitnexus`).",
+ "type": "string"
+ },
+ {
+ "const": "process",
+ "description": "Process-graph choke points (needs `.gitnexus`).",
+ "type": "string"
+ },
+ {
+ "const": "graphify",
+ "description": "Graphify orphan nodes / fragile inferred edges.",
+ "type": "string"
+ }
+ ]
+ }
+}Input schema / $schemaAdded value: +"https://json-schema.org/draft/2020-12/schema"Input schema / properties / filepathAdded value: +{
+ "description": "Source file path relative to the MCP file root.",
+ "type": "string"
+}Input schema / properties / gitnexus_dirAdded value: +{
+ "default": null,
+ "description": "Override `.gitnexus` directory (`dependencies` / `process` targets).",
+ "type": [
+ "string",
+ "null"
+ ]
+}Input schema / properties / graphify_dirAdded value: +{
+ "default": null,
+ "description": "Override Graphify output directory (`target=graphify` only).",
+ "type": [
+ "string",
+ "null"
+ ]
+}Input schema / properties / limitAdded value: +{
+ "default": 5,
+ "description": "Maximum hotspots to return (default 5).",
+ "format": "uint",
+ "minimum": 0,
+ "type": "integer"
+}Input schema / properties / paramsRemoved value: -{
- "additionalProperties": false,
- "properties": {
- "filepath": {
- "minLength": 1,
- "type": "string"
- },
- "gitnexus_dir": {
- "anyOf": [
- {
- "type": "string"
- },
- {
- "type": "null"
- }
- ],
- "default": null
- },
- "limit": {
- "default": 5,
- "maximum": 50,
- "minimum": 1,
- "type": "integer"
- },
- "target": {
- "enum": [
- "cycles",
- "dependencies",
- "process"
- ],
- "type": "string"
- }
- },
- "required": [
- "target",
- "filepath"
- ],
- "type": "object"
-}Input schema / properties / targetAdded value: +{
+ "$ref": "#/$defs/RefactorTargetKind",
+ "description": "Which analysis engine to run: `cycles` (CFG), `dependencies` /\n`process` (need `.gitnexus`), or `graphify` (need Graphify graph)."
+}Input schema / requiredPrevious value: -[
- "params"
-]New value: +[
+ "target",
+ "filepath"
+]v0.4.0-rctopos_assess_snapshottopos_assess_worktree_changetopos_calculate_coveragetopos_compare_codetopos_preference_walkv0.3.11topos_refactorv0.3.10topos_evaluate_file1 field changedInput schema / properties / params / properties / refactor_targetsAdded value: +{
+ "default": 0,
+ "description": "Ranked edit targets to return (0 = off).",
+ "maximum": 25,
+ "minimum": 0,
+ "type": "integer"
+}topos_generate_depgraph2 fields changedInput schema / properties / params / properties / directory / descriptionPrevious value: -"Repository root to analyze (default: the MCP file root)."New value: +"Repo root (default: MCP file root)."Input schema / properties / params / properties / forceAdded value: +{
+ "default": false,
+ "description": "Regenerate even when current.",
+ "type": "boolean"
+}v0.3.9topos_calculate_coverage1 field changedInput schema / properties / params / properties / coverage_threshold / descriptionPrevious value: -"Minimum threshold for declaration and topological coverage policies."New value: +"Minimum threshold for the declaration coverage policy."v0.3.6topos_assess_changesettopos_assess_improvementtopos_assess_snapshottopos_assess_worktree_changetopos_begin_refactortopos_calculate_coveragetopos_compare_codetopos_compare_filestopos_depgraph_statustopos_evaluate_codetopos_evaluate_filetopos_evaluate_projecttopos_generate_depgraphtopos_get_doctopos_inspect_codetopos_preference_walkScored across 18 tools
The set contains several near-sibling families — four assess_* variants, three evaluate_* variants, and a compare_code/compare_files pair — which is inherently risky, but each description explicitly states when to use it and, unusually, when NOT to (e.g. 'do not call this for one file', 'use topos_assess_worktree_change for in-place edits'). The remaining tools (coverage, depgraph, docs, preference_walk, pr_recap, inspect_code) are clearly separate concerns. A careless agent could still pick the wrong assess_* variant, but the guidance resolves most ambiguity.
All names use a uniform topos_ prefix plus snake_case, and nearly all follow a verb_noun shape (evaluate_file, assess_changeset, begin_refactor, calculate_coverage, generate_depgraph). A few are bare verbs or noun phrases (topos_refactor, topos_pr_recap, topos_preference_walk, topos_depgraph_status), which breaks the pattern slightly but remains readable and predictable.
At 18 tools this sits in the heavy/borderline band for a single analysis domain, and a chunk of the count comes from input-shape variants of the same operation (evaluate_code/file/project, compare_code/compare_files, four assess_* tools). The surface is coherent and each tool has a defensible role, but consolidation could cut the count meaningfully without losing capability.
The refactor lifecycle is well covered end to end: snapshot creation (begin_refactor), evaluation at snippet/file/project granularity, four diff/assessment modes, hotspot ranking, AST comparison, dependency-graph status/generation, coverage, and doc lookup. Gaps are minor — no way to list or delete stored snapshots, and no explicit configuration/preference-setting tool (preferences are only documented, not applied).
Scores your code across 12 areas, with findings, fix prompts, and re-assessment in your AI agent
Codebase intelligence for AI agents — dead code, blast radius, ownership.
Code intelligence platform for AI agents. 20 tools for architecture, security & impact analysis.
Lints + auto-fixes how AI coding agents discover any new product. 24 rules, 6 tools, score 0-100.
