sequenceDiagram
    participant U as User/System
    participant C as Claude (Extended Thinking)
    participant T1 as Tool A
    participant T2 as Tool B
    participant T3 as Tool C

    U->>C: Task + Tool Definitions
    Note over C: Extended Thinking:<br/>Plan tool sequence
    C->>T1: Parallel Call 1
    C->>T2: Parallel Call 2
    T1-->>C: Result A (streamed)
    T2-->>C: Result B (streamed)
    Note over C: Extended Thinking:<br/>Compose results, plan next step
    C->>T3: Sequential Call (depends on A+B)
    T3-->>C: Result C
    C->>U: Final composed response

{
  "name": "search_knowledge_base",
  "description": "Search the domain knowledge base for patterns matching a query. Returns ranked results with confidence scores. Use this BEFORE generating recommendations to ground them in verified patterns.",
  "input_schema": {
    "type": "object",
    "properties": {
      "query": {
        "type": "string",
        "description": "Natural language search query describing the pattern or information needed"
      },
      "category": {
        "type": "string",
        "enum": ["bidding", "targeting", "creative", "budget", "general"],
        "description": "Knowledge category to search within"
      },
      "max_results": {
        "type": "integer",
        "default": 5,
        "description": "Maximum number of results to return (1-20)"
      }
    },
    "required": ["query"]
  }
}

interface ToolCall {
  id: string;
  name: string;
  input: Record<string, unknown>;
}

interface ToolResult {
  tool_use_id: string;
  content: string;
  is_error: boolean;
}

async function executeToolCalls(calls: ToolCall[], registry: ToolRegistry): Promise<ToolResult[]> {
  const results = await Promise.allSettled(
    calls.map(async (call) => {
      const handler = registry.get(call.name);
      if (!handler) {
        return { tool_use_id: call.id, content: `Unknown tool: ${call.name}`, is_error: true };
      }
      try {
        const result = await handler.execute(call.input);
        return { tool_use_id: call.id, content: JSON.stringify(result), is_error: false };
      } catch (error) {
        return { tool_use_id: call.id, content: `Error: ${String(error)}`, is_error: true };
      }
    })
  );

  return results.map((r) =>
    r.status === "fulfilled" ? r.value : { tool_use_id: "", content: `Execution failed: ${r.reason}`, is_error: true }
  );
}

async def stream_tool_execution(client, messages, tools):
    """Execute tools with streaming for real-time progress."""
    async with client.messages.stream(
        model="claude-sonnet-4-20250514",
        max_tokens=8096,
        tools=tools,
        messages=messages,
    ) as stream:
        tool_calls = []
        async for event in stream:
            if event.type == "content_block_start" and event.content_block.type == "tool_use":
                tool_calls.append({
                    "id": event.content_block.id,
                    "name": event.content_block.name,
                    "input_json": "",
                })
            elif event.type == "content_block_delta" and hasattr(event.delta, "partial_json"):
                tool_calls[-1]["input_json"] += event.delta.partial_json
            elif event.type == "content_block_stop" and tool_calls:
                call = tool_calls[-1]
                call["input"] = json.loads(call["input_json"])

        if tool_calls:
            results = await execute_parallel_tools(tool_calls)
            messages.append({"role": "assistant", "content": stream.get_final_message().content})
            messages.append({"role": "user", "content": results})
            return await stream_tool_execution(client, messages, tools)

        return stream.get_final_message()

class ToolCache:
    def __init__(self, ttl_seconds=300):
        self.cache = {}
        self.ttl = ttl_seconds

    def cache_key(self, tool_name: str, params: dict) -> str:
        normalized = json.dumps(params, sort_keys=True)
        return f"{tool_name}:{hashlib.sha256(normalized.encode()).hexdigest()[:16]}"

    async def execute_with_cache(self, tool_name, params, executor):
        key = self.cache_key(tool_name, params)
        if key in self.cache:
            entry = self.cache[key]
            if time.time() - entry["timestamp"] < self.ttl:
                return entry["result"]

        result = await executor(tool_name, params)
        self.cache[key] = {"result": result, "timestamp": time.time()}
        return result