Best practice 5

Write documentation and data for agents

Practicepro·con

• Documentation, data, and metadata are now an interfaceInterfaceA component added to an agent's harness so it can reach a tool, data source, or action outside the model, for example an MCP server, a skill, or a plugin. An interface runs code and acts for the user, so it is where much of the risk enters, which is why interfaces are registered and vetted (see Register, vet, and manage agent interfaces)..3·0
  For

  • FAIR Guiding Principles (2016) machine-actionability as founding motivation
  • ELIXIR AI strategy (2026) §6 DOME/OSAI/FAIR reference framework for reusable data, software, models
  • Open and Sustainable AI in the life sciences (OSAI, 2025) openness and documentation that make data, software, models reusable per FAIR
  AgainstNone recorded
• An agentAgentA system built around a language model that carries out multi-step work: it plans, calls tools, reads the results, and decides what to do next. The model supplies the reasoning; the surrounding harness does the acting. Distinct from a chat model that answers one prompt at a time. operates a tool or dataset from its tool description / metadata, docstrings, and docs.4·0
  For

  • W3C DCAT version 3 (2024)
  • Croissant dataset metadata (2024)
  • Datasheets for Datasets (2021)
  • Model Cards for Model Reporting (2019)
  AgainstNone recorded
• User- and agent-facing documentation needs to be precise, current, and published in context with meaning and examples.
• Precise documentation helps human users and agents alike.

For practitionersFor providersFor governance

Write your code and notebooks as if an agent will re-run them; assume that one will. Put units, data versions, and assumptions in the docstring or close to the code. When a resource's documentation misleads your agent, raise the issue with the provider.

Treat docs, docstrings, tool descriptions, and metadata as an interface. Run examples and test them in CI so they cannot drift (e.g., using doctest). Publish data with schemas, controlled vocabularies, and machine-readable metadata, and give examples of how to query it.

Machine-readable documentation is cheap to check and more important than ever. Include it in resource review, and fund documentation and data meaning as essential interface work. Reward it when assessing any resource.

Reasons

Agents read documentation literally. What a human works out from context can send an agent the wrong way, and an out-of-date example can lead to silent failure, if it results in a plausible but wrong result. Data without stated meaning makes the agent guess at meaning and units. The FAIR principles aim at making data findable, accessible, interoperable, and reusable; this now applies to agents. A research agent that tracks a field is only as good as the metadata, citations, and retraction signals it can read. This work also benefits the people who use the resource directly, and current and future maintainers of the resource.

Examples

• A parameter is renamed but its docstring still shows the old name; a human reader infers the new one from context, while the agent calls it verbatim, the run fails, and a plausible but wrong number comes back.
• Examples in the documentation run as doctests in CI, so when the API changes a broken example fails the build and is fixed before it can mislead a human or an agent.
• A tool description gives only prose, with no parameter types, units, or valid ranges; the agent passes an out-of-range value and cannot interpret the error it gets back.
• A dataset is published with its meaning attached: a schema, controlled vocabularies, and machine-readable metadata including provenance and, where relevant, retraction status, so the agent does not have to guess at units or fields. General-purpose formats such as W3C DCAT, Croissant, datasheets, and model cards carry this; domain profiles such as Bioschemas (life sciences) are concrete instances of the same idea.
• A resource ships natural-language-to-query examples, for a query language such as SPARQL or Cypher, so an agent can turn a user's question into a correct query.
• The same documentation is offered in a form an agent can read directly (plain text, markdown, structured metadata), not only as a rendered web page. A convention like llms.txt is one proposed approach, not yet a ratified standard.

Sources

• ELIXIR TF Agentic AI: agenda and rolling best practice (2026), Best Practice items 3 and 5.
• Agentic AI in the higher-education system (2026), §3.3 (research-agent source requirements). Consistent with, grounding only.
• FAIR Guiding Principles (Wilkinson et al. 2016). Machine-actionability as the founding motivation; agents make it concrete.
• W3C DCAT v3 (2024), Croissant (MLCommons 2024), Datasheets for Datasets (Gebru et al. 2021), and Model Cards (Mitchell et al. 2019). Domain-neutral standards for machine-readable data and model documentation.

Change history

• 2026-07-27: Renumbered from BP04 to BP05 on inserting the new BP01 (match the method to the task).
• 2026-07-27: Rewrote Examples as concrete scenarios (actor, action, outcome), including anti-patterns; kept the labelled instances (DCAT, Croissant, datasheets, model cards, Bioschemas, llms.txt).
• 2026-07-26: Rewritten to be domain-neutral (FAIR, DCAT, Croissant, datasheets, and model cards as the general anchors; Bioschemas and SPARQL/Cypher demoted to labelled examples), to add tool descriptions alongside datasets, and to flag llms.txt as a proposed convention rather than a standard.
• 2026-07-25: Created from the ELIXIR TF distillation (hooks 4, 6), grounded in the HFD paper. Replaces the dummy BP0 on documentation and adds the data-and-examples dimension.

Discussion