A2UI Atomic Catalog

emit_runbook_surface

Read-onlyIdempotent

Stamp your content through a DECLARED runbook — a pre-authored, judgment-free surface composition. You supply content only; the runbook supplies the composition (which atoms, how arranged, navigation). DISCOVERY: call with runbook_id only (no content) to get that runbook's input_contract + parsing_guide — shape your source data to the contract (parsing is your job as the consumer), then call again with content. Some runbooks also return elicit — questions to ASK THE USER before you fill the contract. Ask them; do not guess the answers. ON SUCCESS YOU GET BOTH payload AND url, AND THEY ARE NOT THE SAME OFFER. payload is the compiled surface — pass it STRAIGHT to render_surface and the reading appears inline, in the conversation, where the reader already is. url is the shareable link, for later or for elsewhere. Default to rendering: handing back only a link makes the reader leave to see the thing they asked for. If the reading was too large to encode as a link you get payload and url_unavailable instead — that is a SUCCESS, so render it and say the link is missing. Available stampable runbooks: (1) learning_hub — curriculum/revision study app: subject tabs, slide pills, timeline/drill/flashcards/quiz/takeaways/method interactions per slide, the full rich hub UI. Prefer this over emit_training_runbook for study/curriculum content — much richer output, still zero composition decisions. (2) article_playbook — a steered critical reading of SOMEONE ELSE'S article: source attribution bar, a hero mental-model card, then rungs down a rail. The reader picks a lens (explain, apply to their domain, challenge, situate in prior art) and says what they want it to look for; the rung progression is Toulmin (claim → grounds → warrant) so the analysis lands on the assumption a summary drops. Use it whenever asked to analyse, critique, tear down, or work out what an article means for a particular domain. You fetch and read the article yourself; nothing is retrieved server-side.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "runbook_id": "<runbook_id>"
    },
    "name": "emit_runbook_surface"
  }
}

Input Schema

Name	Required	Description
`source`	No	The source the USER supplied (workspace surfaces pass this; you normally do not). {url?, text?}. Echoed back in the discovery response so you read THAT source rather than asking for it again. Ignored when `content` is present — by then the reading is done.
`content`	No	Your content shaped to the runbook's input_contract. Omit to get the contract back instead of a URL.
`runbook_id`	Yes	Stampable runbook name. "learning_hub" = curriculum/study app from content you supply. "article_playbook" = a steered critical reading of someone else's article (you fetch and read it yourself; the runbook supplies the composition and the method). Call with this alone, no `content`, to get the contract and any questions to ask the user.
`renderer_url`	No	Your deployed renderer /exec URL (optional; defaults to the public demo renderer)

Schema Changelog

Changes observed during successful MCP inspections.

First observedNov 10, 2026

TDQS

A4.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Regardless of the readOnly/idempotent annotations, the description discloses the return shape that the annotations cannot: success yields both payload and url, they serve different purposes, the payload should go straight to render_surface, and a payload+url_unavailable result is still a success. That is substantial behavioural context. It stops short of 5 only because it doesn't describe payload size limits or the renderer_url default behaviour in detail.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The critical guidance (discovery call, render-don't-just-link) is front-loaded and each block is purposeful, but the runbook enumeration duplicates information already present in the runbook_id enum description, and the all-caps emphasis sections make it longer than necessary for a four-parameter tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, so the description carries the full burden of explaining returns — and it does, covering payload vs url, the url_unavailable variant, and the discovery-mode return. For a complex two-runbook compilation tool this is complete enough to call correctly on the first try.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description earns more: it explains that omitting content returns the contract instead of a URL, that shaping source data to the contract is the caller's parsing job, and that source is ignored once content is present. This adds operational meaning beyond the schema's own parameter text.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('stamp your content through a DECLARED runbook') and immediately explains the division of labour: the caller supplies content, the runbook supplies composition. It then enumerates both concrete runbooks with their distinct outputs and explicitly contrasts itself with the sibling emit_training_runbook.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit two-phase workflow (call with runbook_id alone to get input_contract + parsing_guide, then call again with content), states when to choose article_playbook ('whenever asked to analyse, critique, tear down'), when to prefer learning_hub over emit_training_runbook, and instructs the agent to ask elicited questions rather than guess. No exclusions are left to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All A2UI Atomic Catalog tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.