DEV Community: Michael S.

Why your agent's tool list keeps drifting away from your database

Michael S. — Tue, 11 Aug 2026 08:56:17 +0000

The usual pitch for GraphQL and agents is that the model requests exactly the fields it needs, so you stop over-fetching. That's a bandwidth argument. Bandwidth stopped being the bottleneck in an agent loop roughly the moment agent loops existed — the model is about to spend four seconds and real money thinking about whatever comes back, so 8KB on the wire is not what's hurting you.

Nearly every GraphQL-for-agents post opens this way, which is why anyone who has shipped one of these stops reading at paragraph two. There's a real argument underneath. It's less flattering to everyone involved, GraphQL included.

You are maintaining two schemas

You have Postgres, and Postgres has a schema. It's authoritative, machine-readable, and updated every time you migrate, because that's what migrating means.

You also have an agent with forty tools, each carrying a name, a description, a JSON Schema for its arguments, and a response shape that lives in someone's head. All of it written by hand, deployed on a cadence that has nothing to do with the database.

That second pile is also a schema. It's lossy, and it has no mechanism for noticing when the first one moves. Nobody sat down and decided to maintain two schemas — you decided to write forty tools, and this is what forty tools turns out to mean eight months later.

The complaint you usually hear about this is verbosity, which is the wrong complaint. The real problem is that the drift is silent:

Change in Postgres	Hand-written REST tool	Generated GraphQL schema
Column added	Invisible until a human edits the tool	Queryable immediately
Column renamed	500, or silently drops the field	Validation error, by name, before execution
Table added	New endpoint, new tool, new description, new deploy	Queryable
Permission tightened	Tool still advertises it; fails at runtime if you're lucky	Field vanishes from that role's schema

Column two is where it hurts, because those failures land at runtime, inside a loop, as a strange tool result the model then reasons its way around. Agents are unreasonably good at reasoning around broken tools. It retries, rephrases, tries a neighbouring tool, and eventually hands you a confident summary built on a field that stopped existing in March. You find out when a customer asks why the numbers moved.

Of those four rows, the renamed column is the one I'd bet on causing your next incident. A rename is the change least likely to trigger anyone's instinct to go check the agent.

Introspection, and why "just introspect" is wrong

Introspection is the fix for drift — the agent asks what exists instead of being told in advance. The problem is that introspection is exhaustive by design, and generated schemas are enormous.

Concrete numbers need a concrete stack, so from here on the examples are Nhost — Postgres with a Hasura GraphQL engine on top, which I'll come back to at the end. Any generator in this class behaves the same way, so translate the commands as needed.

One table in a generated schema doesn't produce one type. It produces the table type, then _bool_exp, _order_by, _insert_input, _set_input, _inc_input if anything is numeric, _on_conflict, _constraint, _update_column, _select_column, _mutation_response, _aggregate, _aggregate_fields, and a statistical family of _avg_fields, _max_fields, _min_fields, _sum_fields, _stddev_fields, _stddev_pop_fields, _var_samp_fields and friends. Every table you own carries a type for computing population variance, in case that ever comes up.

That's north of twenty generated types per table, before any business logic exists. I won't quote a figure from my own project, because the only figure that matters is yours. It's two commands away:

nhost schema dump --role admin -o schema.admin.graphqls
nhost schema dump --role user  -o schema.user.graphqls
wc -c schema.*.graphqls

Run those, then put both files through a tokenizer. The admin number is usually an unpleasant surprise. What matters more is the gap between the two — that gap is this entire post, expressed in bytes.

Piping raw introspection into a context window converts a schema advantage into a token bill. Anyone telling you otherwise is demoing four tables.

The schema is the permission boundary

The property that makes any of this worth the trouble rarely comes up in these posts: roles don't only filter rows, they filter the schema. A role without select permission on internal_notes doesn't get an authorization error when it asks — that field isn't in its version of the type. No permission on a table, and the role doesn't see the table at all.

Introspecting as agent therefore returns a genuinely different, much smaller document than introspecting as admin. The defaults help too. In a zero-trust setup a new role starts with access to nothing and you grant your way up, which compares well against adding a fortieth endpoint to a REST service where the default is whatever the surrounding handlers happened to do.

Narrowing the role collapses two problems into one, because the context bloat and the blast radius shrink together. You stop hand-curating a tool list and start writing a permission set, and the tool list falls out of it.

