WebMCP Tool Validator
Inspects declarative and runtime tool metadata, parameter quality, labels, and security-relevant wording.
Agentic WebExposing Website Functions as WebMCP Tools
A WebMCP tool is a public interface contract wrapped around a website function. The hard part is not calling document.modelContext.registerTool; it is making the name, parameters, effects, errors, and visible interface tell the same truth under automation that they tell a person.
Start with an operation, not a page
Do not expose “the form” as a tool. Identify the bounded operation beneath it: validate one document, calculate one subnet, search one catalog, create one support case. A useful tool has one name a model can select without guesswork, a description that predicts the action and result, and parameters whose labels explain intent rather than repeat variable names. Split unrelated outcomes. A tool named manageAccount that might read a profile, change an email address, or delete the account has avoided interface design and handed the ambiguity to the caller.
Write the contract before registration code. Define accepted types, required fields, formats, size limits, defaults, mutually exclusive inputs, authorization assumptions, success shape, error shape, and side effects. Include what the operation does not do when confusion would be expensive. A validator that parses text but never publishes it should say so. A send operation should name the recipient boundary and whether the call is immediate. Tool metadata is what the agent and often the approving human see; private implementation intent cannot repair vague public words.
Register a contract the runtime can enforce
The current imperative registration point is document.modelContext.registerTool; navigator.modelContext remains a compatibility fallback in older integrations. Registration should bind stable metadata to a handler that validates again at execution time. Schema validation at discovery is not a security boundary: the handler must reject malformed, oversized, unauthorized, or contextually impossible arguments even if a client claims they passed the advertised schema. Normalize data deliberately, preserve meaningful distinctions such as absent versus empty, and return bounded structured results rather than an uncontrolled dump of DOM or server output.
Keep tool lifetime aligned with page lifetime. Do not register duplicate names after every component render, leave stale handlers after navigation, or silently change a contract while retaining the name. If a new version changes required parameters or effects, treat it like an API change. Graceful unsupported-runtime behavior matters too: the visible website must still work without model context, and the registration path must fail quietly rather than breaking the human interface. WebMCP augments a page; it should not become a prerequisite for using it.
The visible UI and tool schema need parity
Parity does not mean the markup and JSON must be character-for-character identical. It means both routes express the same operation and safeguards. If the form requires a hostname but the tool accepts an arbitrary URL, the agent has a broader function than the person. If the UI shows a destructive confirmation but the tool description says only “update,” the automation route has hidden the most important fact. Defaults, allowed values, input constraints, authentication state, locale behavior, and result terminology should agree. Reuse one domain model where possible; duplicated validation inevitably drifts.
Do not let a tool become a secret premium interface to controls the page does not explain. A person should be able to understand what the website can do, what data leaves the browser, and what changes persist, even if an agent performs the call. Conversely, accessibility labels and help text in the UI are excellent source material for parameter descriptions. The WebMCP Tool Validator inspects declarative forms and recognizable runtime registrations, extracts names, descriptions, parameters and labels, and flags compatibility or security wording. It is a static preflight, not proof of handler behavior.
Writing tools need an explicit threat model
Read-only, deterministic operations are the easy starting point. A writing tool crosses trust boundaries: it may send mail, publish content, alter access, spend money, trigger hardware, or delete data. Name the mutation in the verb and description. Bind authorization to the executing user, not to whatever identity an argument claims. Defend against replay with appropriate idempotency, narrow the target, rate-limit expensive actions, and produce an audit record that distinguishes proposal, approval, execution, and outcome. Never place secrets in discovery metadata or return them in a result.
Prompt injection is not solved by a correct schema. Treat page content, tool arguments, remote responses, and retrieved instructions as untrusted data. Enforce server-side permissions and business rules after the call arrives. For irreversible or high-impact effects, use a preview or draft operation followed by a separately authorized commit, with the exact target and consequence visible at approval time. Neutral verbs are dangerous: “manage,” “process,” and “confirm” can conceal deletion or payment from both agent and reviewer. An honest contract gives the safety layer something concrete to judge.
Test metadata, runtime, and abuse paths
Begin with the smallest source fragment that contains one form or registration. Static validation should catch missing names, generic descriptions, unlabeled parameters, suspicious side-effect wording, and obvious compatibility gaps without executing pasted JavaScript. Then test the live page to confirm the deployed source carries the reviewed contract. Follow with runtime tests: valid calls, missing and extra fields, boundary sizes, wrong types, expired sessions, duplicate submissions, concurrent calls, timeouts, partial backend failure, and results containing hostile text. A metadata pass cannot observe permission prompts or actual mutations.
Keep the broader agent-facing documentation aligned. A concise llms.txt Validator may point readers to the page and its operating notes, but it is not tool discovery or runtime registration. Re-run validation whenever labels, inputs, authentication, or effects change. Treat a mismatch as release-blocking: an agent acting on yesterday's contract can be more dangerous than no agent integration at all.
WebMCP is not an A2A Agent Card
WebMCP exposes functions in the context of a website. An A2A Agent Card advertises a network agent: identity, skills, interfaces, transports, capabilities, endpoint URLs, and authentication requirements at a public well-known location. The card helps another agent decide whether and how to communicate before invoking the service. A page tool and an agent skill may wrap related business logic, but their discovery scopes and calling models differ. Do not paste one schema into the other and assume interoperability.
Validate them independently. The A2A Agent Card Validator checks pasted JSON or a public card for discovery shape, identity, skills, interfaces, capabilities, security metadata, and deployment warnings; it never invokes the advertised agent. WebMCP validation inspects page metadata and registration hints; it cannot test runtime semantics either. In both cases the public description must move atomically with the implementation. Stale discovery teaches automated callers a confident falsehood.