Expose the First WebMCP Tool

Our first WebMCP tool should not send a message, edit a document or buy anything.

It should read from the book we control.

We will expose search_book: a bounded operation that finds relevant chapters and passages.

1. Start with a narrow contract

Conceptually, the page registers:

navigator.modelContext.registerTool({
  name: "search_book",
  description: "Search this book for passages related to a query.",
  inputSchema: {
    type: "object",
    properties: {
      query: { type: "string", minLength: 2, maxLength: 300 },
      limit: { type: "integer", minimum: 1, maximum: 10 }
    },
    required: ["query"],
    additionalProperties: false
  },
  execute: ({ query, limit = 5 }) => searchIndex(query, limit)
});

WebMCP is evolving, so the exact registration surface must be checked against the browser version used for an experiment. The durable architecture is name, description, schema and implementation.

2. Validate again inside the implementation

The schema helps an agent construct arguments. It does not replace application checks.

function searchBook({ query, limit = 5 }) {
  if (typeof query !== "string" || query.trim().length < 2) {
    throw new TypeError("query must contain at least two characters");
  }
  if (!Number.isInteger(limit) || limit < 1 || limit > 10) {
    throw new RangeError("limit must be between 1 and 10");
  }
  return index.search(query.trim(), limit);
}

The implementation is the enforcement boundary. Tool descriptions and model-generated arguments remain untrusted input.

3. Bound the result

A read-only tool can still leak excessive content or consume the agent’s context window.

Return references and short excerpts:

{
  "matches": [
    {
      "chapter": 12,
      "title": "The Browser Manages the Model",
      "url": "/books/browser-ai-from-first-principles/12-chapter/",
      "excerpt": "The application asks for a capability..."
    }
  ],
  "truncated": false
}

Limit excerpt length, match count and accessible corpus. “Read-only” describes side effects, not disclosure risk.

4. Preserve origin and registration identity

Two sites can register tools with the same name. The effective identity includes origin and registration instance:

https://programmer.ie + search_book + registration-id

The Observatory should snapshot:

• page origin;
• tool definition;
• registration time;
• schema hash;
• whether the source is declarative or imperative;
• removal or replacement.

An agent’s tool list is time-dependent page state.

5. Trace proposal, admission and execution

A tool call is not one event:

agent proposes search_book
        ↓
arguments validated
        ↓
policy admits read-only call
        ↓
application executes
        ↓
result validated and returned

Each transition gets a correlation ID. A rejected argument should remain visible beside the candidate that produced it.

This lets the debugger distinguish poor tool selection from an implementation failure.

6. Test the tool without a model first

Before asking an agent to discover it, test the deterministic contract:

• valid query returns bounded matches;
• unknown query returns an empty result, not fabricated content;
• long query is rejected;
• excessive limit is rejected;
• excerpts come from the indexed book;
• results remain within the registered origin’s corpus.

Only then evaluate model discovery and selection.

This order prevents tool bugs from being misdiagnosed as reasoning failures.

7. The book becomes addressable software

Once the site exposes operations such as:

get_chapter
search_book
find_concept
compare_chapters
run_experiment

the book is no longer merely text displayed in a browser. It has a semantic interface.

The first tool is deliberately modest. It proves that written knowledge can expose bounded operations without giving an agent unrestricted control of the page.

Conclusion

A useful WebMCP tool combines a semantic name, typed inputs, bounded results, application validation and complete trace identity.

search_book gives us a safe first mechanism. The next problem is behavioral: when several plausible tools exist, will an agent discover and choose the correct one?

Sources and further reading

1. Chrome for Developers, WebMCP.
2. Model Context Protocol, Specification.