A select permission on invoices for a role called agent looks roughly like this:

role: agent
table: invoices
permission:
  columns:        # internal_notes is not here. for this role it does not exist.
    - id
    - amount
    - status
    - customer_id
    - created_at
  filter:
    organization:
      members:
        user_id:
          _eq: X-Hasura-User-Id
  limit: 100

Tenant scoping there is a row filter evaluated in the data layer, keyed off a session variable that arrived in a signed JWT. It isn't a WHERE clause the agent was trusted to remember. And internal_notes isn't hidden so much as absent — there's no prompt injection that extracts a field the type system doesn't contain. The limit is doing more work than it looks like, and I'll come back to it.

The common alternative is a line in a system prompt reading "Only query data belonging to the current user's organization." That's a request, not a control. It sits in the same context window as untrusted user text, with no enforcement and no audit trail, and its failure rate against adversarial input is well documented by now.

Hand-rolled REST can enforce isolation properly, obviously, and the question was never whether it can. It's whether it does so in one declarative place every query passes through, or across forty handlers where one is quietly missing a WHERE clause. Usually it's the latter, and usually the missing one is an endpoint someone added for a quick admin report that was never meant to be permanent.

None of this comes free either. Deep permission filters compile into the generated SQL, where they can get slow in ways that don't surface until they do. The tell is a query that runs fast as admin and slow as user against identical data. Nhost documents this one and points at Postgres JIT compilation as the usual culprit. Worth knowing before you conclude that GraphQL is slow, because it isn't — your permission tree is.

Things that break

Agents write queries no human would type, which produces failure modes GraphQL alone mostly doesn't have. Unbounded lists are the worst of them, because the model has no intuition for cardinality — users is a word to it, not four hundred thousand rows. That's what the limit in the permission was for, and it belongs on every select permission a non-human role has, not just the ones you got around to.

Nesting is close behind, since it costs the agent nothing to write and so it writes it. The containment is a depth limit: on Nhost that's maxDepthQueries under [graphql.security], on a plan that includes it. Self-hosted Hasura puts it behind a tier too, so if yours doesn't have it, you're building a gateway. Set it lower than feels comfortable. An agent has no legitimate reason to go four levels deep, and the queries where it wants to are exactly the ones you'd rather it didn't run.

The same config block has forbidAdminSecret, which rejects any request carrying an admin-secret header. Turn it on and "the agent accidentally ran as admin" becomes structurally impossible instead of something you audit for afterwards. The docs warn that enabling it can break deployments, which is a polite way of saying you probably have something running as admin right now that you've forgotten about.

Mutations are the uglier half, since GraphQL will happily let you insert into three tables in a single call. The partial-failure semantics of that are about as well specified as you'd expect from a spec that mostly declined to have opinions about errors. An agent handed a partial success will improvise.

I avoid finding out what it improvises: one mutation, one table, one call, an idempotency key. It's boring, and I'm aware it's avoidance rather than a solution. Give the agent a read-only role by default too, with writes behind a second role it has to explicitly assume — introspection makes exploration cheap, and models are curious.

The part I haven't solved

The thing I don't have a good answer for is role sprawl, and it follows directly from everything above. Narrow roles are how you control context and permissions at the same time. Follow that far enough and you get a role per agent task, then per-tenant variations, then one for the reporting agent that's almost the support agent's role. Now permission metadata is a thing you maintain by hand.

Which is, you'll notice, structurally the same problem as the hand-maintained tool list. It's smaller, declarative, and lives in one place, so it's a better version of the problem. But I'd be overselling to call it solved, and if you've found a clean pattern here, I'd like to hear it.

When to ignore all of this

If you have six endpoints, write six tools and skip everything above, because at that size this is over-engineering and you'll feel silly. The threshold isn't a table count but a rate of change. Once your schema moves faster than a human remembers to update tool descriptions, manual maintenance has already lost — you just haven't hit the bug yet.

Most of the argument evaporates if your data layer isn't relational, since the permission-filtered-schema property is doing the heavy lifting. That property comes from a mature permission layer over a relational store, not from GraphQL as a language. GraphQL over microservices with hand-written resolvers gives you the schema and none of the enforcement, which is the worst version of this trade available.

And if you're here because agents supposedly work better with GraphQL, they don't especially. Models write mediocre GraphQL alongside their mediocre SQL and their mediocre REST calls. The gain was never query quality — it's that the surface stays honest without anyone maintaining it.

