Design Tools For Voice, Not Text

// Tool 1: Search
async function searchFlights(origin, destination, date) {
  return await db.flights.find({ origin, destination, date });
}

// Tool 2: Filter
async function filterFlights(results, criteria) {
  return results.filter(f => meetsCriteria(f, criteria));
}

// Tool 3: Sort
async function sortFlights(results, sortBy) {
  return results.sort((a, b) => compare(a, b, sortBy));
}

// Tool 4: Paginate
async function paginateFlights(results, page, size) {
  return results.slice(page * size, (page + 1) * size);
}

// Tool 5: Select
async function selectFlight(flightId) {
  return await db.flights.findById(flightId);
}

// Single tool: Find best match
async function findBestFlight(criteria) {
  // Encapsulates: search, filter, sort, rank, select
  const flights = await db.flights.find({
    origin: criteria.origin,
    destination: criteria.destination,
    date: criteria.date
  });
  
  const filtered = flights.filter(f => 
    matchesPreferences(f, criteria.preferences)
  );
  
  const ranked = rankByRelevance(filtered, criteria);
  
  return {
    best_match: ranked[0],
    alternatives: ranked.slice(1, 3),
    why_best: explainRanking(ranked[0], criteria)
  };
}

const tools = [
  {
    type: 'function',
    name: 'search_products',
    description: 'Search product catalog',
    parameters: {
      type: 'object',
      properties: {
        query: { type: 'string' },
        category: { type: 'string' }
      }
    }
  },
  {
    type: 'function',
    name: 'filter_products',
    description: 'Filter product list by criteria',
    parameters: {
      type: 'object',
      properties: {
        products: { type: 'array' },
        max_price: { type: 'number' },
        min_rating: { type: 'number' }
      }
    }
  },
  {
    type: 'function',
    name: 'sort_products',
    description: 'Sort product list',
    parameters: {
      type: 'object',
      properties: {
        products: { type: 'array' },
        sort_by: { type: 'string', enum: ['price', 'rating', 'popularity'] }
      }
    }
  }
];

// Agent makes 3+ tool calls for simple request

const tools = [
  {
    type: 'function',
    name: 'find_product_recommendation',
    description: `Find the best product match for user needs. 
                  Handles search, filtering, sorting, and ranking internally.
                  Returns: best match + 2 alternatives + explanation.`,
    parameters: {
      type: 'object',
      properties: {
        user_need: { 
          type: 'string',
          description: 'What the user is looking for, in their own words'
        },
        constraints: {
          type: 'object',
          properties: {
            max_price: { type: 'number' },
            category: { type: 'string' },
            required_features: { type: 'array', items: { type: 'string' } }
          }
        },
        preferences: {
          type: 'object',
          properties: {
            prioritize: { 
              type: 'string', 
              enum: ['price', 'quality', 'speed', 'popularity'],
              description: 'What matters most to the user'
            }
          }
        }
      },
      required: ['user_need']
    }
  }
];

// Agent makes 1 tool call, gets complete answer

import { RealtimeClient } from '@openai/realtime-api-beta';

class VoiceOptimizedTools {
  constructor() {
    this.client = new RealtimeClient({ apiKey: process.env.OPENAI_API_KEY });
  }

  async setupVoiceAgent() {
    await this.client.connect();
    
    // Register high-level tool
    await this.client.updateSession({
      tools: [
        {
          type: 'function',
          name: 'find_product_recommendation',
          description: `Find best product for user needs. Encapsulates: 
                        search, filter, rank, compare. Returns ready-to-speak 
                        recommendation with explanation.`,
          parameters: {
            type: 'object',
            properties: {
              user_need: { type: 'string' },
              max_price: { type: 'number' },
              category: { type: 'string' },
              prioritize: { 
                type: 'string', 
                enum: ['price', 'quality', 'speed'] 
              }
            }
          }
        }
      ],
      instructions: `
You are a helpful shopping assistant. When users describe what they need,
use find_product_recommendation ONCE to get a complete answer. Don't make
multiple tool calls - the tool handles everything internally.

After getting the recommendation, present it conversationally:
"I found a great option for you: [product]. It's [why it's good]. 
 I also have [alternative 1] and [alternative 2] if you want to compare."
`,
      voice: 'alloy',
      modalities: ['audio']
    });

    // Handle tool calls
    this.client.on('conversation.item.input_audio_transcription.completed', 
      async (event) => {
        console.log('User said:', event.transcript);
      }
    );

    this.client.on('response.function_call_arguments.done', async (event) => {
      if (event.name === 'find_product_recommendation') {
        const result = await this.findProductRecommendation(
          JSON.parse(event.arguments)
        );
        
        // Return result to agent
        await this.client.sendItemContent([{
          type: 'function_call_output',
          call_id: event.call_id,
          output: JSON.stringify(result)
        }]);
      }
    });
  }

