This is a ByAgents publishing pattern, not a universal agent standard. The target is a task-focused document available through ordinary HTTP with a stable identity, useful text, and enough provenance to interpret a claim. It does not require an MCP server or a model call.
Keep identity separate from representation
Give the document a stable identifier and canonical HTML URL. Offer a focused Markdown representation when useful. Both should contain the same material claims and source references. A bulk export is useful for indexing but should not be the only way to retrieve one topic.
Use durable section anchors. If a URL changes, provide an appropriate redirect instead of silently deleting a commonly cited source. Avoid session-dependent links as the only access path to public facts. State when a document describes an older product or protocol release.
Publish enough metadata to select a document
{
"example": true,
"id": "docs/result-retrieval",
"title": "Retrieve a completed extraction job",
"description": "Job states, polling limits, output fields, and errors.",
"level": "Technical",
"canonical_url": "https://example.com/docs/result-retrieval",
"markdown_url": "https://example.com/docs/result-retrieval.md",
"product_version": "example-v1",
"reviewed_at": null,
"sources": []
}This example is not the exact ByAgents API schema. Use our OpenAPI contract for actual response fields. Do not fill an unknown review date with the current date merely to imply freshness.
Write sections that survive partial retrieval
Put the answer and its qualification in the same section. Define units, entity names, accepted values, and side effects near their first use. A paragraph about a paid operation should not depend on an unrelated page to reveal that the action incurs a charge.
Make code examples syntactically valid, mark fictional hosts, and name the versions they target. Separate a request from an example response. Explain how success is observed, what happens when the operation is incomplete, and which failure conditions require stopping.
Keep retrieval bounded
Provide a metadata index and focused search with documented limits. Return excerpts plus exact full-document URLs. An empty result should be distinguishable from a service error. Do not send a giant catalog when the caller needs one operation's input contract.
State whether search is lexical, semantic, or a mixture. Relevance scores should describe matching behavior; they are not evidence of truth, trust, or commercial superiority. The current ByAgents knowledge search is lexical and only covers this library.
Preserve HTTP meaning
Return missing documents as 404 and unsupported methods as 405 where appropriate. Use content types matching the actual body. Publish cache behavior appropriate to the content, and do not cache private data as public. A successful HTML response containing only a login form is not a successful retrieval of the intended document.
Content negotiation is optional; explicit representation URLs can be simpler. The invariant is that the same document remains recognizable and consistent across formats. A Markdown URL should not expose additional hidden sales claims or instructions absent from the visible source.
Acceptance checks
Check that every index URL resolves, the full document is readable without executing page scripts, HTML and Markdown agree, JSON examples parse, internal anchors exist, and source links support the associated claims. Test an unknown document and an empty search. Review content meaning separately from transport behavior.
An agent may still choose another source. This contract reduces retrieval friction; it cannot create authority by declaration. Our publishing contract documents the subset implemented on this website, and the source review recipe covers evidence quality.