codegraph-brain

Overview Schema Source Related Servers Discussions Admin

cgis_context

Get a prompt-ready brief for any fully qualified name: its source, class, direct callers, and callees. Use this before editing a symbol to avoid reading whole files and quickly understand its impact.

Instructions

Prompt-ready brief on one FQN: its source, class, direct callers and callees.

Call this before editing a symbol, instead of reading its files. It follows
calls only, one hop by default. Source is included when the file is found
(see ``source_root``), and the domain when the graph was tagged with one.
For a multi-hop subgraph
over calls, imports, inheritance and references without source, use
``cgis_trace_flow`` (downstream) or
``cgis_analyze_impact`` (upstream).

Returns an XML-tagged prompt — the focal node's source, its enclosing class,
its architectural domain boundary, direct callers (upstream ripple) and
callees (downstream dependencies) — meant to be injected into your context
window in place of raw file dumps. Far more token-efficient than reading
whole files, and structured so boundaries stay unambiguous.

Use ``cgis_ingest`` first if the database does not exist. ``source_root``
locates source files on disk when the graph was ingested from a
sub-directory (e.g. ``"src"`` after ``cgis ingest ./src``); it is safe to
pass even when the stored paths already start with that segment (#228).
When no candidate exists the ``<source>`` block degrades gracefully to
"unavailable".

Input Schema

TableJSON Schema

Name	Required	Description	Default
`fqn`	Yes	Fully qualified name, e.g. pkg.module.Class.method. A unique dot-boundary suffix also resolves; an ambiguous one returns candidates. Use cgis_find_symbol to look a name up.
`depth`	No	Call hops around the focal node; 1 means direct callers and callees.
`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
`source_root`	No	Directory the graph's stored file paths are relative to — normally the project_path given to cgis_ingest; prefer an absolute path. Empty means the server's working directory, so source shows as unavailable when the server runs elsewhere.

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 / depth / description

Added value: +"Call hops around the focal node; 1 means direct callers and callees."

addedInput schema / properties / fqn / description

Added value: +"Fully qualified name, e.g. pkg.module.Class.method. A unique dot-boundary suffix also resolves; an ambiguous one returns candidates. Use cgis_find_symbol to look a name up."

addedInput schema / properties / source_root / description

Added value: +"Directory the graph's stored file paths are relative to — normally the project_path given to cgis_ingest; prefer an absolute path. Empty means the server's working directory, so source shows as unavailable when the server runs elsewhere."

First observedv0.21.0Sep 17, 2026

TDQS

A4.9/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 that only calls are followed, depth defaults to one hop, source is included only when found, source_root behavior including the #228 edge case, and graceful degradation to 'unavailable'. This is rich behavioral disclosure beyond what any schema field states.

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 first sentence immediately states the core deliverable and scope. Subsequent paragraphs each add distinct value: usage guidance, alternative routing, return format rationale, prerequisites, and parameter edge cases. Nothing is wasted, and the most decision-relevant information is front-loaded.

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 4-parameter tool with no annotations, the description covers prerequisites, alternatives, parameter edge cases, output format, and failure behavior. Even with an output schema present, the description's explanation of the XML-tagged prompt and token efficiency adds value an agent cannot infer from the schema alone.

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 100%, so baseline is 3, but the description adds meaningful parameter nuance: source_root is safe to pass even when stored paths already start with that segment, emptiness means the server's working directory, and depth one hop means direct callers/callees. This goes beyond the schema's own parameter 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 and resource: returns a prompt-ready brief on one FQN covering source, class, direct callers, and callees. It also distinguishes itself from siblings by naming cgis_trace_flow and cgis_analyze_impact as multi-hop alternatives, so an agent can tell the tools apart.

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?

Explicitly says when to use it ('before editing a symbol, instead of reading its files'), when not to (for multi-hop subgraphs use cgis_trace_flow or cgis_analyze_impact), and what prerequisite to check ('Use cgis_ingest first if the database does not exist'). This leaves no ambiguity about placement among siblings.

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

Deploy Server