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

# Discovery Tools

> Catalog discovery tools — search_products, get_product, list_catalogs, get_catalog_stats.

## search\_products

Search your product catalog using natural language or keyword queries.

**Parameters:**

| Parameter    | Type    | Required | Description                                 |
| ------------ | ------- | -------- | ------------------------------------------- |
| `query`      | string  | Yes      | Search query (natural language or keywords) |
| `limit`      | integer | No       | Max results (default: 10, max: 100)         |
| `catalog_id` | string  | No       | Filter to a specific catalog                |
| `filters`    | object  | No       | Structured filters (see below)              |

**Example:**

<CodeGroup>
  ```bash cURL theme={null}
  # Via MCP tool call (JSON-RPC)
  curl -X POST "https://app.alana.shopping/api/mcp/sse" \
    -H "Authorization: Bearer sk_live_your_api_key" \
    -H "Content-Type: application/json" \
    -d '{"method":"tools/call","params":{"name":"search_products","arguments":{"query":"cotton t-shirt","limit":5}}}'
  ```

  ```javascript JavaScript theme={null}
  const result = await client.callTool({
    name: "search_products",
    arguments: {
      query: "cotton t-shirt",
      limit: 5,
      filters: { availability: "in_stock", min_price: 20 },
    },
  });
  ```

  ```python Python theme={null}
  result = await session.call_tool(
      "search_products",
      arguments={
          "query": "cotton t-shirt",
          "limit": 5,
          "filters": {"availability": "in_stock", "min_price": 20},
      },
  )
  ```
</CodeGroup>

**Response:**

```json theme={null}
{
  "products": [
    {
      "id": "SKU-001",
      "title": "Blue Cotton T-Shirt",
      "price": 29.99,
      "availability": "in_stock",
      "score": 0.94
    }
  ],
  "total": 47,
  "query_time_ms": 23
}
```

***

## get\_product

Retrieve full details for a specific product by ID or SKU.

**Parameters:**

| Parameter          | Type    | Required | Description                              |
| ------------------ | ------- | -------- | ---------------------------------------- |
| `product_id`       | string  | Yes      | Product ID or SKU                        |
| `include_variants` | boolean | No       | Include variant details (default: false) |

<CodeGroup>
  ```javascript JavaScript theme={null}
  const result = await client.callTool({
    name: "get_product",
    arguments: { product_id: "SKU-001", include_variants: true },
  });
  ```

  ```python Python theme={null}
  result = await session.call_tool(
      "get_product",
      arguments={"product_id": "SKU-001", "include_variants": True},
  )
  ```
</CodeGroup>

***

## list\_catalogs

List all catalogs available in your workspace.

**Parameters:**

| Parameter       | Type    | Required | Description                             |
| --------------- | ------- | -------- | --------------------------------------- |
| `include_stats` | boolean | No       | Include product counts (default: false) |

<CodeGroup>
  ```javascript JavaScript theme={null}
  const result = await client.callTool({
    name: "list_catalogs",
    arguments: { include_stats: true },
  });
  ```

  ```python Python theme={null}
  result = await session.call_tool(
      "list_catalogs",
      arguments={"include_stats": True},
  )
  ```
</CodeGroup>

**Response:**

```json theme={null}
{
  "catalogs": [
    { "id": "cat_abc", "name": "Main Catalog", "product_count": 1432 },
    { "id": "cat_def", "name": "Summer 2026", "product_count": 284 }
  ]
}
```

***

## get\_catalog\_stats

Get statistics for a specific catalog.

**Parameters:**

| Parameter    | Type   | Required | Description |
| ------------ | ------ | -------- | ----------- |
| `catalog_id` | string | Yes      | Catalog ID  |

<CodeGroup>
  ```javascript JavaScript theme={null}
  const result = await client.callTool({
    name: "get_catalog_stats",
    arguments: { catalog_id: "cat_abc" },
  });
  ```

  ```python Python theme={null}
  result = await session.call_tool(
      "get_catalog_stats",
      arguments={"catalog_id": "cat_abc"},
  )
  ```
</CodeGroup>

**Response:**

```json theme={null}
{
  "catalog_id": "cat_abc",
  "product_count": 1432,
  "in_stock": 1298,
  "out_of_stock": 134,
  "avg_optimization_score": 0.76,
  "last_updated_at": "2026-03-17T10:00:00Z"
}
```