topos-mcp

Overview Schema Source Related Servers Discussions Admin

topos_evaluate_file

Scores a source file on disk against SIMPLE, COMPOSABLE, SECURE, and NAVIGABLE quality gates, then returns ranked edit targets. Generates or refreshes GitNexus coupling data when needed.

Instructions

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.

Input Schema

TableJSON Schema

Name	Required	Description
`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.

Schema Changelog

Changes observed during successful MCP inspections.

Changed6 schema fields changedv0.5.0Aug 9, 2026

changedInput schema / $defs / GeneratorInput / enum

Previous value: -[
-  "simple",
-  "composable",
-  "secure"
-]New value: +[
+  "simple",
+  "composable",
+  "secure",
+  "navigable"
+]

changedInput schema / $defs / LatticeElement / description

Previous 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."

changedInput schema / $defs / LatticeElement / enum

Previous 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"
+]

changedInput schema / $defs / UserPreferencesInput / description

Previous value: -"Strict ranking over simple, composable, and secure."New value: +"Strict ranking over simple, composable, secure, and navigable."

changedInput schema / $defs / UserPreferencesInput / properties / ranking / description

Previous value: -"Permutation of simple/composable/secure, best first."New value: +"Permutation of simple/composable/secure/navigable, best first."

changedInput schema / properties / no_composable / description

Previous 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."

Changed1 schema field changedv0.4.4Aug 5, 2026

changedInput schema / properties / gitnexus_dir / description

Previous 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`)."

Changed12 schema fields changedv0.4.0Jul 27, 2026

addedInput schema / $defs

Added 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"
+  }
+}

addedInput schema / $schema

Added value: +"https://json-schema.org/draft/2020-12/schema"

addedInput schema / properties / allow

Added value: +{
+  "default": [],
+  "description": "One-off acknowledged dangerous-call patterns.",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

addedInput schema / properties / filepath

Added value: +{
+  "description": "Source file path.",
+  "type": "string"
+}

addedInput schema / properties / gitnexus_dir

Added 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"
+  ]
+}

addedInput schema / properties / include_security_findings

Added value: +{
+  "default": true,
+  "description": "Include SECURE findings.",
+  "type": "boolean"
+}

addedInput schema / properties / no_composable

Added 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"
+}

removedInput schema / properties / params

Removed 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"
-}

addedInput schema / properties / preferences

Added value: +{
+  "anyOf": [
+    {
+      "$ref": "#/$defs/UserPreferencesInput"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "Optional generator ranking."
+}

addedInput schema / properties / refactor_targets

Added 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"
+}

addedInput schema / properties / verbose

Added value: +{
+  "default": false,
+  "description": "Include raw metrics.",
+  "type": "boolean"
+}

changedInput schema / required

Previous value: -[
-  "params"
-]New value: +[
+  "filepath"
+]

Changed1 schema field changedv0.3.10Jul 12, 2026

addedInput schema / properties / params / properties / refactor_targets

Added value: +{
+  "default": 0,
+  "description": "Ranked edit targets to return (0 = off).",
+  "maximum": 25,
+  "minimum": 0,
+  "type": "integer"
+}

First observedv0.3.6Jul 2, 2026

TDQS

A4.3/5.0

Behavior5/5

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

Annotations only say readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false. The description goes well beyond that, disclosing the concrete side effect (generates/refreshes `.gitnexus` when missing or stale), the observable consequence (ModuleDependencyGraph is attached), and a graceful-degradation path (coupling_available=false plus warnings when GitNexus is absent or generation fails).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose and the COMPOSABLE differentiator are front-loaded, and the following sentences cover the side effect, the failure mode, and the re-call rule without filler. The first sentence's em-dash aside is dense, but every sentence carries information an agent needs.

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

Completeness4/5

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 correctly surfaces key return signals (coupling_available, warnings, agent_contract.next_tool) and the refactor-gating behavior of a repeat call. For an 8-parameter, side-effecting tool this is nearly complete, though the returned verdict/edit-span shape is only alluded to rather than described.

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

Parameters3/5

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

Schema description coverage is 100%, so the baseline is 3. The description largely restates what the schema already documents for `gitnexus_dir` and `no_composable`, adding only the framing that COMPOSABLE is the side-effecting pillar; it adds little syntax or edge-case meaning beyond the structured fields.

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

Purpose5/5

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

States a specific verb and resource (score a file on disk on the SIMPLE/COMPOSABLE/SECURE/NAVIGABLE lattice) and explicitly differentiates itself from siblings: 'the only evaluate tool that can reach COMPOSABLE (side-effecting)'. An agent can distinguish it from topos_evaluate_code, topos_evaluate_project, and the assess_* family without opening another schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit stop condition ('Do not call again when agent_contract.next_tool is absent: the file already passes, or this call already returned the edit span') and explains when the auto-generation path is bypassed via no_composable. It does not name a specific sibling as the alternative when COMPOSABLE is not needed, so it stops short of a full when/when-not routing statement.

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

Deploy Server

topos_evaluate_file

Instructions

Input Schema

Schema Changelog

TDQS

Other Tools