WebMCP Imperative API

👽 Cosmic Companions

Intergalactic Alien Pet Adoption Agency. Browse our catalog of exotic extraterrestrial companions — or let an AI agent find the perfect match for you using WebMCP tools.

10
Species Available
₴250–12,000
Price Range (Galactic Credits)
6
Planets Represented
3
Registered Tools

Available Companions

All Small Medium Large Gentle Chaotic

📡 Agent Tool Log

Real-time log of WebMCP tool invocations. When an AI agent calls a tool, the call and response appear here.

navigator.modelContext
No tool calls yet. Use an agent to interact with this page.

🔎 Imperative API Explained

navigator.modelContext.registerTool()
The core method for the imperative API. You pass it an object with a name, description, inputSchema (JSON Schema for parameters), and an execute function. The browser registers this as a tool that agents can discover and call.
inputSchema — JSON Schema
Defines the parameters the tool accepts using standard JSON Schema. The agent reads this to understand what arguments to pass. Include description fields on each property — this is what the LLM actually reads to decide how to fill in the values.
execute(params) — Returns structured data
This is the big difference from the declarative API. Your execute function receives the agent's parameters, runs your logic, and returns structured data as { content: [{ type: "text", text: "..." }] }. The agent can then reason about the results, chain follow-up calls, or relay findings back to the user in natural language.
Tool chaining pattern
This demo registers three tools that form a natural workflow: search_aliens → get_alien_details → adopt_alien. The agent calls search first, reads the results, picks a candidate, gets more details, and then completes the adoption. Each tool returns data the agent needs for the next step.

📄 Full Tool Registrations

// ── Tool 1: Search Aliens ──
navigator.modelContext.registerTool({
  name: "search_aliens",
  description: "Search the alien pet catalog. Filter by planet of origin,
    size (small/medium/large), temperament (gentle/playful/chaotic/
    independent), special ability, maximum price in Galactic Credits,
    or minimum compatibility score (0-100). Returns a list of matching
    aliens with basic info. Call get_alien_details for full profiles.",
  inputSchema: {
    type: "object",
    properties: {
      planet: {
        type: "string",
        description: "Planet of origin to filter by (e.g., 'Zorbax-7',
          'Krixos Prime', 'Flimora', 'Vexar Minor', 'Grakka',
          'Nebula Drift', 'Zynara', 'Paxia Verdant', 'Xelara')"
      },
      size: {
        type: "string",
        enum: ["small", "medium", "large"],
        description: "Size category to filter by"
      },
      temperament: {
        type: "string",
        enum: ["gentle", "playful", "chaotic", "independent"],
        description: "Temperament to filter by"
      },
      ability: {
        type: "string",
        description: "Special ability to search for (e.g., 'telepathy',
          'shapeshifting', 'fire breath')"
      },
      max_price: {
        type: "number",
        description: "Maximum adoption price in Galactic Credits"
      },
      min_compatibility: {
        type: "number",
        description: "Minimum compatibility score (0-100)"
      }
    }
  },
  async execute(params) {
    const results = searchAliens(params);
    addLog('search_aliens', params, `Found ${results.length} alien(s)`);
    return {
      content: [{ type: "text", text: JSON.stringify({
        totalResults: results.length, aliens: results
      }, null, 2) }]
    };
  }
});


// ── Tool 2: Get Alien Details ──
navigator.modelContext.registerTool({
  name: "get_alien_details",
  description: "Get the full profile of a specific alien pet, including
    detailed bio, diet, care requirements, lifespan, warnings, and
    adoption fee. Requires the alien's ID (e.g., 'zorb-001').
    Use search_aliens first to find IDs.",
  inputSchema: {
    type: "object",
    properties: {
      id: {
        type: "string",
        description: "The unique alien ID (e.g., 'zorb-001', 'krix-002')"
      }
    },
    required: ["id"]
  },
  async execute(params) {
    const details = getAlienDetails(params.id);
    addLog('get_alien_details', params,
      details.error || `${details.name} — ${details.species}`);
    if (!details.error) showDetail(params.id);
    return {
      content: [{ type: "text", text: JSON.stringify(details, null, 2) }]
    };
  }
});


// ── Tool 3: Adopt Alien ──
navigator.modelContext.registerTool({
  name: "adopt_alien",
  description: "Begin the adoption process for an alien pet. This
    navigates to the adoption form page where the adopter's details
    can be filled in. Requires the alien's ID. Use the
    submit_adoption_form tool on the next page to complete
    the adoption.",
  inputSchema: {
    type: "object",
    properties: {
      id: {
        type: "string",
        description: "The unique alien ID to adopt (e.g., 'zorb-001')"
      }
    },
    required: ["id"]
  },
  async execute(params) {
    const a = ALIENS.find(x => x.id === params.id);
    addLog('adopt_alien', params,
      a ? `Navigating to adoption form for ${a.name}...`
        : 'Species not found');
    if (a) window.location.href = `adopt.html?id=${params.id}`;
    return {
      content: [{ type: "text", text: JSON.stringify(
        a ? { status: "navigating_to_form", alien: a.name,
              species: a.species, message: "Redirecting to adoption
              form. Use submit_adoption_form tool on the next
              page to complete the adoption." }
          : { error: "Species not found" }
      ) }]
    };
  }
});