Concretely

The setup I've been describing is Postgres with a permission-aware GraphQL engine on top, which is what Nhost packages — Postgres, GraphQL, auth, storage, functions, event triggers. The part that matters here is that auth and the permission layer are the same system. So x-hasura-user-id in that row filter is a claim from a signed token, not something an application layer asserted and hoped was right.

It doesn't solve the context problem, and it won't stop your agent writing a stupid query. You still have to design the roles, which is where the actual work lives. Most of the value in any of this is one afternoon spent deciding what the agent role is allowed to see, and no platform does that afternoon for you.

What you get is the boundary in one declarative place instead of forty handlers, and a schema that can't drift from its permissions because they're the same object.

What you actually need to ship an AI agent

Michael S. — Thu, 18 Jun 2026 07:37:30 +0000

Everyone's building agents. Half of them are running. The other half have "active plans."

I've been in both camps. The difference isn't the model. Models have been good enough for a while now. It's everything around the model that nobody talks about in tutorials because tutorials end when the demo works.

This is the stuff that bit me. Take it or leave it.

Why build an agent at all

Worth asking before you pick a framework.

The cases where agents actually make sense — and I mean actually get used, not just demoed — are pretty narrow:

You have work that's too variable for a simple automation but too repetitive for a human to do 500 times a day. Customer support triage where the agent needs to know who the user is, what plan they're on, what happened in their last three sessions. Internal ops: pull from four systems, write a Slack summary, done. SaaS features where "AI that knows your account" is the actual value, not a generic chatbot bolted on.

What all of these have in common: the agent needs to remember things. Needs to know who's asking. Needs to not lose its mind when a tool call fails or an LLM provider has a bad afternoon.

Everything below is about making that work.

Orchestration

Use LangGraph. Not because it's elegant (it's not always), but because it handles the stuff that kills you in production and nothing else does it as well right now.

