codegraph-brain

Overview Schema Source Related Servers Discussions Admin

cgis_drift

Compare your ingested code graph against declared ideal patterns to detect per-domain architectural drift, returning verdicts, fit bands, residual scores, and coverage.

Instructions

Report per-domain architectural drift against declared ideal patterns.

Returns JSON: ``any_critical`` verdict, per-domain reports (each carrying a
``fit`` block — nearest alphabet template + residual + good/weak/none band),
the observe-only quotient layer, and ``coverage`` (graph prefixes bound by no
domain). Call after ``cgis_ingest`` to learn whether your edits pushed a
domain past its drift tolerance.

``max_drift`` is now the default tolerance only for domains that omit
``drift_tolerance`` — it no longer caps domains that declare their own
(see #170).

``profile``: when set, score only domains with this profile (plus
profile-less ones). Use when your patterns.yaml mixes languages but the
graph holds one language — avoids false EMPTY reports for other-language
domains that would otherwise fail the gate.

``max_residual``: a domain whose nearest template is farther than this gets
``fit.band = "none"`` ("no template fits") — a grab-bag module or an
alphabet gap, independent of drift tolerance (#177).

Input Schema

TableJSON Schema

Name	Required	Description	Default
`db_path`	No	SQLite graph built by cgis_ingest. A relative path resolves against the MCP server's working directory, not the agent's — prefer an absolute path.	graph.db
`profile`	No	Score only domains with this profile, plus profile-less ones — e.g. one language when patterns.yaml mixes several.
`max_drift`	No	Drift tolerance for domains that declare no drift_tolerance of their own.
`max_residual`	No	Distance to the nearest template beyond which a domain's fit band is "none" (no template fits).
`patterns_path`	No	patterns.yaml (.yaml or .yml) declaring each domain's expected pattern and tolerance, relative to the server's working directory. cgis_init_ontology proposes one.	docs/ontology/patterns.yaml

Output Schema

TableJSON Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed5 schema fields changedv0.21.1Sep 17, 2026

addedInput schema / properties / db_path / description

Added value: +"SQLite graph built by cgis_ingest. A relative path resolves against the MCP server's working directory, not the agent's — prefer an absolute path."

addedInput schema / properties / max_drift / description

Added value: +"Drift tolerance for domains that declare no drift_tolerance of their own."

addedInput schema / properties / max_residual / description

Added value: +"Distance to the nearest template beyond which a domain's fit band is \"none\" (no template fits)."

addedInput schema / properties / patterns_path / description

Added value: +"patterns.yaml (.yaml or .yml) declaring each domain's expected pattern and tolerance, relative to the server's working directory. cgis_init_ontology proposes one."

addedInput schema / properties / profile / description

Added value: +"Score only domains with this profile, plus profile-less ones — e.g. one language when patterns.yaml mixes several."

First observedv0.21.0Sep 17, 2026

TDQS

A4.6/5.0

Behavior5/5

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

With no annotations provided, the description fully discloses behavior. It details the return JSON structure (any_critical, per-domain reports with fit blocks, quotient layer, coverage), explains the nuanced behavior of max_drift (now a default tolerance only for domains without their own), and clarifies max_residual's independence from drift tolerance. This goes beyond a simple report description and covers edge cases and parameter effects.

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?

The description is moderately long but well-structured with paragraphs and code formatting. It front-loads the purpose and return format, then addresses parameter nuances. Each sentence carries informational weight, and the use of backticks and references (#170, #177) adds precision without excessive verbosity. It could be slightly tighter, but it is not padded.

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, the description is thorough. It covers the return format, when to call it (after cgis_ingest), parameter behaviors, and even notes the change in max_drift semantics. The presence of an output schema reduces the need to detail return values, and the description fills the remaining gaps. No essential information for correct invocation is missing.

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 all parameters are already documented. The description adds value by clarifying semantics beyond the schema: max_drift's role as a default only for domains lacking their own tolerance, profile's purpose for filtering by language, and max_residual's meaning for fit.band classification. This extra context elevates the description above the baseline 3.

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's function: 'Report per-domain architectural drift against declared ideal patterns.' It uses a specific verb ('report'), a clear resource ('per-domain architectural drift'), and the context ('against declared ideal patterns'). This distinguishes it from sibling tools like cgis_validate or cgis_metrics, which serve different analytical purposes.

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 explicit usage context: 'Call after cgis_ingest to learn whether your edits pushed a domain past its drift tolerance.' It also provides conditional usage for the 'profile' parameter ('Use when your patterns.yaml mixes languages...'). While it doesn't explicitly mention when not to use the tool or name alternatives, the clear trigger condition and parameter-specific guidance make the usage intent strong.

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

Deploy Server