Tool Discovery

Discovery: The First Handshake

Imagine walking into a workshop for the first time. You don't know what tools are available, what they do, or how to use them. The workshop master greets you: "Let me show you around." They walk you through each tool, explain its purpose, and demonstrate proper usage. That's exactly what tool discovery does for AI agents.

When an AI agent connects to MCIP, its first question is always: "What can you do?" This isn't just politeness — it's essential protocol. The agent needs to understand what tools are available, what parameters they accept, and what responses to expect. Without this discovery phase, the agent would be guessing at capabilities that might not exist.

In a single call to tools/list, an agent learns everything it needs to interact with MCIP. Today that means product discovery through semantic search. Tomorrow, as MCIP evolves into a full Machine Customer Interaction Protocol, the same mechanism will reveal cart management, checkout flows, and order tracking — no integration changes required.

---

How It Works: MCP Protocol Discovery

The Standard Mechanism

MCIP implements the Model Context Protocol (MCP) — an open standard for AI agent communication developed by Anthropic. Discovery follows the MCP specification: agents connect via a transport layer, then call tools/list to receive a catalog of everything the server can do.

This isn't a custom MCIP invention. Any MCP-compatible agent — Claude, ChatGPT with MCP support, custom bots — can connect and discover tools without MCIP-specific integration code. That's the power of building on an open protocol standard.

Connecting and Discovering Tools

Here's how an AI agent connects to MCIP and discovers available tools using the MCP SDK:

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';

// 1. Create MCP client
const client = new Client({
  name: 'my-commerce-agent',
  version: '1.0.0',
});

// 2. Connect to MCIP server via transport
const transport = new StdioClientTransport({
  command: 'node',
  args: ['dist/main.js'],
});
await client.connect(transport);

// 3. Discover available tools
const { tools } = await client.listTools();

console.log(`Found ${tools.length} tools:`);
tools.forEach(tool => {
  console.log(`- ${tool.name}: ${tool.description}`);
});

// Output (current implementation):
// Found 1 tools:
// - search_product: Search for products using natural language with semantic understanding.

The tools array contains everything the agent needs: tool names, human-readable descriptions, and full input schemas. The agent doesn't need hardcoded knowledge of MCIP's capabilities — it learns what's available at connection time.

What the Agent Receives

Each tool in the tools/list response is self-describing:

{
  "tools": [
    {
      "name": "search_product",
      "description": "Search for products using natural language with semantic understanding.",
      "inputSchema": {
        "type": "object",
        "properties": {
          "query": {
            "type": "string",
            "minLength": 1,
            "maxLength": 500,
            "description": "Natural language search query"
          },
          "maxResults": {
            "type": "number",
            "minimum": 1,
            "maximum": 100,
            "default": 10,
            "description": "Maximum results to return"
          },
          "filters": {
            "type": "object",
            "properties": {
              "maxPrice": { "type": "number", "description": "Maximum price filter" },
              "minPrice": { "type": "number", "description": "Minimum price filter" },
              "category": { "type": "string", "description": "Category filter" },
              "inStock": { "type": "boolean", "description": "Only show in-stock items" }
            }
          }
        },
        "required": ["query"]
      }
    }
  ]
}

Think of it as a restaurant menu that doesn't just list dishes but includes ingredients, preparation methods, and dietary information. The agent gets everything needed to make informed decisions about which tools to use and how.

---

Calling a Discovered Tool

Once an agent discovers tools, calling them follows the MCP standard:

// Call the discovered search_product tool
const result = await client.callTool({
  name: 'search_product',
  arguments: {
    query: 'gaming laptop under $1500',
    maxResults: 5,
    filters: {
      maxPrice: 1500,
      inStock: true,
    },
  },
});

console.log(result.content);
// Returns product results with relevance scores

The agent doesn't need to know about MCIP's internal architecture — the LangGraph agentic workflows, Qdrant vector search, or BullMQ ingestion pipeline. It just calls tools by name with the parameters the schema described. MCIP handles the complexity behind the scenes.