The things that matter: state persists across crashes (you don't restart from zero when something hiccups). You can pause mid-execution, wait for a human to approve something, resume. Parallel tool calls without data races. Explicit control flow so you actually know what's running.

Here's what setting up LangGraph with Postgres checkpointing actually looks like. This is the part that makes your agent survive crashes:

from langgraph.graph import StateGraph
from langgraph.checkpoint.postgres import PostgresSaver
from psycopg_pool import ConnectionPool

pool = ConnectionPool(conninfo=os.environ["NHOST_DATABASE_URL"])
checkpointer = PostgresSaver(pool)

graph = StateGraph(AgentState)
graph.add_node("reason", reason_node)
graph.add_node("act", act_node)
graph.add_edge("reason", "act")
graph.add_edge("act", "reason")

app = graph.compile(checkpointer=checkpointer)

# every run is now resumable: crash mid-execution, pick up from last checkpoint
result = app.invoke(
    {"messages": [HumanMessage(content=user_input)]},
    config={"configurable": {"thread_id": user_id}}  # per-user state
)

thread_id is the key thing here. Pass the user's ID and every session is isolated, resumable, and persisted automatically.

The thing nobody warns you about: you can massively over-engineer simple things with it. I've seen a FAQ chatbot end up as a 14-node state graph. LangGraph doesn't stop you from doing that. You have to stop yourself.

When to consider something else: if you're TypeScript-first, look at Mastra before committing. TypeScript-native, growing fast, better DX in a few ways. If you're in an enterprise org that already runs Temporal for workflow orchestration, you might be better off building agent steps as Temporal activities than introducing another stateful runtime. LangGraph is the highest-confidence bet for a new project but it's not a law.

MCP and tools

MCP (Model Context Protocol, Anthropic, late 2024) is the right idea: one protocol for connecting agents to external services instead of custom glue for every tool. GitHub, Slack, Nhost, Google Drive — most have MCP servers now. You connect your agent once and swap tools without rewriting integrations.

The ecosystem is real. The maturity is uneven and I want to be honest about that.

Community MCP servers vary a lot. Some are solid and actively maintained. Some are a weekend project that hasn't been touched in eight months. A few have had genuinely bad security issues. One package shipped clean for 15 versions then added exfiltration code in version 16 (CVE-2025-6514, CVSS 9.6). Anthropic's own official Git MCP server shipped with three CVEs including one that got you RCE through prompt injection. Not a community project. Anthropic's reference implementation.

Treat MCP servers like npm packages: pin versions, audit what they're doing, don't blindly trust community servers for anything that touches sensitive data.

For your own internal business logic: write your own MCP servers. It's simpler than it sounds and means your agent talks to your own systems through the same interface as everything else.

Memory

This is the part of the stack everyone underestimates — and I'm still figuring it out.

Here's the actual problem: LLMs are stateless by default. Every API call starts from zero. For a demo this is fine. For an agent that's supposed to know who you are and remember that you hate long responses, it's not fine.

Short-term memory (within a session) is handled by LangGraph's checkpointer. Store it in Postgres. Not interesting, just works.

Long-term memory (across sessions) is where it gets real. You need two things:

User session ends
       │
       ▼
 ┌─────────────────────────────────────────────┐
 │            What do we store?                │
 └──────────────┬──────────────────────────────┘
                │
       ┌────────┴─────────┐
       ▼                  ▼
  Structured           Semantic
  (Postgres)          (pgvector)
       │                  │
  "user prefers      "last month user
  short responses"    said their budget
  "plan: pro"         was under $10k"
  "timezone: UTC+2"   similarity search
       │                  │
       └────────┬─────────┘
                ▼
     injected into next session's
     system prompt or tool context

If you go pure vector-only because it feels modern, you lose queryability and auditability. You end up with a blob of embeddings you can't inspect or debug. Use both.

Writing to both from inside an agent node:

async def save_memory_node(state: AgentState):
    # structured fact → Postgres
    await nhost.graphql("""
        mutation UpsertMemory($userId: uuid!, $key: String!, $value: String!) {
            insert_user_memory_one(
                object: {user_id: $userId, key: $key, value: $value},
                on_conflict: {constraint: user_memory_pkey, update_columns: [value]}
            ) { id }
        }
    """, {"userId": state["user_id"], "key": "response_preference", "value": "concise"})

    # semantic memory → pgvector
    embedding = await embed(state["last_exchange"])
    await nhost.graphql("""
        mutation InsertEmbedding($userId: uuid!, $content: String!, $embedding: vector!) {
            insert_memory_embedding_one(
                object: {user_id: $userId, content: $content, embedding: $embedding}
            ) { id }
        }
    """, {"userId": state["user_id"], "content": state["last_exchange"], "embedding": embedding})

Not claiming this is the cleanest possible implementation. It's just what the actual write path looks like.

What nobody tells you until you're deep in it:

Conflicting memories. User says "keep it short" in February. In April they say "I need more detail on this." Which one wins? There's no clean answer to this and I don't think anyone has one. You're making judgment calls in your memory logic.

Hallucinated memories. LLMs can "remember" things you never stored. This happens in production and it's unsettling when you first see it.

Memory bloat. You can't just keep appending forever. At some point you need summarization, forgetting, or tiered retrieval. When exactly? What do you summarize vs keep verbatim? How do you decide what to drop? Open questions. Every team doing this seriously has custom logic.

Mem0 is trying to solve some of this. Worth checking its current state. It was promising but I wouldn't call it "plug this in and you're done" yet.

The backend nobody plans for until it's too late

Most agent tutorials treat the backend as "somewhere you store stuff." In practice your agent needs four things:

A database with vector search (memory, covered above)
User identity: who is this person, what are they allowed to do, what's their plan tier
File storage: documents they upload, things the agent generates, outputs you need to persist
Serverless functions for your own business logic, because not every tool is a third-party API

You can stitch these together from separate services. Supabase for the DB, something else for auth, S3 for files, Lambda for functions. It works. It's also four systems to maintain, four permission models to keep in sync, four things that can drift out of alignment.

I use Nhost because it's all of this in one place: Postgres, pgvector, Auth, Storage, Functions, with a consistent permissions model and an MCP server so the agent can interact with all of it through a single interface. Less surface area, same capabilities.

Not the only answer. The argument is coherence, not uniqueness.

LLM Gateway

I skipped this on an earlier project. Then Anthropic had a three-hour incident and the product was down. That was the last time I skipped it.

What a gateway does: sits between your orchestrator and the model API. Handles fallback (Anthropic down → route to GPT-4o automatically), caching (same prompt hits cache instead of costing another call), per-session cost limits (a runaway agent loop can rack up hundreds of dollars before anyone notices, and that's not hypothetical), and load balancing across API keys at scale.

LiteLLM is what I'd start with. Open-source, self-hosted, 100+ providers behind a unified OpenAI-compatible API. Takes an afternoon to set up. Covers everything you need early on.

Portkey when you need more: guardrails, PII redaction, audit trails, more sophisticated routing policies. Went fully open-source in early 2026.

Rough heuristic I've seen cited: below ~$10K/month in LLM spend you can get away with a simple wrapper. Above that, treat the gateway as infrastructure, not an optional add-on.

The model

Pick Claude or GPT-4o and start. This layer is genuinely commoditizing.

What still matters: tool calling reliability is not equal across models. Multi-step agentic tool use, long chains, recovery from bad tool outputs — Claude 3.5 Sonnet is the most consistent in my experience. GPT-4o is close. Open-weight models are better than they were and will keep getting better but they still lag on complex recovery scenarios. The gap narrowed. It's not gone.

Cost at scale: route by step complexity. Simple classification or routing steps don't need the big model. Haiku or GPT-4o mini for those, expensive model for the reasoning steps. If your agent makes 25 LLM calls per session and 20 of them are simple, you're wasting money.

Security

This section didn't exist in the 2024 version of guides like this. It does now.

The attack you need to understand: indirect prompt injection. Your agent fetches a document. That document contains hidden instructions. The model executes them because it can't distinguish between content and instructions in context.

This is not theoretical. Supabase's Cursor agent processed support tickets with embedded SQL to exfiltrate integration tokens. Attackers submitted support tickets containing the attack payload. The agent had privileged DB access and trusted what it read.

Anthropic's own Git MCP server shipped CVEs that allowed RCE through prompt injection. Path traversal, argument injection, repo scoping bypass. If the reference implementation shipped with that, assume third-party community MCP servers are higher risk.

There's no complete defense because this is architectural — it's a property of how LLM context windows work, not a bug you can patch. What you can do:

Least privilege. If the agent only needs to read, give it read access. Don't grant write "just in case."
Treat tool outputs as untrusted. Validate and sanitize MCP responses before they enter the model context.
Gate irreversible actions. Before the agent sends an email or modifies a payment record, validate against policy. Require explicit user confirmation where stakes are high.
Vet MCP servers. Pin versions. Audit what they're doing before putting them near anything sensitive.

Observability

I always wire this up last. I always regret it.

Agents fail silently in ways that are hard to catch. A normal API returns a 500. An agent that retrieves the wrong memory or calls the wrong tool returns something that looks like a valid response. The failure is invisible until a user notices or until you look at the numbers and something's off.

You need step-level traces: which node ran, what tool was called with what exact input, what it returned, what was in the prompt at that moment, how long each step took, what it cost. Not logs. Traces.

LangSmith is what I use. Native to LangGraph, one environment variable, and the trace UI is genuinely good. The lock-in is real — it's LangChain's product. But nothing else is as functional for this specifically right now.

Open-source alternative: Langtrace. OpenTelemetry-compatible, you own the data, integrates with Grafana or Datadog. More setup, less polished UI.

One thing to actually instrument yourself: correlation between agent traces and user sessions. You want to be able to take a user complaint, look up their session, and see the full chain of what happened. This doesn't come for free. Wire it up early.

What's still a mess

Memory architecture. Nobody has the clean answer. How to handle conflicting signals, what to summarize vs keep, when to forget: every team doing this seriously has custom logic. If someone's selling you a complete solution, probe it hard.

Evals. Most teams still rely on human review because automated evaluation of open-ended agent behavior is genuinely hard to build well. Building eval datasets that catch real regressions and not just happy-path behavior takes real investment most teams don't make until something goes wrong in prod.

Multi-agent patterns. Planner-executor setups, debate loops, agent hierarchies: people are using all of these in production. No consensus on when to use which. Evolving fast.

MCP security. The protocol is less than two years old. CVEs are appearing. Stay current.

Cost. A 20-step agent loop at 1,000 sessions/day is real money. Build token budget controls before you need them, not after you get the bill.

The model is maybe 10% of why agents succeed or fail in production.

The rest is whether it remembers things, whether it knows who it's talking to, whether you can see what it's doing when something goes wrong, and whether it doesn't get compromised by content it reads from the world.

Stack: LangGraph (or Mastra) · Claude · LiteLLM/Portkey · Nhost (Postgres + pgvector + Auth + Storage + Functions) · MCP · LangSmith (or Langtrace) · Vercel AI SDK