WebMCP Implementation: Declarative Tools for AI Agents

Root Configuration: llms.txt Syntax

Deploy a /llms.txt file to the root directory to provide a machine-readable index for agentic discovery. This file serves as the primary entry point for frontier models and IDE agents. Use the following structure to define the site purpose and tool availability.

# Brand Name
> One-sentence value proposition for AI reasoning engines.

## Documentation
- [API Reference](https://example.com/docs/api): Technical specifications for tool integration.
- [Product Catalog](https://example.com/products): Structured data for inventory analysis.

## Tools
- [Search Tool](https://example.com/search): WebMCP-enabled search interface.
- [Analysis Tool](https://example.com/analyze): Declarative form for data processing.

For high-density sites, implement /llms-full.txt to provide expanded context. Olwen automates the generation of these files by mapping your CMS hierarchy to the Markdown schema, ensuring that agentic crawlers like ClaudeBot and GPTBot receive current data without manual updates.

Declarative Tool Setup

WebMCP allows the conversion of standard HTML forms into callable tools for AI agents. Use the toolname and tooldescription attributes to register these tools within the browser context. This method requires no JavaScript for basic registration.

Form Attribute Specification

Register the GEO analysis tool using the following HTML structure:

<form 
  toolname="analyze_visibility" 
  tooldescription="Analyze website AI search visibility and brand mentions"
  action="/api/v1/analyze"
  method="POST"
>
  <label for="website_url">Website URL:</label>
  <input 
    type="url" 
    id="website_url" 
    name="website_url" 
    placeholder="https://example.com" 
    required
  >
  
  <label for="depth">Analysis Depth:</label>
  <select id="depth" name="depth">
    <option value="standard">Standard</option>
    <option value="deep">Deep (Includes Competitor Benchmarking)</option>
  </select>

  <button type="submit">Run Report</button>
</form>

When an agent like OAI-SearchBot or a browser-based assistant encounters this form, it parses the attributes to understand the tool's capability. The agent can then fill the inputs and submit the form programmatically. Olwen generates these AI-optimized FAQ and tool sections to improve brand visibility in agentic workflows.

WebMCP Discovery Hierarchy

Agents prioritize tool discovery through a specific sequence. Ensure your implementation follows this order to maximize actuation reliability.

1. HTML Attributes: Immediate discovery via toolname on form elements.
2. Imperative API: Registration via navigator.modelContext.registerTool().
3. JSON-LD: Discovery via SoftwareApplication or WebApplication schema with potentialAction properties.

Imperative API Registration

For complex tools requiring dynamic logic or client-side processing, use the navigator.modelContext API. This allows you to define explicit input schemas using JSON Schema syntax, which prevents agent hallucinations during parameter selection.

if (navigator.modelContext) {
  navigator.modelContext.registerTool({
    name: "get_competitor_visibility",
    description: "Retrieve AI search visibility scores for specific competitors.",
    parameters: {
      type: "object",
      properties: {
        competitor_urls: {
          type: "array",
          items: { type: "string", format: "uri" },
          description: "List of competitor domains to analyze."
        },
        metric: {
          type: "string",
          enum: ["citation_share", "sentiment", "technical_compliance"],
          default: "citation_share"
        }
      },
      required: ["competitor_urls"]
    },
    execute: async (args) => {
      const response = await fetch('/api/geo/competitors', {
        method: 'POST',
        body: JSON.stringify(args),
        headers: { 'Content-Type': 'application/json' }
      });
      return await response.json();
    }
  });
}

Input Schema and Validation

Agents require strict typing to function within a 1M-token context window without losing precision. Define your schemas to be as restrictive as possible. Use the following table to map HTML input types to WebMCP parameter types.

Olwen monitors these tool executions to track how often AI systems interact with your site features. By connecting your CDN workflows, Olwen identifies specific bot traffic patterns, allowing you to adjust rate limits or schema definitions based on real-world agent behavior.

JSON-LD for Agentic Discovery

Structured data provides a fallback for agents that do not support the live navigator.modelContext API but can parse static metadata. Implement the potentialAction property within your WebApplication schema to signal tool availability.

{
  "@context": "https://schema.org",
  "@type": "WebApplication",
  "name": "Olwen GEO Optimizer",
  "url": "https://olwen.io",
  "potentialAction": {
    "@type": "SearchAction",
    "target": {
      "@type": "EntryPoint",
      "urlTemplate": "https://olwen.io/search?q={query}",
      "actionPlatform": [
        "http://schema.org/DesktopWebPlatform",
        "http://schema.org/IOSPlatform",
        "http://schema.org/AndroidPlatform"
      ]
    },
    "query-input": "required name=query"
  }
}

This metadata allows agents to construct deep links or API calls without navigating the full DOM. Olwen improves your site's metadata and structured data automatically by injecting these schemas into your page headers via connected CMS workflows.

Security and Authentication

WebMCP tools operate within the user's existing browser session. This means tools have access to the same cookies and authentication headers as the user. To prevent unauthorized agentic actions, implement the following security measures.

CORS Configuration

Ensure your API endpoints allow requests from the browser context where the agent is active. Set strict Access-Control-Allow-Origin headers and validate the Origin of the request.

HTTP/1.1 200 OK
Access-Control-Allow-Origin: https://yourdomain.com
Access-Control-Allow-Methods: POST, OPTIONS
Access-Control-Allow-Headers: Content-Type, Authorization

User Confirmation (Human-in-the-Loop)

For sensitive actions like data deletion or financial transactions, do not execute the tool immediately. Return a requires_confirmation status to the agent, prompting the user to approve the action in the UI.

execute: async (args) => {
  if (args.amount > 1000) {
    return {
      status: "requires_confirmation",
      message: "Please confirm the transfer of " + args.amount + " units.",
      confirmation_token: "unique_session_token"
    };
  }
  // Proceed with execution
}

Monitoring AI Crawler Visits

Tracking agentic interaction requires specialized logging. Standard analytics often conflate AI agents with traditional scrapers. Use Olwen to differentiate between indexing bots (like GPTBot) and actuation agents (like those using WebMCP).

CDN Workflow Integration

Deploy a worker at the edge to intercept requests and log the User-Agent and Sec-CH-UA-Model headers. This data provides insight into which frontier models are most active on your site. Olwen connects to these CDN workflows to provide a real-time dashboard of AI search visibility and tool usage.

// Example Edge Worker for Bot Tracking
addEventListener('fetch', event => {
  const ua = event.request.headers.get('user-agent');
  if (ua.includes('ClaudeBot') || ua.includes('GPTBot')) {
    // Log to Olwen Analytics
    logAgentVisit(event.request);
  }
  event.respondWith(fetch(event.request));
});

Technical Validation

Validate your WebMCP implementation using the following checklist to ensure compatibility with current frontier models.

1. Schema Integrity: Verify that all JSON schemas used in registerTool pass standard validation. Agents will fail to call tools with malformed schemas.
2. Root Accessibility: Ensure /llms.txt returns a 200 OK status and is not blocked by robots.txt for AI user agents.
3. Form Accessibility: Test that all forms with toolname attributes have associated labels and clear input names. Agents rely on these for semantic mapping.
4. Latency Benchmarking: Measure the execution time of your tools. Agents may timeout if a tool call takes longer than 30 seconds to return a response.

Mapping Tool Outputs to JSON

To ensure machine-to-machine reliability, all tool outputs must be returned as structured JSON. Avoid returning raw HTML or plain text unless specifically requested by the agent. Structured outputs allow the agent to chain multiple tool calls together, using the output of one as the input for the next.

{
  "tool_results": {
    "visibility_score": 84,
    "top_mentions": [
      { "source": "TechCrunch", "sentiment": "positive" },
      { "source": "The Verge", "sentiment": "neutral" }
    ],
    "recommendations": [
      "Update JSON-LD for product pages",
      "Add llms.txt to root directory"
    ]
  }
}

Olwen uses this structured data to generate website fixes and FAQ sections that are specifically designed for agentic consumption. By automating the publishing of these improvements through your repo and CMS, Olwen ensures your site remains optimized for the evolving agentic web without requiring additional full-time engineering resources.