suggest-concepts

name	suggest-concepts
description	Explore the CPG of an analyzed codebase and suggest semantic concepts and operations to tag nodes with what they are and what they do.

Suggest Concepts and Operations for a CPG

Your task is to explore a Code Property Graph (CPG) of an analyzed codebase and suggest semantic concept and operation overlays to tag the nodes you find. You must answer with the tool cpg_suggest_llm_concepts_and_operations and not with lists, tables or text.

About the CPG

The Code Property Graph is a language-agnostic representation of source code. It unifies the abstract syntax tree (AST), control flow, and data flow of a program into a single graph. Nodes represent syntactic and semantic elements (functions, calls, variables, records, etc.), and edges connect them.

On top of the raw graph we layer overlays Concept and Operation nodes, which attach higher-level meaning to existing CPG nodes.

Concepts and Operations

Concepts describe what something is.

• Attached to nodes that represent or hold a thing (variables, fields, records, sometimes functions).
• Examples: user_email → Data, api_token → Secret, an AuthService class → Authentication.
• A concept can have properties and a set of operations associated with it.

Operations describe what something does.

• Attached to nodes that perform an action, most often calls (function or method calls).
• Examples: requests.post(...) → HttpRequest, file.write(...) → FileWrite, encrypt(...) → Encryption.
• Every operation belongs to a concept.

Rules:

• A concept can stand on its own. An operation always needs a concept.
• Keep names short and semantic: one word where possible (Encryption, Logging, Secret).

Workflow

1. Load existing concepts and operations

Call cpg_list_llm_concepts_operations once, before anything else.

• If the result is non-empty, reuse those concept and operation names and their property schemas wherever they semantically fit. Do not invent a duplicate under a different name.
• If the result is empty suggest new ones.

2. Explore the code comprehensively

Before suggesting follow a multistep approach by calling other tools to explore the graph, so one listing is rarely enough: Combine several of:

• cpg_list_functions, cpg_list_records, cpg_list_calls, cpg_list_calls_to, etc. for overview.
• cpg_get_node to inspect a specific node in detail (if needed).

Keep exploring until you have real node IDs for every concept and operation you intend to suggest.

3. Suggest via the tool

Suggest one concept per turn: emit a single cpg_suggest_llm_concepts_and_operations tool call, then proceed to the next concept on your next turn.

Pass REAL node IDs returned by the previous tools. Never pass placeholder, invented, or guessed IDs. If you don't have a real ID, go back to step 2.

For each call provide:

• The concept's nodeId (typically a record, field, or variable).
• Each operation's nodeId pointing to the node where the action is realized.
• Reasoning so the user can judge the suggestion.

4. Stop

Once you have called the tool for every concept you want to suggest, your turn is done. The user reviews the suggestions and decides what to accept. Do not apply anything yourself.