topos-mcp

Overview Schema Source Related Servers Discussions Admin

topos_evaluate_file

Score a file on the SIMPLE, COMPOSABLE, SECURE, and NAVIGABLE quality lattice, generating .gitnexus data when missing to enable COMPOSABLE scoring and give agents a concrete target.

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.

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.6/5.0

Behavior5/5

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.

Conciseness4/5

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.

Completeness5/5

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.

Parameters4/5

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.

Purpose5/5

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.

Usage Guidelines4/5

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.

Deploy Server

topos_evaluate_file

Instructions

Input Schema

Schema Changelog

TDQS

Other Tools