The Topos MCP server provides AI agents with structural code quality metrics across three pillars — SIMPLE, COMPOSABLE, and SECURE — to evaluate, compare, inspect, and iteratively improve code quality.
Evaluate Code Quality
Score inline code, individual files, or entire projects/directories with topos_evaluate_code, topos_evaluate_file, or topos_evaluate_project. Returns a quality medal (GOLD → SLOP) with per-pillar scores. Supports Python, Rust, JavaScript, TypeScript, and C++.
Inspect Code Details
Use topos_inspect_code for per-function breakdowns of cyclomatic complexity, entropy, and the full quality verdict.
Assess Refactors & Changes
topos_assess_improvement — compare a baseline vs. proposed variant inline.
topos_assess_worktree_change — compare an in-place edited file against a git baseline (primary refactor loop tool).
topos_assess_changeset — assess multi-file changesets, detecting complexity relocation and project-level regressions.
topos_begin_refactor / topos_assess_snapshot — snapshot-based workflow for uncommitted/untracked files.
Structural Comparison
Compute AST tree-edit distance between code strings or files with topos_compare_code and topos_compare_files.
Test Coverage Analysis
Measure structural (UAST) and semantic (ECT) test coverage with topos_calculate_coverage.
Dependency Graph Management
Check status with topos_depgraph_status and generate the .gitnexus graph (required for COMPOSABLE scoring) with topos_generate_depgraph.
Preference & Lattice Utilities
topos_preference_walk — compute a preference-ordered relaxation walk through the 8-element quality lattice, helping agents gracefully downgrade goals under budget constraints.
topos_get_doc — retrieve Markdown documentation on agent contracts, lattice, metrics, preferences, and workflows.
All tools support preference rankings (simple/composable/secure), allow (acknowledge risky calls), verbose (raw metrics), and include_security_findings options.
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/toposPrefer 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)
└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:topos status shows every registration, while topos uninstall opens the same selector, previews exactly what will change, and removes everything Topos installed. 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.
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
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 | ||
| include_security_findings | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the safety profile is covered. The description adds extra behavioral context: 'Each file is compared to baseline_ref (new files have no baseline)' and mentions specific flags like 'complexity_relocated_within_file' and 'project_regression'. This goes beyond the annotations by describing the comparison behavior and result flags, though it omits details on security findings or authorization.
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 three sentences, tightly packed with essential information: purpose, usage, key behavior, flags, and return type. There is no fluff or repetition; every sentence serves a distinct role. It is front-loaded with the core action and immediately followed by practical guidance.
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 the tool's complexity (6 parameters, nested preferences object, no output schema), the description provides a solid overview: it explains the baseline comparison, flags, and return type. It lacks details on some parameters (e.g., `include_security_findings`) and the exact shape of `ChangesetResult`, but the schema covers most parameter semantics. The description is sufficient for an agent to decide when to use this tool and what to expect at a high level.
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 67%, so the schema carries most parameter info. The description enhances `baseline_ref` by explaining that each file is compared to it and noting that new files have no baseline. This adds practical meaning beyond the schema's 'Git baseline ref each file is compared against.' However, it does not clarify undocumented parameters like `gitnexus_dir` or `include_security_findings`, but the description's contribution is still valuable.
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 a specific verb and resource: 'Assess a multi-file changeset against a git baseline and roll the per-file verdicts into a project before/after.' This distinguishes it from sibling tools that focus on single files, improvements, or snapshots. The mention of 'multi-file changeset' and 'project before/after' adds a unique scope not seen in other tool names.
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 gives explicit usage context: 'Use for a module split or any edit spanning several files.' This tells the agent when to select this tool, but it does not explicitly state when not to use it or name alternative tools for single-file assessments. The guidance is clear enough for basic selection but lacks exclusionary or comparative notes.
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 | python | |
| preferences | No | Optional generator ranking. | |
| current_code | No | Inline baseline source; COMPOSABLE is unavailable. | |
| gitnexus_dir | No | ||
| 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, and destructiveHint, so the description doesn't need to repeat safety profile. It adds value by explaining the tool is read-only in its own words, describes the return shape (AssessmentResult with status and deltas), and clarifies the side-by-side variant context. No contradiction with annotations, and it provides useful behavioral context beyond the structured fields.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, no fluff. The first sentence states the core action, the second gives alternatives, and the third ties to specific parameters and return type. Highly front-loaded and 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 9 parameters and no output schema, the description provides enough context for selection and invocation: it states the purpose, names the variant params, gives alternatives, and notes the return type. It doesn't detail every parameter, but the high schema coverage fills that gap. Missing details like the exact content of status values are not critical for tool selection/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 78%, which is high, so the schema already documents most parameters. The description goes beyond this by explicitly naming the key params for the variant input (proposed_code, proposed_filepath) and framing them as the defining use case. This adds semantic clarity that the schema alone does not convey.
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 uses a specific verb+resource: 'Compare a baseline to a side-by-side proposed variant (read-only).' It clearly states what the tool does and distinguishes it from siblings by explicitly noting it is 'for variants supplied as proposed_code or proposed_filepath.' It also mentions the return type (AssessmentResult), reinforcing the tool's role.
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 and when-not-to-use guidance by naming alternatives: 'For normal edit-in-place loops, use topos_assess_worktree_change or snapshot first with topos_begin_refactor then topos_assess_snapshot.' This directly helps the agent choose between this tool and its siblings.
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.
| 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 | ||
| include_security_findings | No | Include SECURE findings. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds meaningful behavior: the baseline is read from git via git show with default HEAD, compared to the working-tree file, and the tool is stateless with no prior call needed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences, front-loaded with the core function and immediately followed by the alternative path. Every sentence earns its place, with no filler or tautological restatement.
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 6-parameter tool with no output schema, the description provides essential selection context: what the tool does, how the baseline is sourced, and when to delegate to snapshot-based flows. It doesn't describe the output shape, but the assess verb and sibling context make the purpose and typical usage sufficiently clear.
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 83%, so most parameters are already documented. The description adds context to baseline_ref by specifying the git show mechanism and default HEAD, and clarifies that filepath refers to the current working-tree file. This goes beyond the schema's brief field labels.
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+resource: 'Assess an in-place edit against a git revision', and names it 'the common refactor loop'. It clearly distinguishes from sibling assess tools by emphasizing the git baseline vs working-tree comparison and explicitly directs untracked/new files to begin_refactor + assess_snapshot.
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 explicitly says when to use the tool ('the common refactor loop') and provides an explicit alternative for untracked/new files or uncommitted pre-edit baselines. It also notes that no prior call is required, which helps with session sequencing.
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. | |
| preferences | No | Optional generator ranking. | |
| gitnexus_dir | No | .gitnexus directory. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that the only side effect is writing a snapshot record and that it returns a snapshot_id, but this contradicts the annotation idempotentHint=true. Writing a snapshot record implies each call creates a new side effect, so repeated calls would not be idempotent. This is an annotation contradiction.
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 dense, front-loaded sentences: purpose plus side effect, return value plus follow-up workflow, and the specific usage condition. Every sentence earns its place with no 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?
The description covers purpose, side effect, return value, follow-up call, and the usage condition, which is quite complete for a 3-parameter tool with no output schema. However, the unresolved contradiction with idempotentHint leaves a behavioral gap around repeated calls.
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 provides meaning for all three parameters. The description adds only the filepath context and the workflow but does not explain preferences or gitnexus_dir beyond what the schema states.
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 it persists the file's current source as a baseline snapshot before editing, with a specific verb and resource. It also distinguishes itself from siblings like topos_assess_snapshot by framing this as the initial step in a refactor workflow.
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 provides a usage condition ('Use this when the baseline is not a committed git revision') and a concrete workflow: call this tool, edit the file, then call topos_assess_snapshot. This gives clear direction versus alternatives.
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 | Yes | Paths to the test suite files (relative to project root). | |
| 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 read-only, idempotent, and non-destructive behavior. The description adds algorithm details ('UAST bipartite declaration matching and k-gram path recall') and states the return type ('CoverageResult'), going beyond the annotation baseline without contradicting it.
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 focused sentences, front-loaded with the main purpose, followed by a usage caveat and technical summary. No redundant or filler content; every sentence adds value.
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 rich annotations and full schema coverage, the description is sufficient for tool selection and invocation. It even names the return type, though it does not elaborate on CoverageResult fields, which would be needed for full completeness given no output 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 the input schema fully documents all parameters. The description references 'k-gram path recall' which gives slight extra meaning to the `k` parameter, but generally does not need to compensate for schema gaps.
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 ('measure') and resource ('test suite exercises its program-under-test via structural UAST coverage'), clearly distinguishing it from siblings by noting it is a standalone signal separate from the quality lattice and pointing to `topos_evaluate_*` for quality verdicts.
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 explicitly says when to use this tool (as a standalone coverage signal) and when not to (when a quality verdict is needed, use `topos_evaluate_*` instead), providing clear context relative to alternatives.
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. 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. | |
| target | Yes | Comparison file path. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, which the description reinforces by stating 'Read-only; parses both files, never writes or scores.' Additionally, the description adds behavioral details like computing AST distance and returning a ComparisonResult, which go beyond 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 three sentences, front-loaded with the core purpose, followed by safety and usage guidance. Every sentence adds value without redundancy or fluff.
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 purpose, safety, usage, and output (returns ComparisonResult, referencing `topos_compare_code`). Given the tool's moderate complexity and the presence of rich annotations, the description is complete for an agent to understand and invoke the tool 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?
The input schema has 100% coverage with descriptions for both parameters ('Baseline file path.' and 'Comparison file path.'). The description does not add further semantics beyond what the schema provides, so a baseline score of 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?
The description clearly states the tool computes AST (tree-edit) distance between two source files. It specifies the verb 'compute' and resource 'AST distance', and distinguishes itself from sibling tools like `topos_assess_*` by stating it is for clone detection or refactor impact, not quality verdicts.
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 explicitly says when to use: for clone detection or refactor impact. It also provides a clear alternative: use `topos_assess_*` for a quality verdict. This gives direct guidance on tool selection.
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 readOnly and idempotent hints, but the description adds valuable behavioral disclosure beyond that: 'Never shells out and never mutates state.' It also explains the failure modes (missing, stale, load/schema failure), which is not captured in annotations and helps the agent interpret the tool's behavior.
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 three sentences, front-loaded with the core purpose, and every sentence adds value: what it does, how it distinguishes outcomes, and safety guarantees. No filler or 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?
For a simple read-only status tool with no output schema, the description adequately covers purpose, failure modes, and next steps. It does not specify the exact return format, but given the simplicity and the 'what to do next' guidance, it is sufficiently complete for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for both parameters, and each parameter already has a clear description in the schema. The tool description does not add additional parameter-level meaning, so the baseline of 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?
The description clearly states a specific verb ('Report') and resource ('.gitnexus' availability and freshness), and distinguishes it from sibling tools by focusing on status rather than generation or assessment. The read-only scope and the distinction between missing, stale, and failure states give precise purpose.
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: check this before trusting COMPOSABLE, and it tells the agent what to do next based on the state. It doesn't explicitly name alternatives like topos_generate_depgraph, but the read-only nature and 'what to do next' provide clear contextual guidance.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| allow | No | One-off acknowledged dangerous-call patterns. | |
| verbose | No | Include raw metrics. | |
| filepath | Yes | Source file path. | |
| preferences | No | Optional generator ranking. | |
| gitnexus_dir | No | `.gitnexus` store under the MCP file root (default: `<file root>/.gitnexus`). Freshness and regeneration always use the file root as the project root; this only selects the store path inside it. If missing or stale, this tool generates/refreshes first (see `no_composable`). | |
| no_composable | No | Skip GitNexus detection/generation; score SIMPLE/SECURE/NAVIGABLE only, exactly like a missing `.gitnexus` did before this tool started generating it automatically. | |
| 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?
The description discloses key behavioral traits beyond annotations: it generates/refreshes .gitnexus when missing or stale, attaches a ModuleDependencyGraph, and handles GitNexus absence gracefully with coupling_available=false and warnings. This exceeds the general hints in annotations (readOnlyHint=false, idempotentHint=false) and adds actionable context.
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 deliver a dense but well-structured explanation. The purpose is front-loaded, side effects are in the second sentence, and failure handling in the third. It is slightly long but every sentence earns its place, 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?
For a complex tool with 8 parameters, side effects, and dynamic generation, the description covers the essential behaviors: lattice scoring, .gitnexus generation conditions, side-effecting nature, and graceful fallback. It also mentions key output fields. Without an output schema, this 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 coverage is 100%, so the baseline is 3. The description adds value by explaining the relationship between no_composable and gitnexus_dir, the default behavior related to .gitnexus, and the output fields coupling_available/warnings, which gives context beyond the property 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?
The description clearly states the tool scores a file on disk on the SIMPLE/COMPOSABLE/SECURE/NAVIGABLE lattice, using a specific verb and resource. It also distinguishes itself from siblings by being 'the only evaluate tool that can reach COMPOSABLE', which separates it from other evaluate tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for when to use this tool (when COMPOSABLE evaluation or file-level scoring is needed) and implies alternatives via the sibling list. It explains side-effecting behavior and the no_composable escape hatch, but it does not explicitly name or exclude sibling tools.
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 (Python, Rust, JavaScript,
TypeScript, C++, Go) in one walk — no language argument — and skips
unsupported files. The rollup takes the project-wide minimum per
dimension (weakest file floors it). Returns page-global named lists
(hard_fails, leaf_composable_zeros, maintainability_giants)
plus a paginated per-file table (gate failures first); page with
limit / offset.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | 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. | |
| allow | No | Dangerous-call patterns to acknowledge for this run only. | |
| limit | No | Per-file rows to return per page (1–500, default 25). | |
| 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 (best first). The top-ranked generator sets scorer priority; omit to default to SIMPLE priority. | |
| gitnexus_dir | No | `.gitnexus` store under the MCP file root (default: `<file root>/.gitnexus`). Freshness and regeneration always use the file root as the project root; this only selects the store path inside it. If missing or stale, this tool generates/refreshes first (see `no_composable`). If generation isn't possible, COMPOSABLE is reported as unavailable rather than failing the whole evaluation. | |
| no_composable | No | Skip GitNexus detection/generation; score SIMPLE/SECURE/NAVIGABLE only, exactly like a missing `.gitnexus` did before this tool started generating it automatically. | |
| 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 indicate readOnlyHint=false, but the description goes far beyond that: it discloses the specific side effect of generating/refreshing `.gitnexus`, the behavior of skipping unsupported files, the rollup taking the project-wide minimum, and the graceful degradation when generation is not possible (`coupling_available`/`warnings`). This is exactly the kind of contextual detail that helps an agent predict side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is information-dense with five sentences, each addressing a distinct concern: main purpose, language autodetection, rollup semantics, return values/pagination, and side-effect behavior. It is front-loaded and free of filler, though the final sentence is long and packs multiple clauses. For a complex tool with 9 parameters, this density is warranted.
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 explicitly naming the returned lists (`hard_fails`, `leaf_composable_zeros`, `maintainability_giants`) and describing the paginated per-file table with gate failures first. It also covers side effects, failure fallback, and parameter-triggered behavior. Together with the heavily documented schema, the description provides a complete operational 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 coverage is 100%, so the schema already documents each parameter. The description adds value by explaining how `no_composable` controls the .gitnexus generation workflow, how `limit`/`offset` drive pagination, and how `gitnexus_dir` relates to project-root behavior. This goes beyond the schema's per-parameter descriptions and links them to the overall execution model.
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 a specific verb+resource+scope: 'Recursively score every supported source file in a directory' on the four-dimension lattice. It explicitly lists supported languages, notes autodetection with no language argument, and distinguishes itself from file-level evaluation by referencing `topos_evaluate_file`.
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 makes clear this is for whole-directory evaluation and even mentions `same as topos_evaluate_file` for .gitnexus generation, which implicitly contrasts it with the file tool. However, it never explicitly states when to use this vs a sibling (e.g., 'use topos_evaluate_file for a single file'), so the guidance remains implied rather than directly articulated.
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?
Discloses side-effecting nature, the underlying `gitnexus analyze` command, conditional no-op behavior, and force regeneration. Annotations only provide generic hints (readOnlyHint=false, idempotentHint=false); the description adds meaningful behavioral context beyond those.
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, front-loaded with purpose and side-effect. The second sentence efficiently explains no-op and force behavior. 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?
Covers the tool's purpose, side effects, default behavior, and force parameter. No output schema exists, but for a side-effecting graph generation tool this is adequate for an agent to select and invoke 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 coverage is 100% and every parameter (force, directory, gitnexus_dir) already has a clear description. The description restates force=true behavior but adds no new parameter semantics 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?
Clearly states the specific action: generate the `.gitnexus` dependency graph via GitNexus. This distinguishes it from sibling tools like `topos_depgraph_status` (status check) and `topos_generate_graphify_graph` (different graph type).
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?
Provides clear context: default behavior ensures the graph and no-ops when current, which implies when to use it (to guarantee graph existence). Does not explicitly name alternatives or exclusions, but the context is sufficient for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate the Graphify knowledge graph (graphify-out/graph.json)
via the external graphify CLI (side-effecting).
Use before topos_refactor(target="graphify") when no graph exists.
Skips regeneration when a graph is already present unless
force=true. Wholly independent of .gitnexus/GitNexus — never
feeds the scored pillars. For GitNexus dep graphs use
topos_generate_depgraph instead.
| Name | Required | Description | Default |
|---|---|---|---|
| force | No | Regenerate even when current. | |
| directory | Yes | Absolute directory in the project to analyze. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description enriches the annotations by explaining the side-effecting nature, the skip-if-existing behavior, and the independence from GitNexus. It aligns perfectly with annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false) and adds meaningful context beyond them, such as the force flag's effect and the tool's scope.
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 yet information-dense: every sentence serves a purpose, from the main action, to usage guidance, to behavioral nuances, to alternative tools. It is front-loaded with the primary action and flows logically, with no redundant or filler content.
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 side-effecting tool without an output schema, the description covers all essential aspects: what it does, when to use it, when to force regeneration, how it relates to other tools, and its independence from GitNexus. It is complete enough for an agent to select and invoke the tool 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?
The schema already covers both parameters (100% coverage), so the baseline is 3. The description adds extra value by clarifying the behavior of `force=true` in the context of skipping regeneration, which provides semantic understanding beyond the schema's simple 'Regenerate even when current.' This lifts the score above baseline.
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 the tool's purpose: generating the Graphify knowledge graph at a specific path (`graphify-out/graph.json`) via an external CLI. It also distinguishes itself from the sibling tool `topos_generate_depgraph` by explicitly noting the difference, making the purpose unambiguous.
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 usage context: 'Use before topos_refactor(target="graphify") when no graph exists' and also gives a direct alternative: 'For GitNexus dep graphs use topos_generate_depgraph instead.' This clearly tells the agent when and when not to use the tool.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| code | No | ||
| 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 | Path to the source file inside the project root. Prefer this 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 MCP file root (default: `<file root>/.gitnexus`). Freshness/regeneration use the file root as the project root; this only selects the store path. Only used with `filepath` — inline `code` has no module to place in the graph. | |
| no_composable | No | Skip GitNexus generation; score whatever `.gitnexus` is already there, or SIMPLE/SECURE/NAVIGABLE only when there is none. | |
| 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 provide readOnlyHint=false, and the description goes further by disclosing the side-effecting nature: it 'generates/refreshes .gitnexus... so this tool is side-effecting.' It also clarifies reachable lattice elements for inline code and agreement with `topos_evaluate_file`, adding behavioral context beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but well-structured: it front-loads the purpose, then covers usage, return shape, side effects, and mode differences. Every sentence contributes relevant information; there is no filler or redundancy for a tool of this complexity.
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 the tool's complexity (9 parameters, two modes, side effects, no output schema), the description covers the return value (InspectionResult), the behavioral difference between modes, the side-effect condition, and the alternative tools. Schema handles parameter details; description covers the behavioral and decision context 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 description coverage is high (89%), so the baseline is 3. The description adds cross-parameter meaning by explaining the `code` vs `filepath` decision, the `no_composable` bypass, and the default `top_n_functions` behavior. It doesn't restate each parameter's schema but enriches the important choices.
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 a specific verb+resource: 'Full metric breakdown for a single code unit (inline string or file).' It immediately distinguishes itself from siblings by stating 'use `topos_evaluate_*` when the medal alone is enough,' making the tool's unique role clear.
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?
Provides explicit when-to-use guidance: 'Use when you need the per-function detail behind a verdict' and names the alternative (`topos_evaluate_*`). It also states the exactly-one constraint for `code`/`filepath` and explains the side-effecting behavior with `filepath` versus inline `code`.
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}, most-preferred first. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds 'Pure and read-only (lattice math only; no files, no scoring),' which reinforces and expands the safety profile by explicitly ruling out file operations and scoring. This is useful context beyond the annotations. It also clarifies the effect of the 'current' parameter (truncates the walk to steps strictly above it), which helps predict behavior.
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—three sentences that efficiently cover purpose, usage context, and output structure. It front-loads the core action in the first sentence, is free of filler, and every clause adds value. The structure is well organized for quick parsing by an agent.
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?
While there is no output schema, the description enumerates the result fields (walk, next_step, progress, aspirational_target/fallback_target, induced_order), which covers return-value essentials. The input schema is rich, including detailed enum definitions for LatticeElement. For a read-only lattice-math operation with one required parameter, this is sufficiently complete. It could be slightly richer on what 'relaxation walk' implies, but the existing context is strong.
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 three parameters (ranking, target, current) with clear descriptions. The tool description itself adds limited parameter-specific detail; it only mentions 'steps from target down to just above current' in the output, which indirectly references the 'current' parameter. Since the schema handles parameter semantics well, the baseline of 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?
The description opens with a specific action and resource: 'Turn a generator ranking into a preference-ordered relaxation walk.' This clearly distinguishes it from siblings like topos_evaluate_code or topos_compare_files, which are evaluation/comparison tools. It also names the concrete output type (PreferenceWalkResult) and its key components.
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 explicitly states when to use the tool: 'Call after an evaluation to pick the next verdict to aim for, or to relax the goal gracefully under a token/time budget.' This gives clear context. It does not explicitly mention alternatives or when-not-to-use, so it falls short of a 5, but the usage guidance is strong.
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),
process (execution choke points; needs .gitnexus), or graphify
(orphan/fragile edges; needs a Graphify graph from
topos_generate_graphify_graph). 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), `dependencies` / `process` (need `.gitnexus`), or `graphify` (need Graphify graph). | |
| filepath | Yes | Source file path relative to the MCP file root. | |
| gitnexus_dir | No | Override `.gitnexus` directory (`dependencies` / `process` targets). | |
| graphify_dir | No | Override Graphify output directory (`target=graphify` only). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the safe/advisory nature is expected. The description adds valuable context beyond annotations: it discloses engine-specific prerequisites (.gitnexus, Graphify graph), states the return type (RefactorResult with hotspots), and clarifies that it does not score the four pillars. It does not mention error behavior when prerequisites are missing, but that is a minor gap given the coverage.
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 yet comprehensive: a one-sentence core purpose, a one-sentence differentiation, a concise enumeration of target engines with prerequisites, and a brief note on the return type. Every sentence carries information and there is no 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 tool with five parameters, two required, and several engine-specific prerequisites, the description covers the main purpose, alternatives, prerequisites, and return structure. It does not exhaustively document all edge cases (e.g., behavior without .gitnexus) but is sufficiently complete given the complexity and the lack of an output 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 parameters have detailed descriptions in the schema itself. The tool description restates some parameter guidance (e.g., which targets need .gitnexus) and adds the relationship between gitnexus_dir/graphify_dir and specific targets, but it does not significantly augment the schema. A baseline of 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?
The description clearly states the tool's function with a specific verb and resource: 'Rank structural refactor hotspots for one file'. It explicitly distinguishes itself from siblings by noting it does not score the four pillars and directing the reader to topos_evaluate_* and topos_assess_* for those purposes.
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 guidance on when to use this tool versus alternatives: it says to use topos_evaluate_* for medals and topos_assess_* to verify edits. It also mentions prerequisites for specific targets (e.g., dependencies/process need .gitnexus) and names topos_generate_graphify_graph as a prerequisite for graphify.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Each tool has a clearly distinct purpose with detailed descriptions that differentiate similar-sounding tools (e.g., four assess variants for different comparison scenarios, evaluate vs. assess). No two tools are ambiguous in their intended use.
Most tools follow the `topos_<verb>_<noun>` pattern (e.g., topos_evaluate_file, topos_generate_depgraph). However, `topos_depgraph_status` breaks the pattern by having a noun-noun structure, and `topos_begin_refactor` uses verb-verb. Overall consistent but with minor deviations.
With 18 tools, the surface is well-scoped for a code quality and refactoring platform. Each tool serves a distinct function without redundancy, covering evaluation, assessment, comparison, generation, and utility functions.
The tool set covers a wide range of use cases: evaluating code, assessing changes, generating graphs, comparing snippets, and providing documentation. A minor gap is the lack of snapshot management tools (e.g., listing or deleting snapshots), but core workflows are supported.
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.
AI-powered codebase analysis — call graphs, security, dead code, complexity. 150+ tools.
Ground-truth code graph for your codebase: exact callers, callees, symbols & dependencies.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/Krv-Labs/topos'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
