topos-mcp

Overview Schema Source Related Servers Discussions Admin

topos_evaluate_file

Score a file on disk on the SIMPLE / COMPOSABLE / SECURE / NAVIGABLE lattice — the only evaluate tool that can reach COMPOSABLE (side-effecting).

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

Name	Required	Description
`allow`	No	One-off acknowledged dangerous-call patterns.
`verbose`	No	Include raw metrics.
`filepath`	Yes	Source file path. Prefer an absolute path.
`preferences`	No	Optional generator ranking.
`gitnexus_dir`	No	`.gitnexus` store under the file root (default: `<file root>/.gitnexus`); generated/refreshed when missing or stale (see `no_composable`).
`no_composable`	No	Use no dependency graph, even an existing `.gitnexus`; score SIMPLE/SECURE/NAVIGABLE only.
`security_scan`	No	Run Sighthound even if SECURE passed; report-only.
`refactor_targets`	No	Ranked edit targets to return, gate failures first (default 3; 0 = off; capped at 25).
`include_security_findings`	No	Include SECURE findings.

Schema Changelog

Changes observed during successful MCP inspections.

Changed6 schema fields changedv0.11.0Oct 14, 2026

changedInput schema / properties / filepath / description

Previous value: -"Source file path."New value: +"Source file path. Prefer an absolute path."

addedInput schema / properties / gitnexus_dir / anyOf

Added value: +[
+  {
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]

changedInput schema / properties / gitnexus_dir / description

Previous value: -"`.gitnexus` store under the MCP file root (default:\n`<file root>/.gitnexus`). Freshness and regeneration always use the\nfile root as the project root; this only selects the store path\ninside it. If missing or stale, this tool generates/refreshes first\n(see `no_composable`)."New value: +"`.gitnexus` store under the file root (default: `<file root>/.gitnexus`);\ngenerated/refreshed when missing or stale (see `no_composable`)."

removedInput schema / properties / gitnexus_dir / type
```
Removed value: -[
-  "string",
-  "null"
-]
```

changedInput schema / properties / no_composable / description

Previous value: -"Skip GitNexus detection/generation; score SIMPLE/SECURE/NAVIGABLE\nonly, exactly like a missing `.gitnexus` did before this tool\nstarted generating it automatically."New value: +"Use no dependency graph, even an existing `.gitnexus`; score\nSIMPLE/SECURE/NAVIGABLE only."

addedInput schema / properties / security_scan

Added value: +{
+  "default": false,
+  "description": "Run Sighthound even if SECURE passed; report-only.",
+  "type": "boolean"
+}

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

Behavior5/5

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

Goes well beyond annotations: it discloses the side effect (generating/refreshing .gitnexus), the condition under which it happens (missing or stale), the default CLI-equivalent behavior, and a graceful failure mode (coupling_available=false with warnings). This is consistent with readOnlyHint=false and non-idempotent, adding real context about what changes on disk and what happens when it fails.

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

Conciseness4/5

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

Front-loads the purpose and unique differentiator before the side-effect details, and every sentence carries information. It is dense and slightly heavy with parentheticals, but nothing is padded or redundant.

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

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 9-parameter mutation tool with no output schema, it covers the essentials: side effects, failure handling, and terminology that maps to output fields (coupling_available, warnings, agent_contract.next_tool). Return-shape detail is partial, but the safety-relevant behavior an agent needs is present.

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

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, but the description adds value the schema does not: it explains the interplay between no_composable and gitnexus_dir (auto-detection path, gating of generation) and the always-on pillars. It clarifies behavior of specific parameters beyond their individual field descriptions.

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

Purpose5/5

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

States a specific verb (score) and resource (a file on disk) plus the lattice dimensions it evaluates against. It explicitly differentiates itself from siblings by claiming to be 'the only evaluate tool that can reach COMPOSABLE', so an agent can distinguish it from topos_evaluate_project, topos_evaluate_code, and topos_assess_snapshot without opening a schema.

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

Usage Guidelines4/5

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

Names the distinguishing condition ('the only evaluate tool that can reach COMPOSABLE') and gives an explicit when-not rule ('Do not call again when agent_contract.next_tool is absent'). It stops short of routing to specific sibling tools by name (e.g. when to prefer topos_evaluate_project instead), so it is clear context but not a full when/when-not/alternative map.

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

Deploy Server

topos_evaluate_file

Instructions

Input Schema

Schema Changelog

TDQS

Other Tools