A Field Guide to AI Documentation: Model Cards, Eval Reports, Agent Cards, and More

Every developer learns the same documentation types. The README. The API reference. Code comments. Maybe an architecture doc if the team is disciplined. That was the whole vocabulary for decades.

Then AI arrived and quietly created an entire new category of documentation — one nobody taught us to write, that isn't in any bootcamp or CS degree, and that you're increasingly expected to produce anyway. Sometimes because a teammate needs it. Sometimes because an auditor does. And, as of 2026, sometimes because it's the law.

This is a field guide to that new landscape. I'll walk through the real doc types, grouped by what they document, with what each one is, when you need it, and why it exists. But first, the one idea that ties all of them together — because once you see it, every one of these makes sense.

Why AI needed new documentation at all

Here's the thing that broke.

For our entire careers, documentation described deterministic behavior. A function takes an input and returns the same output every time. You could document exactly what it does, because it does exactly one thing. The code itself was, in a sense, the ultimate documentation of what would happen.

AI shattered that assumption. A generative model can produce a different output for the same input twice in a row. An agent can take a path nobody wrote. You cannot document exact behavior for a system that doesn't behave the same way twice — so documentation had to shift from "what it does" to a different set of questions:

• What was it trained on?
• How did we measure it?
• What is it allowed to do?
• What did it actually do?

Every doc type below is an answer to one of those four questions. They aren't paperwork — they're trust artifacts. In a deterministic world, trust came for free from the code. In a probabilistic world, trust has to be manufactured through documentation, because it's the only way anyone — a teammate, an auditor, a regulator, a user — can believe your AI does what you claim. Keep that in mind and the whole landscape organizes itself.

Group 1: Documenting the model and the data

These are the foundational ones — the docs that describe the ingredients of an AI system.

Model cards

What it is: A short, structured document describing a single trained model — its intended use, the data it was trained on, its evaluation results, its limitations, and its out-of-scope uses. Think of it as a nutrition label for a model: at a glance, what's in it and what it's safe for.

When you need it: Any time you ship, publish, or hand off a model someone else will rely on. Introduced by Mitchell et al. in 2019, model cards are now standard on model hubs like Hugging Face — and under the EU AI Act, they (or an equivalent) are a regulatory requirement for high-risk systems. If you fine-tune a model and give it to another team, they need a model card to use it responsibly.

Why it exists: Because "here's a model, good luck" is how you get someone deploying a system into a context it was never meant for. The model card answers what is this model, really, and where should it not be used — the questions the weights themselves can't tell you.

Datasheets for datasets

What it is: The data-side twin of the model card. A structured document describing a dataset — where it came from, how it was collected, its composition, its known biases, consent and licensing, and what it should and shouldn't be used for. Introduced by Gebru et al. (2018/2021).

When you need it: Whenever a dataset outlives the person who made it — which is always. If your model's behavior is ever questioned, the first question is "what was it trained on?", and a datasheet is the answer you'll wish you'd written at the time.

Why it exists: Because most AI failures trace back to the data, and data provenance is almost never obvious after the fact. A datasheet forces the dataset's creators to be intentional and honest about its origins and limits — before those limits become someone's incident.

System cards

What it is: A step up from a model card. Where a model card documents one trained model, a system card documents the complete AI system — often a pipeline of multiple models, plus architecture, safety evaluations, operational constraints, and deployment context. Crucially, a system card documents how the system behaves, not how it's used (that's the difference from traditional product docs).

When you need it: When your AI isn't one model but a stack — a router, a fine-tune, retrieval, chained components (which, in 2026, is most real systems). Frontier labs publish system cards for their big models (the GPT system cards are the canonical examples) precisely because "the model" is really a system.

Why it exists: Because modern AI is rarely a single model, and documenting only the model misses everything that emerges from the combination. The system card is where a forward-deployment engineer figures out whether the whole thing fits their use case.

Group 2: Documenting the evaluation

This is the newest and most underrated genre — and arguably the most important, because it's where trust is actually earned or faked.

Eval reports (eval factsheets)

What it is: Documentation of how you evaluated an AI system and what you found — the test set, the methodology, the assumptions behind the metrics, and how confident you should be in the results. "Eval factsheets" formalize this with the same rigor datasheets brought to data.

When you need it: Any time you make a claim about how well an AI performs — which is any time you ship one. Especially critical for agents and anything customer-facing.

Why it exists: Here's the sharp insight that justifies the whole genre. A model card gives you the score, but not how the score was obtained — and the "how" is the part that tells you whether to trust it. "95% accuracy" means nothing until you know on what data, under what conditions, with what definition of correct. Eval reports document the methodology, not just the number. A benchmark result with no eval report is a marketing claim, not evidence.

Regression evals and benchmark cards

What it is: Two close relatives. A regression eval is documentation of the tests you re-run to make sure a model or prompt change didn't quietly break behavior that used to work (the AI-era version of a regression test suite). A benchmark card documents the benchmark itself — what it actually measures, its limitations, how to read its scores — so people stop treating a leaderboard number as gospel.

When you need it: Regression evals the moment you're changing a model or prompt in production. Benchmark cards whenever you publish or cite a benchmark.

Why it exists: Because AI systems drift, and "it worked before" isn't verifiable without a documented, repeatable eval — and because raw benchmark numbers, undocumented, mislead more than they inform.

Group 3: Documenting the agents

Brand new territory, and the most relevant to anyone building right now. Until recently there was no analog to model cards for agents. In 2026, that changed.

Agent cards

