Connect a WebMCP tool

This how-to connects a host application tool to a visible clue. The application remains responsible for executing the action.

Register semantic targets

Use stable, application-owned identifiers:

<section
  data-viewcue-target="payments.method"
  data-viewcue-label="Payment method"
  data-viewcue-description="Available channels for this bill"
>
  <!-- host application controls -->
</section>

Avoid passing arbitrary CSS selectors, XPath, raw HTML, or JavaScript into the clue API. The target registry is intentionally explicit and bounded.

Show a clue from a read or guidance tool

const explainTerm = {
  name: "explain_tax_term",
  title: "Explain a tax term",
  description: "Explain a term and point to where it appears on the page.",
  inputSchema: {
    type: "object",
    properties: { term: { type: "string" } },
    required: ["term"],
    additionalProperties: false,
  },
  annotations: { readOnlyHint: true },
  execute: async ({ term }: { term: string }) => {
    await window.ViewCue?.showClue({
      targetId: "payments.kap-kjs",
      title: `Term: ${term}`,
      message: "This code identifies the tax and deposit type for the payment.",
      ensureVisible: true,
    })

    return JSON.stringify({ ok: true, term, clueShown: true })
  },
}

await document.modelContext.registerTool(explainTerm)

The tool’s execute() owns the result and any application behavior. ViewCue only adds the visual explanation.

Optionally show activity

Some applications want a visible activity state around a consequential tool. Wrap that tool when you want the optional lifecycle connected to the real execute() call:

const visiblePrepare = window.ViewCue?.instrumentTool(preparePayment, {
  targetIds: ["payments.method", "payments.review"],
  label: "Prepare a payment method",
})

await document.modelContext.registerTool(visiblePrepare || preparePayment)

This may render planned, executing, completed, or failed. It is an optional example of a clue, not a requirement for every WebMCP tool.

Preserve normal application behavior

Do not replace the host application’s event handlers with ViewCue calls. A tool may still:

• click or select a host control;
• type into a host field;
• submit a host form;
• call an API;
• update application or business state.

ViewCue makes the relevant context visible; it does not block or impersonate those actions.