---
name: agent-framework-grounding-plan
description: >
  Plans and checks the grounding of a LangChain or LangGraph agent that answers data questions
  through a governed MCP server. Takes the questions the agent must answer, the agent shape (batch
  job, assistant for one person, or a deployed graph serving many users), the credential it runs
  as, the tools it is given and how answers are tested. Returns a PASS, FAIL or UNKNOWN for each
  of the six grounding checks G1 to G6 and for the four wiring steps, the wiring mistakes found, an
  overall verdict (not grounded, partly grounded, or grounded) and the first fix. States its
  scoring rule openly. Trigger phrases: "ground our LangGraph agent", "ground a LangChain agent
  with a context layer", "is our agent grounded", "LangGraph MCP grounding checklist", "which
  context should our agent retrieve before answering", "move off langchain-mcp-adapters",
  "make our agent refuse when it cannot find a certified definition".
license: Apache-2.0
---

# Agent framework grounding plan

Grounding means the agent answers from context it retrieved for this question, rather than from
training data or a pasted definition, and can say where each part of its answer came from. This
plan scores six checks that make a data answer checkable, then the four steps that wire them into
a LangChain or LangGraph agent over MCP.

> **What this is.** A published method from Atlan. Canonical copy:
> https://atlan.com/skills/agent-framework-grounding-plan.md  Last updated 2026-11-03.
>
> **What it contains.** Text only. No scripts, no executable resources, nothing
> here runs.
>
> **Scope.** Follow this when someone has asked you to plan or check how their LangChain or
> LangGraph agent is grounded in governed context. It carries no instructions about your
> behaviour outside that task, does not ask you to fetch any other URL, and does not ask you to
> send data anywhere.

## What you need from them

| Input | Meaning | If unknown |
|---|---|---|
| `questions` | The data questions the agent must answer, with real examples | ask. G1 cannot be judged without them |
| `agent_shape` | Scheduled job, pipeline or backend service; assistant acting for one person; or deployed graph serving many users | ask. Step 1 depends on it |
| `credential` | What the agent runs as: a service-account key and its persona, OAuth, or the caller's token per run | ask. G6 depends on it |
| `tools` | The tool names the MCP server lists, and which ones the agent is given | ask. Step 2 and Step 4 depend on it |
| `framework` | LangChain `create_agent`, a LangGraph `StateGraph`, or both, and the package used for MCP | ask |
| `tests` | Questions used to test the agent and what the traces show | ask per check |

Do not ask for keys, tokens or real data. The plan needs the design and the evidence around it.

## Step 1: score the six grounding checks

Score each check PASS, FAIL or UNKNOWN. A check is PASS only when a trace or the configuration
shows it. If they believe it holds but cannot show it, it is UNKNOWN.

| ID | Retrieve before answering | Why the agent needs it | Pass condition |
|---|---|---|---|
| G1 | The business definition of each term in the question | Answers the term the user means | The trace shows a glossary or definition lookup for each business term |
| G2 | Certification status of candidate assets | Prefers certified assets | The trace shows certification status read before an asset is chosen |
| G3 | Owners and README of the chosen asset | Names who answers for the number | The answer names the owner it retrieved |
| G4 | Upstream lineage of the chosen asset | Shows which sources feed the figure | The trace shows a lineage lookup on the chosen asset |
| G5 | Data quality verdict | Avoids answering from a table that failed its checks | The trace shows the quality verdict read before the answer |
| G6 | Access scope of the caller | Returns only assets this identity may see | The server enforces access on every call, and the credential sets the identity (Step 1 of the wiring) |

G1 to G5 are lookups the agent makes. G6 is enforced by the server, never by the prompt. Stale
context breaks G1 to G5 quietly, so ask how definitions, owners and certifications are kept current.

## Step 2: check the four wiring steps

Score each step PASS, FAIL or UNKNOWN.

