Nutrition Labels for Software

Before you adopt a piece of software, you have a short list of questions. What is it built from? What can it do? What does it touch when it runs? The answers usually exist somewhere in manifests, READMEs, and source. These labels put them in one small file.

Take a tool you are about to let an agent use. Does it read files, change them, or send information anywhere? The ToolFacts label on one of our own tools answers in a few lines: no credentials required, no telemetry, no outside destinations. Most of its tools touch neither disk nor network. The widest-reaching one reads a single project tracking file. Read that, and the approval decision takes a minute instead of a source dive. That is what these labels are for.

The family started on July 31. That morning ModelFacts didn't exist. By lunch it had a spec, a schema, a validator, a generator, and a website, and by evening it had siblings with specs of their own. This post was written that week and expanded in September, once the labels were on the tools we ship. It's about the labels, and a little about how a day like that is possible now.

It started with AppFacts, our nutrition label for software. Package manifests are complete but noisy: full dependency trees, dev tooling, pinned versions, written for package managers rather than for a person getting their bearings. README tech-stack sections are the opposite problem, readable prose that goes stale the week after you write it. AppFacts sits between the two. One small file, YAML a machine can parse on top, a rendered label a human can read in a minute below.

Then we noticed the same problem wherever software gets adopted, always at the same moment: right when you have to decide whether to trust something. It shows up with an ordinary web app, and again at every layer of an AI system.

A product's feature list is written to sell, and it rarely separates what ships today from what is planned. Model cards already carry structured metadata and evaluation results in their front matter, and the prose below it can run thousands of words. What they don't give you is a compact, consistent adoption view: the same dozen facts, in the same places, for every model you're comparing, with the gaps marked. "Trained on the internet" is still not a fact. An MCP server you install today can read your disk and call home, and nothing requires it to say so in a form you can compare across servers. An agent acting on your behalf has some set of things it will do without asking, and good luck finding that list written down.

The family

So AppFacts got siblings. One label per question you have at adoption time. The family door is xfacts.dev.

AppFacts labels the body. What is this app built from?
ModelFacts labels the brain. What went into this model, what can it do out of the box, and how hot are its built-in filters?
ToolFacts labels the toolbelt. What does this instrument touch when invoked?
AgentFacts labels the hands. What may this actor do, and on what leash?
SkillFacts labels the playbook. What will this teach my agent to do?
FeatureFacts labels the terrain. What can this product do?

You don't need all six. AppFacts and FeatureFacts fit any app, AI or not. ToolFacts fits tools and integrations. ModelFacts, AgentFacts, and SkillFacts cover the AI layers when a system has them. A spreadsheet app with no model inside it needs two labels, and that is a complete set.

Every label follows the same two rules. First, facts and assessments stay distinct. A context window or a knowledge cutoff is a factual declaration. A qualitative rating, when a label includes one, is an assessment by whoever wrote the file. "This model is very creative" belongs in marketing copy unless the label marks it as an assessment and names the source. Second, when a fact isn't disclosed, the file says undisclosed, because the absence of a fact is itself a fact worth labeling. A comparison table where half of one column reads "undisclosed" tells you something no marketing page will.

The most interesting reader of these labels isn't a person. It's your agent's harness.

A label a human reads is documentation. A label software acts on is infrastructure. ToolFacts is designed so a harness can read a toolset's side-effect facts and set approval policy mechanically: wave through the read-only tools, gate the writes, always ask before anything destructive. That's the trajectory for the whole family. Each label starts as a disclosure and ends as an input to policy.

The step between those two needs a trust model, and the label doesn't supply it. A label is a claim by whoever wrote it. The MCP specification says the same thing about tool annotations: treat them as untrusted unless they come from a server you already trust. So a ToolFacts file discloses; your policy still needs a reason to believe the disclosure, whether that's the publisher's identity, your own review of the server, or a derived check against what the server actually exposes at the handshake. Our validator checks structure and allowed values. It does not certify that a label is true.

What we didn't label

A suite like this dies by sprawl, so there's an admission rule. A label earns a domain only if someone adopts a thing and needs to trust it at that moment, the essential facts are objective and mostly machine-derivable, and no existing format already answers the question. DataFacts fails the third test, since dataset labels have been tried and the ground is well covered. PromptFacts fails the second, because prompts are mostly judgment. Saying no is the same muscle as always.

Where the labels come from matters too. Our generators extract machine-readable fields directly where they exist: package metadata, model config, and for tools, what a server lists when you ask. The handshake is the inventory. Declarations a person writes name their sources and stay distinct from the extracted values. A human still has to classify reach and side effects. That classification is the label.

About that one day

I wrote recently that a weekend build is usually a demo, not a product. That still holds for anything that has to run unattended for paying users. Specs and validators are a gentler case: July 31 bought specs, schemas, working tooling, and a plan, and the months since went into putting labels on real tools and finding out which fields earned their place.

The day itself is the point of the fire essay made concrete. The loop between having an idea and holding a working artifact used to run in months. And the reason four labels came fast is the other essay: the what was settled before any building started. Every label is the same decision, applied to a new question. Once that's aligned, the hows get cheap.

Since then

I built the rest of the shop. A couple dozen tools, most of them public on the open-source shelf. They wear the labels.

AppFacts sits in the repo next to the README: ForgeTrail, Smell Check, FilePress, ollanet, LocalSlip, LocalHelm, and the rest of the shelf. ToolFacts sits on the MCP servers we actually run: ForgeTrail, ollanet, DictaWhisper. SkillFacts sits on the skills we publish, one file per package, not one file per product. TemperPass has four. DocuPuncture has three.

What is not next: a directory of every public agent, or another label that fails the admission rule. FeatureFacts cleared it. The question is what a product can do, the facts can be structured, and a file tree is not that answer.

Everything is open. The specs and schemas are CC0, the tooling is MIT, and the repos live on our GitHub. Adopt a label, or argue with a field. Do not send a new label unless it clears the three tests.

Notes for label maintainers

Each label site has a portable viewer. A /v URL carries a compressed card in the hash, so nothing is stored on our server and you can pass the link around. LocalHelm can show those cards on its Sites board, including which repo is missing a label. Panel, the derived tool-surface view, is on the hub. TOOL_FACTS.md stays the file you write.

Several of our tools were renamed: ForgeKit is now ForgeTrail, aiBreze is now Smell Check, and LocalBerth is now LocalSlip. A label that still carries the old name has drifted.

If it's worth adopting, it's worth labeling.