Evidence — Shopping Assistant 10-Tool Core

The shopping assistant archetype's universal tool set. Every production single-agent shopping assistant in the demo app implements all 10. Vertical-specific additions go ON TOP of these 10.

The 10 tools

1. algolia_search_index (built-in)

The foundation. Single index per shopping assistant. Used by the agent to retrieve real product data with real objectIDs that downstream tools then reference. Always present.

2. suggest_searches — discovery primary

Suggest 1-3 relevant searches with optional facet filters.

{
  "name": "suggest_searches",
  "type": "client_side",
  "description": "Primary discovery tool for suggesting relevant product searches. Use when user wants to explore new products.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "message": { "type": "string", "description": "Friendly intro message" },
      "suggestions": {
        "type": "array",
        "description": "1-3 search suggestions",
        "items": {
          "type": "object",
          "additionalProperties": false,
          "required": ["query", "label", "facets"],
          "properties": {
            "query": { "type": "string" },
            "label": { "type": "string" },
            "facets": {
              "type": "array",
              "items": {
                "type": "object",
                "additionalProperties": false,
                "required": ["attribute", "type", "values"],
                "properties": {
                  "attribute": { "type": "string", "enum": ["gender", "color.original_name", "price.value"] },
                  "type": { "type": "string", "enum": ["list", "range"] },
                  "values": { "type": "array", "items": { "type": "string" } },
                  "value": { "type": "string", "description": "For range facets, 'min:max' format" }
                }
              }
            }
          }
        }
      }
    },
    "required": ["suggestions", "message"]
  }
}

3. suggest_conv_prompts — follow-up prompts

3-4 conversational follow-ups.

{
  "name": "suggest_conv_prompts",
  "type": "client_side",
  "description": "Suggest 3-4 follow-up prompts to guide user conversation",
  "inputSchema": {
    "type": "object",
    "properties": {
      "message": { "type": "string" },
      "initialQuery": { "type": "string" },
      "conversationPrompts": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "prompt": { "type": "string" },
            "type": { "type": "string", "enum": ["refinement", "discovery", "outfit", "general"] }
          },
          "required": ["prompt", "type"]
        }
      }
    },
    "required": ["initialQuery", "conversationPrompts", "message"]
  }
}

4. ui_refinement — filter visible results

Modify visible search results without starting a new search.

{
  "name": "ui_refinement",
  "type": "client_side",
  "description": "Filter or narrow down currently visible results by color, size, price, brand, etc. Do not use for new searches or gender changes.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "message": { "type": "string", "description": "Explains refinements applied AND any omitted because not available" },
      "facets": {
        "type": "array",
        "description": "Include ONLY facets that exist in availableFacets data and are explicitly requested by user",
        "items": {
          "type": "object",
          "additionalProperties": false,
          "required": ["attribute", "type", "configWidgetType"],
          "properties": {
            "attribute": { "type": "string" },
            "type": { "type": "string", "enum": ["list", "hierarchical", "range", "toggle", "numericMenu"] },
            "values": { "type": "array", "items": { "type": "string" } },
            "paths": { "type": "array", "items": { "type": "string" } },
            "value": { "type": "string", "description": "For range, 'min:max'" },
            "configWidgetType": { "type": "string" }
          }
        }
      }
    },
    "required": ["facets", "message"]
  }
}

5. view_product — single PDP

Show detail view of one product.

{
  "name": "view_product",
  "type": "client_side",
  "description": "Show details for a specific product the user wants to view.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "message": { "type": "string" },
      "productId": { "type": "string" },
      "productName": { "type": "string" },
      "productImageUrl": { "type": "string" },
      "productImageAttribute": { "type": "string" }
    },
    "required": ["productId", "productName", "productImageUrl", "message"]
  }
}

6. compare_products — comparison table

Side-by-side comparison with verdict.

{
  "name": "compare_products",
  "type": "client_side",
  "description": "Compare selected products and highlight key differences. Provide a recommendation based on comparison.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "message": { "type": "string" },
      "comparisonText": { "type": "string", "description": "2-3 sentences, ≤300 chars" },
      "table": { "type": "array", "items": { "type": "object" } },
      "recommendation": { "type": "string" },
      "products": {
        "type": "array",
        "items": {
          "type": "object",
          "additionalProperties": false,
          "required": ["objectID", "name", "image", "price"],
          "properties": {
            "objectID": { "type": "string" },
            "name": { "type": "string" },
            "price": { "type": "string" },
            "color": { "type": "string" },
            "brand": { "type": "string" },
            "category": { "type": "string" },
            "rating": { "type": "string" },
            "image": { "type": "string" }
          }
        }
      }
    },
    "required": ["comparisonText", "products", "recommendation", "message"]
  }
}

7. show_products — product cards

Display 5-8 product cards by objectID.

{
  "name": "show_products",
  "type": "client_side",
  "description": "Display product cards in chat using objectIDs from algolia_search_index results. CRITICAL: Only send objectIDs you have retrieved from a search - never invent.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "objectIDs": {
        "type": "array",
        "items": { "type": "string" },
        "minItems": 1,
        "maxItems": 10
      },
      "message": { "type": "string" }
    },
    "required": ["objectIDs"]
  }
}

8. bundle_suggestion — Algolia Recommend wrapper

Related/bought-together products.

{
  "name": "bundle_suggestion",
  "type": "client_side",
  "description": "Suggests products that pair well with a specific item. Use when users ask for complementary items, accessories, or items to complete a set.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "objectID": { "type": "string" },
      "model": { "type": "string", "enum": ["related-products", "bought-together"] },
      "message": { "type": "string" },
      "reason": { "type": "string" }
    },
    "required": ["objectID", "message"]
  }
}

9. trending_items — empty-input "what's hot"

Zero-argument tool, frontend resolves trending from analytics.

{
  "name": "trending_items",
  "type": "client_side",
  "description": "Find the current trending items. Use this whenever trying to find the current trending items.",
  "inputSchema": {
    "type": "object",
    "properties": {},
    "required": []
  }
}

10. welcome_prompts — conversation starters

3-4 starter prompts at session open.

{
  "name": "welcome_prompts",
  "type": "client_side",
  "description": "Generate simple, short conversation starters for a shopping assistant based on demo config.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "message": { "type": "string" },
      "initialQuery": { "type": "string", "description": "Should always be 'welcome_suggestions'" },
      "conversationPrompts": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "prompt": { "type": "string" },
            "type": { "type": "string", "enum": ["discovery", "general", "refinement", "outfit"] }
          },
          "required": ["prompt", "type"]
        }
      }
    },
    "required": ["message", "initialQuery", "conversationPrompts"]
  }
}

Vertical-specific additions

Notes

• Total 10 tools is ABOVE Algolia's official "3-5 max" recommendation. Production assistants exceed this and work because they are heavily prompt-tuned and the tools are well-described.
• For our AskAI-archetype agents (Maverick / Elena / Bruno), the 3-5 ceiling is more directly applicable — we don't need 10+ tools, we need 2-4 render tools.
• The 10-tool core is reference, not template for us. We're not building shopping assistants.