Best practices

Operation: GET /api/customers/{id}
Use Case: Customer support agent needs to lookup customer details to personalize 
          responses when helping with account issues. Agent will use name, email, 
          and account status to confirm identity and tailor advice.
Expected Volume: ~200 calls/day during business hours (9am to 5pm EST)
Data Sensitivity: PII (names, emails, phone numbers, account status)
Required Permissions: Read-only, user-scoped (agent can only access data for the 
                      authenticated customer they're assisting)
User Authentication: JWT token with customerId claim, issued by our auth service

Operation: GET /api/customers/{id}
Use Case: Need customer data for agent

You are a customer support assistant for JetBank with access to these tools:

Tools:
- getCustomerProfile(customerId): Retrieve customer name, email, account status. 
  USE WHEN: User asks about their account, you need to personalize responses.
  REQUIRES: User must be authenticated (JWT token with customerId claim).

- searchKnowledgeBase(query): Find help articles about products and policies.
  USE WHEN: User asks product questions, policy questions, "how do I" questions.
  PUBLIC: No authentication needed, safe to call anytime.

- listTransactions(accountId, startDate, endDate): Get transaction history.
  USE WHEN: User asks "What did I spend on?", "Show my recent activity".
  REQUIRES: accountId format ACC-XXXXXX, authenticated user must own the account.

Guidelines:
1. Always verify customer identity before calling getCustomerProfile or listTransactions.
2. Try searchKnowledgeBase first for common questions ("What's your return policy?").
3. If a tool fails, apologize: "I'm having trouble accessing that right now. Let me connect you with a specialist."
4. NEVER fabricate customer data. If getCustomerProfile returns an error, say "I couldn't retrieve your account information" instead of guessing.
5. Cache tool results in conversation context - don't call getCustomerProfile multiple times in one conversation.

You are a customer support assistant. You have access to tools. Use them when needed.

class CustomerSupportAgent:
    def __init__(self):
        self.conversation_cache = {}  # Reset per conversation
    
    def get_customer_profile(self, customer_id):
        # Check cache first
        if customer_id in self.conversation_cache:
            return self.conversation_cache[customer_id]
        
        # Cache miss - call tool and store result
        profile = self.mcp_client.call_tool(
            "getCustomerProfile", 
            {"customerId": customer_id}
        )
        self.conversation_cache[customer_id] = profile
        return profile

class CustomerSupportAgent:
    def get_customer_info(self, customer_id):
        try:
            return self.mcp_client.call_tool(
                "getCustomerProfile", 
                {"customerId": customer_id}
            )
        except RateLimitError:
            return "I'm experiencing high load. Please try again in a moment."
        except UnauthorizedError:
            return "I don't have permission to access that information."
        except ToolNotFoundError:
            return "That feature is temporarily unavailable."
        except Exception as e:
            # Log error internally
            self.logger.error(f"Tool call failed: {e}")
            # User-friendly message
            return "I encountered an error. Please contact human support."

if tool_name == "generateMonthlyReport":
    print("Generating your monthly report - this typically takes 20-30 seconds...")
    result = agent.call_tool("generateMonthlyReport", {"customerId": "CUST-789123"})
    print("Report ready!")

def test_mcp_connection():
    """Run this before deploying agent to production"""
    
    # 1. Tool discovery works
    try:
        tools = mcp_client.call("tools/list")
        print(f"✓ Tool discovery: {len(tools.tools)} tools available")
    except Exception as e:
        print(f"✗ Tool discovery failed: {e}")
        return False
    
    # 2. Tool invocation works (use a safe read-only operation)
    try:
        result = mcp_client.call_tool("getAccountBalance", {
            "accountId": "ACC-999999"  # Test account
        })
        print(f"✓ Tool invocation works")
    except Exception as e:
        print(f"✗ Tool invocation failed: {e}")
        return False
    
    # 3. Rate limit handling works
    print("Testing rate limit handling (this will trigger 429 errors)...")
    try:
        for i in range(150):  # Exceed typical 100/minute limit
            mcp_client.call("tools/list")
    except RateLimitError as e:
        print(f"✓ Rate limit handling works: {e}")
    except Exception as e:
        print(f"⚠ Unexpected error during rate limit test: {e}")
    
    # 4. Error handling works
    try:
        mcp_client.call_tool("getAccountBalance", {
            "accountId": "INVALID"  # Will trigger validation error
        })
    except ValidationError as e:
        print(f"✓ Validation error handling works")
    except Exception as e:
        print(f"⚠ Unexpected error type: {e}")
    
    return True

# Customer support agent - MCP runbook

## Available tools
- getCustomerProfile(customerId): Retrieve customer name, email, account status. Contains PII - handle carefully.
- listTransactions(accountId, startDate, endDate): Transaction history. Requires user authentication.
- searchKnowledgeBase(query): Help articles. Safe, public data.

## Common issues

### "rate limit exceeded" (429 errors)
**Cause**: Agent exceeded 100 calls/minute quota
**Solution**: Wait 60 seconds for window to reset. If sustained, request quota increase via platform team.
**Prevention**: Implement caching (see "Performance" section above)

### "authentication failed" (401 errors)
**Cause**: API key expired, revoked, or misconfigured
**Solution**: Check secret management system for current key. Request new key from platform team if needed.
**Escalation**: If key is valid but errors persist, contact Grand Central support via platform team.

### Tool unavailable errors
**Cause**: Grand Central platform outage or maintenance
**Solution**: Check status page at status.grandcentral.example.com. Agents should fall back to knowledge-only responses.

## Escalation
- Platform Team: [email protected], Slack: #platform-support
- Grand Central Support: Contact via platform team (they have direct support channel)