# Jellybox WebMCP Framework Specification

## Version 1.0 — Standalone Core

**Author:** Press Rogers  
**Version:** 1.0  
**Profile:** `standalone-core`  
**Published:** 7 November 2026  
**Editorial revision:** 8 November 2026

### Purpose

The Jellybox WebMCP Framework provides a common model and interface for a website’s agent-facing space. A **Jellybox** is that space, accessible through WebMCP. The framework describes it in terms of contexts and actions and specifies eight tools for working within it.

WebMCP supplies the ability to expose and call website tools. The framework adds consistent organisation, discovery and execution rules. An agent can use the same eight-tool vocabulary across websites while learning each site’s capabilities from its readme and action descriptions. A website’s agent-facing space can exist without following these rules; an implementation adopts them to provide the interface defined here.

### What this specification defines

Version 1.0 defines the framework’s terms, the eight-tool interface, the shapes of its inputs and results, and the behaviour an implementation must provide. Contexts, actions and application data remain specific to each website.

Tool results identify `protocolVersion: "1.0"`. A conforming implementation identifies `interfaceEdition: "1.0"` and `interfaceProfile: "standalone-core"` in its introduction. A website’s application version is separate from the framework version.

### How to read it

The [framework explanation](#framework) introduces the model in plain language. The numbered chapters below define the requirements. The [implementation guide](#creator-guide) explains how to apply them; the [reference files](#downloads) supply the schemas, registration manifest and checklist.

The [website implementation status](#compatibility) describes this site’s component separately. Publishing or reading this specification does not certify a runtime. This specification and its associated schemas are available under the [MIT License](/downloads/LICENSE).

## 1. Scope

This specification defines the Standalone Core profile of the Jellybox WebMCP Framework: its model of contexts, actions and views, its eight-tool interface, and its interaction and execution rules.

The eight framework tools are the required core. A website may also expose additional WebMCP tools with its own descriptions, inputs and results.

The framework applies to the agent-facing space already available when a website exposes tools through WebMCP. It does not introduce agent access itself. Adopting the framework gives that access a consistent structure and contract.

A context selects the agent’s place of work. A view identifies a human-facing page or presentation. Context selection and view navigation are independent. Actions connect to the website’s own information and application logic.

WebMCP calls execute through the browser’s tool mechanism. Context selection, discovery and other operations can run in page JavaScript. An operation contacts a backend only when its implementation needs one. WebMCP’s browser mechanism and the framework’s application-level rules have distinct responsibilities. See the [WebMCP documentation](https://developer.chrome.com/docs/ai/webmcp/imperative-api).

Standalone Core prescribes no application framework, database, hosting service, visual design or agent provider. It requires no central registration or hosted Jellybox account. The website remains responsible for authentication, business rules, persistence and its human interface.

## 2. Conventions and normative material

**MUST**, **MUST NOT**, **SHOULD**, **SHOULD NOT** and **MAY** express the requirement levels defined by BCP 14. Lowercase usage has its ordinary meaning. [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119.html) and [RFC 8174](https://www.rfc-editor.org/rfc/rfc8174.html)

Sections 1–11 and the input schemas, output contract, registration manifest and action conventions are normative. Section 12 and the appendices explain their use. Reader summaries and navigation do not add requirements. Appendix A lists the published files and their roles.

Inputs and results use JSON-compatible values. Action schemas use JSON Schema 2020-12 and the portable profile in Section 6.9. Schemas check structure; the accompanying tool contracts define the required behaviour. [JSON Schema 2020-12](https://json-schema.org/draft/2020-12)

The eight tool input schemas define the Version 1.0 input contract. Unknown fields in closed tool arguments, references and bindings MUST be rejected. Each action’s schema governs the contents of `parameters`.

Clients MUST tolerate unfamiliar optional output metadata. Additional execution requirements MUST be declared in the action descriptor’s `extensions` array. A client MUST NOT execute an action with an unsupported required extension. Optional metadata MUST NOT conceal requirements or change core field meanings.

## 3. Conceptual model

### 3.1 The space and the framework

A **Jellybox** is the agent-facing space of a website, accessible through WebMCP. The term identifies the website as it is available to an agent through its tools. It does not imply a second website, a copy of its data or a separate server.

The **Jellybox WebMCP Framework** provides the model, terminology and interface rules for organising that space. WebMCP makes website tools callable; the framework specifies a consistent way to discover work, understand it and carry it out.

A website can expose WebMCP tools without adopting the framework. The requirements below apply when an implementation provides the framework’s interface.

### 3.2 Contexts, actions and views

A **context** groups information and actions for a particular place of work. It often serves as the agent’s virtual equivalent of a page. One context may correspond to one visible webpage; a small site may offer all its useful work in a single home context. The framework also permits contexts that combine material from several pages or have no dedicated visible page.

An **action** is a website-defined operation available in a context. It can read information, calculate a result or change application state. Its description explains its parameters, results, effects and conditions. Availability can change as the website’s state or the caller’s permissions change.

A **view** is a human-facing presentation or route. Several views can share a context; a view can show information from several contexts. These mappings are authored by the website. A URL is not automatically a context reference, and a context hierarchy is optional.

### 3.3 Learning and using a Jellybox

`readme` introduces the particular website’s Jellybox. It explains the useful areas, how to find work and the limits of the interaction. `list_contexts` discovers contexts; `list_actions` discovers their current capabilities; `describe_actions` returns the contracts needed to use them.

These descriptions give the agent information it can use during the task. It can reuse that knowledge while it remains valid and refresh the relevant description or state when it changes.

The surrounding chat carries the person’s instructions and the agent’s replies. That collaboration is not a capability created by the framework. The framework defines the agent’s interaction with the website.

### 3.4 Independent selection and presentation

Each **interaction** has an `interactionId`, its own selected context and a selection revision. The human-facing view is tracked separately. Independent interactions MUST NOT share a mutable selection pointer.

Entering a context MUST NOT navigate the person’s page. Human navigation MUST NOT silently change an interaction’s selected context. Reading an introduction, inspecting another context or describing an action MUST NOT select it or perform its business operations.

`navigate_to_view` deliberately changes the human-facing view. It preserves the agent’s selection by default; adopting the view’s default context is a separate, guarded option. An action can update information visible in the current view without navigating it. Other presentation effects MUST be declared, and execution MUST NOT silently retarget the interaction.

### 3.5 The eight-tool interface

| Tool | Responsibility |
| --- | --- |
| `readme` | Introduce the Jellybox and start or resume an interaction. |
| `current_context` | Report the selected context and human-facing view. |
| `list_contexts` | Discover contexts without entering them. |
| `enter_context` | Select the agent’s place of work. |
| `list_actions` | Discover actions in a context. |
| `describe_actions` | Obtain complete action contracts and bindings. |
| `perform_action` | Execute a described action. |
| `navigate_to_view` | Deliberately show a human-facing view. |

Capabilities offered through the framework MUST be exposed as actions through this interface. Additional capabilities do not add a ninth framework tool. Other WebMCP tools MAY coexist, but MUST NOT be required to complete a workflow offered through the framework.

### 3.6 Execution vocabulary

| Term | Meaning |
| --- | --- |
| Host | The website code that provides the interface and enforces its rules; it may use local JavaScript and backend services. |
| Target | The particular Jellybox and runtime instance to which a reference belongs. |
| Reference | An exact identifier returned by the host for a context, action or view. |
| Binding | The execution coordinates and revisions returned with an action description. |
| Precondition | An application revision that must still match before an operation runs. |
| Receipt | The retained state or outcome of a request carrying an identity. |

A reference or binding identifies work; it does not grant permission. The website checks authority when the operation runs.

## 4. Identifiers, references and bindings

Identifiers and revision tokens defined by the public input schemas are non-empty strings of at most 512 characters. They are opaque and case-sensitive. Clients MUST preserve returned values rather than construct them from labels, URLs or assumed numbering.

### 4.1 Target

A standalone target contains these three fields. The values below illustrate the shape; clients use references returned by the host:

```json
{
  "kind": "jellybox",
  "id": "site-main",
  "instanceId": "instance-7"
}
```

`id` identifies the environment; `instanceId` identifies the runtime scope in which its references, interactions and receipts are meaningful. A matching `id` alone does not establish the same target.

A host MUST reject references belonging to an unsupported or different instance. It MUST issue a new instance identity when it cannot preserve the state needed to honour the previous instance’s references and retry guarantees.

The target schema also accepts `kind: "jellyhub"`, reserved for hosting integrations. Standalone Core does not require a Jellyhub or define multi-target hosting behaviour. A Standalone Core implementation MAY reject a Jellyhub request as unavailable.

### 4.2 Entity reference

Contexts, actions and views use the same reference shape:

```json
{
  "target": {
    "kind": "jellybox",
    "id": "site-main",
    "instanceId": "instance-7"
  },
  "entityId": "context:home"
}
```

The term `entityId` denotes a referenced item; it does not require an entity-based application architecture. The invoked tool determines the required reference type. A context reference MUST NOT be accepted as a view reference merely because its identifier exists.

The input schemas also permit an aspect reference, consisting of an entity reference plus `aspectId`, for revision preconditions. An implementation without aspect support MUST reject such a precondition rather than disregard it.

### 4.3 Revisions and binding

`selectionRevision` identifies the interaction’s selection state. `descriptorRevision` identifies the action contract evaluated in that context. Content revisions identify application data. These are distinct tokens and MUST NOT be treated as interchangeable.

For Standalone Core actions, the binding MUST contain `target`, `contextRef`, `selectionRevision` and `descriptorRevision`. The input schema’s structurally optional context fields are therefore semantically required by this profile.

A binding MAY also contain `capabilityUse` and `capabilityUseRevision`, identifying a host-defined capability-use record and its revision. When returned, both MUST be preserved and validated. A capability reference is not a substitute for authorization.

Clients MUST return the complete binding from `describe_actions` without alteration. Hosts MUST validate it against the exact action, target, context and selection before execution. They MUST NOT substitute the current visible view or silently redirect an outdated binding.

## 5. Interaction state and results

### 5.1 Interaction lifetime

Calling `readme` without `interactionId` creates an interaction with a documented initial context. Supplying an existing identifier resumes that interaction without changing its valid selection.

An interaction identifier correlates state; it is not proof of identity or permission. Hosts MUST bind interactions to the appropriate browser or authenticated security scope. Independent interactions MUST NOT share a mutable selection pointer.

When a selected context disappears or becomes unusable, the host MUST invalidate its old selection. It MAY select a documented fallback or return an unavailable-context state. Invalidation MUST advance `selectionRevision`, including when the resulting `contextRef` is null. Any fallback MUST be reported in subsequent context state. Previously prepared bindings MUST NOT execute in the fallback context.

The host MUST disclose interaction lifetime, persistence and receipt-retention guarantees through the typed `readme.data.lifecycle` object. Its idle and maximum lifetimes are positive whole seconds or null for no configured timeout. An authorized, public-shape-valid call resets the idle timer; rejected authentication and malformed requests do not. The maximum lifetime is measured from creation and never extended. Logout, explicit invalidation and runtime disposal may end the security or runtime scope earlier. Both persistence flags cover interactions, references, revisions and all receipt reservations/outcomes together; they MUST NOT claim preservation of only part of that state. Recovery after reload, restart or disconnection MUST NOT be implied unless the necessary interaction, revision and receipt state is actually preserved.

### 5.2 Common result envelope

Whenever a tool callback produces a Jellybox result, that result contains `protocolVersion`, `status`, `data` and `effects`. It MUST also include the resolved `target` when known, the valid `interactionId` and `context` when available, and the accepted `requestId` when applicable.

A context state contains `contextRef`, `selectionRevision`, `viewRef`, `defaultViewRef`, `presentationRevision` and `unavailableReason`. `unavailableReason` is null for a selected context, and a `{code, message}` reason when `contextRef` is null. `selectionRevision` remains a nonempty token in the null state; `defaultViewRef` is then null. References to absent contexts or views are `null`; a valid selected context has a non-null `contextRef`. `viewRef` describes the current presentation route, not proof that every pixel has rendered. `defaultViewRef` describes the selected context’s default view, which may differ from `viewRef`.

| Field | Meaning |
| --- | --- |
| `protocolVersion` | The interface version, `"1.0"`. |
| `status` | The operation outcome listed below. |
| `target`, `interactionId` | The resolved runtime and valid interaction, when known. |
| `context` | The corresponding selection and presentation observation, when available. |
| `data` | The tool’s result, or `null` when no successful result is supplied. |
| `effects` | Truthful reports of known changes and uncertainty. |
| `requestId`, `receipt` | The accepted identity and retained execution state, when applicable. |

The output contract defines the complete combinations for each tool and outcome. A small envelope example is not a substitute for those schemas.

| Status | Meaning |
| --- | --- |
| `completed` | The operation reached its declared completion condition. |
| `rejected` | Validation, authorization or a precondition prevented execution. |
| `cancelled` | Cancellation was confirmed before the requested operation applied effects. |
| `failed` | The call did not return a successful action result. For an interim running/unresolved receipt this does not mean the underlying operation failed; inspect `receipt.state` and `error.code`. Otherwise execution or output delivery failed with the reported known outcome. |

Every non-completed result MUST include `error.code` and `error.message`. It MUST accurately report known effects and uncertainty. An empty `effects` array on a failed response is not evidence of rollback.

An effect report identifies its `scope`, affected `refs`, `outcome` and known `revisions`. Core outcomes are `applied`, `not_applied` and `unknown`. A revision entry uses `{ "ref": ..., "revision": ... }`. No completed result may describe an unperformed effect as applied.

A receipt-bearing response includes `requestId` and `receipt: { "state": "running" | "unresolved" | "terminal" }`. These fields apply only to accepted `perform_action` identities. Terminal receipts contain no `unknown` effect outcomes. Rejected or confirmed-cancelled results MUST NOT report applied effects. Completed results MUST NOT report unknown effects. A replayed terminal receipt describes the original operation, including its original context snapshot. Clients needing current state MUST call `current_context`; they MUST NOT interpret an old receipt as a fresh observation.

## 6. Tool contracts

All optional-input defaults below are semantic defaults. They need not be inserted into the caller’s JSON object. Hosts MUST validate the public tool schema before processing its request.

### 6.1 `readme`

**Purpose:** Introduce the environment and establish or resume an interaction.

**Required input:** None.  
**Optional input:** `interactionId`, `target`, `topics`.

Omitted `target` addresses the local application. `active_jellybox` is a bootstrap selector; the response MUST resolve it to an exact target. In a standalone application it refers to that application’s Jellybox. Exact returned target references are also accepted. A `jellyhub` selector MAY be rejected by a standalone host.

With no `interactionId`, the host MUST create an independently selected interaction. With a valid existing identifier, it MUST preserve that interaction’s valid selection, including when returning introductory material. An expired identifier MUST produce `invalid_interaction`, not silently create a replacement interaction.

The returned `data` MUST contain `name`, application `version`, `interfaceEdition: "1.0"`, `interfaceProfile: "standalone-core"`, the eight tool-name strings in `tools`, `guidance`, `lifecycle` and `views`. The output schema fixes their structure. The introduction SHOULD begin with a concise, useful account of this website’s space: the work it supports, its main contexts and the next appropriate discovery steps. It MAY return a topic index and provide longer guidance only when requested. A small space does not need a large catalogue or a long introduction. Guidance contains the text fields `contexts`, `actions`, `presentation`, `unavailable` and `lifetime`. Lifecycle contains `interactionLifetime`, `preservesAcrossReload`, `preservesAcrossRestart`, `receiptRetention: "interaction-lifetime"`, `initialContextRef` and `fallbackContextRef`. A null fallback means that invalidation leaves an unavailable selection. The view catalogue follows Section 6.10. Guidance MUST identify how to discover contexts, describe and execute actions, navigate views, handle unavailable capabilities, and understand state lifetime and persistence. It SHOULD explain how the operations relate to the website’s normal pages and application state. Descriptions teach the agent; they do not create executable capabilities or grant authority. `topics`, an array of at most 20 strings, requests focused guidance; unsupported topics MUST NOT be represented as supported capabilities.

`readme` MUST NOT execute business actions, navigate a view or obtain additional permissions merely by being read.

### 6.2 `current_context`

**Purpose:** Report the interaction’s selection separately from the human-facing presentation.

**Required input:** `interactionId`.

The result’s `data` MUST contain the context state defined in Section 5.2. The same observation MUST be used for the envelope’s `context`; the two MUST NOT contradict each other.

This operation MUST NOT change a valid selection, invoke an action or navigate the presentation. Reconciliation of an invalidated selection is governed by Section 5.1.

With no usable selection, this tool still completes with the explicit null-context state and its reason. `list_contexts` and explicit-context inspection remain available as authorized; operations requiring a selected context reject with `not_available`. The returned selection revision is the token used for subsequent guarded selection changes. It is not an application-content revision.

### 6.3 `list_contexts`

**Purpose:** Discover contexts without selecting one.

**Required input:** `interactionId`.  
**Optional input:** `target`, `mode`, `cursor`, `limit`.

Omitted `target` uses the interaction’s target. `mode` defaults to `available`; `discoverable` additionally includes unavailable contexts whose existence the caller is permitted to know. `limit` defaults to 50 and MUST be an integer from 1 to 100. An omitted or null cursor starts a new enumeration.

The result’s `data` contains `items` and `nextCursor`. Each context item MUST include `ref`, `title`, `revision` and `availability`. It SHOULD include a description and MUST provide `viewRef` when a default view is available. Absence of a default view MUST NOT imply that the context is unavailable. A context item's `revision` versions its discoverable summary and availability metadata; it MUST NOT be advertised as a content revision unless the application explicitly identifies the same revision domain.

Availability contains `available` and `reasons`. Each reason contains `code` and `message`; unavailable discoverable entries MUST have at least one reason. Hidden contexts MUST NOT be disclosed merely because `discoverable` was requested.

The operation MUST NOT enter a context or navigate a view. Pagination requirements are defined in Section 7.1.

### 6.4 `enter_context`

**Purpose:** Explicitly select an available context for this interaction.

**Required input:** `interactionId`, `contextRef`, `expectedSelectionRevision`.

The host MUST validate the reference’s target and type, context availability, caller authorization and the expected selection revision. Selection checking and replacement MUST form one atomic operation.

A mismatch MUST return `stale_context` without applying the requested selection change. Success MUST select the requested context, issue a fresh selection revision and return the resulting context state. Every accepted entry issues a fresh revision, including deliberate re-entry into the same context. Successful `data` is the resulting context-state object, identical to the envelope's `context` observation.

This operation MUST NOT navigate the human-facing view or change another interaction’s selection. Merely entering a context MUST NOT execute that context’s business actions.

### 6.5 `list_actions`

**Purpose:** Discover action summaries for a context.

**Required input:** `interactionId`.  
**Optional input:** `contextRef`, `target`, `mode`, `cursor`, `limit`.

With no `contextRef`, the selected context is inspected. An explicit context reference requests inspection only: the host MUST NOT adopt it as the interaction’s selected context. An explicit target MUST be consistent with the context reference and supported runtime scope.

Mode, limit and cursor defaults are the same as for `list_contexts`. The result’s `data` contains `items` and `nextCursor`. Each action summary MUST include `ref`, `revision`, `title`, `summary` and `availability`.

An action summary's `revision` is the descriptor revision for that action evaluated in the inspected context. The host MUST evaluate availability against the inspected context and current caller permissions. An action’s availability in one context does not imply availability in another.

Listing is not a substitute for description. Before executing an action inspected in another context, the client MUST enter that context and obtain a binding there through `describe_actions`.

### 6.6 `describe_actions`

**Purpose:** Return complete contracts for named actions in the selected context.

**Required input:** `interactionId`, `actionRefs`.

`actionRefs` MUST contain between 1 and 20 exact action references. The result’s `data.actions` MUST preserve request order and contain one descriptor for each requested reference. Repeated references retain their corresponding positions.

A reference that is unknown, wrongly targeted or not disclosable MUST reject the request rather than silently disappear from the result. A known, disclosable but unavailable action MUST be described with `availability.available: false` and an explanation.

#### The action contract

Every descriptor MUST supply the concrete fields defined by the output schemas:

| Field | Required meaning |
| --- | --- |
| `ref`, `revision`, `operation.id` | Action reference, descriptor revision and application operation identifier. `revision` equals `binding.descriptorRevision`. |
| `title`, `description` | Purpose, behavior and important limits. |
| `inputSchema`, `outputSchema` | Self-contained schemas for the parameter object and completed action `data`. |
| `availability` | Boolean, reasons and `basis` containing the exact context reference, selection revision and descriptor revision used for this description. |
| `binding` | Exact input-compatible execution binding for the selected context. |
| `effects` | Array of possible effect declarations, each with `scope`, affected `refs` when knowable, and `description`. |
| `preconditions` | The typed none, fixed or resolved contract defined below. |
| `coordinates` | Identifier-bearing schema locations, each with `schemaPointer`, `kind`, `scope` and `description`. |
| `completion` | `condition`, `persistence`, `description` and nullable `verificationActionRef`. |
| `atomicity` | `atomic` or `best-effort`. |
| `retry` | Object with `policy: idempotent` or `request-id-required`. |
| `concurrency` | A declared `strategy` and precise `description`. |
| `authorization` | `confirmation: none`, `possible` or `required`, plus a description of the authority enforced by the host. |
| `extensions` | An array of `{id, required, data}` records; an empty array means no declared extensions. |

#### References and effects

All core references in a Standalone Core descriptor, including action, binding, context, availability basis, capability use, effect subjects, precondition subjects, resolver and verification action references, MUST belong to the descriptor binding's exact target instance. Application data describing external systems must not masquerade as a cross-target core reference.

Core effect scopes are `application`, `selection`, `presentation` and `external`. A possible effect whose target depends on parameters MAY have an empty declared `refs` array, but its description and coordinates MUST explain what may be affected. Actual effect reports use the same scopes plus `outcome` and known `revisions`. Bookkeeping of the interaction and its receipts is not an application business effect.

`coordinates.schemaPointer` is a JSON Pointer into the supplied `inputSchema`, not into a particular parameter instance. It identifies the schema node describing the relevant reference or opaque identifier, including nodes inside array items. Its `kind` and `scope` use the output schema's fixed vocabulary. The pointer MUST resolve through recognized 2020-12 subschema locations, not merely to an object or Boolean. Locations within const, enum, default, examples or other instance/annotation data are not schema nodes. Descriptions MUST explain narrower application-specific scope. An action with no identifier parameters uses an empty array.

#### Preconditions

Preconditions have exactly one mode:

- `none`: `checks` is empty and `resolverActionRef` is null. No application revision checks are required, though the host still validates binding, authority and all additional supported checks the caller supplies.
- `fixed`: `checks` contains the exact required current `{ref, revision}` checks and `resolverActionRef` is null. The caller returns all required checks in `perform_action.preconditions`.
- `resolved`: `checks` is empty and `resolverActionRef` identifies an action available in this selected context. The resolver inputSchema MUST be structurally identical to the primary action's inputSchema, ignoring object member ordering. It accepts the same intended parameter object without coercion, and completes with `{preconditions: [...]}`. Its output follows `action-conventions.json`. It MUST be effect-free, use `retry.policy: idempotent`, require no application preconditions and not depend on another resolver. A primary action MUST NOT name itself as its resolver; resolver references MUST resolve to an available descriptor in this same context and target. Resolver cycles are forbidden. The client describes and invokes it through the ordinary tools, then supplies its checks to the primary action. The primary action independently enforces the required checks; resolver output is not authority.

Every required check MUST be supplied, including its expected token, before effects. Missing required checks reject with `precondition_required`; mismatched supplied current tokens reject with `stale_revision`. The maximum remains 100 checks. Checks whose revisions become stale between discovery and execution reject safely rather than being refreshed implicitly.

#### Completion, retries and extensions

Completion condition `returned` means a read/result is available; `committed` means the declared operation has applied; `submitted` means work was accepted, not finished. Submitted work MUST expose a `verificationActionRef` inspectable in the submitting action’s context. Submitted data MUST return a stable job or operation reference, and the verification action descriptor MUST explain how that reference is supplied to inspect the work. Persistence is `none`, `instance` or `durable`: respectively no persistent application state, retained only within the declared runtime scope, or committed to storage intended to survive runtime disposal. The description MUST state any material limits; durable does not claim infallible external infrastructure.

Concurrency strategies are `serialized`, `precondition-checked`, `snapshot` and `best-effort`. The description MUST specify the actual scope and guarantees. These declarations do not weaken required atomic validation, binding checks or deduplication. `idempotent` applies only to effect-free actions with an empty effects declaration; every action with possible business or external effects uses `request-id-required`.

An extension identifier MUST be unique within the descriptor. A client MUST NOT execute when it does not implement an extension whose `required` value is true. Optional unfamiliar extensions and ordinary extra metadata may be ignored. Extension data MUST NOT silently replace a core field, add echoed binding fields or weaken core guarantees.

Descriptor revisions MUST change when a contract change could invalidate a prepared invocation, including changed schemas, required preconditions, effects, confirmation requirements or required extensions. Describing an action MUST NOT execute it, select another context or grant permission.

### 6.7 `perform_action`

**Purpose:** Execute one described action against its explicit binding.

**Required input:** `interactionId`, `actionRef`, `binding`, `parameters`.  
**Optional input:** `requestId`, `preconditions`.

`parameters` MUST be an object valid against the action's described input schema and portable schema profile. Missing standalone binding context/selection fields reject with `invalid_request`; a supplied but outdated binding rejects with `stale_binding`. `preconditions` MAY contain up to 100 revision checks, each identifying a subject and expected revision. Unsupported preconditions MUST be rejected rather than ignored.

#### Validation and execution

Before effects are applied, the host MUST validate the interaction’s security scope, action and target references, binding, availability, authorization, parameter schema and every required precondition. Validation and execution MUST be coordinated so a concurrent change cannot bypass those checks.

A stale binding or content revision MUST cause rejection, not automatic reinterpretation under new state. If an action requires human confirmation, the host MUST obtain that confirmation through an appropriate trusted mechanism before applying the protected effect.

Actions that mutate application state or initiate external effects MUST require `requestId` and advertise `retry.policy: "request-id-required"`. Idempotent, effect-free reads MAY omit it. The exact retry and receipt rules in Section 7.2 apply.

#### Results

Only a `status: completed` action result MUST contain `data` satisfying the advertised `outputSchema`, together with truthful actual effect reports. If the operation applied but its action output fails validation or cannot be represented, return `status: failed`, `error.code: output_validation_failed`, `data: null` and known applied effects. An accepted identity records this as a terminal receipt only when all effect outcomes are established; it MUST NOT repeat the write. If any effect outcome remains unknown, return an unresolved receipt with `outcome_unresolved` and preserve output-validation diagnostics only as secondary metadata. Presentation failure is separate: preserve the action's status, data and effects and add `presentationWarnings`. Lost transport delivery MUST NOT overwrite an already recorded outcome.

Completion of a submission action means submission, not completion of the submitted work. A long-running job MAY be represented as application data and inspected through further discoverable actions; no ninth Jellybox polling tool is introduced.

### 6.8 `navigate_to_view`

**Purpose:** Explicitly change the human-facing presentation.

**Required input:** `interactionId`, `viewRef`.  
**Optional input:** `contextBehavior`, `expectedSelectionRevision`.

`contextBehavior` defaults to `preserve`. In this mode, navigation MUST preserve the interaction’s selected context and selection revision. `expectedSelectionRevision` has no effect in preserve mode. `presentationRevision` is an observation, not a guard that this input contract can supply. Preserve mode protects selection, not against a newer human or agent navigation. Hosts MUST order logical route changes by acceptance; a later accepted route supersedes an earlier one even if rendering finishes out of order. Hosts MUST NOT let an older renderer completion silently restore an obsolete route. After an uncertain navigation, clients SHOULD inspect current state and determine whether another navigation is still intended rather than blindly replay it.

With `contextBehavior: "use_view_default"`, the host MUST require `expectedSelectionRevision`, validate it, resolve the view’s default context and validate that context’s availability and authorization. Only after all checks succeed may it accept the navigation and adopt that context with a fresh selection revision. This combined state change MUST be atomic at logical route acceptance and context adoption; rendering may finish later. A view declared `lifetimeEffect: ends-instance` MUST reject `use_view_default` with `navigation_boundary_unsupported` before either requested state change. An implementation claiming `preserves-instance` MUST actually retain the interaction, revisions and receipt guarantees across that navigation boundary. Missing `expectedSelectionRevision` rejects with `invalid_request`; a missing or unavailable default context causes rejection. A stale expected revision rejects with `stale_context`.

#### Route acceptance

The host MUST validate the view reference and navigation authorization. It MUST NOT interpret a view reference as an arbitrary URL or executable script. A failed precondition MUST NOT leave half of the requested combined state change applied.

Success uses `data: {viewRef, context}` and reports the accepted view reference, the same resulting context state as the envelope, and a presentation effect. In preserve mode the selection remains unchanged while the runtime remains alive; navigation that ends the instance does not promise later recovery under that old instance. The host MAY acknowledge an accepted route before an asynchronous renderer finishes; it MUST NOT claim that the view has finished rendering unless that has been established.

Navigation MUST NOT automatically submit forms, commit edits or perform unrelated business actions. Unsaved user work SHOULD be retained or protected by explicit confirmation before it is discarded.

### 6.9 Portable action schemas

Action schemas MUST supply their required schema resources within the descriptor's schema document. `$ref` and `$dynamicRef` MUST resolve only to those supplied resources under 2020-12 resolution rules. Embedded resource `$id` values and anchors are supported. After base-URI resolution, a resource identifier MUST NOT identify different schema locations. Within each resource, an anchor name, including names declared by $anchor or $dynamicAnchor, MUST NOT identify different locations. Ambiguous duplicate identifiers or anchors reject the schema before reference resolution; `$id` is an identifier and base URI, never permission to fetch. Validation MUST NOT retrieve network resources. Unknown required vocabularies make the action non-executable until supported.

This edition supports the standard 2020-12 core, applicator, validation, unevaluated, metadata, format-annotation and content vocabularies. `format` is annotation, not an implicit assertion. Stronger format requirements MUST be expressed through supported validation assertions or a declared required extension. A schema requiring the format-assertion vocabulary is not executable under the unextended profile.

Schema `default` does not alter supplied parameters, required fields or request identity. Hosts MUST NOT silently coerce types, inject application defaults or normalize identifiers to make an otherwise invalid request valid. Application schemas SHOULD advertise the numeric range and precision their transport and runtime can support; hosts and bindings MUST reject numeric values they cannot preserve from their input boundary before acceptance rather than introduce further lossy comparison.

### 6.10 View discovery

`readme.data.views` contains `items`, `complete` and `discovery`. A view item contains its exact `ref`, title, description, nullable `defaultContextRef`, availability, and `lifetimeEffect: preserves-instance` or `ends-instance`. Availability remains subject to execution-time authorization.

If `complete` is true, the items enumerate every view currently offered for agent navigation and `discovery` is null. If false, `discovery` contains a `contextRef` and `actionRef` for an effect-free catalogue action. The client may enter that context, describe the action and invoke it through the same eight tools. The catalogue action MUST accept `{cursor, limit}` with a nullable opaque cursor and limit 1–100, and return `{items, nextCursor}` under `action-conventions.json`. It must require no application revision checks, use `retry.policy: idempotent`, and apply the same snapshot and authorization rules as core discovery. The first cursor is null. When `complete` is false, inline items are an advisory subset. Starting the discovery action with `cursor: null` enumerates the complete authorized catalogue independently of that subset. Clients deduplicate exact view references when combining inline and enumerated items.

Within one target instance, an exact view reference's material navigation contract is stable. Its lifetimeEffect and default-context adoption meaning MUST NOT change incompatibly under that reference. When either changes, retire the old reference and issue a new one; invocation of the old reference rejects with not_available. Ordinary content, labels and current availability may change without replacing the reference. This prevents stale discovery from silently changing an ends-instance or default-adoption decision even though the input has no view-descriptor revision guard.

Every agent-addressable view MUST be discoverable through the complete inline catalogue or that action, including views that are no context's default. A client MUST use returned references, not construct them from labels or URLs. A view catalogue action is application capability, not a ninth Jellybox tool.

## 7. Consistency, retries and cancellation

### 7.1 Discovery consistency

Availability is an observation, not a promise of later permission. Hosts MUST re-evaluate it when entering a context or executing an action.

Pagination cursors MUST be opaque and scoped to the caller’s authorized query, target, mode and inspected context. A later page MUST either continue the same enumeration snapshot or reject an invalidated cursor. It MUST NOT silently mix inconsistent enumerations. `nextCursor: null` means that enumeration is complete.

Selection changes and application-content changes are independent. A human edit MAY invalidate an action’s content preconditions without changing the agent’s selection. A human view change alone MUST NOT retarget a prepared action.

### 7.2 Request identity and receipts

These rules apply to `perform_action` requests carrying `requestId`, including effect-free reads when the caller supplies an identifier. The identity is scoped by security principal, exact target instance, interaction and request identifier. No other core tool acquires a receipt through this mechanism. Interaction expiry and invalidation are scoped by security principal, exact target instance and interaction identifier; equal identifier strings in another scope MUST NOT be invalidated together.

The host first validates public shape and identity/security scope. It then checks an existing identity before rejecting solely because selection, descriptor state or content revisions changed. Fresh authorization determines whether the stored outcome may be disclosed. Denial MUST NOT expose or alter the stored receipt and MUST NOT redispatch its operation.

For new work, complete binding, authority, availability, parameter, required-extension, confirmation and precondition validation, then reserve the identity atomically with the final checks before protected effects can begin. A pre-acceptance rejection does not reserve an identity. If an accepted queued request later fails a fresh check, it may record a terminal rejected result with no applied effects.

#### Request equality

The semantic request consists of action reference, binding, parameters and preconditions within its identity scope. Omitted preconditions equal an empty array. Object member order is ignored; array order and Unicode strings remain exact. Booleans and null compare by value. JSON numbers compare by their mathematical value at the delivered input boundary, with negative zero equal to zero. No string trimming, Unicode normalization, type coercion, fresh defaults or other application-specific normalization is permitted. A binding that parses serialized input MUST preserve supported numeric values without loss or reject unsupported values before acceptance. Jellybox does not guarantee recovery or detection of precision lost before that boundary. Implementations MUST NOT introduce further lossy normalization when comparing or retaining requests. Exact identifiers or decimal quantities beyond the binding’s supported numeric precision SHOULD use schema-declared strings. The original normalized comparison value is retained and is not rewritten when schemas or application state change.

#### Receipt states

Reusing a reserved identity with a different semantic request returns `request_id_conflict` without dispatch. Concurrent identical requests share one reservation and MUST NOT duplicate effects. Accepted identities have this lifecycle:

| State | Response and permitted transition |
| --- | --- |
| `running` | Execution was accepted and is still being established. An identical caller may wait for its outcome or receive `failed`, `request_in_progress`, null data and this receipt state. It may transition to unresolved or terminal. |
| `unresolved` | At least one effect outcome is unknown. Return `failed`, `outcome_unresolved`, null data and truthful unknown effect reports. Evidence-based reconciliation may transition to terminal; a retry never restarts execution. |
| `terminal` | The complete operation outcome is established. Return the recorded completed, rejected, cancelled or failed outcome. No effect outcome is unknown. This state does not transition back to execution. |

Interim running/unresolved responses are observations, not immutable final receipts. Their `failed` status does not establish that the underlying operation failed or had no effects. They MUST NOT direct the caller to create a new request identifier for the same intended effect. A permanently uncertain external operation remains unresolved until the declared interaction/recovery scope ends; the host must not invent certainty merely to finish it.

A terminal receipt retains the operation status, action data, error if any, actual effect reports and original context snapshot. Identical authorized retries return that recorded outcome without re-execution. Transport metadata or presentation warnings may describe delivery separately but MUST NOT rewrite the recorded operation. A replay is not a new observation of current selection or content; call `current_context` when needed.

The host MUST retain enough reservation or receipt state to prevent duplicate execution for the entire declared interaction lifetime, including across reload/restart when promised. It MAY refuse new work with `request_capacity_exceeded` at a documented capacity limit. It MUST NOT evict a reservation or receipt and silently execute that identity again within its scope. Ending an instance ends its recovery scope unless all required state was explicitly preserved. Expiry is not evidence that an uncertain external operation did not happen; clients must reconcile through application records before initiating the intended effect again.

These rules do not assert universal exactly-once execution by remote services. They require one dispatch per accepted identity within this host's guarantee and truthful handling of uncertainty, not an unsupported promise about an external system.

### 7.3 Cancellation and presentation failures

A request cancelled before dispatch MUST NOT execute. A queued request SHOULD be removed when cancellation is received.

Cancellation after execution starts does not prove rollback. If the operation commits, its receipt MUST retain that outcome. If the outcome is unresolved, a failure MUST report uncertainty rather than a confirmed cancellation.

A timeout, lost response or disconnected browser MUST NOT be interpreted as proof that no write occurred. An identical retry observes the retained reservation or receipt while its declared scope remains valid. It may still report unresolved uncertainty; it is never permission to redispatch.

A rendering error MUST NOT convert a successful committed action into a reported failed write. Hosts MAY return `presentationWarnings` while preserving the action receipt.

## 8. Errors and security

### 8.1 Error identifiers

The following codes define common failure categories. Implementations MAY provide additional, documented codes.

| Code | Meaning |
| --- | --- |
| `invalid_request` | Public tool arguments are malformed or contain unsupported properties. |
| `invalid_interaction` / `session_ended` | The interaction is unknown, expired or no longer usable. |
| `wrong_target` | A reference does not belong to the supported target instance. |
| `not_available` | The requested context, action or view cannot currently be used. |
| `permission_denied` / `confirmation_required` | Required authority or trusted confirmation is absent. |
| `stale_context` | The expected selection revision no longer matches. |
| `stale_binding` | The described action binding is no longer current. |
| `stale_revision` | An application-content revision precondition failed. |
| `invalid_parameters` | Action parameters do not satisfy their declared schema. |
| `request_id_required` / `request_id_conflict` | A required request identity is missing or has been reused inconsistently. |
| `invalid_cursor` / `stale_cursor` | A pagination cursor is invalid or its enumeration has changed. |
| `unsupported_precondition` / `unsupported_aspect` | A requested revision check cannot be enforced. |
| `cancelled` / `execution_failed` | Confirmed cancellation or established execution failure, with accurate effect reporting. |
| `request_in_progress` / `outcome_unresolved` | Interim receipt observations; the underlying operation is running or has an unknown effect outcome. |
| `output_validation_failed` | The operation's output violates its declared schema or cannot be represented; report committed effects truthfully and do not repeat them. |
| `precondition_required` | A required application revision check was not supplied. |
| `request_capacity_exceeded` | New request identity was not accepted because the documented capacity is exhausted. |
| `navigation_boundary_unsupported` | Combined route/context adoption cannot preserve its guarantees across the declared navigation boundary. |
| `unsupported_extension` / `unsupported_schema` | Required extension or schema semantics cannot be safely interpreted. |

Errors SHOULD explain a safe next step. They MUST NOT reveal hidden contexts, secrets or unauthorized record contents through diagnostic detail.

### 8.2 Authority and untrusted content

The website remains responsible for authentication, authorization, input validation and effect control. Context entry, successful discovery, a valid binding or possession of a request identifier MUST NOT independently grant authority.

Hosts MUST enforce authorization at execution time. The person’s conversation supplies the task and its direction. The interface does not replace that conversation or require a second on-page conversation. Consequential actions MUST still follow the site’s applicable consent policy. An agent-supplied Boolean or textual statement MUST NOT be accepted as proof that a person approved an operation.

Application content, imported text and action results MUST NOT be permitted to rewrite the trusted tool registry or grant permissions. Clients SHOULD treat instructions embedded in such content as data rather than authority. Hosts MUST respect browser-origin boundaries and MUST NOT expose secrets through tool metadata or results. These requirements are consistent with WebMCP’s treatment of tool and output injection risks. [WebMCP](https://webmachinelearning.github.io/webmcp/)

## 9. WebMCP binding

A conforming WebMCP implementation MUST register all eight core tools through the supported browser WebMCP mechanism, with the exact names, descriptions and input schemas in `webmcp-registration.json`. This manifest defines the required framework registrations; additional site tools are permitted under Section 11. The browser’s imperative interface uses `document.modelContext.registerTool`; browser feature detection and compatibility handling remain implementation responsibilities. [WebMCP](https://webmachinelearning.github.io/webmcp/) and its [imperative API](https://developer.chrome.com/docs/ai/webmcp/imperative-api)

#### Result delivery

For Version 1.0, a callback-produced Jellybox result is delivered in a wrapper containing `content`, `structuredContent` and `isError`:

```javascript
{
  content: [{ type: "text", text: JSON.stringify(result) }],
  structuredContent: result,
  isError: result.status !== "completed"
}
```

`result` is the Jellybox envelope from Section 5.2. The text and structured representations MUST describe the same result. This wrapper is Jellybox’s binding choice, not a claim that WebMCP requires an MCP-style result wrapper. A browser or bridge may serialize the callback payload for delivery.

An action’s `outputSchema` validates the action-specific `result.data`. A WebMCP registration-level output schema, when supplied, MUST instead describe the actual callback payload. These two schema levels MUST NOT be confused.

#### Registration and lifetime

Tool annotations MUST be conservative. `perform_action` MUST NOT be advertised as universally read-only when it can dispatch writes. Annotations are metadata, not enforcement of permissions or consent. Action-specific meaning is delivered through descriptions; a general tool annotation cannot replace an action’s declared effects or the host’s checks. [WebMCP](https://webmachinelearning.github.io/webmcp/)

#### Navigation and interrupted delivery

Browser execution and result delivery are distinct from a Jellybox result. A browser or bridge may return null when navigation is triggered, or surface an unload/transport exception such as AbortError before a callback result is delivered. These are transport-level no-result outcomes, not Jellybox completed, rejected, cancelled or failed envelopes. Clients MUST NOT invent an envelope or infer rollback, confirmed cancellation or absence of effects from them. Callback-produced results still obey the schemas and wrapper above. [WebMCP](https://webmachinelearning.github.io/webmcp/) and its [imperative API](https://developer.chrome.com/docs/ai/webmcp/imperative-api)

After an ends-instance navigation with no delivered result, observe the destination and bootstrap with readme without the old interaction identifier, then use the new exact returned target and interaction. Do not replay the old navigation, references or interaction into the new instance. If an operation's effect is uncertain, preserve that uncertainty and use authorized application records or the retained receipt scope to reconcile it; a new bootstrap is not permission to repeat a write.

Implementations MUST connect the execute callback's operation signal to their cancellation handling. An operation abort requests cancellation; it does not prove rollback after execution starts. Registration lifetime/unregistration signals are separate from operation cancellation. Removing a registration MUST NOT be treated as proof that in-flight execution was cancelled; registration disposal and cancellation of an already-running operation are separate responsibilities. Preserve the outcome and receipt according to Section 7 even when result delivery is interrupted. [the imperative API](https://developer.chrome.com/docs/ai/webmcp/imperative-api)

Registrations MUST be removed when their runtime is disposed. Partial registration failure MUST NOT leave an apparently complete, usable Jellybox interface. If native WebMCP is unavailable, a manual demonstration MAY remain available, but it MUST NOT be described as an active native WebMCP connection.

## 10. Conformance

An implementation conforms to **Jellybox WebMCP Framework — Standalone Core, Version 1.0** only when it satisfies all applicable MUST and MUST NOT requirements and the input/output schemas and action conventions.

A conformance report MUST identify the exact specification edition, implementation version, browser binding tested and any extensions. Passing schema validation alone is insufficient. Reports MUST separate structural fixture checks, reference-model tests, actual runtime behavior and native browser-binding execution; a reference model is not proof of another implementation's behavior.

At minimum, behavioural verification MUST cover:

| Test | Required observation |
| --- | --- |
| C01 — Required core | All eight exact framework tools and their contracts exist; additional site tools may coexist. |
| C02 — Independent interactions | Selecting a context in one interaction does not retarget another. |
| C03 — Passive discovery | Readme resumption and discovery preserve valid selection and presentation. |
| C04 — Context entry | Correct revisions succeed; stale revisions reject without navigation. |
| C05 — View independence | Human navigation and preserve-mode agent navigation do not retarget prepared actions. |
| C06 — Explicit adoption | Adopting a view default requires the current revision and succeeds or fails atomically. |
| C07 — Contextual availability | Availability is context-sensitive, rechecked, and does not expose hidden records. |
| C08 — Binding and validation | Wrong instances, stale bindings, invalid parameters and unsupported checks reject before effects. |
| C09 — Retry safety | Sequential and concurrent identical retries do not duplicate writes; changed requests conflict. |
| C10 — Honest outcomes | Late cancellation, lost responses and rendering failures do not imply rollback. |
| C11 — Lifecycle and pagination | Expired instances reject; invalidated enumerations do not silently continue inconsistently. |
| C12 — Host authority | References, content and agent-supplied confirmations cannot bypass authorization. |
| C13 — Typed results | Every tool returns its complete output shape; completed action data satisfy their action schema. |
| C14 — Receipt lifecycle | Running/unresolved observations do not redispatch; evidence-based terminalization and terminal replay retain the original operation. |
| C15 — Equality | Object order and empty-precondition defaults compare consistently; arrays, strings and distinct large numbers retain their declared meaning. |
| C16 — Output failure | A committed write with invalid output yields a terminal failed receipt with applied effects; rendering trouble preserves the action outcome. |
| C17 — Required metadata | Unsupported required extensions or schema resources block execution; optional metadata remains tolerable. |
| C18 — Revision acquisition | Fixed and resolved preconditions are obtainable and independently enforced; resolver chains and hidden required tokens are not needed. |
| C19 — View catalogue | Non-default views are discoverable, pagination is consistent and ends-instance combined adoption rejects before state changes. |
| C20 — Edition and registration | The introduction identifies this edition/profile and registrations match the canonical manifest. |
| C21 — Native no-result delivery | Actual browser navigation null/unload/transport outcomes are not fabricated into envelopes or rollback claims; ends-instance recovery bootstraps a new exact target without replaying old references. |
| C22 — Cancellation ownership | Actual operation-signal cancellation is distinguished from registration disposal; unregistering a tool does not falsely cancel or duplicate in-flight effects. |
| C23 — Stable view contracts | Material lifetime/default-context changes issue a new view reference and reject the old one before navigation. |
| C24 — Semantic validator counterexamples | Cross-target descriptors, resolver self/cycles, pointers into instance data and ambiguous schema resource identities are rejected; generated interim receipts satisfy the full result contract. |

The accompanying implementation checklist turns C01–C24 into a report template. A report records tested behaviour and limitations; it does not obtain conformance by counting tests. A manual demonstration alone does not establish native WebMCP operation.

## 11. Extension and compatibility rules

Implementations MAY register additional WebMCP tools alongside the eight framework tools. Additional tools MUST use distinct names and MUST NOT replace or alter the required core contracts. Their descriptions, input schemas and results belong to the website; the framework's action bindings and result wrapper do not automatically apply to them.

Website owners and developers choose which capabilities to expose as contextual actions and which to expose directly as additional tools. A direct tool's registration description can give an agent relevant information before it calls any tool. Additional tools are optional; all eight framework tools remain required for conformance.

Implementations MAY add contexts, views and contextual actions without changing the eight core contracts. Action parameters and successful data belong to the application and are specified by action schemas. Optional output metadata may expand, but required execution extensions use the explicit descriptor mechanism. Core meanings, reference shapes, binding checks, revision domains, error semantics and view independence MUST be preserved.

Changes to a contract that could invalidate a prepared invocation MUST change its descriptor revision. Changes to required tool names, input shapes or core semantics require a separately identified interface-contract revision; they MUST NOT silently masquerade as this edition.

Version 1.0 defines the input, result and behavioural contract. The result’s `protocolVersion` and the introduction’s `interfaceEdition` are both `"1.0"`; `interfaceProfile` identifies the applicable profile. The website’s own application version is independent of this interface.

An implementation MUST report the edition it supports. Matching the input schemas alone does not establish conformance. Implementers use the checklist to verify the required behaviour.

## 12. Working through the interface

The tools support an agent’s work on the website. The surrounding chat supplies the task and conversation; this section describes the website interaction.

1. **Read the introduction.** `readme` explains the particular Jellybox and returns an exact target and interaction. Keep those references for the task.
2. **Choose a place to work.** Use `list_contexts` when discovery is needed. `enter_context` selects a context without moving the person’s page.
3. **Understand the available work.** `list_actions` shows current actions. `describe_actions` supplies the chosen actions’ complete contracts. Keep useful descriptions while their bindings and required state remain valid.
4. **Perform the action.** `perform_action` uses the returned binding, parameters and preconditions. The website checks the request and applies its own application logic. Effects may appear in the visible page without changing its route.
5. **Continue or show a result.** Consult another context when useful. Use `current_context` for a fresh observation and `navigate_to_view` when deliberately showing a view to the person.

This is a description of the tools’ relationship, not a fixed sequence to repeat. An agent can remain in one context for an entire task. It should refresh the information that has changed, rather than rediscovering the whole website before each action.

A stale binding needs a fresh description; a stale content precondition needs current data. An uncertain identified action needs an exact retry within its recovery scope, not a new identity for the same intended effect.

## Appendix A. Publication files

The complete Version 1.0 package contains the following files. All normative schemas can be used without fetching remote resources.

| File | Role |
| --- | --- |
| `Jellybox-WebMCP-Framework-Specification.md` | This specification, including the implementation guide. |
| `tool-input-schemas.json` and `schemas/` | The eight Version 1.0 tool input schemas. |
| `output-contract.schema.json` | The complete Version 1.0 output contract and shared definitions. |
| `tool-output-schemas.json` and `result-schemas/` | Self-contained per-tool result schemas derived from the output contract. |
| `webmcp-registration.json` | Canonical tool names, descriptions, input schemas and conservative annotations. |
| `action-conventions.json` | Schemas for view-catalogue discovery and revision-resolution results. |
| `FRAMEWORK-GUIDE.md` | The plain-language introduction to the framework. |
| `CREATOR-GUIDE.md` | The implementation guide, also included as Appendix C. |
| `IMPLEMENTATION-CHECKLIST.md` | A report template for C01–C24 and deployment-specific evidence. |
| `PUBLICATION-NOTES.md` | Framework terminology, versioning and publication scope. |
| `LICENSE` | The MIT licence for the original framework documentation and schemas. |
| `SHA256SUMS` | Digests of the specification package’s files. |

The package’s `SHA256SUMS` file provides integrity checks for its contents.

Result schemas use Version 1.0 identifiers and define the result structure. The complete package supplies the reference files needed to implement this contract. Further examples can be published separately without changing the core interface.

The [downloads](#downloads) provide the complete package and the principal individual files. The current website component’s implementation status is documented separately from the framework specification.

## Appendix B. References

1. [WebMCP browser API](https://webmachinelearning.github.io/webmcp/) — Web Machine Learning Community Group. Browser tool registration, execution and security considerations.
2. [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119.html) — Key words for use in RFCs to indicate requirement levels.
3. [RFC 8174](https://www.rfc-editor.org/rfc/rfc8174.html) — Interpretation of uppercase and lowercase requirement words.
4. [JSON Schema 2020-12](https://json-schema.org/draft/2020-12) — The schema vocabulary used for parameters and results.
5. [WebMCP imperative API](https://developer.chrome.com/docs/ai/webmcp/imperative-api) — Chrome implementation guidance for JavaScript tool registration and execution.

The framework’s Version 1.0 contract is defined by this publication. Browser implementation details should be checked against the browser API documentation when an integration is built or upgraded.

## Appendix C. Implementation guide

Apply the framework to the information and operations your website already makes available to agents. The guide explains the design choices; the numbered specification chapters define the requirements.

## What you are implementing

You are implementing the Jellybox WebMCP Framework’s eight-tool interface for your website. WebMCP already provides the mechanism for exposing callable tools. The framework adds a common model of contexts and actions, an introduction through `readme`, and explicit rules for discovery, execution and view navigation.

Start with the website’s useful capabilities. Organise them into contexts that make the work understandable. A context can match an existing page, or one home context can provide everything a small site needs. Connect its actions to the website’s own application logic.

The person’s chat and normal pages remain available. The interface lets the agent work with the same website while choosing its own context independently of the visible page.

## 1 Choose useful work and its boundaries

Decide which parts of the website an agent should be able to read or use. Describe a useful task in plain language, then identify the information, actions and existing business rules it needs.

Keep three roles clear: the **context** is the agent’s focus, the **action** is an operation, and the **view** is what the person sees. Map them deliberately. Moving between contexts should not require the person’s page to follow.

Authentication, validation, data storage and effects remain application responsibilities. Reuse those responsibilities when adding the interface.

## 2 Introduce the space and return stable references

Write `readme` as the first useful explanation an unfamiliar agent receives. Say what the website offers, which contexts help with common work, how to discover and use actions, and how long references and results remain valid. Provide longer guidance through requested topics or reading actions when useful.

Return exact references for the target, contexts, actions and views. Give each interaction an independent selection. Make the initial context useful; a small space can start and remain in one context.

Return a context’s default view when one exists. Provide every agent-addressable view through the complete inline catalogue or the discovery action defined in Section 6.10. Neither discovery nor reading should move the person’s page.

## 3 Describe complete actions

An action summary helps the agent choose what to inspect. A full descriptor teaches it how to perform the operation. Include its purpose, parameter and result schemas, current availability, effects, binding, preconditions, completion and retry rules. Section 6.6 is the complete contract.

Use the website’s real operations and meaningful names. Make the parameter schema precise, including limits and identifier scope. The output schema describes successful `result.data`; it does not describe the surrounding WebMCP wrapper.

Use fixed preconditions when the required revisions are already known. Use a declared, effect-free resolver when checks depend on the intended parameters. Keep effects and confirmation requirements explicit. An action name entered as content does not register code or confer authority.

## 4 Keep selection, presentation and data distinct

Track the selected context separately for each interaction, the human-facing view separately for the page, and application content with its own revisions.

`selectionRevision` guards context changes. `descriptorRevision` guards the described action contract. Content revisions guard the data an action depends on. One token must not stand in for all three.

Let action results update normal application views. Reserve route changes for explicit navigation and declared presentation effects. Protect unsaved human input when a requested route change would discard it.

Document what survives reload, logout, restart and disconnection. Rotate the runtime instance identity when its reference and receipt guarantees can no longer be preserved.

## 5 Connect the eight tools

Use the published input schemas and registration manifest. Connect each tool to its specified responsibility and return the defined result wrapper. Register through the browser’s supported WebMCP API and clean up only the registrations your runtime owns.

You may also register additional site tools with their own names, descriptions, input schemas and results. All eight framework tools remain required. Choose a direct tool when its capability or registration description should be available upfront; choose a contextual action when it belongs in the framework's discovery and execution flow.

Contexts and discovery can run in the page’s JavaScript environment. Connect an action to a backend when that operation needs one. A local browser interface is not a promise that every action is offline or that a browser-held value is durable.

Expose a clear unsupported-browser state when the API is unavailable. Human controls may remain usable, but a manual control does not establish that a native agent connection exists.

## 6 Execute once and retain the outcome

Before applying effects, validate the exact target, interaction, binding, current authority, parameters and required revisions. Coordinate these checks with the operation so a concurrent change cannot bypass them.

For an identified request, reserve its identity before effects and retain the resulting execution state. An identical retry retrieves or waits for that same operation. A different semantic request under the same identity is rejected.

Connect the receipt to the system that commits the change. Browser memory alone does not establish backend deduplication or restart recovery. If an external outcome is unknown, preserve that uncertainty and use the application’s records to reconcile it. Cancellation or a lost response does not prove rollback.

Section 7 defines the exact equality, retention and cancellation rules.

## 7 Return useful errors

Explain what prevented progress and the next appropriate step, without revealing information the caller may not see. Distinguish unavailable work, stale state, missing authority, invalid parameters and an uncertain outcome.

A stale description can be refreshed. A refused permission check cannot be repaired by inventing a new reference. An uncertain identified operation must not be repeated as a new action merely because its response was lost.

Keep the original operation outcome separate from a later presentation or delivery problem.

## 8 Verify the integration

Use the implementation checklist to report every applicable C01–C24 requirement. Validate the fixed tool inputs, the tool-result envelope and each action’s own inputs and successful data.

Exercise the actual runtime with independent interactions, changing availability, concurrent edits, retries, cancellation and navigation. Test the supported browser binding separately from in-process fixtures. Record the browser, client, application version, persistence scope and any unsupported cases.

Check the person’s normal interface as well as tool results. A shared state change should appear correctly; an agent context change should leave the human route alone. Test an end-to-end task with an independently operated agent before claiming that client is supported.

## Where to go next

Use the [conceptual model](#conceptual-model) to check the space’s design, the [eight tool contracts](#tool-contracts) to implement the interface, and the [implementation rules](#consistency-retries-cancellation) to verify its behaviour.

The [downloads](#downloads) contain the specification, schemas, canonical registrations, action conventions and checklist. The [implementation status](#compatibility) explains the current website component. Additional worked examples can be published as a separate companion to the specification.

