How to Debug WebMCP Tool Discovery and Registration Failures

Quick answer: If a WebMCP tool appears to register but an AI agent cannot find it, debug three separate stages: (1) whether the current browser and page actually support document.modelContext.registerTool(), (2) whether the expected tool appears in await document.modelContext.getTools() from the correct document and origin, and (3) whether the connected agent can see and invoke that tool. A registration log is not proof of agent discovery, and agent discovery is not proof of successful tool execution. On WordPress, ModelGain WebMCP Forms 0.1.0 provides additional per-form diagnostics for Contact Form 7. The released plugin can fill supported human-visible fields only; it never submits a contact form.

Need to test a WordPress form? Get ModelGain WebMCP Forms from WordPress.org, check the exact form in Tools → WebMCP Forms, and follow the read-only checks below before performing any fill test. If document.modelContext is simply missing, use our Chrome WebMCP setup guide first. If you have not enabled the exact Contact Form 7 form, follow the per-form opt-in walkthrough. This article starts where those prerequisites end: tool lifecycle, page discovery, name mismatches and agent visibility.

Registration, discovery and invocation are not the same checkpoint

The Chrome imperative WebMCP API makes a website-side tool available through registerTool(). getTools() returns tools accessible in the calling document’s context; the agent then has to connect to that page, choose an appropriate tool and provide valid arguments. Chrome’s WebMCP DevTools panel distinguishes Available Tools from Invoked Tools, including call counts and error details. Treat each as independent evidence.

Step 1: Check the browser API in the exact page you want the agent to use

Open the real HTTPS staging page containing the expected form and select its document in Chrome DevTools Console. In supported Chrome testing environments, run this read-only check:

console.log({
  origin: location.origin,
  secure: isSecureContext,
  registerTool: typeof document.modelContext?.registerTool,
  getTools: typeof document.modelContext?.getTools
});

Both method values should normally be "function" for the corresponding imperative API tests to proceed. If the API is missing, confirm your Chrome version, experimental WebMCP settings, any required relaunch and the correct frame. A WordPress plugin cannot create a missing native browser API. Chrome has moved its experimental API surface over time: use document.modelContext, not legacy navigator.modelContext. Read the current Chrome reference, and use the dedicated browser preflight article for the flags and build-specific details.

If the API works but no tool appears, that is a different failure. Continue without changing browser flags again. Record the URL, active frame, browser version and exact API results; avoid collecting real contact details or authentication tokens in debugging logs.

Step 2: Inspect the names and origins the current page can actually discover

Once getTools is present, run this from the intended page. It lists metadata only; it does not invoke tools or send a Contact Form 7 request:

const tools = await document.modelContext.getTools();
console.table(tools.map(({ name, origin, description }) => ({
  name, origin, description
})));
// Find the exact tool name configured for your form.

Do not assume the first tool belongs to the form you are testing; names are the stable identifier to compare with the WordPress admin registry. A tool can be registered in one document but unavailable to an agent operating another page, another tab or an origin it has not been authorized to inspect. Chrome’s default getTools() scope includes tools the calling document can access from its own origin and permitted same-origin frames; cross-origin iframe access requires additional explicit permissions and origin selection.

If the tool is visible here but your agent still says “no tools”: check whether its connected Chrome tab, frame, origin and runtime session are the same as the ones you just inspected. A generic AI chat product is not automatically a WebMCP-connected browser agent. See Chrome’s agent-assisted WebMCP debugging guide and the WebMCP DevTools panel for supported instrumentation.

Step 3: Read ModelGain’s registration diagnostics before editing your form

For ModelGain WebMCP Forms 0.1.0, inspect the staging form in Tools → WebMCP Forms. The target ID must belong to a compatible form, be explicitly marked Expose, and have a unique resolved tool name. The plugin will not register a tool for new, disabled, incompatible or name-colliding forms. The per-form opt-in guide covers the exact save behavior; the field compatibility matrix explains why a checkbox, acceptance field, upload or other unsupported form-tag blocks the entire form.

The released plugin adds a read-only frontend diagnostics object only when its runtime script has been loaded. In the same correct document, inspect:

window.ModelGainWebMCPFormsDiagnostics?.tools
// e.g. { "modelgain.cf7.form_41": {
//   formId: 41, toolName: "...", status: "registered", message: "..."
// }}

This is ModelGain-specific diagnostic data, not part of the standard WebMCP API. It can distinguish these states:

The plugin schedules an initial scan and then watches DOM changes. On a dynamically inserted or removed form, it can register or unregister tools, with a short scan delay. The underlying registration is tied to an AbortSignal. If an enabled form disappears, is rendered twice or the page unloads, previously registered tools may be withdrawn. Therefore, a stale screenshot of “registered” is not proof of the tool’s current availability.

What if the diagnostics object is undefined? Do not immediately conclude the native API is broken. The plugin only enqueues its runtime when at least one enabled, compatible, uniquely named form exists in the current WordPress configuration. Check the admin registry, frontend page source, actual JS load and cached page version. A script that never loaded cannot report a registration status.

Step 4: Compare the published page configuration with the live form

On a test page with the ModelGain runtime loaded, these read-only checks identify the plugin’s configured form IDs, registered names and the form instances actually rendered:

console.table(
  (window.ModelGainWebMCPForms?.forms ?? [])
    .map(({ formId, toolName }) => ({ formId, toolName }))
);
console.log(
  "CF7 form instances:", document.querySelectorAll("form.wpcf7-form").length
);

