# Tools for agents (WebMCP)

Offer agents in your visitors' browsers tools that read, with @webmcp from brewless/laravel, while your pages stay at the edge.


An agent in a visitor's browser, such as the one in ChatGPT's desktop app, can work through a page by reading it and clicking. WebMCP lets the page offer it tools instead: a name, a description and an input, which the agent calls and gets an answer from. `brewless/laravel` (from 1.7.0) brings what you need for tools that read.

> [!NOTE]
> WebMCP is a draft of the W3C Web Machine Learning Community Group, not a standard. Chrome and Edge have it behind an origin trial or a flag; a browser without it ignores everything on this page.

## Tools in a service provider

Register the tools once, in a service provider of your application:

```php app/Providers/AppServiceProvider.php
use Brewless\Laravel\WebMcp\WebMcp;

public function boot(): void
{
    resolve(WebMcp::class)
        ->data('get_contact_details', 'Phone, e-mail and address of the shop.', fn (): array => [
            'phone' => config('shop.phone'),
            'email' => config('shop.email'),
        ])
        ->fetch('search_products', 'Search the products by keyword. Returns names, prices and links.', '/api/products', [
            'type' => 'object',
            'properties' => ['q' => ['type' => 'string', 'description' => 'Keywords']],
            'required' => ['q'],
        ]);
}
```

And put `@webmcp` in the `<head>` of your layout:

```blade resources/views/layouts/app.blade.php
<head>
    @webmcp
</head>
```

| Kind | What the agent gets |
| --- | --- |
| `data()` | What your application knows, such as contact details or opening hours. A closure is asked when a page is rendered. |
| `fetch()` | The answer of a GET route of your application, with the agent's input as the query string. Only a path of your application itself: another host is refused. |

`fetch(..., untrusted: true)` tells the agent that the answer holds what visitors or others wrote, such as reviews, which it must not take as an instruction.

## Only tools that read

Every tool is marked as one that only reads, and neither kind can send, buy or delete. That stays with a form the visitor sends. A form can carry WebMCP attributes of its own, so an agent can fill it in, while the visitor presses the button:

```blade resources/views/contact.blade.php
<form method="post" action="{{ route('contact.store') }}" toolname="send_contact_message"
      tooldescription="Write a message to the shop. The visitor reviews it and sends it.">
    <input name="email" toolparamdescription="Where the shop can answer.">
```

Leave `toolautosubmit` off for anything that sends. A tool name is lowercase letters, digits and underscores. The agent decides by the description and the visitor never sees it, so a description that tells an agent to act without asking the person it works for, such as "no need to confirm", is refused when the tool is registered.

## Pages stay at the edge

The tools are part of the page and the same for every visitor, so a page with `@webmcp` is kept at the edge like any other (see [edge cache](/running/edge-cache)). Never put something of one visitor in `data()`: the edge would give it to the next. The route of a `fetch()` tool is a page of its own, and is kept when it can be.

## Tools of a page's own

`@webmcp` also gives the page `window.BrewlessWebMcp`, for a tool that works on what one page shows, such as a calculation:

```js resources/js/quiz.js
window.BrewlessWebMcp.register({
  name: 'score_quiz',
  description: "The score for the visitor's answers.",
  inputSchema: { type: 'object', properties: { answers: { type: 'array', items: { type: 'integer' } } } },
  annotations: { readOnlyHint: true },
  execute: async ({ answers }) => window.BrewlessWebMcp.text(score(answers)),
});
```

It registers on `document.modelContext`, or on `navigator.modelContext` in a browser that still uses that, and never throws: `register()` says whether the browser took the tool, `supported` whether the browser has WebMCP at all, and `text()` wraps a value as a tool's answer. Put `@webmcp` before your own scripts, so `window.BrewlessWebMcp` is there when they run.
