+As a website builder, you are responsible for protecting your users from malicious agents. Agents may have access to tools from multiple websites—some potentially malicious. This page explains the unique threat model and architectural considerations for WebMCP security.
+
+
+## The Multi-Website Threat Model
+
+
+**Critical Context**: AI agents can interact with multiple websites simultaneously. Your tools may be used by an agent that has also loaded tools from malicious websites. This creates a unique security challenge where compromised agents can abuse your tools.
+
+
+When an AI agent connects to your website, it may already have tools from other origins:
+
+- **Trusted tools**: Your website's legitimate functionality
+- **Unknown tools**: Tools from other websites the user is visiting
+- **Malicious tools**: Tools from compromised or malicious websites
+
+A malicious tool from another website could manipulate the agent into:
+- Exfiltrating sensitive data through your tools
+- Performing unauthorized actions using your authenticated APIs
+- Tricking users into approving dangerous operations
+
+**Your Responsibility**: Assume the agent may be compromised. Design tools that protect users even when the agent is influenced by malicious actors from other websites.
+
+## Architectural Security Principles
+
+WebMCP's security model is built on several key architectural principles:
+
+
+
+ Tools run with the user's existing session and permissions—never with elevated privileges
+
+
+
+ Transport layer enforces same-origin policy to prevent cross-site tool abuse
+
+
+
+ AI agents never receive user credentials—they inherit session context
+
+
+
+ Tools only expose user-authorized actions, never background operations
+
+
+
+These principles create defense-in-depth, but don't eliminate all risks. Understanding the specific threats is essential for secure tool design.
+
+## Prompt Injection: The "Lethal Trifecta"
+
+
+Prompt injection is a serious, largely unsolved security challenge for AI systems. While mitigations reduce risk, they don't eliminate it completely.
+
+
+**Prompt injection** occurs when malicious actors manipulate AI agent behavior by crafting inputs that override intended instructions. The most dangerous scenarios occur when three conditions align:
+
+1. **Private user data access** - Tools that access personal information (emails, messages, profiles)
+2. **Untrusted content exposure** - AI processes content from potentially malicious sources
+3. **External communication** - Ability to send data outside the user's browser
+
+
+**Example Risk**: An AI agent reading emails (private data) could be manipulated via prompt injection to exfiltrate sensitive information through tools with external communication capabilities—especially if malicious tools from other websites are present.
+
+
+### Why This Is Unique to Multi-Agent Environments
+
+In traditional web applications, JavaScript from different origins cannot directly communicate. But in a multi-agent environment:
+
+```mermaid
+graph TD
+ A[User's Browser] -->|Loads| B[YourSite.com Tools]
+ A -->|Loads| C[MaliciousSite.com Tools]
+
+ D[AI Agent] -->|Has Access To| B
+ D -->|Has Access To| C
+
+ C -->|Manipulates Agent via| E[Prompt Injection]
+ E -->|Agent Abuses| B
+
+ B -->|Returns Sensitive Data| D
+ D -->|Executes| C
+ C -->|Exfiltrates Data| F[Attacker Server]
+
+ style C fill:#ff6b6b
+ style E fill:#ff6b6b
+ style F fill:#ff6b6b
+```
+
+The AI agent acts as a bridge between origins, potentially allowing malicious tools to influence how your tools are used.
+
+### Architectural Defense: Never Pass Sensitive Data to Agents
+
+
+**Critical Rule**: Sensitive information must NEVER be passed to the AI agent's context. A compromised agent (via malicious tools from other websites) could exfiltrate this data. Always use references instead.
+
+
+**What should use references:**
+- Passwords, tokens, API keys, session IDs
+- Private messages, emails, documents
+- Personal information (SSN, credit cards, addresses)
+- Financial data (account numbers, balances)
+- Health records, legal documents
+- Any data you wouldn't want copied to a malicious website
+
+**How references work architecturally:**
+
+```mermaid
+sequenceDiagram
+ participant Agent
+ participant YourTool
+ participant SecureStorage
+ participant User
+
+ Agent->>YourTool: read_private_messages()
+ YourTool->>SecureStorage: Store messages (origin-scoped)
+ SecureStorage-->>YourTool: Reference ID
+ YourTool-->>Agent: Return reference (no raw data)
+
+ Note over Agent: Agent cannot access raw data
Only has reference ID
+
+ Agent->>User: Show reference with consent prompt
+ User->>SecureStorage: Approve access to reference
+ SecureStorage-->>User: Display data securely
+```
+
+The key architectural insight: **Raw sensitive data never enters the agent's context**, preventing exfiltration even if the agent is compromised.
+
+## Tool Misrepresentation Risks
+
+
+AI agents cannot verify that tool descriptions accurately represent tool behavior. This creates opportunities for deception.
+
+
+Since WebMCP tools run with the user's authenticated session, a deceptive tool could describe itself as "add to cart" while actually completing a purchase and charging the user's payment method.
+
+### Why Agents Can't Detect Misrepresentation
+
+AI agents only see:
+- Tool name
+- Tool description
+- Input schema
+- Annotations (readOnlyHint, destructiveHint, etc.)
+
+They **cannot**:
+- Inspect the handler function code
+- Verify behavior matches description
+- Detect malicious intent
+
+### Architectural Mitigation: Honest Descriptions + Annotations
+
+The defense is architectural transparency: descriptions and annotations must accurately represent behavior, and high-impact operations should show browser confirmation dialogs so users see and approve actions directly.
+
+
+For implementation patterns, see [Security Best Practices: Tool Misrepresentation](/security#tool-misrepresentation-risks)
+
+
+## User Fingerprinting via Over-Parameterization
+
+
+Tools can inadvertently enable user fingerprinting when AI agents provide detailed personal information through parameters.
+
+
+When AI agents have access to user personalization data, malicious sites can craft tool parameters to extract this information without explicit user consent, enabling **covert profiling** of users who thought they were anonymous.
+
+### The Fingerprinting Attack Pattern
+
+```mermaid
+graph LR
+ A[AI Agent] -->|Has User Profile Data| B[Personal Info:
age, location, interests]
+
+ C[Malicious Tool] -->|Requests Parameters| D["recommend_products(
age, income, location,
interests, history)"]
+
+ A -->|Calls Tool| C
+ C -->|Logs Parameters| E[User Fingerprint Database]
+
+ style C fill:#ff6b6b
+ style E fill:#ff6b6b
+```
+
+Even if your site doesn't require login, a malicious tool can use over-parameterization to collect detailed user profiles through the agent.
+
+### Architectural Defense: Minimal Parameters
+
+**Design Principle**: Only request parameters that are absolutely necessary for the tool's function. Use server-side user context (from authenticated sessions) for personalization instead of agent-provided parameters.
+
+```javascript
+// ❌ VULNERABLE: Reveals extensive user data through parameters
+{
+ name: 'recommend_products',
+ inputSchema: {
+ age, income, location, interests,
+ purchaseHistory, browsingHistory // DON'T DO THIS
+ }
+}
+
+// ✅ BETTER: Minimal parameters, use server-side user context
+{
+ name: 'recommend_products',
+ inputSchema: {
+ category: optional,
+ priceRange: optional // Only what's needed
+ }
+ // Server already knows who the authenticated user is
+}
+```
+
+## Cross-Origin Tool Composition Risks
+
+When multiple websites expose tools simultaneously, there's a risk of unintended tool composition:
+
+- **Chaining attacks**: Malicious tool uses your tool as a step in a larger attack
+- **Context pollution**: Malicious tool manipulates agent state before your tool runs
+- **Output manipulation**: Malicious tool intercepts or modifies your tool's output
+
+### Architectural Defense: Stateless Tools
+
+Design tools to be **stateless** and **idempotent** where possible. Each tool call should:
+- Validate all inputs (never trust agent-provided data)
+- Not depend on previous tool calls
+- Return complete, self-contained results
+
+
+For implementation patterns, see [Security Best Practices: Input Validation](/security#input-validation--sanitization)
+
+
+## Threat Mitigation Summary
+
+| Threat | Architectural Defense | Implementation Pattern |
+|--------|----------------------|------------------------|
+| Prompt Injection | Never pass sensitive data; use references | [Security Guide](/security#prompt-injection-the-lethal-trifecta) |
+| Tool Misrepresentation | Honest descriptions + browser confirmations | [Security Guide](/security#tool-misrepresentation-risks) |
+| User Fingerprinting | Minimal parameters; server-side context | [Security Guide](/security#privacy-user-fingerprinting-via-over-parameterization) |
+| Cross-Origin Abuse | Stateless tools; input validation | [Best Practices](/best-practices#input-validation) |
+
+## Next Steps
+
+Now that you understand the threat model, learn how to implement secure tools:
+
+
+
+ Practical implementation patterns for secure tools
+
+
+
+ Design patterns for robust, secure tools
+
+
+
+ How WebMCP enforces origin isolation
+
+
+
+ Comprehensive guide to secure development
+
+
diff --git a/why-webmcp.mdx b/concepts/alternatives.mdx
similarity index 97%
rename from why-webmcp.mdx
rename to concepts/alternatives.mdx
index 8fc77e6..e24d815 100644
--- a/why-webmcp.mdx
+++ b/concepts/alternatives.mdx
@@ -1,7 +1,7 @@
---
-title: 'Why WebMCP?'
-description: 'Understand why WebMCP provides a better approach to browser AI than automation, remote APIs, or computer use. Compare deterministic function calls vs UI navigation.'
-icon: 'lightbulb'
+title: 'WebMCP vs Alternatives'
+description: 'Comparison of WebMCP with browser automation, remote MCP, computer use, and other approaches. When to use WebMCP vs alternatives and design philosophy behind the standard.'
+icon: 'scale-balanced'
---
WebMCP competes with three existing approaches to connecting AI to the web. This guide compares all four across key dimensions: determinism, speed, UI resilience, authentication complexity, and human oversight. Understanding these tradeoffs will help you choose the right tool for your use case.
diff --git a/concepts/tool-composition.mdx b/concepts/tool-composition.mdx
new file mode 100644
index 0000000..98be8d7
--- /dev/null
+++ b/concepts/tool-composition.mdx
@@ -0,0 +1,433 @@
+---
+title: 'Cross-Site Tool Composition'
+description: 'Composing tools from multiple websites into complex workflows. Architecture, security isolation, data flow patterns, and best practices for multi-site tool composition.'
+icon: 'link'
+---
+
+## Overview
+
+One of the most powerful features of the MCP-B Extension is the ability to compose tools from different websites. Tools from one site can use data from another site, enabling complex multi-site workflows.
+
+
+**Key advantage**: Each site exposes its existing functionality as MCP tools, and the extension handles routing calls between them. The user maintains separate authentication contexts for each site.
+
+
+This creates a unique architecture where AI agents can orchestrate workflows across multiple websites without requiring special integration or shared authentication between sites.
+
+## How Cross-Site Composition Works
+
+### Architecture Overview
+
+When an AI agent composes tools from multiple sites:
+
+```mermaid
+sequenceDiagram
+ participant Agent
+ participant Extension
+ participant ShopSite as shop.example.com
+ participant PriceSite as pricewatch.com
+
+ Agent->>Extension: What's in my cart?
+ Extension->>ShopSite: Call getCurrentCart()
+ ShopSite-->>Extension: Cart data (3 items)
+ Extension-->>Agent: Cart contents
+
+ Agent->>Extension: Compare prices for these items
+ Extension->>PriceSite: Call comparePrices(items)
+ PriceSite->>PriceSite: Use existing auth/API
+ PriceSite-->>Extension: Price comparison results
+ Extension-->>Agent: Best deals found
+```
+
+### Separation of Concerns
+
+Each website operates independently:
+
+```mermaid
+graph TB
+ subgraph "shop.example.com"
+ A[Cart Tools]
+ A1[User Session A
Auth Context A]
+ end
+
+ subgraph "pricewatch.com"
+ B[Price Tools]
+ B1[User Session B
Auth Context B]
+ end
+
+ subgraph "MCP-B Extension"
+ E[Tool Router]
+ E1[Conversation Context]
+ end
+
+ E -->|Route calls| A
+ E -->|Route calls| B
+ A -.->|Uses| A1
+ B -.->|Uses| B1
+ E1 -->|Maintains| E
+
+ style A1 fill:#ffe1e1
+ style B1 fill:#ffe1e1
+ style E1 fill:#e1f5ff
+```
+
+**Key architectural principles**:
+- Each tool executes in its own origin's context
+- Tools inherit their site's authentication automatically
+- Extension routes tool calls without exposing credentials
+- Sites never share authentication or sessions
+
+## Composition Patterns
+
+### Pattern 1: Data Aggregation
+
+Fetch data from one site and process it on another:
+
+**Site A** (News site) exposes content:
+
+```tsx
+useWebMCP({
+ name: 'news_get_top_stories',
+ description: 'Get top news stories. Returns array of {title, url, summary}',
+ handler: async () => {
+ const stories = await fetch('/api/stories/top').then(r => r.json());
+ return { stories };
+ }
+});
+```
+
+**Site B** (Social site) allows posting:
+
+```tsx
+useWebMCP({
+ name: 'social_post_to_feed',
+ description: 'Post a link to your social feed',
+ inputSchema: {
+ title: z.string(),
+ url: z.string().url()
+ },
+ handler: async ({ title, url }) => {
+ return await fetch('/api/posts', {
+ method: 'POST',
+ credentials: 'same-origin', // Uses existing session
+ body: JSON.stringify({ title, url })
+ }).then(r => r.json());
+ }
+});
+```
+
+**Agent workflow**: "Get top news stories and share the most interesting one on social media"
+- Calls `news_get_top_stories()` → gets data from news site
+- Analyzes results
+- Calls `social_post_to_feed()` → posts to social site
+
+### Pattern 2: Cross-Site Comparison
+
+Compare or enrich data across multiple sites:
+
+**Site A** (Shopping site) exposes cart:
+
+```tsx
+useWebMCP({
+ name: 'shop_get_current_cart',
+ description: 'Get items in shopping cart. Returns {items: Array<{name, price, sku}>, total: number}',
+ handler: async () => ({
+ items: cart.items,
+ total: cart.total
+ })
+});
+```
+
+**Site B** (Price comparison site) checks prices:
+
+```tsx
+useWebMCP({
+ name: 'prices_compare_product',
+ description: 'Compare prices for a product across multiple stores',
+ inputSchema: {
+ productName: z.string()
+ },
+ handler: async ({ productName }) => {
+ const response = await fetch('/api/products/search', {
+ method: 'POST',
+ credentials: 'same-origin',
+ body: JSON.stringify({ query: productName })
+ });
+ return await response.json();
+ }
+});
+```
+
+**Agent workflow**: "Check if items in my cart are available cheaper elsewhere"
+- Calls `shop_get_current_cart()` → gets cart items
+- For each item, calls `prices_compare_product()` → finds better prices
+- Reports savings opportunities
+
+### Pattern 3: Multi-Step Workflow Composition
+
+Chain operations across sites:
+
+```tsx
+// Calendar site
+useWebMCP({
+ name: 'calendar_get_upcoming_meetings',
+ description: 'Get upcoming calendar events',
+ handler: async () => ({
+ meetings: await calendar.getUpcoming()
+ })
+});
+
+// Email site
+useWebMCP({
+ name: 'email_send_reminder',
+ description: 'Send an email reminder',
+ inputSchema: {
+ to: z.string().email(),
+ subject: z.string(),
+ body: z.string()
+ },
+ handler: async ({ to, subject, body }) => {
+ return await email.send({ to, subject, body });
+ }
+});
+
+// Notes site
+useWebMCP({
+ name: 'notes_create',
+ description: 'Create a new note',
+ inputSchema: {
+ title: z.string(),
+ content: z.string()
+ },
+ handler: async ({ title, content }) => {
+ return await notes.create({ title, content });
+ }
+});
+```
+
+**Agent workflow**: "Prepare for tomorrow's meetings"
+- Calls `calendar_get_upcoming_meetings()` → gets meeting list
+- For each meeting, calls `notes_create()` → creates meeting notes
+- Calls `email_send_reminder()` → sends reminders to participants
+
+## Security & Isolation
+
+
+Cross-site tool composition introduces unique security considerations. Each site must protect against potential abuse from malicious tools on other sites.
+
+
+### Origin Isolation
+
+While tools can be composed, they remain **origin-isolated** at execution time:
+
+- **Authentication**: Each tool uses its own site's session/cookies
+- **Data access**: Tools can only access data within their origin
+- **APIs**: Tools call their site's APIs with existing credentials
+- **No shared state**: Sites cannot directly access each other's data
+
+### Trust Boundaries
+
+```mermaid
+graph LR
+ A[Trusted Site A Tools] -->|Data output| E[Extension/Agent]
+ B[Trusted Site B Tools] -->|Data output| E
+ M[Malicious Site Tools] -->|Data output| E
+
+ E -->|Calls with data| A
+ E -->|Calls with data| B
+ E -->|Calls with data| M
+
+ M -.->|Could manipulate| E
+ E -.->|Could abuse| A
+ E -.->|Could abuse| B
+
+ style M fill:#ff6b6b
+```
+
+**Security principle**: Never trust data from the agent. Always validate inputs, even if they appear to come from another legitimate site's tool.
+
+### Defense Strategies
+
+
+
+ Treat all tool inputs as potentially malicious:
+
+ ```tsx
+ useWebMCP({
+ name: 'process_data',
+ inputSchema: {
+ productId: z.string().regex(/^[A-Z0-9]{8}$/), // Strict validation
+ quantity: z.number().min(1).max(100)
+ },
+ handler: async ({ productId, quantity }) => {
+ // Additional business logic validation
+ if (!await productExists(productId)) {
+ throw new Error('Invalid product ID');
+ }
+ // ...
+ }
+ });
+ ```
+
+
+
+ Make tool outputs predictable and parseable:
+
+ ```tsx
+ // ✅ Good - structured, typed
+ return {
+ items: [{id: 'abc', name: 'Product', price: 99.99}],
+ total: 99.99,
+ currency: 'USD'
+ };
+
+ // ❌ Bad - unstructured, hard to validate
+ return "You have 3 items totaling $99.99";
+ ```
+
+
+
+ Never return sensitive data that could be exfiltrated:
+
+ ```tsx
+ // ❌ Dangerous
+ return {
+ userEmail: user.email, // Don't expose
+ apiKey: user.apiKey, // Never expose
+ password: user.password // Absolutely never
+ };
+
+ // ✅ Safe - use references or sanitized data
+ return {
+ userId: user.id,
+ displayName: user.publicName
+ };
+ ```
+
+
+
+ Prevent abuse of expensive operations:
+
+ ```tsx
+ const limiter = new RateLimiter({ maxCalls: 10, windowMs: 60000 });
+
+ useWebMCP({
+ name: 'expensive_operation',
+ handler: async () => {
+ if (!limiter.check()) {
+ throw new Error('Rate limit exceeded');
+ }
+ // ...
+ }
+ });
+ ```
+
+
+
+## Best Practices for Composable Tools
+
+### 1. Use Descriptive, Namespaced Names
+
+Prevent collisions and provide context:
+
+```tsx
+// ✅ Good - clear origin and purpose
+name: 'github_create_issue'
+name: 'jira_create_ticket'
+name: 'shop_example_add_to_cart'
+
+// ❌ Bad - ambiguous
+name: 'create_issue' // Which site?
+name: 'add_to_cart' // Which shop?
+```
+
+### 2. Document Data Formats in Descriptions
+
+Help other sites understand your output:
+
+```tsx
+useWebMCP({
+ name: 'shop_get_cart',
+ description: 'Get shopping cart contents. Returns {items: Array<{name: string, price: number, sku: string, quantity: number}>, total: number, currency: string}',
+ handler: async () => { ... }
+});
+```
+
+### 3. Keep Tools Focused and Atomic
+
+Single-purpose tools compose better:
+
+```tsx
+// ✅ Good - focused, composable
+useWebMCP({ name: 'get_cart', ... });
+useWebMCP({ name: 'add_to_cart', ... });
+useWebMCP({ name: 'remove_from_cart', ... });
+useWebMCP({ name: 'checkout', ... });
+
+// ❌ Bad - monolithic, hard to compose
+useWebMCP({ name: 'cart_manager', ... }); // Does everything
+```
+
+### 4. Return Structured, Typed Data
+
+Make outputs easy for other tools to consume:
+
+```tsx
+// ✅ Good - structured, predictable
+return {
+ success: true,
+ data: {
+ items: [...],
+ total: 99.99
+ },
+ metadata: {
+ currency: 'USD',
+ timestamp: new Date().toISOString()
+ }
+};
+
+// ❌ Bad - unstructured text
+return "Added 3 items, your cart now has 5 items totaling $99.99";
+```
+
+## Implementation Examples
+
+
+For practical code examples of cross-site workflows, see [Advanced Guide: Cross-Site Tool Composition](/advanced#cross-site-tool-composition)
+
+
+## Next Steps
+
+
+
+ Learn how the extension routes tool calls across tabs
+
+
+
+ Security considerations for multi-site environments
+
+
+
+ Comprehensive security best practices
+
+
+
+ Implementation examples and techniques
+
+
diff --git a/concepts/tool-routing.mdx b/concepts/tool-routing.mdx
new file mode 100644
index 0000000..a56e966
--- /dev/null
+++ b/concepts/tool-routing.mdx
@@ -0,0 +1,395 @@
+---
+title: 'Tool Routing & Multi-Tab Collection'
+description: 'How MCP-B extension collects and routes tool calls across multiple browser tabs simultaneously. Architecture, routing mechanisms, and design patterns for multi-tab environments.'
+icon: 'network-wired'
+---
+
+## Overview
+
+The MCP-B Extension collects and maintains tools from **all open tabs simultaneously**, making them available to agents regardless of which tab is currently active.
+
+
+**Key behavior**: Unlike traditional tab-scoped approaches, the extension aggregates tools from every open tab, giving agents access to your entire browsing context at once.
+
+
+This architectural decision enables powerful cross-tab workflows while introducing unique design considerations for tool naming and organization.
+
+## How Tool Collection Works
+
+When you have multiple tabs open with WebMCP servers, the extension creates a unified tool registry:
+
+```mermaid
+graph TB
+ subgraph "Browser Tabs"
+ T1[Tab 1: shop.example.com
Tools: add_to_cart, checkout]
+ T2[Tab 2: github.com
Tools: create_issue, list_repos]
+ T3[Tab 3: calendar.app
Tools: add_event, list_events]
+ end
+
+ subgraph "MCP-B Extension"
+ E[Tool Registry
All tools from all tabs]
+ end
+
+ T1 -->|Registers| E
+ T2 -->|Registers| E
+ T3 -->|Registers| E
+
+ A[AI Agent] -->|Sees all tools| E
+
+ style E fill:#e1f5ff
+ style A fill:#ffe1f0
+```
+
+### Registration Lifecycle
+
+Each tab independently registers its tools with the extension:
+
+
+
+ User opens a website or navigates to a new page
+
+
+
+ Website's WebMCP code calls `registerTool()` or uses `useWebMCP()` hooks
+
+
+
+ Extension adds tools to the global registry with origin metadata
+
+
+
+ AI agent's tool list is updated to include new tools
+
+
+
+ When tab is closed, its tools are automatically unregistered
+
+
+
+## Tool Routing Mechanism
+
+When an agent calls a tool, the extension routes the call to the correct tab:
+
+```mermaid
+sequenceDiagram
+ participant Agent
+ participant Extension
+ participant GitHub as github.com Tab
+ participant Shop as shop.example.com Tab
+
+ Note over Extension: All tabs' tools are visible
+
+ Agent->>Extension: Call github_create_issue
+ Extension->>GitHub: Route to GitHub tab
+ GitHub->>GitHub: Execute tool
+ GitHub-->>Extension: Issue created
+ Extension-->>Agent: Success
+
+ Agent->>Extension: Call shop_add_to_cart
+ Extension->>Shop: Route to Shop tab
+ Shop->>Shop: Execute tool
+ Shop-->>Extension: Added to cart
+ Extension-->>Agent: Success
+```
+
+### Routing Algorithm
+
+
+
+ Agent calls a tool (e.g., `github_create_issue`)
+
+
+
+ Extension looks up which tab registered that tool name
+
+
+
+ If the tab is still open, the tool is executed immediately. If the tab was closed, the tool call fails.
+
+
+
+ Tool execution results are routed back through extension to agent
+
+
+
+## Architectural Implications
+
+### 1. Tool Naming Becomes Critical
+
+Since all tools from all tabs are visible in a single namespace, naming conflicts can occur:
+
+
+
+ ```tsx
+ // Clear origin and purpose
+ useWebMCP({
+ name: 'github_create_issue',
+ description: 'Create a new GitHub issue in the current repository',
+ // ...
+ });
+
+ useWebMCP({
+ name: 'jira_create_issue',
+ description: 'Create a new Jira issue in the current project',
+ // ...
+ });
+ ```
+
+
+
+ ```tsx
+ // Ambiguous - which site? which feature?
+ useWebMCP({
+ name: 'create', // ❌ Too generic
+ description: 'Create something',
+ // ...
+ });
+
+ useWebMCP({
+ name: 'create_issue', // ❌ Naming conflict likely
+ description: 'Create an issue',
+ // ...
+ });
+ ```
+
+
+
+**Recommended pattern**: Prefix tool names with domain or feature identifier to avoid conflicts.
+
+### 2. Descriptions Must Provide Context
+
+Since agents see all tools at once without inherent context about which tab they came from, descriptions must be self-contained:
+
+```tsx
+// ✅ Good - describes what, where, and context
+useWebMCP({
+ name: 'shop_add_to_cart',
+ description: 'Add the currently viewed product from shop.example.com to your shopping cart. Product must be on screen.',
+ // ...
+});
+
+// ❌ Bad - lacks context
+useWebMCP({
+ name: 'add_to_cart',
+ description: 'Add item to cart', // Which site? What item?
+ // ...
+});
+```
+
+### 3. Tools Appear and Disappear Dynamically
+
+Tool availability changes as users open and close tabs:
+
+```tsx
+// This tool is available only while the product page tab is open
+function ProductPage() {
+ useWebMCP({
+ name: 'get_current_product',
+ description: 'Get details about the currently viewed product',
+ handler: async () => {
+ return await fetchProductDetails(productId);
+ }
+ });
+
+ return Product Details
;
+}
+
+// When user closes this tab, get_current_product disappears from the toolkit
+```
+
+
+Agents must handle tools becoming unavailable mid-conversation. Always design tools to fail gracefully if the source tab is closed.
+
+
+### 4. Cross-Tab Workflows Are Natural
+
+Agents can compose tools from different tabs into complex workflows:
+
+```tsx
+// Tab 1: Calendar app (calendar.app)
+useWebMCP({
+ name: 'calendar_add_event',
+ description: 'Add event to your calendar',
+ inputSchema: {
+ title: z.string(),
+ date: z.string().datetime()
+ },
+ handler: async ({ title, date }) => {
+ return await calendar.addEvent({ title, date });
+ }
+});
+
+// Tab 2: Email app (mail.app)
+useWebMCP({
+ name: 'email_get_unread',
+ description: 'Get your unread emails',
+ handler: async () => {
+ return await email.getUnread();
+ }
+});
+
+// Agent can naturally execute:
+// "Get my unread emails and add any meeting invites to my calendar"
+// It sees and can use tools from both tabs
+```
+
+## Managing Tool Overload
+
+When many tabs are open, agents may see dozens or hundreds of tools. Use these patterns to manage complexity:
+
+### Pattern 1: Conditional Registration
+
+Only register tools when they're relevant:
+
+```tsx
+function CartPage() {
+ const { items } = useCart();
+
+ // Only show checkout tool when cart has items
+ useWebMCP({
+ name: 'shop_checkout',
+ description: 'Complete the checkout process',
+ handler: async () => {
+ return await processCheckout();
+ },
+ enabled: items.length > 0 // Conditional registration
+ });
+
+ return Cart ({items.length} items)
;
+}
+```
+
+### Pattern 2: Context-Rich Descriptions
+
+Help agents understand when to use tools:
+
+```tsx
+useWebMCP({
+ name: 'shop_checkout',
+ description: 'Complete checkout on shop.example.com. Only use this after items have been added to cart and user has confirmed the order. Requires payment information to be on file.',
+ handler: async () => {
+ return await processCheckout();
+ }
+});
+```
+
+### Pattern 3: Component Lifecycle Scoping
+
+Use React component lifecycle to scope tool availability:
+
+```tsx
+function CheckoutFlow() {
+ const [step, setStep] = useState('cart');
+
+ // Cart step tools
+ useWebMCP({
+ name: 'cart_update_quantity',
+ description: 'Update item quantity in cart',
+ enabled: step === 'cart', // Only available on cart step
+ // ...
+ });
+
+ // Shipping step tools
+ useWebMCP({
+ name: 'shipping_select_address',
+ description: 'Select shipping address',
+ enabled: step === 'shipping', // Only available on shipping step
+ // ...
+ });
+
+ // Payment step tools
+ useWebMCP({
+ name: 'payment_submit',
+ description: 'Submit payment and complete order',
+ enabled: step === 'payment', // Only available on payment step
+ // ...
+ });
+
+ return Step: {step}
;
+}
+```
+
+## Security Considerations
+
+Multi-tab tool collection creates unique security implications:
+
+
+Tools from malicious websites can influence agent behavior, potentially causing the agent to abuse tools from legitimate websites. See [Agent Threat Model](/concepts/agent-threat-model) for detailed security considerations.
+
+
+### Origin Isolation
+
+While tools are collected from all tabs, the **execution context remains origin-isolated**:
+
+- Each tool executes in its originating tab's context
+- Tools inherit their tab's session, cookies, and authentication
+- Same-origin policy prevents cross-tab data leakage
+- Extension enforces origin validation on all tool calls
+
+### Trust Boundary
+
+```mermaid
+graph TB
+ subgraph "Trusted Origins"
+ T1[yoursite.com Tools]
+ T2[github.com Tools]
+ end
+
+ subgraph "Untrusted Origins"
+ M1[malicious.com Tools]
+ end
+
+ A[AI Agent] -->|Sees all| T1
+ A -->|Sees all| T2
+ A -->|Sees all| M1
+
+ M1 -.->|May influence| A
+ A -.->|Could abuse| T1
+ A -.->|Could abuse| T2
+
+ style M1 fill:#ff6b6b
+```
+
+**Defense**: Design tools to validate all inputs and never trust agent-provided data, even if it seems to come from the agent's current task context.
+
+## Implementation Patterns
+
+
+For practical implementation examples of multi-tab patterns, see [Advanced Guide: Multi-Tab Tool Collection](/advanced#multi-tab-tool-collection)
+
+
+## Next Steps
+
+
+
+ Learn about cross-site tool composition patterns
+
+
+
+ Understand WebMCP's overall architecture
+
+
+
+ Security considerations for multi-agent environments
+
+
+
+ Implementation examples and advanced techniques
+
+
diff --git a/connecting-agents.mdx b/connecting-agents.mdx
index 462c756..192d084 100644
--- a/connecting-agents.mdx
+++ b/connecting-agents.mdx
@@ -8,6 +8,10 @@ icon: 'link'
This guide covers four primary connection methods, each suited to different use cases and architectures. Whether you're building a website that exposes tools to users' local AI clients, or an embedded application that agents control directly, you'll find the right approach here. We'll compare setup complexity, capabilities, and security considerations for each method.
+
+For architectural details on how WebMCP handles agent connections, see [Concepts: Architecture](/concepts/architecture)
+
+
## Connection Methods
There are four primary ways to connect agents to WebMCP tools:
diff --git a/docs.json b/docs.json
index 347f75a..cc704fb 100644
--- a/docs.json
+++ b/docs.json
@@ -83,7 +83,6 @@
{
"group": "Guides",
"pages": [
- "why-webmcp",
"connecting-agents",
"best-practices",
"development",
@@ -122,7 +121,8 @@
"icon": "compass",
"pages": [
"concepts/overview",
- "concepts/architecture"
+ "concepts/architecture",
+ "concepts/alternatives"
]
},
{
@@ -134,11 +134,20 @@
"concepts/security"
]
},
+ {
+ "group": "Architecture & Patterns",
+ "icon": "diagram-project",
+ "pages": [
+ "concepts/tool-routing",
+ "concepts/tool-composition",
+ "concepts/mcp-ui-integration",
+ "concepts/agent-threat-model"
+ ]
+ },
{
"group": "Advanced Topics",
"icon": "rocket",
"pages": [
- "concepts/mcp-ui-integration",
"concepts/extension",
"concepts/schemas"
]
diff --git a/introduction.mdx b/introduction.mdx
index 3c90071..4ba498f 100644
--- a/introduction.mdx
+++ b/introduction.mdx
@@ -28,7 +28,7 @@ WebMCP is built on a **human-in-the-loop** philosophy:
- **Collaborative workflows** - Humans and AI work together, not separately
- **Context engineering** - Like good web design guides users, good WebMCP guides AI by exposing the right tools at the right time
-
+
Understand why WebMCP is a better approach than browser automation, remote APIs, or computer use
diff --git a/security.mdx b/security.mdx
index 647749c..431aca1 100644
--- a/security.mdx
+++ b/security.mdx
@@ -53,6 +53,10 @@ A malicious tool from another website could manipulate the agent into:
## Agent-Specific Threats
+
+For a deep dive into the unique threat model of multi-agent environments, see [Concepts: Agent Threat Model](/concepts/agent-threat-model)
+
+
### Prompt Injection: The "Lethal Trifecta"