Skip to main content
Glama

Find a waste runbook

find_playbooks
Read-onlyIdempotent

Find runbooks for suspected cloud-waste patterns by provider, service, waste category, or confidence; each includes a detection query you can run in your own account.

Instructions

Finds runbooks for a suspected cloud-waste pattern, filterable by provider, service, waste category or detection confidence. Useful when the user asks how to detect or fix a specific waste pattern; each runbook includes a detection query the user can run in their own account. This connector has no access to the user's accounts.

Use this with ``query`` for a symptom or a "which of my X" question in
the user's own words: "our AWS bill has NAT gateway charges but nothing
uses them", "which of my RIs are about to expire", "my NAT gateway
processes 10TB to S3", "should I delete these old snapshots", "our Log
Analytics ingestion doubled", "which VMs are running for nothing",
"passerelle NAT qui ne sert à rien". Every runbook declares the
questions it answers (English and French); the result is ranked by
those, then by title and service, and carries ``matched_question``; the
first entry is the one ``get_playbook(name=)`` fetches. Facets narrow
the set first; ``query`` ranks what is left.

Use this with the facets alone to browse: "what waste can we clean up safely
without review" (confidence), "every idle pattern on Azure" (scope and
waste category). 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(query="which of my RIs are about to expire")`` - ranked runbooks
- ``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:
    query: the user's symptom or question in their own words, up to
        1,000 characters, English or French. Ranks the facet-filtered runbooks by
        the questions they declare, their title and their service;
        returns at most five, best first, each with ``match_score``
        and ``matched_question`` (a runbook is read whole, so its
        ``suggested_section`` is null).
    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}``. With
``query`` the entries are ranked and capped at five. A facet filter that
matches nothing also returns `hint` and `valid_values`, so a typo is
distinguishable from a genuine gap in coverage; a ``query`` that matches
nothing returns `hint` alone.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "find_playbooks"
  }
}

Input Schema

NameRequiredDescriptionDefault
queryNo
scopeNo
serviceNo
confidenceNo
waste_categoryNo

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv1.51.0
    • addedInput schema / properties / query
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "string"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "title": "Query"
      +}
  2. First observedv0.1.0

TDQS

A4.7/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly/idempotent/closed-world, and the description reinforces this with 'This connector has no access to the user's accounts' and 'each runbook includes a detection query the user can run in their own account'. It adds genuine behavior beyond annotations: ranking order (matched questions, then title and service), a five-result cap, match_score/matched_question fields, and the hint/valid_values distinction between a typo and a coverage gap. It stops short of describing latency or ranking tie-break subtleties, so not a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose and the query-vs-facet split are front-loaded, and the examples earn their space by showing real invocation shapes. It is long and somewhat redundant, though: the query ranking and the five-result cap are each explained twice (body paragraph, then again under Args and Returns), which could be tightened.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a five-parameter, zero-coverage, read-only search tool, everything needed to call it correctly is present: filter semantics, enum values, ranking behavior, result cap, and follow-up path to get_playbook. The return shape is restated even though an output schema exists, which is harmless surplus rather than a gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0% and enums are absent from the schema, so the description carries the full burden — and does: it enumerates all scope values, all eight waste_category values, and defines the three confidence tiers ('obvious' one signal, 'likely' two, 'possible' needs review). It also states exact case-insensitive matching, the 1,000-character query limit, and the AND semantics of combining filters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb+resource: 'Finds runbooks for a suspected cloud-waste pattern', and names the filter dimensions. It distinguishes itself from the sibling get_playbook by explicitly stating that the first result is the one get_playbook(name=) fetches, so an agent can route without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit when-to-use branches: with ``query`` for a symptom or 'which of my X' question, with facets alone to browse, with both combined ('Facets narrow the set first; ``query`` ranks what is left'). It supplies seven concrete user-utterance examples, including a French one, plus four call examples, and names the follow-up tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.