Finds the runbook for a specific cloud waste pattern, filtered by
provider, service, waste category or detection confidence. Useful
before answering a specific waste or cost-fix question: each runbook
includes a tested detection query the user can run in their own
account, so it also serves questions about the user's own resources.
Use this for questions like "which VMs are running for nothing",
"why is our NAT bill so high", "my NAT gateway processes 10TB to S3",
"should I delete these old snapshots", "which of our RIs are about to
expire", "what waste can we clean up safely without review" - anything
that names a provider, a waste category, or how confident the
detection needs to be before acting. Patterns
covered include NAT gateways and VPC endpoints, expiring Savings
Plans / RIs / reservations, snapshot sprawl, S3 lifecycle gaps, idle
or stopped VMs, orphaned disks / public IPs / EBS volumes, GPU and
SageMaker sizing, Kubernetes idle capacity, and schedule blindness.
All filters are optional and combine with AND semantics. String matching
is case-insensitive and exact. Examples:
- ``find_playbooks(scope="aws")`` - all AWS-specific playbooks
- ``find_playbooks(waste_category="idle")`` - every idle-resource pattern
- ``find_playbooks(scope="cross-cloud", confidence="obvious")``
Args:
scope: ``"aws"``, ``"azure"``, ``"gcp"``, or ``"cross-cloud"``.
service: Provider service exact-match (e.g. ``"AWS NAT Gateway"``).
waste_category: ``"orphaned"``, ``"idle"``, ``"overprovisioned"``,
``"commitment-mismatch"``, ``"schedule-blindness"``,
``"modernization"``, ``"ai-ml-inefficiency"``, or ``"egress"``.
confidence: ``"obvious"`` (single signal is enough),
``"likely"`` (two signals required), or ``"possible"``
(needs human review). From the OptimNow three-tier confidence
model in `finops-waste-detection-playbooks`.
Returns ``{"filters": {...}, "playbooks": [...], "total": N}``. A query
that matches nothing also returns `hint` and `valid_values`, so a typo is
distinguishable from a genuine gap in coverage.