codegraph-brain

Overview Schema Source Related Servers Discussions Admin

cgis_metrics

Analyze a whole code graph to surface coupling bottlenecks, God classes, and critical nodes via PageRank and fan-in/out metrics.

Instructions

Whole-graph architectural metrics — coupling bottlenecks, God classes, PageRank.

Returns JSON ``{bottlenecks, god_classes, critical}`` computed with vectorized
DuckDB aggregations over the whole graph (fan-in/fan-out coupling,
declared-member counts, PageRank) — the global "what are the hotspots?" view
that complements the node-local trace/impact/context tools. Requires the
optional ``duckdb`` extra; an unavailable dependency is reported as a normal
❌ message.

``exclude`` drops any node whose FQN contains one of the given dot-segments
(e.g. ``["tests"]`` removes both ``tests.*`` and ``domains.*.tests.*``) so
test/vendor scaffolding stays out of the rankings.

``scope`` is its complement: it keeps only nodes under one of the given
dot-prefixes, anchored and cut on a dot boundary, so
``["domains.reservation"]`` is that subtree and not
``domains.reservation_archive``. Use it for a per-domain review. The two
compose, and they differ where it matters for PageRank — ``exclude`` removes
nodes from the propagation graph, ``scope`` filters the rows and lets rank
propagate over the whole graph, so a scoped run reports how central the
subtree is *globally*. Coupling in-degree likewise keeps counting callers
from outside the scope, which is the ripple a domain review is after (#239).

Input Schema

TableJSON Schema

Name	Required	Description	Default
`limit`	No	Top-N rows returned per section.
`scope`	No	Keep only nodes under any of these dot-prefixes, e.g. ["domains.billing"]; rank still propagates over the whole graph.
`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
`exclude`	No	Drop nodes whose FQN contains any of these dot-segments, e.g. ["tests"]; they are removed from PageRank propagation too.

Output Schema

TableJSON Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed4 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 / exclude / description

Added value: +"Drop nodes whose FQN contains any of these dot-segments, e.g. [\"tests\"]; they are removed from PageRank propagation too."

addedInput schema / properties / limit / description
```
Added value: +"Top-N rows returned per section."
```

addedInput schema / properties / scope / description

Added value: +"Keep only nodes under any of these dot-prefixes, e.g. [\"domains.billing\"]; rank still propagates over the whole graph."

First observedv0.21.0Sep 17, 2026

TDQS

A4.7/5.0

Behavior5/5

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

With no annotations, the description carries the full burden and does so thoroughly: it discloses the optional duckdb dependency, how unavailable dependencies are reported, how exclude removes nodes from PageRank propagation, how scope differs in propagation semantics, and that coupling in-degree still counts callers outside the scope. This goes far beyond the schema and annotative defaults.

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 front-loaded with the core purpose and result shape, then dives into parameter semantics and behavioral nuances. It is longer than a minimal definition, but most sentences earn their place because they clarify subtle ranking behavior that materially affects invocation and interpretation. A slightly tighter ending would make it even cleaner.

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 algorithmic complexity and the absence of annotations, the description is remarkably complete: it covers return shape, dependency risk, error behavior, parameter semantics, composition rules, and the graph-propagation model. An agent has enough information to select, invoke, and interpret the results correctly without additional documentation.

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

Parameters5/5

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

Although schema coverage is 100%, the description adds substantial meaning beyond the schema: it gives concrete examples for exclude (tests.* and domains.*.tests.*), explains dot-boundary anchoring for scope, describes how the two parameters compose, and clarifies their differing effect on PageRank and coupling measurements. This is exactly the kind of semantic enrichment the schema alone cannot provide.

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 names a specific verb and resource: computes whole-graph architectural metrics (coupling bottlenecks, God classes, PageRank). It explicitly distinguishes itself from node-local trace/impact/context tools, so an agent can identify what this tool is for without inspecting the 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?

It clearly states when to use this tool—for the global hotspot view and per-domain reviews—and contrasts it with node-local tools as complementary rather than substitutable. It does not list specific sibling alternatives by name for exclusion, but the context and scope/exclude guidance give strong directional usage cues.

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

Deploy Server