topos-mcp

Overview Schema Source Related Servers Discussions Admin

topos_inspect_code

Inspect a code snippet or file to receive detailed quality metrics: per-function complexity, total functions, entropy, and a lattice evaluation. Use to understand the specifics behind a Topos verdict.

Instructions

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.

Input Schema

TableJSON Schema

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.

Schema Changelog

Changes observed during successful MCP inspections.

Changed7 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 generation; score whatever `.gitnexus` is already\nthere, or SIMPLE/SECURE only when there is none."New value: +"Skip GitNexus generation; score whatever `.gitnexus` is already\nthere, or SIMPLE/SECURE/NAVIGABLE only when there is none."

changedInput schema / properties / preferences / description

Previous value: -"Strict total order on the three generators; see\n`topos://docs/preferences`."New value: +"Strict total order on the four generators; see\n`topos://docs/preferences`."

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`). Only used\nwith `filepath` — inline `code` has no module to place in the graph."New value: +"`.gitnexus` store under the MCP file root (default:\n`<file root>/.gitnexus`). Freshness/regeneration use the file root\nas the project root; this only selects the store path. Only used\nwith `filepath` — inline `code` has no module to place in the graph."

Changed13 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 for this inspection.",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

addedInput schema / properties / code

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

addedInput schema / properties / filepath

Added value: +{
+  "default": null,
+  "description": "Path to the source file inside the project root. Prefer this for\nlarge files.",
+  "type": [
+    "string",
+    "null"
+  ]
+}

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`). Only used\nwith `filepath` — inline `code` has no module to place in the graph.",
+  "type": [
+    "string",
+    "null"
+  ]
+}

addedInput schema / properties / language

Added value: +{
+  "default": "python",
+  "description": "Language for inline `code`; ignored for `filepath`, which is\nautodetected from the file extension.",
+  "type": "string"
+}

addedInput schema / properties / no_composable

Added value: +{
+  "default": false,
+  "description": "Skip GitNexus generation; score whatever `.gitnexus` is already\nthere, or SIMPLE/SECURE only when there is none.",
+  "type": "boolean"
+}

removedInput schema / properties / params

Removed value: -{
-  "additionalProperties": false,
-  "description": "Arguments for ``topos_inspect_code``.",
-  "properties": {
-    "allow": {
-      "description": "One-off acknowledged dangerous-call patterns for this inspection. Mirrors CLI --allow and is fully disclosed in the evaluation.",
-      "items": {
-        "type": "string"
-      },
-      "type": "array"
-    },
-    "code": {
-      "anyOf": [
-        {
-          "minLength": 1,
-          "type": "string"
-        },
-        {
-          "type": "null"
-        }
-      ],
-      "default": null
-    },
-    "filepath": {
-      "anyOf": [
-        {
-          "minLength": 1,
-          "type": "string"
-        },
-        {
-          "type": "null"
-        }
-      ],
-      "default": null,
-      "description": "Path to the source file inside the project root. Prefer this for large files."
-    },
-    "language": {
-      "default": "python",
-      "description": "Language for inline `code`; ignored for `filepath`, which is autodetected from the file extension.",
-      "type": "string"
-    },
-    "preferences": {
-      "anyOf": [
-        {
-          "additionalProperties": false,
-          "description": "Strict ranking over simple, composable, and secure.",
-          "properties": {
-            "ranking": {
-              "description": "Permutation of simple/composable/secure, best first.",
-              "items": {
-                "description": "The three quality generators of ``G_qual``.",
-                "enum": [
-                  "simple",
-                  "composable",
-                  "secure"
-                ],
-                "type": "string"
-              },
-              "maxItems": 3,
-              "minItems": 3,
-              "type": "array"
-            },
-            "target": {
-              "anyOf": [
-                {
-                  "description": "The 8 quality verdicts, from SLOP (none) to IDEAL (simple+composable+secure).",
-                  "enum": [
-                    "SLOP",
-                    "SIMPLE",
-                    "COMPOSABLE",
-                    "SECURE",
-                    "SIMPLE_COMPOSABLE",
-                    "SIMPLE_SECURE",
-                    "COMPOSABLE_SECURE",
-                    "IDEAL"
-                  ],
-                  "type": "string"
-                },
-                {
-                  "type": "null"
-                }
-              ],
-              "default": null,
-              "description": "Optional explicit target verdict."
-            }
-          },
-          "required": [
-            "ranking"
-          ],
-          "type": "object"
-        },
-        {
-          "type": "null"
-        }
-      ],
-      "default": null,
-      "description": "Strict total order on the three generators; see ``topos://docs/preferences``."
-    },
-    "top_n_functions": {
-      "default": 10,
-      "description": "Return at most this many functions, sorted by descending cyclomatic complexity. Keeps agent context lean on large files.",
-      "maximum": 200,
-      "minimum": 1,
-      "type": "integer"
-    },
-    "verbose": {
-      "default": false,
-      "description": "Include raw probe metric floats under each file in the response.",
-      "type": "boolean"
-    }
-  },
-  "type": "object"
-}

addedInput schema / properties / preferences

Added value: +{
+  "anyOf": [
+    {
+      "$ref": "#/$defs/UserPreferencesInput"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "Strict total order on the three generators; see\n`topos://docs/preferences`."
+}

addedInput schema / properties / top_n_functions

Added value: +{
+  "default": 10,
+  "description": "Return at most this many functions, sorted by descending cyclomatic\ncomplexity. Keeps agent context lean on large files.",
+  "format": "uint",
+  "minimum": 0,
+  "type": "integer"
+}

addedInput schema / properties / verbose

Added value: +{
+  "default": false,
+  "description": "Include raw probe metric floats under each file in the response.",
+  "type": "boolean"
+}

removedInput schema / required
```
Removed value: -[
-  "params"
-]
```

First observedv0.3.6Jul 2, 2026

TDQS

A4.9/5.0

Behavior5/5

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.

Conciseness5/5

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.

Completeness5/5

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.

Parameters4/5

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.

Purpose5/5

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.

Usage Guidelines5/5

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.

Deploy Server

topos_inspect_code

Instructions

Input Schema

Schema Changelog

TDQS

Other Tools