Give Your Artifact Publish Tool an Output Schema

Table of contents

1. Why the publish result needs a contract
2. The minimum useful shape for one artifact
3. Use the same pattern for project links and compare flows
4. Keep structured output small and safe
5. Final checklist

Why the publish result needs a contract

A publish tool sits at a boundary: the model is done generating HTML, and the next step is review, sharing, or revision. If that boundary returns a loose blob of fields, every client and prompt has to guess what matters.

The MCP spec now treats tool outputs as a first-class schema surface. Tools can declare an outputSchema, and when they do, servers must return structured results that match it. OpenAI's Apps SDK has also started recommending outputSchema for tools that return structured content.

That matters for BinHTML-style workflows because publishing is not the end of the task. The next agent or human still needs a clean handoff. They need a stable link, a title, a visibility state, and enough review metadata to know what to do next.

This is the same product stance behind MCP docs and API docs: publish the artifact once, then pass around the managed link.

The minimum useful shape for one artifact

For a single published artifact, keep the structured result boring and explicit.

A practical schema usually includes:

• artifactId for the system record
• url for the viewer link the user should open
• managementUrl for visibility, expiry, revocation, and source settings
• title for the published artifact name
• visibility for the current share mode
• expiresAt when the link is time-boxed
• sourceAvailable so reviewers know whether source inspection is possible
• compareUrl when the publish step created or updated a revision chain
• nextAction as one short sentence the agent can show directly

This is narrower than returning the whole publish payload from your backend. That is deliberate. The model needs the fields that drive the next action, not every storage detail.

If your current tool still returns raw markup or a giant unschematized JSON object, fix that first. The companion pattern is covered in Return Links, Not HTML: MCP Tool Results for Generated Artifacts.

Use the same pattern for project links and compare flows

The benefit gets bigger when one prompt publishes more than one thing.

If an agent creates a report, an appendix, and a dashboard, the tool result should still have one clear top-level handoff. Usually that means a project share URL plus a short list of included artifacts. Keep the shape consistent with single-artifact publishing so prompts do not need a different mental model.

A simple progression looks like this:

1. Publish each artifact.
2. Return one project link for the bundle.
3. Include optional compare metadata when the output is a revision rather than a first publish.

That plays well with BinHTML's project-link and review workflow. The user opens one share page, then drills into the artifact viewer or compare when they need to inspect a revision. If you need the broader bundle pattern, pair this post with Project Share Pages: One URL for a Multi-Artifact Handoff.

Keep structured output small and safe

Schema discipline is also a security and privacy decision.

OpenAI's MCP guidance warns against putting sensitive information in tool JSON, and the Apps SDK security guidance recommends including only the data required for the current prompt. That fits publishing tools well.

Good structured output should usually avoid:

• raw sourceHtml
• tokens, signed URLs, or bearer credentials
• large embedded source snapshots
• internal storage paths that are not useful to the reviewer

If reviewers need deeper provenance, give them a product surface for that instead of pushing everything into the tool result. In BinHTML terms, that usually means the viewer link, the management link, and explicit source-access controls. The deeper audit trail belongs in the published artifact workflow, not in every chat transcript. For that side of the handoff, see Source Access: The Audit Trail for AI-Generated HTML.

Final checklist

Before you ship a publish tool for generated HTML, check five things:

• The tool declares an outputSchema when it returns structured content.
• The result includes the viewer URL and the management URL as separate fields.
• The top-level shape works for both one artifact and a grouped project handoff.
• The result does not repeat raw HTML or sensitive data.
• The agent can turn the structured result into one short final message without custom parsing.

Final thought: the best artifact publishing tools are predictable. A clean outputSchema turns BinHTML links into a reusable handoff format instead of a one-off prompt trick.