codegraph-brain

Overview Schema Source Related Servers Discussions Admin

cgis_find_symbol

Resolve a partial symbol name to ranked candidate fully qualified names (FQNs) before tracing flows or analyzing impact. Filters by node type and FQN prefix to remove read-the-file-first guesswork.

Instructions

Resolve a partial symbol name to candidate FQNs (substring match, ranked).

Call this BEFORE ``cgis_trace_flow`` / ``cgis_analyze_impact`` /
``cgis_get_structure`` when you know a short name (e.g.
``get_reservation_prices``) but not its full FQN — it removes the
read-the-file-first guesswork. Returns JSON ``[{fqn, name, type, file,
line}]`` ranked exact > prefix > substring. ``kind`` filters by node type
(FUNCTION / METHOD / CLASS / …); ``fqn_prefix`` scopes the search.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`kind`	No	Only return this node type, e.g. FUNCTION, METHOD or CLASS (any case). An unknown type matches nothing rather than raising an error.
`limit`	No	Maximum number of candidates to return.
`query`	Yes	Leaf symbol name to search for, without dots (e.g. get_flow_result) — not an FQN. Case-insensitive substring match, ranked exact > prefix > substring.
`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
`fqn_prefix`	No	Only return symbols at or under this FQN prefix, matched on whole dot-segments: app.svc does not match app.svc_alt, and a partial segment matches nothing.

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

Added value: +"Only return symbols at or under this FQN prefix, matched on whole dot-segments: app.svc does not match app.svc_alt, and a partial segment matches nothing."

addedInput schema / properties / kind / description

Added value: +"Only return this node type, e.g. FUNCTION, METHOD or CLASS (any case). An unknown type matches nothing rather than raising an error."

addedInput schema / properties / limit / description

Added value: +"Maximum number of candidates to return."

addedInput schema / properties / query / description

Added value: +"Leaf symbol name to search for, without dots (e.g. get_flow_result) — not an FQN. Case-insensitive substring match, ranked exact > prefix > substring."

First observedv0.21.0Sep 17, 2026

TDQS

A4.4/5.0

Behavior4/5

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

With no annotations provided, the description carries the full burden. It discloses the ranking order (exact > prefix > substring), the JSON return shape, and that kind/fqn_prefix filter results. It does not explicitly state the operation is read-only, but as a lookup tool this is implied. It adds meaningful behavioral context beyond the schema.

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?

Three sentences with no filler. The purpose is front-loaded, usage guidance follows immediately, and the return format and key filters are mentioned compactly. Every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 5-parameter tool with an output schema and no annotations, the description covers the core purpose, when to use it, return format, and two of the filtering parameters. It omits explicit mention of 'limit' and 'db_path', but those are fully described in the schema. Error behavior (e.g., unknown kind) is covered in the schema, not the description, which is acceptable.

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

Parameters3/5

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

Schema coverage is 100%, so the schema already documents all five parameters. The description adds marginal value by relating 'kind' and 'fqn_prefix' to their filtering effects, but it does not elaborate on 'limit' or 'db_path'. This is baseline 3 with slight extra context.

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 precise verb+resource: 'Resolve a partial symbol name to candidate FQNs (substring match, ranked).' It explicitly names the sibling tools it precedes (cgis_trace_flow, cgis_analyze_impact, cgis_get_structure), making differentiation clear without reading schemas.

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?

It gives an explicit condition for use: 'Call this BEFORE cgis_trace_flow / cgis_analyze_impact / cgis_get_structure when you know a short name but not its full FQN.' It even states the alternative it removes ('read-the-file-first guesswork'), leaving no ambiguity about when to invoke this tool.

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

Deploy Server