  async findProductRecommendation(params) {
    // HIGH-LEVEL TOOL: Encapsulates entire workflow
    
    // Step 1: Search (internal, user doesn't hear this)
    const allProducts = await this.searchProducts(params.user_need, params.category);
    
    // Step 2: Filter (internal)
    const filtered = this.filterProducts(allProducts, {
      max_price: params.max_price,
      min_rating: 4.0  // default quality threshold
    });
    
    // Step 3: Rank (internal)
    const ranked = this.rankProducts(filtered, params.prioritize || 'quality');
    
    // Step 4: Select best + alternatives
    const best = ranked[0];
    const alternatives = ranked.slice(1, 3);
    
    // Step 5: Generate explanation
    const explanation = this.explainRecommendation(best, params);
    
    // Return everything agent needs to speak naturally
    return {
      recommendation: {
        name: best.name,
        price: best.price,
        rating: best.rating,
        key_features: best.features.slice(0, 3),
        why_recommended: explanation
      },
      alternatives: alternatives.map(p => ({
        name: p.name,
        price: p.price,
        key_difference: this.compareToRecommendation(p, best)
      })),
      search_summary: `Found ${allProducts.length} products, narrowed to ${filtered.length} matches`
    };
  }

  async searchProducts(query, category) {
    // Your actual search logic
    return await db.products.find({
      $text: { $search: query },
      category: category
    }).limit(100);
  }

  filterProducts(products, constraints) {
    return products.filter(p => 
      (!constraints.max_price || p.price <= constraints.max_price) &&
      (!constraints.min_rating || p.rating >= constraints.min_rating)
    );
  }

  rankProducts(products, prioritize) {
    const scoreFunctions = {
      price: (p) => 1 / p.price,  // lower is better
      quality: (p) => p.rating * p.review_count,
      speed: (p) => p.shipping_days < 2 ? 10 : 1,
      popularity: (p) => p.sales_rank
    };
    
    const scoreFunc = scoreFunctions[prioritize] || scoreFunctions.quality;
    
    return products
      .map(p => ({ ...p, score: scoreFunc(p) }))
      .sort((a, b) => b.score - a.score);
  }

  explainRecommendation(product, params) {
    const reasons = [];
    
    if (params.prioritize === 'price') {
      reasons.push(`best value at $${product.price}`);
    } else if (params.prioritize === 'quality') {
      reasons.push(`highly rated (${product.rating} stars from ${product.review_count} reviews)`);
    }
    
    if (product.features.some(f => params.user_need.toLowerCase().includes(f.toLowerCase()))) {
      reasons.push(`has the features you mentioned`);
    }
    
    return reasons.join(', ');
  }

  compareToRecommendation(alternative, best) {
    if (alternative.price < best.price * 0.8) {
      return `much cheaper at $${alternative.price}`;
    } else if (alternative.rating > best.rating) {
      return `higher rated (${alternative.rating} stars)`;
    } else {
      return `different feature set`;
    }
  }
}

// Usage
const voiceTools = new VoiceOptimizedTools();
await voiceTools.setupVoiceAgent();

// User: "I need a laptop for video editing under $2000"
// Agent makes 1 tool call, gets complete recommendation, speaks naturally

// ❌ Operation-based (text agent style)
await searchUsers();
await filterByRole();
await sortByActivity();
await selectTop5();

// ✅ Task-based (voice agent style)
await findRelevantTeamMembers({ task: 'code review', skills: ['TypeScript'] });

// ❌ Returns raw data
{
  results: [...],
  total: 47,
  page: 1
}

// ✅ Returns presentation-ready data
{
  top_match: { name: "...", why: "..." },
  alternatives: [ ... ],
  summary: "Found 3 great options out of 47 total",
  next_question: "Would you like to hear more about the top choice?"
}

// ❌ Agent forgets what it found
{
  result: { id: 123, name: "Product A" }
}

// ✅ Agent remembers for follow-up questions
{
  result: { id: 123, name: "Product A" },
  context: {
    search_query: "wireless headphones under $200",
    alternatives_ids: [124, 125],
    why_chosen: "best battery life in price range"
  },
  follow_up_suggestions: [
    "Check shipping time",
    "Compare to alternatives",
    "Add to cart"
  ]
}

// ❌ Requires separate tool call for each action
await getProduct(id);
await checkInventory(id);
await getShipping(id);

// ✅ Returns everything user likely needs next
await getProductDetails(id) {
  return {
    product: { ... },
    in_stock: true,
    ships_in: "2 days",
    related_products: [...],
    can_add_to_cart: true
  };
}