Skip to content

Work with an AI agent on your code

Once an agent is connected via MCP, you don't drive the tools — you ask questions in your own words and the agent chooses what to call. This page covers the things worth knowing anyway: which questions the code model answers especially well, how to get a guided tour instead of a wall of file paths, and how to work across several projects at once.

Give the agent standing instructions

An agent reads the tool descriptions on its own, but it doesn't know your preferences. If your client supports a project instructions file — CLAUDE.md for Claude Code, .cursorrules for Cursor — a few lines there change the agent's behavior for every future session:

# Code navigation

An Understand MCP server is configured for this project. Prefer its tools over reading source
files when you need to find an entity, trace callers, or map dependencies.

When I ask you to walk through, trace, or explain how something works across source locations,
present a code tour rather than listing file:line references in the reply.

The second paragraph matters more than it looks. Guided tours are the feature people like most once they've seen one, and the feature agents are least likely to reach for unprompted — a plain list of locations is always an acceptable-looking answer, so nothing pushes the agent past it. One sentence of standing instruction is what makes tours the default.

Ask questions that need the whole project

These are the questions where the code model beats reading files, because the answer depends on code the agent would otherwise have to find by searching for text:

  • "Who calls Analyzer::run?" — exact callers, including through virtual dispatch, not just lines that happen to contain the name.
  • "Which classes implement Device?" — real inheritance and overrides, not naming conventions.
  • "What breaks if I change this header?" — every file that includes it, directly or transitively.
  • "Is anything still using this function?" — the reliable way to ask before deleting something.
  • "What's in this file?" — a structured list of what's defined there, with line numbers.
  • "Are there CodeCheck violations in the file I'm working on?" — the same violations Understand shows you.

Cross-language questions work the same way. In a codebase where C calls into Fortran, or C# wraps a native library, the call graph crosses that boundary because Understand analyzed both sides.

Two habits pay off. Name things exactly when you can — the entity name the agent gets back from a search is more precise than a description, especially with overloads. And ask for the reasoning path, not just the answer: "who calls this, and how does it get there from main?" produces a chain you can check, rather than a claim you have to trust.

Get a guided tour instead of a list of paths

When an explanation spans several places in the code — a startup sequence, a request path, how a setting reaches the thing it configures — ask for a tour:

"Walk me through how a parse request gets from the UI to the parser."

With Understand open, the agent builds an ordered set of stops with its own annotations, and you step through them in the editor: each stop navigates to the location while you read what the agent has to say about it. It's the difference between a list of twelve file paths and a narrated route through them.

Tours need the GUI, because they drive the editor. If you're working headless the agent will fall back to describing the locations in text.

Point the agent at what you're looking at

The traffic runs both ways. Ask the agent to take you somewhere — "open the definition of the resolver thread" — and it navigates the Understand editor there. This is often the fastest way to end a conversation: once you've found what you were after, jump to it rather than copying a path.

Work with more than one database

The agent can hold several databases open at once and query each by a short handle. Three capabilities matter here, and they're the only tool names worth knowing, because you are usually the one who decides when to use them:

  • list the databases it knows about — the ones open now, plus ones opened recently, whether they were last opened in Understand or by an agent, and how long ago.
  • open one, by path or by a name from that list.
  • close one when you're done with it.

Just ask in words: "what databases do you know about?", "open the firmware project too", "close the old baseline."

Three things follow from how it works:

With two or more open, every query names a database. With one open the agent can leave it implicit; past that it must be explicit, and if it forgets it gets an error listing the open databases rather than an answer from an arbitrary one. Wrong-project answers are the failure mode this design exists to prevent.

Nothing opens by itself. The server will list candidates for you, but it never opens one on its own initiative and never picks between them — including when there's only one candidate. Every open reports the full path it resolved, so it's always visible which project you're actually querying.

Closing a database never closes Understand. It disconnects the agent, and shuts down a headless server the agent started itself. A project you have open in the GUI stays open; the agent just stops routing queries to it.

Refer to databases by your own name

Handles come from filenames, so several test.und files produce test, y-test, z-test — and which one gets the bare test depends on the order they were opened. Rather than tracking that, rename them in conversation:

"Refer to z/test as test1."

Or all at once, by role rather than by path:

"Call the three I just opened main, feature, and baseline."

The agent keeps the mapping, uses your names when it talks to you, and translates to the real handles when it queries. No setup required — it's just the agent following an instruction.

Compare across versions or variants

Two databases of the same codebase at different points in time — or two product variants — turn a whole class of question into a direct comparison:

"baseline is last release and main is now. Which of the functions that call into the licensing module are new?"

The agent runs the same query against both and diffs the results. The same shape works for "did this interface's implementers change", "what's newly unused", and "which files gained dependencies."

Keep the database current

The agent's answers are only as fresh as the analysis. After code changes — yours or the agent's — ask it to re-analyze, and it updates the database incrementally rather than re-analyzing everything. Whether it's allowed to do that without asking is the Allow reparse setting in the project's MCP settings.

If you'd rather control analysis yourself, set that to Never and re-analyze from Understand or from und between tasks. What you should avoid is re-analyzing by other means while the agent is mid-task; let it finish, or let it do the reparse.

What this doesn't do

The MCP server answers questions and drives the editor. It doesn't edit your code — when an agent changes a file it uses its own editing tools, and Understand's role is telling it what the change affects before and after. Nor is it a way to run Understand headlessly for scripting: for automation, use the und command line or the Python API, which are built for it.