cgis_trace_flow
Trace downstream dependencies of a fully qualified name through calls, imports, inheritance, DI and references to answer what X depends on, with configurable depth and output.
Instructions
Downstream subgraph of one FQN: everything it reaches within depth hops.
Follows every edge except containment — in practice calls, imports,
inheritance, DI dependencies and references — between internal code, so this
answers "what does X depend on?". Containment and
stdlib/third-party nodes are left out unless ``include_structure`` /
``include_external`` ask for them (external covers stdlib, third-party and
unresolved call targets) — the same view as the CLI's ``trace``.
For what depends on X use
``cgis_analyze_impact``; for only the members of a module or class,
``cgis_get_structure``; for a source-included brief to read before editing
one symbol, ``cgis_context``.
Test code is left out unless ``include_tests`` asks for it, and at most
``max_nodes`` nodes come back, nearest first, as for impact.
``output_format="text"`` returns the subgraph as an indented tree, one line
per node with children in call-site order, so a flow reads top down — about
a fifth of the json for the same answer; ``"mermaid"`` (default) a diagram;
``"json"`` a joinable ``{root, nodes, edges, coverage}`` payload
with real FQNs (not display hashes) for agent/CI use. ``coverage`` counts
the calls the traversed functions make that resolved to nothing, and
``top_unresolved`` names the most frequent. Read the names, not only the
ratio: in Python most are methods on untyped locals (``logger.info``,
``items.append``), which cut nothing short. Use ``cgis_ingest`` first if
the database does not exist yet.
Input 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 | Maximum edge hops downstream, over calls, imports, inheritance, DI dependencies and references (plus containment with include_structure). A hop from a base or interface method to its overrides costs no depth. | |
| 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 |
| max_nodes | No | Most nodes to return, nearest levels first. A level that does not fit is cut and the walk stops there; the answer says where and how many were left out, so a smaller depth or a narrower FQN can follow. | |
| include_tests | No | Also return test code. Off by default: on a large repo tests outnumber the production code an answer is about. The answer says how many were left out — a floor when it is also truncated, since levels past the cut are not walked. A root that is itself a test keeps them. | |
| output_format | No | "text" for an indented tree, one line per node — the cheapest to read; "mermaid" for a diagram; or "json" for a payload with real FQNs, to compute with (case-insensitive). Any other value returns an error. | mermaid |
| include_external | No | Also return stdlib, third-party and unresolved call targets — calls on values whose type is decided at runtime. Off by default, as in the CLI, because they dominate the payload; in json, coverage/top_unresolved still counts what was dropped. | |
| include_structure | No | Also follow containment (CONTAINS/DECLARES): a module's or class's own members, and the class or file enclosing a symbol. Off by default, as in the CLI; cgis_get_structure is the tool for members alone. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |