> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mcp-b.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Tool lifecycle and dynamic registration

> Why WebMCP tools must be registered, replaced, and removed as page context changes.

A site's valid actions change with route, selected record, permissions, and
workflow state. The published tool set should change with them.

Agents should see only actions that are currently
meaningful and authorized, with descriptions and schemas that match the active
application context.

```mermaid theme={null}
flowchart TD
  Current["Current registration"] -->|"context changes or cleanup"| Abort["Abort the old signal"]
  Abort --> Removed["Old tool is removed"]
  Removed -->|"another tool is valid"| Register["Register replacement<br/>with a new signal"]
  Removed -->|"no tool is valid"| None["No registered tool"]
  Register --> Current
  Removed -. "toolchange" .-> Refresh["Consumers refresh their catalog"]
  Register -. "toolchange" .-> Refresh
```

The current registration pattern ties a tool to an `AbortSignal`:

```ts title="Registration lifetime" theme={null}
const controller = new AbortController();
await document.modelContext?.registerTool(tool, { signal: controller.signal });

// Remove the registration during route or component cleanup.
controller.abort();
```

Duplicate names reject instead of replacing the existing tool. When a route,
description, schema, or permission boundary changes, abort the old registration
before publishing the replacement:

```ts title="Replace a registration" theme={null}
controller.abort();

const nextController = new AbortController();
await document.modelContext?.registerTool(nextTool, {
  signal: nextController.signal,
});
```

The document remains the owner of this lifecycle. Callers do not retain a
separate runtime or server handle. The `toolchange` event lets consumers refresh
their catalog after registration or cleanup.

See [Build your first React tool](/tutorials/first-react-tool) and the
[WebMCP API sources](/reference/webmcp/standard-api).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.