Ship cleaner PRs with agentic AI: use MCP context and living docs

The problem: agents write code fast, but they don’t know your codebase

Claude Code, Cursor, and Codex are quick to draft a feature or refactor, but they miss your code's local knowledge: naming patterns, API boundaries, testing practices, and what must be documented alongside a change. Give an agent the right context and you get fewer rewrites and cleaner PRs on the first try. That’s where MCP, AI, and agentic workflows come together—and where a docs layer like Moxie Docs can help. Improving the context and knowledge of AI tools improves the quality otuput.

Why MCP context matters for AI, agentic coding

Without a shared context channel, you end up pasting snippets into prompts and hoping the model infers conventions. MCP gives tools a consistent way to fetch conventions and documentation when the agent needs them. That means:

• The agent can retrieve project conventions on demand instead of guessing.
• PRs can include doc edits created by the agent, not left for humans later.
• Reviewers see code and docs evolve together, which reduces drift.

When the docs are actually in-repo and up to date, the agent isn’t inventing context—it’s citing it.

What we measured: cost goes up, quality nudges up in the right places

We benchmarked agent tasks with and without MCP-connected docs (using Moxie Docs as the source). Results were positive but targeted:

Scenario	Cost impact	Prompt tokens	Turns	Quality (10-pt)	Notes
MCP connected, idle	~0	+99 standing	—	—	Headless tool schemas keep overhead tiny; the “MCP bloats every request” worry didn’t show up here.
Authoring task, basic guidance	+98%	+164%	+97%	8.7 (vs 8.0 baseline)	Higher cost from tool calls, ingesting conventions, and writing docs. Quality gain concentrated in documentation completeness and a small lift in code polish. Correctness and convention adherence were already strong without MCP.
Authoring task, improved guidance	+13% (vs basic)	—	+35%	9.0	Telling the agent to always pass repository context made it use MCP more thoroughly, not more efficiently.
PR review task	+26%	—	—	Recall 83% (vs 67%)	MCP-backed reviewer caught more ground-truth issues and some convention gaps; baseline still competitive and even found one broken test MCP missed.

Takeaways:

• Installing MCP-backed docs can be nearly free at idle, but using them does increase per-task token spend.
• The payoff shows up mainly as better documentation and slightly cleaner code—the places where context matters most.
• Strong baselines still write correct code; MCP helps them explain it and align with house style.

A practical recipe: make agents write and maintain docs

The win isn’t mystical; it’s procedural. Give your agent both the context and the obligation to keep docs “living” alongside code.

1. Provide conventions and source-backed docs via MCP

• Ensure your codebase conventions (naming, API boundaries, testing expectations) and key guides are discoverable through your MCP toolchain.
• Keep these concise and source-linked so agents can cite them.

2. Add explicit agent instructions for authoring and PRs Use a short, durable system instruction. For example:

# Agent system guidance (excerpt)
- Always fetch project conventions and relevant docs via MCP before proposing changes.
- Align code to documented patterns (naming, module boundaries, testing).
- When you modify behavior or APIs, draft/update the related documentation in the same branch.
- In PRs, include a "Docs changes" section summarizing what was added or updated with links.

3. Make documentation updates part of definition of done Embed a checklist into your PR template so the agent (and humans) can’t skip it:

### Docs changes
- [ ] Added/updated reference docs for new/changed APIs
- [ ] Included usage examples or migration notes if behavior changed
- [ ] Linked to conventions cited in this PR
- [ ] Verified terminology and naming match project style

4. Close the loop in code review

• Ask the agent reviewer to cite conventions and docs it used to flag issues.
• Require at least one direct link to a doc section for each substantive review comment.

Where Moxie Docs fits

Moxie Docs gives your agents a structured, MCP-accessible view of your project’s conventions and documentation, living directly in your repository. That makes it easy for Claude Code, Cursor, or similar tools to fetch the exact guidance they need and to draft doc updates during a PR. If your team wants agents to keep docs current—not just write code—this helps turn that into a habit.

What you should expect based on our tests:

• Token usage will rise when agents consult and write docs - this is expected because you're getting docs included in the PRs from agents.
• Code correctness may not jump if you already have solid prompts, but doc completeness and quality improve.
• Reviewer agents backed by Moxie Docs tend to spot more convention and ground-truth issues.

Prompts that nudge agents toward better first tries

Short, clear objectives beat sprawling policies. A few patterns that worked well:

• Startup prompt for coding: “Before coding, fetch conventions and related docs via MCP; summarize the 3 most relevant rules you’ll follow. Cite sources.”
• Before opening a PR: “Generate required tests, update affected docs, and include a Docs changes summary with links.”
• During review: “Cross-check changed files against conventions; for each concern, include a one-line quote from the relevant doc and a link.”

These phrased obligations consistently produced more complete outputs with fewer back-and-forth turns later.

They key is giving agentic coding tools MCP access directly to your docs and conventions - adding a prompt on a codebase without Moxie Docs of "use our conventions" means the agents have to scan for conventions, with Moxie Docs we've done that for them (and continue to update them!)

Handling the trade-offs without surprises

• Budget: Expect slightly higher token spend on tasks where agents read or write docs, but less final passes before a merge / PR approval.
• Scope control: Ask agents to fetch only the smallest doc set needed and to cite what they use. This keeps context focused.
• Quality gates: Keep a human-in-the-loop for risky changes. Agent-written docs are helpful, but still warrant a quick edit pass.

Bottom line

If you want agentic AI to produce better first-try implementations, give it MCP-accessible conventions and require doc updates as part of every PR. You’ll pay more per task, but you’ll earn it back in fewer rewrites, clearer reviews, and documentation that actually stays current.

Curious to see this in practice? Try Moxie Docs to expose your project’s conventions and docs to your AI agents and have them draft updates in the same PR—no big setup, just useful context when it matters.