Gemini Function Calling: Tool Integration & Multi-Tool Patterns

{
  "tools": [
    {
      "functionDeclarations": [
        {
          "name": "search_catalog",
          "description": "Search the product catalog by keyword. Returns matching products with name, price, SKU, and stock status.",
          "parameters": {
            "type": "OBJECT",
            "properties": {
              "query": {
                "type": "STRING",
                "description": "Search keyword. Supports partial matches. Use specific product terms (e.g., 'wireless headphones', not 'audio stuff')."
              },
              "category": {
                "type": "STRING",
                "description": "Optional. Filter by product category. Valid values: 'electronics', 'clothing', 'home', 'sports'."
              },
              "max_results": {
                "type": "INTEGER",
                "description": "Maximum number of results to return. Default 5, max 20."
              },
              "in_stock_only": {
                "type": "BOOLEAN",
                "description": "If true, only return products currently in stock. Default false."
              }
            },
            "required": ["query"]
          }
        }
      ]
    }
  ]
}

// BAD — generic, no guidance
{
  "name": "get_weather",
  "description": "Get the weather."
}

// GOOD — specific, includes usage guidance
{
  "name": "get_weather",
  "description": "Get current weather conditions for a location. Use this when the user asks about current temperature, precipitation, wind, or general conditions. NOT for forecasts beyond 48 hours — use get_forecast for longer-range predictions. Location can be city name, ZIP code, or coordinates."
}

You have access to the following tools:
- search_catalog: Find products by keyword
- check_inventory: Check stock at specific warehouse
- calculate_shipping: Estimate shipping cost and delivery time
- create_order: Place an order (requires confirmation)

TOOL USE GUIDELINES:
1. Always search the catalog before answering product questions —
   never answer from memory.
2. If a search returns no results, try a broader query before
   telling the user the product doesn't exist.
3. Before calculating shipping, confirm the user's location.
4. NEVER create an order without explicit user confirmation.
   Show the order summary first and ask "Should I place this order?"
5. If a tool returns an error, explain the error to the user
   in plain language and suggest what to do next.
6. If you need information from multiple tools, call them in the
   optimal order (e.g., search first, then check inventory for
   relevant products).

For product availability questions, follow this sequence:
1. search_catalog(query) → get matching products
2. For each relevant product: check_inventory(sku, warehouse)
3. If inventory is low (< 5 units): calculate_shipping(zip, sku)
4. Present findings: "X is in stock at [warehouse], shipping
   would be $Y and arrive by [date]. Y is low stock — only 3 left.
   Z is out of stock but expected back [date]."

Do not call step 2 before step 1 completes.
Do not present findings until all relevant checks are done.

When a user asks to compare products, call search_catalog for
each product simultaneously — do not wait for one result before
searching the next.

Example user: "Compare iPhone 16 Pro, Pixel 10, and Galaxy S26"
→ Call search_catalog("iPhone 16 Pro"),
        search_catalog("Pixel 10"),
        search_catalog("Galaxy S26") in parallel.

TOOL ERROR HANDLING:

If a tool returns an error:
1. Don't panic or apologize excessively. State: "I wasn't able to
   [what you tried to do] because [plain-language explanation of error]."
2. If the error is recoverable (timeout, rate limit), retry once
   automatically with the same parameters.
3. If the error is not recoverable (invalid input, not found):
   a. Explain what went wrong
   b. Suggest what the user can do differently
   c. Offer an alternative approach if one exists
4. NEVER fabricate tool results. If a function fails, report the
   failure. Do not guess what the result would have been.

Example error responses:
- "I couldn't check inventory for SKU 12345 — the warehouse system
  is temporarily unavailable. Would you like me to try again?"
- "I can't calculate shipping to that ZIP code because it's outside
  our delivery area. Our service currently covers the continental US."

Before calling any function, ask yourself:
1. Can I answer this from the conversation context?
2. Has this exact query already been answered in this conversation?
3. Is this function call actually necessary, or am I calling it
   out of habit?

Example: If the user says "show me the blue one" after you've already
displayed search results that include a blue product, reference the
existing results rather than searching again.

However: When in doubt, call the function. Stale information is
worse than an unnecessary API call.

// Your function response (wrapped by the SDK/Framework in
// role: "function" / parts: [{functionResponse: {name, response}}])
{
  "name": "search_catalog",
  "response": {
    "query": "wireless headphones",
    "total_results": 142,
    "returned": 5,
    "products": [
      {
        "sku": "WH-1000XM6",
        "name": "Sony WH-1000XM6 Wireless Headphones",
        "price": 349.99,
        "currency": "USD",
        "in_stock": true,
        "stock_level": "high",
        "rating": 4.7,
        "review_count": 2843,
        "key_features": [
          "Active noise cancellation",
          "30-hour battery life",
          "Multipoint connection"
        ]
      }
    ],
    "search_tip": "Add 'over-ear' or 'in-ear' to refine results."
  }
}