If the target name appears in the configuration but the diagnostics report not_present, the expected CF7 form does not appear in the document as a normal rendered instance. Verify the embedded form ID and the rendered page, not just the WordPress admin title. If diagnostics show ambiguous, a duplicate shortcode, repeated component, mobile-only clone or another duplicated rendering may have created more than one instance of the same ID; keep a single instance on the isolated test page.

If you recently renamed a tool, changed its supported fields, unchecked Expose or updated a form, an already-open tab can retain the old page configuration. Open a fresh document, check the new tool name and compare public HTML against the saved settings. Where applicable, invalidate stale WordPress page, CDN or reverse-proxy caches. ModelGain v0.1.0 is not a universal remote-session revocation service; a saved disable setting must be verified against newly opened pages as well as any still-open sessions.

Step 5: Watch registration changes and investigate the agent separately

Chrome documents a toolchange event for changes to available tools. In supported builds, attach a read-only listener and then repeat the action that causes your form to appear or disappear:

document.modelContext.addEventListener("toolchange", async () => {
  const names = (await document.modelContext.getTools())
    .map(tool => tool.name);
  console.log("Currently discoverable WebMCP tools:", names);
});

Use this only when the event interface is supported by your browser. It does not itself force registration or change exposure settings. You can also inspect Chrome DevTools → Application → WebMCP in builds that provide that panel. The Available Tools list shows discovered names and descriptions; the Invoked Tools log and invocation count show what was actually called and whether it failed. A tool’s visibility with zero invocations is different from a failing tool execution.

Agent-side tools such as Chrome DevTools for agents may need their WebMCP experimental category explicitly enabled; the current command-line flag and support status depend on the agent tooling release. Follow the vendor’s current agent debugging instructions rather than copying historical CLI switches into every environment. An agent may also choose not to call an available tool for a given prompt. That choice is not, by itself, evidence of failed website registration.

Cross-origin iframes: a different discovery and permission boundary

A tool in an iframe is not automatically available to every parent document. Chrome’s current imperative API guidance distinguishes same-origin discovery from cross-origin access. For cross-origin frames, tool registration may require the embedding page’s allow="tools" Permissions Policy delegation, the registered tool’s exposedTo origins and the consumer’s explicit getTools({ fromOrigins: [...] }) request. All of these are permission decisions—not mere debugging switches.

Do not add broad iframe permissions or origin exposure just to make a missing tool visible. First identify whether the form is in the top-level document, a same-origin frame or a third-party cross-origin frame. The current ModelGain plugin registers on the form’s own page using its published runtime; it does not turn a WordPress page into a globally accessible cross-origin MCP service.

Why can a visible tool still fail when called?

A discovered WebMCP tool has a declared input schema. If your agent uses the wrong field names, misses required inputs, sends an invalid email or select option, or calls a tool after it has been unregistered, discovery may have been fine while invocation fails. Chrome DevTools’ WebMCP panel shows the specific arguments, output and errors. Keep this distinction when assigning an issue to the browser, WordPress form adapter or agent implementation.

For ModelGain v0.1.0, the runtime validates the submitted tool arguments against supported fields and rejects an invalid input object before changing any form control; success fills the user-visible fields and returns submitted: false with requiresHumanReview: true. Test it with synthetic data and do not click Send. See our safe no-submission acceptance procedure for a positive and negative case. Successful filling is never proof that a contact message was delivered, and this plugin does not provide automatic form submission.

Fast troubleshooting matrix: pick the first failing layer

What to record in a useful bug report

Record the Chrome version, tested URL and origin (redacting private hostnames as necessary), whether the form is in the top document or iframe, the expected CF7 form ID, resolved WebMCP tool name, admin compatibility/opt-in status, exact runtime diagnostics status, getTools() names, the browser DevTools panel’s available and invoked states, and whether navigation or a cache refresh occurred. Do not include real customer values, agent credentials, raw private messages or tokens. A reproducible report lets developers distinguish registration, discovery and execution regressions.

Frequently asked questions

Does registered mean an AI agent must be able to find the tool?

No. It records that ModelGain’s browser registration completed for a form instance. An agent must still operate in an appropriate page, origin and client environment; page lifecycle and tool visibility can change after that status was written.

Is getTools() a WordPress API or a site-wide plugin inventory?

Neither. It is a browser WebMCP method that discovers tools accessible to the calling document under its origin and permission rules. Use WordPress admin separately for all saved forms and exposure decisions.

Why did a tool disappear when the form was removed or the page changed?

The current ModelGain runtime monitors form instances and ties registration to an abortable lifecycle. A missing or duplicated instance can invalidate the registration. After form edits or navigation, use the current page and a fresh discovery request rather than relying on a previous tool list.

Can I make an agent discover the tool by enabling automatic submit?

No. Submission is unrelated to discovery. ModelGain WebMCP Forms 0.1.0 only fills approved Contact Form 7 fields. The visitor retains responsibility for reviewing and submitting through the original form. See why human approval remains separate.

Next: establish one reproducible working path

Use a dedicated WordPress staging page with a single compatible, explicitly exposed Contact Form 7 form and a browser that actually supports imperative WebMCP. Confirm the exact resolved tool name in WordPress admin, registered in ModelGain diagnostics, the same name in getTools(), and then—only when needed—an isolated fill-only execution. Once those gates pass, troubleshoot the particular agent connection rather than widening form exposure.

ModelGain WebMCP Forms explains the product’s supported feature set; WordPress.org is the official install authority. For related steps, use the Chrome setup guide, per-form opt-in guide, supported-field reference and no-submit acceptance checklist. Together they isolate browser support, administrator permission, field compatibility, tool lifecycle and agent execution without conflating any of these with real form submission.