What it is: A 2026 documentation standard for operational AI agents. Where a model card describes a model, an agent card captures an agent's operational attributes: its roles, its memory taxonomy, its tool integrations, its communication protocols, its monitoring hooks, its governance scope, and its evaluation metrics.

When you need it: When you deploy an agent that acts — calls tools, touches data, runs unattended. Anyone who has to operate, audit, or trust that agent needs to know what it can reach and how it's monitored.

Why it exists: Because an agent is a fundamentally different thing to document than a model — it acts, it has memory, it uses tools, it runs over time. Model cards and datasheets couldn't capture any of that, so a new artifact had to fill the gap. The agent card is how you make an acting system transparent, comparable, and auditable.

Policy cards

What it is: Machine-readable runtime governance for autonomous agents — documentation of what an agent is allowed to do, in a form that can actually be enforced while it runs, not just read by a human afterward.

When you need it: For any agent with real permissions — one that can send, spend, delete, or change things. This is the formalized version of a principle worth repeating: for a system that acts unpredictably, you can't document what it will do, so you document what it's allowed to do.

Why it exists: Because with agents, the interesting failure isn't "wrong output," it's "unsanctioned action." A policy card turns the boundaries into an artifact — ideally one the runtime checks — so an agent's permissions are explicit, auditable, and enforced instead of living in someone's head.

AGENTS.md / CLAUDE.md

What it is: The practical, in-the-repo instruction files that coding agents actually read — project conventions, constraints, architecture notes, and rules written for the AI to follow while working in your codebase.

When you need it: The moment you let an AI agent work in your repo. Without one, the agent improvises conventions; with one, it follows yours.

Why it exists: Because the agent is now a reader of your documentation — and it will faithfully do the wrong thing if you never wrote down the right thing. This is the doc type where "documentation" and "programming the AI" quietly merge.

Group 4: Documenting for governance and compliance

Rising fast, driven by regulation — and increasingly not optional.

Audit trails

What it is: An immutable, append-only record of every consequential model or agent decision in a production system — used as evidence for compliance, audits, and incident investigation.

When you need it: Any production AI that makes decisions with consequences. When something goes wrong (and it will), the audit trail is how you reconstruct what actually happened.

Why it exists: Because for a system that acts, the log is the documentation of what it did — and "what did it actually do?" is unanswerable without a durable, tamper-evident record. It's the fourth of our four questions, made concrete.

Compliance cards, AI cards, and transparency reports

What it is: A family of governance documents — compliance cards / AI cards (machine-readable risk and compliance documentation inspired by the EU AI Act), use case cards (documenting a specific deployment's intended use and risk), and transparency reports (public-facing accounts of what a system does and its limitations).

When you need it: When you operate under a regulatory regime — which is a rapidly growing "when." The EU AI Act mandates documentation for high-risk systems, and Singapore's Model AI Governance Framework for Agentic AI (launched January 2026) is the first framework explicitly requiring autonomous-AI documentation: risk assessments, limits on agent authority, human accountability at critical decision points.

Why it exists: Because AI documentation stopped being a nice-to-have and became a legal artifact. Governance without documentation is just a promise, and regulators have stopped accepting promises.

The idea that ties it all together

Step back and look at the whole map, and the pattern is unmistakable.

Model cards and datasheets answer what was it trained on? Eval reports answer how did we measure it? Agent cards and policy cards answer what is it allowed to do? Audit trails answer what did it actually do? Every single one of these documents exists because AI broke the thing that used to make documentation easy: determinism. When a system won't behave the same way twice, you can't document its behavior — so you document its ingredients, its measurement, its boundaries, and its history instead.

That's why these aren't bureaucracy, even though they can feel like it. They're trust artifacts. In the old world, the code told you what would happen, so trust was free. In this world, trust has to be built, deliberately, in writing — because a model card is how a teammate trusts your fine-tune, an eval report is how a reviewer trusts your accuracy claim, a policy card is how an operator trusts your agent near production, and an audit trail is how an investigator trusts your account of an incident.

The takeaway

Nobody taught us to write these. There was no reason to — until the systems we build stopped being predictable, and "read the code" stopped being a sufficient answer to "what does this do?"

The developers who thrive in this era won't just be the ones who can build AI systems. They'll be the ones who can make those systems trustworthy to everyone else — and increasingly, that's a documentation skill. It's an oddly human one, too: judgment about what to disclose, honesty about how you measured, clarity about where you drew the boundary. The machine can help you write these. It can't decide what belongs in them. That part is still yours.

So the next time you ship something with a model in it, ask the question we were never trained to ask: not just "does it work?" but "could anyone else tell that it works, and where it doesn't, from what I wrote down?" That question, and the docs that answer it, are the quiet infrastructure the whole AI era is going to run on.

Which of these have you actually had to write — and, honestly, which did you not know existed until just now? I'd genuinely like to know where the real practice is, versus where the standards say it should be. And if there's a doc type you're using that I left off the map, add it below.

Sources & further reading: Model Cards (Mitchell et al., 2019); Datasheets for Datasets (Gebru et al., 2018/2021); System Cards (frontier-lab system cards, e.g. OpenAI's GPT system cards); Eval Factsheets and BenchmarkCards (2025–2026 evaluation-documentation research); Agent Cards and Policy Cards (2025–2026 agent-documentation standards); and governance frameworks including the EU AI Act and Singapore's Model AI Governance Framework for Agentic AI (Jan 2026). Standards in this space are evolving quickly — treat specifics as current-as-of-writing and check primary sources for the latest.