This is part of our ongoing exploration of ECA's evolution, "ECA: The Next Chapter". Earlier posts covered the journey from Vienna to Athens, the Modeler API, in-context customization, the new Workflow Modeler, test, replay and debug, and where ECA, FlowDrop and Maestro fit together. This post is about documentation that machines read: the ECA Guide, the MCP server, and the AI agent skill.

I watched an AI agent read a page about token syntax this morning. The one I wrote months ago explaining the difference between [event:user:mail] and - the page humans skip because they already think they understand tokens, then get the prefix wrong anyway.

The agent read every word. Built a working model on the first try.

I have written documentation since 1989. Thirty-seven years. It is how I got into IT - I did not own a personal computer before that job. My first task was writing software documentation, and I have not stopped since.

All of it for humans. I assumed they would read it, understand it, apply it. That assumption was generous. Most humans skim. Many skip entirely. Some read carefully, then forget the details.

Machines do not skim.

The documentation challenge nobody talks about

ECA has 1,206 plugins. Not a typo. 266 events, 94 conditions, 846 actions.

Each one needs documentation. What it does, when to use it, what tokens it provides, what configuration it requires. Multiply by 1,206. Add conceptual pages explaining how the pieces fit together - token syntax, model structure, testing patterns, best practices.

Nobody memorizes 1,206 plugins. You learn the twenty you use most, search for the rest. If the documentation is good, you find answers. If not, you ask in Slack or give up.

The ECA Guide is not new. The first commit landed January 20, 2022, more than four years ago. What we did last year was overhaul it. Comprehensive coverage - all events, conditions, actions. Tutorials. Examples. Interactive models embedded via the standalone viewer from Post 4. The Guide grew from helpful reference into something close to complete.

Then the documentation stopped being only for humans.

What changed

Late 2025, someone asked: "Could an AI agent help users build ECA models?"

Interesting question. AI agents are good at translation - natural language to code, English to automation. But they need knowledge. Context. Understanding of what ECA is, what plugins exist, how tokens work.

They need documentation.

We made the ECA Guide machine-readable. Not as an afterthought. As infrastructure.

Three access methods that exist today:

1. MCP server at https://ecaguide.org/mcp

Model Context Protocol server. Public. Three tools:

• search_docs(query, top_k) - BM25 keyword search across all documentation, ranked results with excerpts
• get_page(path) - read a specific page by path, like eca/concepts/events/index.md
• list_sections() - the documentation index of all sections and pages

Point an AI agent at that URL. It has the full Guide as queryable context.

2. llms.txt at https://ecaguide.org/llms.txt

Structured index of all pages with descriptions - the llms.txt standard. Browse the index, fetch what you need.

Also https://ecaguide.org/llms-full.txt - complete documentation in one file, about 151,000 words. Use llms.txt to discover what exists, then fetch specific pages or read it all if your context window fits.

Honesty check: most agents and LLMs do not use the llms.txt standard yet. Adoption is early. But the dog food is in the bowl and waiting. The day they learn how tasty it is, the Guide is already served.

3. Clean Markdown for any page

Add the Markdown filename to any page URL. Most pages live at index.md, so https://ecaguide.org/eca/concepts/events/ becomes https://ecaguide.org/eca/concepts/events/index.md - raw Markdown, no HTML wrapper, no navigation. Just content.

The complete plugin reference lives at https://ecaguide.org/plugins/ - all 1,206 plugins, auto-generated, each with its own page.

The AI agent skill

We packaged this into an ECA agent skill. Not specific to one AI platform - a pattern any agent can use.

Find it at https://ecaguide.org/.well-known/skills/. That .well-known path is another standard we leaned on, the same convention browsers and services use to discover things at predictable locations. An agent does not need to be told where our skill lives. It looks where the standard says to look.

The skill tells an agent how to reach ecaguide.org, which MCP tools are available, how to access pages as Markdown, and core ECA concepts to understand models.

An AI agent with this skill can explain ECA concepts, analyze an existing model and suggest improvements, or build a model from a natural-language description.

That last one is the lightning moment.

What this looks like in practice

I open an AI agent. Point it at ecaguide.org via MCP. Describe a workflow in plain English:

"When a content item is published, send the author an email with a link to the published page."

The agent reads the documentation. Searches for "content insert event." Finds presave and insert events for content. Reads both. Decides insert is more appropriate - we want to act after the entity is written, not before.

Searches for "send email action." Finds "Send email" (action_send_email_action). Reads the page. Sees it needs a recipient, subject, and body. Notes it can use tokens.

Searches for "entity tokens." Finds token documentation explaining the saved content is available as [node:...], and how to reach the author's email through it. Reads the bracket syntax page that explains when you need the event prefix.

Builds the model. Three nodes: one event, one action. Token references correct on the first try.

I used to get that syntax wrong myself - before I wrote the documentation page explaining why it matters. The agent read that page, absorbed the lesson, applied it correctly.

The documentation I wrote for humans is now read more thoroughly by machines. I can prove it with numbers.

The machines already showed up

I checked the analytics for the last six months. Two sources: the human-facing Guide and the MCP server.

Humans: about 11,400 visits, roughly 17,300 page views.

