Prompts Describe Behavior. Software Guarantees It.
Why we moved 9,238 lines of testing expertise out of prompts and into an MCP server — and what the launch of periscope-mcp says about where agent knowledge should live.
Every AI agent session ends the same way: everything the agent figured out dies with the context window. The industry's default answer is to write it down — longer system prompts, bigger instruction files, another paragraph of "remember to check X before Y." We think that answer draws the line in the wrong place, and we just launched a project that draws it differently.
periscope-mcp is an open-source MCP server that gives AI agents 74 Playwright tools to QA, test, and analyze web apps. This post isn't a feature tour. It's about the one idea the whole project is built on:
Prompts describe behavior. Software guarantees it.
Advice vs. guarantee
A prompt is advice. It costs context tokens every single session, it depends on the model executing it faithfully every single time, and it has nowhere to keep state between calls. Ask an agent to "check WCAG contrast ratios" in a prompt and you get a plausible number — computed slightly differently each run, by a language model doing math in its head.
Software is a guarantee. Periscope's check_color_contrast tool returns the
same ratio every run, because it's arithmetic in code, not a vibe in context.
Its INP measurement comes from a real PerformanceObserver reading actual
Event Timing entries — something you cannot prompt a model into doing, because
the capability has to live inside the browser, before the page's own scripts
load.
That's the dividing line: the more deterministic, stateful, and regression-tested a capability becomes, the less it belongs in a prompt and the more it belongs in code.
The 36:1 ratio
Periscope makes the split measurable. The server is 9,238 lines of
executable knowledge — the WCAG math, the crawler, the auth-expiry
detection, the overlay-intercept click fallback, the network-mock engine, the
per-interaction INP time series. Sitting on top is a 254-line agent guide
(AGENTS.md) that an agent reads once per session.
Roughly 36 lines of guarantee for every line of advice. And the advice layer only contains what genuinely belongs in language: when to force a click, what order to arm a network wait, what to tell the user when an update needs a restart. Judgment stays in the prompt. Execution moves into code — where it costs zero context, runs identically every time, and remembers.
Try to express periscope as a prompt and the problem is obvious: you'd be
pasting thousands of lines of "please do this correctly from a description"
into every session, paying for them in tokens each time, and hoping the model
performs them without variance. There is no prompt long enough to be a
PerformanceObserver.
Knowledge that compounds instead of evaporating
Here's the part we didn't fully appreciate until we lived it. Periscope was hardened by pointing a second AI agent at it and having it test real, authenticated production apps. Every piece of friction that agent hit became a GitHub issue — 19 so far, every one closed with a fix and a regression test, verified by a CI suite that drives a real browser (102 tests at the time of writing).
Compare the two ways a lesson can be preserved:
- As a prompt, the lesson is another paragraph every future agent must read, spend tokens on, and hopefully obey. It can be skimmed, misweighted, or contradicted by the next paragraph.
- As code, the lesson is enforced. When the test agent discovered that Radix UI portal overlays silently swallow ~30% of clicks, the fix became an automatic fallback inside the click tool itself — plus a test that fails if it ever regresses. No future agent needs to know the lesson exists. It just stops being possible to hit the bug.
Prompts transfer knowledge. Servers preserve it. One erodes with every session; the other compounds with every fix.
What this doesn't mean
This isn't a claim that every MCP server needs thousands of lines of logic. Transport adapters — thin servers that standardize access to many systems behind one protocol — are legitimate and useful; a common interface is real value even when little logic lives behind it. (Credit where due: an early draft of this argument dismissed them, and a third AI agent reviewing our README talked us out of it.)
The claim is narrower and sharper: when a capability needs to be correct, repeatable, or stateful, putting it in a prompt is a category error. Testing is the perfect example — a QA verdict that varies run-to-run isn't a verdict at all.
Built honest, because agents can't squint
One design consequence of taking guarantees seriously: the tools refuse to
lie. A drag-and-drop that silently did nothing comes back flagged, with the
recovery path spelled out. An expired session names why it's gone. A
self-update reports restart_required: true instead of pretending new code is
already running. At the end of a run, a session_report tool renders every
tool call — arguments, verdicts, timings, screenshots — into an HTML+PDF
dossier a human can review.
Deterministic tools that report honestly turn an agent from a plausible narrator into something you can actually trust with QA.
Get it
Periscope is open source under AGPL-3.0 and works with any MCP client — Claude Code, Codex, Cursor, Windsurf, or your own agent:
git clone https://github.com/segentic-lab/periscope-mcp && cd periscope-mcp && ./install.sh
The repo ships with the AGENTS.md judgment layer to paste into your agent's
system prompt, and a describe_tools catalog the agent can query on its own.
More of our open-source work lives at lab.segentic.dev.
One last piece of provenance, because it's the thesis in miniature: this project was co-developed by one AI agent, battle-tested by a second, and its README was edited on the advice of a third. The knowledge they generated didn't end with their sessions. It's in the code now — guaranteed.