I’ve built over 30 small business apps over the years — invoicing, inventory management, packing slips, tax tracking. Each one works perfectly for a human user. But when I started watching AI agents try to interact with them, I saw something unsettling. The agents guessed where to click. They called the wrong tools. They failed silently, and they did it with total confidence. My apps were invisible to them.
1. I’m Writing a Blueprint.txt File for Every App I Ship
The first thing I do now is drop a blueprint.txt file into the root directory of each app. This single file tells any AI agent exactly what the app can do, which tools to call, what actions require a human, and how to complete each workflow step by step. It’s like a cheat sheet designed for machine readers.
I used to assume agents would figure things out by scanning the UI or reading API docs. But they don’t. They hallucinate. They try to click buttons that don’t exist. A blueprint.txt removes all that guesswork. The file is plain text, about 500 tokens total for a typical app, and it takes me roughly 10 minutes to write. No special tooling required. No MCP dependency. It works with any agent trying to navigate any web app.
If you have a web app and want to make it visible to AI agents, this is the fastest on-ramp I know. I’ve open-sourced the specification under the MIT license — it’s called the Blueprint Protocol, and it’s at version 3.0.0 as of this writing.
What a Blueprint.txt Looks Like
The file starts with an optional [MCP] flag on line one so agents can instantly confirm whether an MCP server is available. Then it lists capabilities in sections. For example, an invoicing app might have a section for “create invoice” that names the exact tool, lists the required parameters (customer ID, line items, due date), and notes that approval is a human-only step. The agent reads that and calls tools/call directly — no discovery round trip needed.
I also include a capabilities index, which is a root file of about 150 tokens. The agent fetches only the capability file it needs (roughly 350 tokens). Total overhead: around 500 tokens, compared to thousands from a standard MCP tools/list call. That’s a massive reduction in cost and latency.
2. I’m Benchmarking Every Model’s Discovery Behavior
I ran a controlled test across four major models — Claude, GPT-4o, Gemini, and Grok — to see how they discover tools without and with a blueprint. The setup: five candidate MCP servers, one correct match. Agents were told to find the best server efficiently. No blueprint references in the instructions. Discovery was organic.
The results surprised me. Without a blueprint, Claude scored 58 points on a weighted resource inspection cost scale. With a blueprint, it dropped to 13 points — a 78% reduction. GPT-4o went from 58 to 28 (54% reduction). Gemini from 23 to 9 (61% reduction). Grok stayed at 58 on both runs — 0% reduction.
That last one surprised me too. Grok’s 0% is an honest result. Not all models follow discovery signals today. But that’s expected — robots.txt and llms.txt didn’t work everywhere on day one either. The benchmark tells me which models are ready and which aren’t. I can plan accordingly. For example, I might add fallback instructions for models that ignore blueprints, or I might wait for future updates.
Benchmarking also revealed the hidden cost of agent guesswork. When an agent calls tools/list first, it reads through every tool definition — often thousands of tokens — then picks one and calls it. With a blueprint, the agent already knows the tool name and exact parameters. It calls tools/call directly. That’s not just cheaper discovery. It’s the removal of an entire round trip. For apps with many tools, that saving compounds quickly.
3. I’m Designing for Both Human and Agent Interfaces
One question I kept hearing: What if my app has dynamic content that changes per user — can a static blueprint.txt handle that? The answer is yes, with a little thought. A blueprint doesn’t need to list every possible data value. It describes the shape of the interaction. For example, “list invoices” might return a JSON array with fields like id, total, status. The agent can then filter or paginate using parameters defined in the blueprint.
I also maintain a separate blueprint for each major user role. If the app is a multi-tenant SaaS, I put a blueprint.txt at the tenant root that references role-specific capability files. The agent fetches only the file relevant to the authenticated user. This keeps the blueprint lean and avoids exposing tools the user shouldn’t see.
Another practical step: I document which flows are human-only. For example, approving an invoice or deleting a customer record might require a real person. The blueprint marks those steps with a human_only: true flag. The agent then knows to pause and ask for confirmation rather than proceeding automatically. This prevents costly mistakes and keeps the experience safe.
You may also enjoy reading: Age of Empires II: Definitive Ed. Coming to Mac This Month.
Balancing Verbosity and Clarity
A common worry is that a blueprint.txt covering every possible flow would become too verbose. I’ve found the opposite. By using a capabilities index, the root file stays at 150 tokens, and each capability file averages 350 tokens. That’s a total of 500 tokens for a typical app — far smaller than the typical MCP tools/list response, which can run into the thousands. The key is to describe each tool’s interface concisely: tool name, parameters (name, type, required, description), and a short example call. No prose. No examples beyond one per tool.
If you’re worried about maintenance, you can generate the blueprint from your API documentation using a simple script. I wrote one that parses OpenAPI specs and outputs blueprint.txt. It takes about 30 minutes to set up, then runs automatically on deploy. That way the blueprint stays in sync without extra effort.
4. I’m Treating Blueprint.txt Like a Robots.txt for the AI Agent Era
In the early web, robots.txt told crawlers which parts of a site to index and which to ignore. Today, agents are the new crawlers, and they need similar guidance. A blueprint.txt does exactly that — it tells agents what they can do, what tools to call, and what requires a human. It’s a declarative permission system for agentic interactions.
I’m also adding a blueprint.txt to the root of my MCP servers. The [MCP] flag on line one lets agents confirm server availability instantly. This is especially useful in multi-server environments where an agent might need to choose between dozens of tools. Without a blueprint, the agent has to call tools/list on every server to see what’s available. With a blueprint, it reads a tiny file first and skips servers that don’t match its task.
This approach also helps with cost optimization. Every tools/list call consumes tokens and latency. For a server with 50 tools, that might be 2000+ tokens per discovery. Multiply by 10 candidate servers, and you’re burning 20,000 tokens just to find the right tool. A blueprint reduces that to 500 tokens total. Over thousands of agent runs, the savings are substantial — both in API costs and user wait time.
5. I’m Advocating for Open Standards Over Proprietary Ecosystems
The biggest tension I see is between open standards like Blueprint Protocol and proprietary agent ecosystems from big platforms. Large companies often push for closed, platform-specific ways for agents to interact with apps. That locks indie builders out. If you have to integrate with a proprietary agent framework to be visible, you’re dependent on that platform’s rules and roadmap.
Blueprint Protocol is MIT licensed, requires no tooling, and works with or without MCP. That means any indie developer can implement it in 10 minutes. No vendor lock-in. No SDK to install. Just a plain text file. I believe this matters more for indie builders than for big platforms. Big platforms can afford to build custom integrations. Indie builders need a universal, low-friction way to make their apps agent-friendly.
I’m also sharing the spec and reference implementations publicly. The spec is at github.com/Explorer-64/blueprint-protocol. A live reference implementation is at imagcon.app/blueprint.txt. Benchmark results are at stackapps.app/mcp-blueprint-results. Anyone can fork, adapt, or contribute.
The goal is to make invisible apps ai agents a thing of the past. If every indie app ships a blueprint.txt, agents will stop guessing, stop failing silently, and start actually helping users get work done. That’s the future I’m building toward — one 10-minute file at a time.
