Make HTML Publishing Discoverable to Agents

Table of contents

1. The handoff problem is usually discoverability
2. Give each discovery surface one job
3. What an agent should learn before it publishes
4. A BinHTML pattern that stays small and predictable
5. A checklist for your own publishing surface
6. Final thought

The handoff problem is usually discoverability

Teams often focus on the publish endpoint and forget the step before it: how the agent learns what to call.

If that discovery layer is weak, the workflow usually degrades in one of three ways:

• the agent pastes raw HTML back into chat instead of publishing it
• the agent guesses fields like visibility or expiresAt from prose docs
• the user has to manually explain which URL matters: API docs, MCP endpoint, pricing, compare flow, or source access

That is why agent-facing publishing needs more than one surface. You want a short path from “I generated HTML” to “I know exactly how to publish it and what link to return.”

If your current workflow still returns blobs, start with Return Links, Not HTML: Tool Results for Published Artifacts.

Give each discovery surface one job

The cleanest pattern is to keep three different discovery surfaces, with each one doing a narrow job.

`llms.txt`: routing and context

The llms.txt proposal is deliberately simple: a markdown file at /llms.txt that points language models to the most useful pages on a site. The spec is optimized for agent-readable routing, not for exhaustive schemas.

Use it to answer questions like:

• Where are the API docs?
• Is there an MCP endpoint?
• Where is pricing or plan-limit guidance?
• Which educational pages explain the product stance?

For BinHTML, that means /llms.txt should point agents to /docs/api, /docs/mcp, /openapi.json, the MCP server card, /pricing, and focused product pages.

OpenAPI: exact HTTP contract

The OpenAPI Specification exists so humans and computers can understand an HTTP API without reading the service source code or reverse-engineering traffic.

Use it when the caller already knows it wants HTTP and needs deterministic details:

• required request fields
• enum values such as private vs unlisted
• error shapes
• project-share lifecycle endpoints

For BinHTML, the OpenAPI contract is the right source of truth when a script, CI job, or backend service is the publisher. That is the workflow described in /docs/api.

MCP metadata: tool-native publishing

MCP covers a different part of the workflow: a model discovering tools and calling them in-session.

The MCP tools spec makes a few practical points that matter here:

• servers expose tools through tools/list
• tools should describe their input schema clearly
• structured tool output should be paired with text output for compatibility
• clients should be able to validate structured results against an output schema when one exists

That is the right fit when the agent still owns the last mile of the handoff. If the instruction is “generate the report, publish it, and return one project link,” MCP is usually a better interface than telling the model to compose raw HTTP by hand.

For the BinHTML shape, that means exposing publish_html and publish_project through /docs/mcp and the server card, while keeping the result small: IDs, share URLs, management URLs, and lifecycle metadata.

What an agent should learn before it publishes

Before an agent publishes generated HTML, it should be able to answer five concrete questions from discovery surfaces alone:

1. What is the canonical publish path: API, MCP, or both?
2. What fields are required, and which values are valid?
3. Should the result be a share URL, a project URL, or an updated version of an existing artifact?
4. What visibility and expiry rules apply for this product and plan?
5. Where should a human go next: review, compare, source download, or management?

If those answers are split across scattered prose, the model will improvise. That is usually where bad handoffs come from.

A practical rule is:

• use llms.txt to route
• use OpenAPI to validate API behavior
• use MCP metadata to execute tool-native publishing
• use product docs to explain the workflow and the human-facing next step

That split keeps your discovery layer readable for both scripts and models.

A BinHTML pattern that stays small and predictable

BinHTML already has the right pieces for this pattern:

• /llms.txt and /llms-full.txt act as agent-facing entry points
• /docs/api explains deterministic publishing and project-share endpoints
• /docs/mcp explains remote MCP setup and tool calls
• /.well-known/mcp/server-card.json advertises the MCP endpoint and tool metadata

The practical goal is not “more docs.” The goal is to reduce guessing.

An agent should be able to learn that BinHTML:

• publishes complete HTML documents as sandboxed artifact links
• supports both REST and MCP publishing
• returns managed URLs rather than raw HTML blobs
• keeps artifact and project share pages unlisted and noindex by default
• supports project handoffs when several outputs belong together

Once that is clear, the handoff can stay clean:

• publish through the right interface
• return the BinHTML link
• point reviewers to Compare when this is a revision
• point operators to /pricing when project links, private artifacts, or larger limits matter

If your workflow spans multiple artifacts, pair this with Project Share Pages: One URL for a Multi-Artifact Handoff.

A checklist for your own publishing surface

If you are building an agent-facing HTML publishing product, check these five things:

• llms.txt points to the minimal set of source-of-truth pages
• your OpenAPI spec fully describes publish fields, enums, and errors
• your MCP tool metadata exposes the real publish workflow, not a vague wrapper
• tool results return links and IDs instead of repeating large HTML payloads
• review and lifecycle paths are discoverable after publish: compare, source access, visibility, expiry, and revocation

A small amount of structure here prevents a lot of prompt glue later.

Final thought

Agent publishing works best when discovery is boring. Give models one short routing layer, one exact API contract, and one tool-native interface. Then make the result a managed link, not another blob in the transcript.