MCP document generation with progressive discovery

Progressive discovery keeps an MCP document server small at the tool boundary without hiding the operations behind it. Runstamp exposes one list → describe → invoke path for operations and one list → describe → run path for reusable local-preview Document Jobs. This article analyzes that architecture. It does not report a tool-selection or token-use benchmark.

The design question is not “how many capabilities?”

An MCP client finds tools with tools/list and calls one with tools/call. The MCP tools specification requires every listed tool to have an input schema. That boundary is clean, but it leaves a design choice: expose every document operation as a top-level tool, or expose a smaller discovery interface that returns operation contracts on demand?

Those choices answer different questions.

• A large top-level catalog optimizes for direct discovery: the model can see each action immediately.
• A compact gateway optimizes for staged context: the model first narrows the operation, then loads only the selected schema.
• An imperative editing interface optimizes for fine-grained state changes: create a deck, add a slide, add a shape, and save.
• A declarative render interface optimizes for whole-document planning: validate one structured document request, then render it.

None of these interaction models wins by definition. The right choice depends on tool-selection accuracy, schema size, round trips, recoverability, authorization, and the amount of state the agent must maintain. Claims about one model using fewer tokens or selecting the right operation more often require an executed benchmark with pinned models, prompts, clients, catalogs, and scoring. Runstamp has not published that benchmark, so this analysis stays at the architectural level.

What progressive discovery means in Runstamp

Runstamp publishes six MCP tools in two progressive paths:

The repository-backed product boundary is explicit: every operation in the stable catalog is public GA through local packages, the SDK, CLI, MCP server, and authenticated Managed API. Platform review, approval, release, delivery, webhook, billing, usage, notification, and audit workflows are separately generally available through the authenticated control plane.

The intended sequence is therefore:

list(filter?)
  -> choose one descriptor
  -> describe(name)
  -> inspect availability + schema + error/loss vocabulary
  -> construct input
  -> invoke(name, input)
  -> branch on the structured result

The list step can be filtered by domain, verb, or availability. A PPTX request does not need the complete DOCX, XLSX, PDF, and common-operation schemas. The describe step returns the contract for the chosen operation. The invoke step resolves the binding again rather than trusting that an earlier list response is still current.

Why “list, describe, invoke” is more than a naming convention

The stages isolate three decisions that have different failure modes.

1. Selection

Selection asks which operation matches the user’s intent. The model should compare compact descriptors rather than infer an operation name from memory. A filter is useful only when it narrows the search without suppressing a relevant operation. When no descriptor fits, the correct outcome is to ask for clarification or report that the requested capability is absent.

2. Contract acquisition

Description asks what valid input looks like now. This is where the agent learns required fields, finite enums, resource constraints, declared errors, possible losses, and whether a local binding exists. Fetching the schema after selection reduces stale prompt examples: the runtime contract, not an article or model memory, is authoritative.

3. Execution

Invocation asks the runtime to perform one operation with the validated input. The server must resolve the named descriptor and binding, reject unknown fields where the schema is exact, preserve the operation-result envelope, and return typed errors for document conditions. A failed invocation should not cause the agent to invent another field or silently switch operations.

Separating these decisions makes logs easier to interpret. A bad selection is not a schema-validation failure. A valid schema for an unavailable operation is not an execution error. A runtime resource limit is not evidence that the operation was described incorrectly.

Progressive discovery does not remove MCP’s own tool list

The six Runstamp functions are still ordinary MCP tools. A client discovers them through MCP’s tools/list, and invokes them through tools/call. “Progressive” describes the two application protocols inside those tools: each path lists compact identities, expands one selected contract, and executes only that contract.

That distinction matters when evaluating context cost. A client still receives the schemas for the six gateway tools. The claimed savings, if any, would come from not registering every underlying operation and Job schema as a separate top-level tool. How much context this saves depends on the client’s schema serialization, caching, prompt construction, and the comparison catalog. It cannot be inferred from top-level tool counts alone.

A safe agent loop

The basic control loop should fail closed:

const listed = await callTool("runstamp_list_operations", {
  domain: "pptx",
  availability: "local",
});