Machines through the MCP server: about 244,000 visits and 734,000 page reads.

Around 21 times more visits and 42 times more page reads from machines than from humans. In six months. I did not advertise the MCP server - mentioned it in a few places, put it on the Guide. The machines found it and got to work.

Two honest caveats. Machine traffic includes crawling and indexing, not only careful model-building. And a "page read" by an agent is not the same as a human sitting down to learn. But the direction is unmistakable. What I built for people is now consumed mostly by software. This is both funny and useful.

What this means for different groups

End users: Ask an AI for help with ECA. It has the full Guide as context. Stuck on a model? Describe what you want. The agent reads the docs you would have skipped and builds a working starting point.

Drupal ecosystem: Documentation becomes infrastructure - not just reference material, but machine-readable knowledge AI agents consume and act on. Lowers the barrier to entry dramatically. Views, Layout Builder, Commerce could all copy this pattern. Drupal becomes AI-native, not AI-adjacent.

Developers: AI pair programming for automation. Describe the workflow, AI builds the model, you refine it. The agent reads documentation you do not have time to read and surfaces relevant pieces when you need them.

AI and agent developers: The MCP server pattern and agent-skill pattern are reusable. Study how the ECA MCP server works, build similar servers for your complex systems. The pattern works for any domain where visual configuration needs AI assistance.

ECA's own AI integration

Worth noting: ECA itself has AI integration plugins. The ai_integration_eca and ai_integration_eca_agents modules. An "AI: Trigger Agent" action. An "ECA Tool" event. A "Set tool output" action.

ECA can be driven by AI agents and expose itself as tools to AI agents. The Guide makes that documentation accessible. Loop closes nicely.

Not overclaiming. These are tools you can use today if you have the AI integration modules enabled. The point is the symmetry - agents can build ECA models, and ECA models can invoke agents.

The pattern others should copy

This is bigger than ECA.

Drupal has many complex configuration systems. Views. Layout Builder. Workflows. Permissions. Commerce. All powerful, all have learning curves, all rely on documentation humans may or may not read.

The pattern:

1. Write comprehensive documentation (you should do this anyway)
2. Make it machine-readable (MCP server, llms.txt, clean Markdown endpoints)
3. Create an agent skill packaging access patterns and core concepts
4. AI agents can now help users configure your system

Documentation stops being only reference material. It becomes infrastructure.

Investment in good documentation multiplies impact. Every doc page becomes training data. Quality compounds when machines can read and apply it.

The funding note nobody wants to write

Writing and maintaining 1,206 plugin pages plus concept documentation is unglamorous work. Mostly unpaid. Few notice until something is missing or wrong.

Now demonstrably force-multiplied because AI agents consume it. Still unglamorous. Still mostly unpaid. But the impact is visible - agents build working models because documentation exists and is accurate.

Documentation is invisible work that multiplies impact. Worth saying out loud.

What comes next

This is early. The MCP server works. The agent skill exists. Agents can build models from natural language today. We are learning what patterns work best.

So far, this AI help lives outside Drupal. You need your own agent, your own client software, your own setup. Fine for technical users. A wall for everyone else.

The plan is to bring AI assistants into the new Workflow Modeler from Post 4, right in the UI. Describe what you want in the modeler, get a model back, refine it on the canvas. Ask the assistant why a node is there, or how to add a condition, without leaving the screen you are working in. The same Guide, the same MCP server, the same skill - now reachable from the place where you build models. In context, where Post 3 argued ECA needs to be.

Questions we are exploring: How much context does an agent need to build good models? All 151K words? Just relevant pages? Can agents suggest model improvements by analyzing structure and comparing against best practices? Can agents help maintain documentation by detecting gaps when they fail to answer questions? How do we keep documentation and code in sync as ECA evolves?

The foundation is solid. Improvements will make it more powerful.

The bigger picture

Documentation is evolving into something new. Not replacing the human use case - people still need to learn ECA, read tutorials, understand concepts. But adding a machine use case that was not imaginable five years ago.

AI agents read differently than humans. They do not skim, skip pages they think they understand, forget details, or get impatient.

They also do not have intuition. Cannot infer unstated assumptions. Will confidently apply what they read, whether right or wrong. Quality matters more, not less.

Writing documentation knowing machines will read it changes nothing about what you write - still clear explanations, accurate examples, comprehensive coverage. But it reframes why it matters.

The page you write helps a human today. Tomorrow it helps an agent help a hundred humans. Investment compounds.

Try it yourself

The ECA Guide is public. The MCP server is public. The agent skill pattern is documented.

If you use AI agents in your workflow, point one at ecaguide.org. Ask it to explain an ECA concept or build a model. Watch it read documentation and apply what it learns.

If you build AI agents, study the MCP server implementation. The pattern works for any domain with comprehensive documentation and complex configuration.

If you maintain a Drupal module with complex config, consider this pattern. Your documentation could be infrastructure too.

If you find documentation gaps - places where you or an agent could not find the answer - tell us. Documentation improves when we know what is missing.

Join Drupal Slack #eca-next-gen. Try the AI assistance. Contribute to the Guide. Report documentation gaps. Help us figure out what this new documentation-as-infrastructure pattern should look like.

The machines are reading. We should make sure they read something good.