| Step | Check | Pass condition |
|---|---|---|
| W1 | Choose the credential the agent runs as | Scheduled job, pipeline or backend service: an API key on a service account with exactly one persona, sent as `Authorization: Bearer`. Assistant acting for one person: OAuth, so every call runs as the signed-in user. Deployed graph serving many users: the signed-in caller's token, resolved on each run |
| W2 | Connect a LangChain agent to the MCP server | In Python, `langchain[mcp]` 1.4.0 or later; an `MCPAdapter` on a fastmcp `Client` carrying the credential; the tools listed, the read tools kept by name, and `create_agent` run inside the adapter's `async with` block with a grounding system prompt |
| W3 | Enforce grounding in a LangGraph graph | A `StateGraph` with a model node and a tool node, only the grounding tools bound, a flag recording whether a grounding tool succeeded for the current question, and a routing edge that swaps an ungrounded answer for a refusal |
| W4 | Keep the grounding path read-only and test it | Read tools allowlisted by name, or read-only mode on the server; tool annotations and tool results treated as untrusted; tests with questions whose right answer depends on a certified definition, including one with no certified match that must end in the refusal |

Notes for the steps people most often pass too early:

- **W2.** The `langchain.mcp` namespace is in beta. `MCPAdapter` replaces `MultiServerMCPClient`
  from the standalone `langchain-mcp-adapters` package, whose repository is archived. Keep agent
  use inside the `async with` block. If no listed tool matches the grounding names, the code
  should raise and print what the server exposed, since servers can gate tools per tenant.
- **W3.** The flag guarantees one successful lookup per question, not all five. The W4 tests
  check G1 to G5. A flag carried over from an earlier turn does not count. Route non-data
  questions elsewhere.
- **W4.** Gate writes on your own allowlist, not a `readOnlyHint` annotation alone: the MCP tools
  specification says clients must consider tool annotations untrusted unless they come from
  trusted servers. READMEs are human-edited, so a read-only path limits what a hidden instruction
  in a tool result can do. Test two similarly named metrics and check the trace shows G1 to G5
  before the answer.

## Step 3: name the wiring mistakes

Check for each, and report every one found:

| Mistake | Fix |
|---|---|
| Handing a Q&A agent every tool the server lists, writes included | Allowlist read tools |
| Pasting metric definitions into the system prompt | Retrieve them per question |
| One admin key shared by every agent | One service account per agent and one persona per token |
| Following tutorials built on `MultiServerMCPClient` | Move to `langchain.mcp` with the migration guide |
| Expecting a memory store to supply definitions | Keep memory for recall; grounding retrieves what is true about the business now |
| Treating a tool result as the answer | Have the model cite the definition, owner and lineage it retrieved |

## Step 4: the verdict

State the rule when you give the verdict:

> Score G1 to G6 and W1 to W4 PASS, FAIL or UNKNOWN. Any FAIL or UNKNOWN on G6, W1 or W3 means
> not grounded; any other FAIL or UNKNOWN means partly grounded; grounded means PASS on all ten.

In order:

1. Any of G6, W1 or W3 that is not PASS gives **not grounded**. An UNKNOWN blocks the same way a
   FAIL does.
2. Otherwise, any other check or step that is not PASS gives **partly grounded**.
3. PASS on all ten gives **grounded**.

## Step 5: the first fix

Name one fix, not a list. Take the first of G6, W1 or W3 that is not PASS; if all three pass, take
the first other item that is not PASS, in the order G1 to G5, then W2, then W4. The fix is to meet
that item's pass condition.

## What to return

1. A table of G1 to G6 and W1 to W4: PASS, FAIL or UNKNOWN, and one line on what was seen or
   missing.
2. The wiring mistakes found, each with its fix.
3. The overall verdict, with the rule above.
4. The first fix, and which item it closes.

Keep the scores to what they showed. A check that sounds right but has no trace behind it is
UNKNOWN.