Learnings from Neon / MCP and AX

Build 2025 taught me something good

Moral of the story

Don’t hand an LLM a catalog of 100-plus low-level APIs. Start with the real job-to-be-done, then expose the smallest set of clearly named, task-oriented tools the agent needs to finish that job—nothing more, nothing less. (hugs4bugs.me)

---

Concrete example — Neon’s MCP-powered SQL-migration workflow

Neon’s database-as-a-service team built a purpose-built MCP server that lets an agent carry out a safe schema migration in four well-labeled steps instead of juggling dozens of generic endpoints:

Step	MCP tool	Why it exists	What it actually does (behind the scenes)
1	prepare_database_migration	Begin migration in a throw-away sandbox	Creates a temporary branch and applies generated DDL so nothing touches main until verified. (neon.com)
2	run_sql (or run_sql_transaction)	Let the agent verify its own work	Runs read-only checks on the temp branch—e.g., “SELECT …” to confirm the new column exists. (needle-ai.com)
3	describe_table_schema / get_database_tables	Provide structured evidence if more inspection is needed	Returns schema details so the agent can sanity-check edge cases before committing. (needle-ai.com)
4	complete_database_migration	Commit with one decisive call	Applies the migration to the main branch and deletes the temp branch when everything looks good. (neon.com, needle-ai.com)

Why this works

1. Narrow choice surface – Four domain-specific tools are cognitively cheap for the LLM to choose among; accuracy rises as “tool roulette” disappears. (hugs4bugs.me)
2. Workflow encoded in tool semantics – The names themselves (“prepare…”, “complete…”) teach the agent the required order, so you don’t need brittle prompt rules.
3. Safety baked in – The temp branch guarantees you can roll back automatically if verification fails—no human rescue mission required.
4. Higher-level abstraction – Instead of “run arbitrary SQL,” the agent calls “prepare migration,” aligning with the human mental model of migrate my schema safely.

---

Quick checklist for your own agentic tool design

1. Start with JTBD – State the outcome in plain language before thinking about endpoints.
2. Collapse steps – Combine low-level actions into single, task-centric tools (≤ 10 ideally).
3. Name tools verb-first, goal-oriented – e.g., create_safe_backup, not POST /v1/db/backup.
4. Encode guardrails in the tool – Side-effect-free sandboxes, confirmations, or staged commits.
5. Document with examples – LLMs learn patterns; show a happy-path call and the expected response.
6. Write evals early – Treat the agent like a new client; test that it can pick the right tool sequence. (neon.com)

Use this pattern and your agents will feel decisive and reliable instead of timidly guessing among a sea of functions.

---

On Labeling

1. “Supported actions” table in Neon’s own guide

Neon’s Get started with Cursor and Neon Postgres MCP Server guide publishes a clean, one-liner description for every tool.
A few highlights (verbatim):

Tool	Official description
prepare_database_migration	“Initiates a database migration process. Creates a temporary branch to apply and test the migration safely before affecting the main branch.”
complete_database_migration	“Finalizes and applies a prepared database migration to the main branch. Merges changes from the temporary migration branch and cleans up temporary resources.”
run_sql	“Executes a single SQL query… Supports both read and write operations.”
describe_table_schema	“Retrieves the schema definition of a specific table, detailing columns, data types, and constraints.”
get_database_tables	“Lists all tables within a specified Neon database.”

Why it’s useful:

• Verb-first names make intent obvious (prepare_…, complete_…).
• Outcome-focused descriptions (“creates a temporary branch”) teach workflow order without extra prompt rules.
• The list groups tools by intent (project management, SQL, migrations, tuning), so an agent’s search space stays mentally small.

---

2. Andre Landgraf’s MCP Night demo (LinkedIn transcript)

Andre, Neon’s DevRel engineer, explains why they wrote prepare_database_migration as a stateful tool instead of exposing dozens of low-level endpoints:

“It’s a stateful tool we specifically built for our MCP server… You really have to think of the LLM as your new client and build an MCP server that makes it as successful as possible.” (linkedin.com)

Key takeaways for labeling manuals:

1. Expose the atomic “jobs” an LLM actually performs (e.g., start migration, commit migration)—not generic CRUD verbs.
2. Encode guardrails in the tool contract (temp branches, read-only checks) so safety is implicit.
3. Keep the set small; Neon’s migration flow works with just four tools, yet covers 95 % of the job.

---

Putting it together — a minimal spec excerpt you can mirror

{
  "name": "prepare_database_migration",
  "description": "Stage a schema change in a temporary branch so the agent can test it safely before production.",
  "parameters": {
    "project_id":  { "type": "string",  "description": "Neon project ID" },
    "sql":         { "type": "string",  "description": "DDL statements to apply" }
  }
}

Copy the same labeling pattern (verb_noun, outcome-first description, tight parameter list) for your own JTBD-oriented tools and you’ll give any agent the kind of “good manual” Neon provides out-of-the-box.

---

3. Official Neon MCP docs — the short labels

Tool	One-line description (verbatim from docs)
prepare_database_migration	Initiates a database migration process. Creates a temporary branch to apply and test the migration safely before affecting the main branch. (neon.tech)
complete_database_migration	Finalizes and applies a prepared database migration to the main branch. Merges changes from the temporary migration branch and cleans up temporary resources. (neon.tech)

Why this matters:
The names are verb-first and outcome-oriented, so an LLM sees the workflow (“prepare → complete”) instead of a pile of CRUD endpoints.

---

4. Needle AI tools library — the full “operator manual”

Below is an abbreviated excerpt for prepare_database_migration that shows how Neon supplies LLM-friendly context: use-cases, mandatory follow-ups, and even response templates.

<tool name="prepare_database_migration">
  <use_case>
    Performs schema migrations by auto-generating & executing DDL.
    Supports CREATE / ALTER / DROP operations.
    1. Parse natural-language request
    2. Generate SQL
    3. Execute in a *temporary* branch
    4. Verify before touching main
  </use_case>

  <workflow>
    1. Create temp branch
    2. Apply migration SQL
    3. Return migration-ID + branch info for verification
  </workflow>

  <important_notes>
    • After running, you MUST test with `run_sql` on the temp branch  
    • Ask the user for approval before committing  
    • Then call `complete_database_migration`
  </important_notes>

  <response_instructions>
    ALWAYS include  
      – Migration ID  
      – Temporary Branch Name & ID  
      – Migration Result  
    Do **not** expose low-level SQL or column types in the reply.
  </response_instructions>

  <example>
    INCORRECT → “I added a *boolean* column …”  
    CORRECT   → “I added the **is_published** column …”
  </example>
</tool>

(needle-ai.com)

Why this matters:

1. LLM coaching – The <important_notes> and <response_instructions> blocks explicitly tell the agent what to do next and how to talk back to the user.
2. Safety baked in – The workflow forces a temp branch + human confirmation before any production commit.
3. Examples for grounding – Concrete “correct vs incorrect” replies prime the model to produce the right style.

---

How to reuse these patterns in your own MCP surface

1. Keep the surface small – two tools cover 95 % of the migration JTBD.
2. Name tools verb-first, goal-focused (prepare_*, complete_*).
3. Embed guardrails – create temp resources and require human approval before destructive steps.
4. Add rich hints – include <use_case>, <workflow>, and <response_instructions> sections so the LLM never guesses what’s next.

Drop these snippets directly into design docs or slide decks and your team will immediately see why a four-tool surface (prepare, verify, complete, diagnose) beats exposing 100 raw API calls.