Two Search Modes, One Tool

Behind search_product, MCIP provides two complementary search modes:

Simple Vector Search — Direct embedding similarity search in Qdrant. Fast, low-latency for straightforward queries. No LLM calls — pure vector search.

Agentic Hard-Filtered Search — The full LangGraph workflow: parallel filter extraction (brand, category, price) via GPT-4o-mini, brand validation against the store catalog via Qdrant facet search, hybrid vector + payload filtering, and LLM verification of results.

The REST API exposes these as separate endpoints (/search and /hard-filtering/search), but through MCP, the agent interacts with a unified search_product tool. The intelligence is in the protocol, not the agent.

---

How MCIP Registers Tools (Server-Side)

If you're building MCIP extensions or contributing tools, here's how tool registration works under the hood.

MCIP uses @rekog/mcp-nest (v1.8.4) — a NestJS integration for the Model Context Protocol. Tools are defined with decorators and Zod schemas:

 import { Tool } from '@rekog/mcp-nest';
import { z } from 'zod';

// Define the parameter schema with Zod
const SearchProductSchema = z.object({
  query: z.string().min(1).max(500).describe('Natural language search query'),
  maxResults: z.number().min(1).max(100).default(10).optional(),
  filters: z.object({
    maxPrice: z.number().positive().optional(),
    minPrice: z.number().positive().optional(),
    category: z.string().optional(),
    inStock: z.boolean().optional(),
  }).optional(),
});

// Register the tool with MCP
@Tool({
  name: 'search_product',
  description: 'Search for products using natural language with semantic understanding.',
  parameters: SearchProductSchema,
})
async searchProduct(params: z.infer<typeof SearchProductSchema>) {
  return this.searchService.search(params);
}

This is the beauty of the approach:

• Zod schemas define both validation rules AND the discovery response. Write the schema once, and agents automatically learn the interface.
• NestJS decorators handle MCP protocol plumbing. No manual JSON-RPC wiring.
• Type safety flows from schema to handler — TypeScript catches mismatches at compile time.

When tools/list is called, @rekog/mcp-nest automatically serializes all registered @Tool decorators into the MCP response. Adding a new tool is as simple as adding another decorated method.

---

Current Tools vs. Roadmap

✅ Available Now

The Bigger Picture

MCIP is a Machine Customer Interaction Protocol — not just a search tool. Product discovery is the first module, but the three-layer architecture (Presentation & Protocol → Application Services → Domain & Infrastructure) is designed for the full commerce lifecycle:

• Phase 1 (Current): Product discovery via search_product
• Phase 2: Cart management (add_to_cart, view_cart, update_cart_item, clear_cart)
• Phase 3: Checkout flows and order tracking
• Phase 4: Personalization and recommendations

Each phase adds new tools to the MCP interface. Agents that already integrate with MCIP will discover new commerce capabilities automatically through the same tools/list call.

---

Discovery Best Practices

Cache Tool Specs, Refresh Periodically

Tool definitions change infrequently — usually only on MCIP version upgrades. Smart agents cache the tools/list response and refresh on reconnection or at reasonable intervals (e.g., daily). This reduces overhead while ensuring new capabilities aren't missed.

Use Descriptions for Routing

The description field in each tool isn't just documentation — it's how AI agents decide which tool to use. When a user says "I need a laptop," the agent reads the description for search_product and knows it's the right tool. When cart tools arrive, "add this to my cart" will naturally route to add_to_cart based on its description.

Handle Unknown Tools Gracefully

As MCIP evolves, new tools will appear. Build agents that discover and adapt rather than hardcoding tool names. Check tools/list for available capabilities rather than assuming a fixed set.

Respect the Schema

Zod schemas aren't just suggestions — they're enforced. Sending invalid parameters returns clear error messages:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The 'maxPrice' field must be a positive number, received -100"
  }
}

Read the schema constraints during discovery to avoid validation errors at call time.

---

Technology Stack