docs: add creative agent setup verification

[sangilish]

Summary

• add a deployment-checklist assertion for non-empty creative.supported_formats
• document a vendor-neutral MCP get_adcp_capabilities connectivity probe
• show the canonical format declaration shape buyers should expect

Why

Creative-agent implementers and buyers have no runnable setup check in the deployment guide. The new probe verifies endpoint reachability and the canonical creative-format discovery surface without depending on a specific vendor or the deprecated list_creative_formats discovery path.

Closes #5877.

Validation

• node tests/snippet-validation.test.cjs --file docs/creative/implementing-creative-agents.mdx
• node tests/docs-nav-validation.test.cjs
• npm run check:seo (passed with existing repository warnings)
• git diff --check

No changeset: documentation-only, non-normative addition.

[aao-secretariat]

⚠️ Argus review could not complete

The automated review encountered an issue (possibly reached max turns, timed out, or failed to post the final gh pr review). A human reviewer should take this PR.

View workflow run

_{This is an automated message from the Argus AI review workflow.}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 089723774b

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[bokelley]

The new capability probe and example match the 3.1 schema, but this same deployment checklist still says list_creative_formats must return all formats four lines later. That contradicts this PR’s stated goal and the canonical-format docs, where creative.supported_formats replaces the deprecated discovery surface. Please replace that checklist item with something like: creative.supported_formats includes every format the agent offers for discovery. With that stale requirement removed, this looks ready.

[bokelley]

One additional blocker from the full audit: the raw curl example calls tools/call before MCP initialize / notifications/initialized and never propagates Mcp-Session-Id. A compliant stateful MCP endpoint may correctly reject this probe even when the creative agent is healthy. Please either use a lifecycle-aware MCP client in the runnable check or show the complete handshake and session-header propagation. The readiness result must not classify a compliant stateful server as unreachable.

[bokelley]

Fixed in 0935944. The accordion now does the full MCP lifecycle before calling tools/call:

1. initialize — POSTs to establish a session and captures Mcp-Session-Id from the response headers
2. notifications/initialized — sent with the session header (required by the MCP spec before any tool call)
3. tools/call for get_adcp_capabilities — sent with the session header propagated

The session header is only added when the server returns one ([ -n "$SESSION_ID" ] && HEADERS+=(...)), so the probe also works correctly against stateless servers. A compliant stateful server will no longer be falsely classified as unreachable.

---

Generated by Claude Code

[aao-secretariat]

⚠️ Argus review could not complete

The automated review encountered an issue (possibly reached max turns, timed out, or failed to post the final gh pr review). A human reviewer should take this PR.

View workflow run

_{This is an automated message from the Argus AI review workflow.}

[bokelley]

Re-reviewed the refreshed diff. The deployment checklist now uses creative.supported_formats instead of the deprecated list_creative_formats requirement, and the runnable probe now performs the MCP initialize/initialized handshake and carries Mcp-Session-Id before tools/call. Both requested corrections are present; checks are green.

[aao-secretariat]

Clean, accurate docs addition. The verification probe teaches the sanctioned discovery path — creative.supported_formats on get_adcp_capabilities — not the deprecated one, which is the right shape.

Things I checked

• Wire shape matches schema. The example payload (creative.supported_formats[].capability_id + format with format_kind/params) matches get-adcp-capabilities-response.json:1045-1060 exactly: capability_id optional, format required, ProductFormatDeclaration shape. No drift.
• Request envelope is correct. The probe sends adcp_version: "3.1" (release-precision) plus adcp_major_version: 3 (integer). version-envelope.json:8-24 — buyers SHOULD emit both through 3.x; adcp_major_version is deprecated but honored until 4.0. Sending both is the documented correct behavior, not redundancy.
• protocols: ["creative"] is a valid request enum value (get-adcp-capabilities-request.json:22).
• Deprecation claim is accurate. canonical-formats-migration.mdx:202 — list_creative_formats is uniformly deprecated; :207 names creative.supported_formats as the creative-agent replacement. Replacing the checklist line and citing the deprecated path in the PR body is consistent with established precedent, not a fresh assertion.
• MCP lifecycle in the probe is correct. initialize → capture Mcp-Session-Id → notifications/initialized (no id, correct for a JSON-RPC notification) → tools/call. The [ -n "$SESSION_ID" ] guard handles stateless servers that omit the session header — fail-safe for both server modes.
• No changeset needed. Touches docs/creative/**, not docs/reference/** or static/schemas/source/** — not wire-touching. Author's "no changeset: documentation-only" call is right.
• Test plan is honest. Validation bullets (snippet-validation on this file, docs-nav, SEO, git diff --check) cover the added bash/JSON blocks; no unchecked manual-verification items.

Minor nits (non-blocking)

1. Linked anchor. The prose links [canonical format declaration](/docs/creative/canonical-formats); the deep migration detail (identical supported_formats excerpt) lives in canonical-formats-migration.mdx. Both pages exist, so this is fine — a pointer to the migration page might save an implementer a hop, but not worth a revision.

LGTM.

[bokelley]

Re-approval after updating onto current main: the requested creative.supported_formats checklist correction and MCP initialize/session handshake remain intact.