const selected = selectOneDescriptor(listed);
if (!selected) return askForClarification();

const described = await callTool("runstamp_describe_operation", {
  name: selected.name,
});

if (!described.binding.available) {
  return reportUnavailable(described.binding.reason);
}

const input = buildInputFromSchema(described.inputSchema, userRequest);
const result = await callTool("runstamp_invoke_operation", {
  name: described.name,
  input,
});

return result.status === "ok"
  ? inspectArtifactAndLosses(result)
  : recoverFromTypedError(result.error);

This is illustrative pseudocode, not a copy-paste response type. The live contract returned by runstamp_describe_operation remains the source of truth.

Several safety properties follow from the loop:

• The operation name comes from the list response rather than free-form generation.
• The input is built after the full schema is retrieved.
• Availability is checked before invocation and enforced again by the server.
• Errors remain data the agent can branch on instead of prose it must parse.
• Losses remain visible even when an artifact is produced successfully.
• The artifact is inspected before a human or downstream system treats it as released.

Recovery belongs in the contract

Document generation can fail for deterministic reasons: invalid input, unsupported format details, missing assets, resource limits, a requested descriptor without a public binding, or a loss policy that rejects degraded output. An agent should not use the same retry behavior for all of them.

The last row is important. A successful file write is not necessarily faithful conversion. If a font was substituted, a macro dropped, or an unsupported element degraded, the agent needs a structured loss ledger. Otherwise “success” collapses operational completion and content fidelity into one ambiguous boolean.

Declarative and imperative document tools solve different jobs

A whole-document renderer is a good fit when the agent can express the intended artifact as structured data before execution. A sequence of editing tools can be better when the user is interactively modifying an existing file, needs application-native actions, or must inspect state between steps.

Progressive discovery also works with either style. A server could describe a declarative pptx.render contract, an imperative pptx.addShape contract, or both. The important architecture is staged schema loading and an explicit availability boundary, not a claim that every document workflow should be one call.

For Runstamp’s public local engines, the common path is declarative: select a format operation, load its exact contract, provide a complete structured input, and receive an operation result with artifact identity, diagnostics, losses, and a receipt. That design reduces hidden session state, but it does not eliminate review, application compatibility checks, or release controls.

How the missing benchmark should be run

A defensible progressive-discovery benchmark would compare at least two interfaces over the same underlying capabilities:

1. Catalogs: one top-level tool per operation versus a list/describe/invoke gateway.
2. Tasks: exact-match operation requests, ambiguous requests, unavailable operations, malformed inputs, and recovery cases.
3. Agents: pinned model, client, system prompt, temperature, tool-calling mode, and context policy.
4. Measures: tool-schema tokens actually delivered, correct operation selection, valid input on first attempt, total calls, recovery success, wall time, and final task correctness.
5. Controls: randomized operation names where semantics permit, distractor descriptors, repeated trials, and manual adjudication blind to interface.
6. Reporting: raw transcripts, catalog snapshots, scoring code, exclusions, failures, and confidence intervals.

The comparison must keep capability coverage constant. Comparing three gateway tools with dozens of unrelated tools would confound interaction design with catalog content. It must also score end-to-end correctness, not only prompt tokens: an interface that saves context but increases failed calls may be worse for the actual job.

Until such a corpus is executed and published, the bounded conclusion is architectural: progressive discovery postpones loading an underlying operation’s full schema until after selection. It is a design hypothesis for improving context and recovery, not measured proof of better agent performance.

Practical checklist

Use this checklist when designing any MCP document server:

• Keep descriptor identity separate from executable availability.
• Make selection, contract retrieval, and invocation observable as different events.
• Return exact schemas and reject unknown or stale fields.
• Use typed, stable error codes with retryability and remediation.
• Report fidelity losses separately from diagnostics and hard failures.
• Bind artifacts and receipts to exact bytes where the workflow requires provenance.
• Require inspection and approval before treating generated output as released.
• Benchmark with matched capabilities before claiming token, latency, or selection improvements.

Runstamp’s MCP package guide documents the current operation and Job paths. The JSON layer architecture explains the structured intermediate representation behind the render path, and the validation model defines the evidence boundary for format and application checks.