Prompting best practices

The CloudQuell tools work best with specific, well-scoped questions. A few habits get you accurate answers in fewer tokens.

0. Start with the briefing, then drill down

For anything open-ended — “how are we doing?”, “what should I look at?”, a Monday-morning review, a scheduled check — start with get_finops_briefing. One call returns freshness, the month-end forecast, top movers, anomalies, budgets at risk, expiring commitments and open savings, in that order, with the freshness verdict first so every figure below it carries its trust level. Asking those seven questions separately costs seven round trips and leaves you to decide the order. Then drill into only the two or three sections that crossed a threshold, using the tool named for that section — get_forecast, compare_periods, investigate_anomaly, get_budget_status, get_expiring_commitments, get_savings. The briefing tells you where to look; those tools are how you look. One caveat that matters: a section listed in sectionsUnavailable was not produced, and is not a zero — say so rather than reporting it as “nothing found”.

Skip the briefing when you already know the question. “What did AmazonRDS cost in May?” is one specific tool call, and wrapping it in a briefing just adds noise.

1. Be specific about what you want

Vague questions make the agent guess at filters and time windows.

• ❌ “How’s our cloud spend?”
• ✅ “What was our total AWS spend in May 2026, and which three services grew the most vs. April?”

State the metric (total, growth, %, count), the dimension (by service, by account, by cost center), and the comparison (vs. last month, vs. budget).

2. Scope by account and timeframe

Most tools accept a date range, an account, a service, and/or an integration_id. Naming them keeps results relevant and small.

• ✅ “Savings opportunities over $100/month in the prod account.”
• ✅ “Cost by service for 2026-05-01 to 2026-05-31.”
• ✅ “Commitments for integration int-123 only.”

Dates are YYYY-MM-DD. If you don’t know the exact account or service string, ask the agent to call get_metadata first (see #6).

3. Group by to save tokens

Asking for an aggregate is far cheaper — and clearer — than asking for raw rows.

• ❌ “List every line item for last month.”
• ✅ “Group last month’s spend by product” → query_costs view=detailed, group_by=product.

For long lists, say how many you want: “top 10 …” maps to a limit, and the tools already sort the most relevant rows first.

3b. Pivots are async — expect a job handle on big windows

run_cost_pivot runs an Athena job. A narrow pivot (one or two dimensions, a few months) usually comes back with rows inside the wait. A wide one — three dimensions, daily granularity, a whole provider — will hand back a jobId and a status instead. That is not a failure: call get_cost_pivot with the job_id a second or two later. Resubmitting starts a second query and wastes the first.

If a pivot fails with RESPONSE_TOO_LARGE, the answer is a smaller question, not a smaller limit — drop a dimension, shorten the window, or add a services / account_names / cost_centers filter. The backend builds the whole response before limit is ever considered.

Ask for the pivot you want in one go rather than iterating:

“Break last quarter’s AWS spend down by usage type, monthly.”

…rather than asking for a total first and then a breakdown, which runs two jobs.

4. One question per prompt

Each tool call answers one shaped question. Bundling unrelated asks (“show savings and budgets and rename the org”) makes the agent juggle tools and muddles the answer. Ask sequentially; use the answer to inform the next prompt. Investigations are the exception — “investigate the RDS spike” is one intent that legitimately chains calls.

5. Specify the output format you want

The agent controls response_format (concise vs. detailed) on your behalf, but you can steer the presentation:

• “Give me a short table of the top 5 by savings.”
• “Just the total and the % change — one line.”
• “Detailed: include resource ids and regions.” (nudges toward detailed).

Ask for detailed only when you actually need every field — concise is the default for a reason (lower token cost, faster).

6. Discover valid filter values first

If a filter doesn’t match, you’ll get empty results. When unsure, ask the agent to look up the vocabulary:

“What services, tag keys, and accounts can I filter on?” → get_metadata

Then filter with exact values (e.g. AmazonRDS, not “RDS”; the account name or its 12-digit id).

7. Confirm writes explicitly

Writes are off by default for every organization. If the agent reports writes_disabled_for_org, that is the expected answer for a connection nobody has opted in — an org admin turns writes on at Settings → Organization → AI agent access, and the agent cannot do it for you. insufficient_role means writes are on but your account is not an admin.

Once writes are enabled, they still need confirm: true. Make your intent unambiguous so the agent sets it:

• ✅ “Create the budget now — name it ‘Prod AWS monthly’, $50k, starting July 1, alert at 80% and 100%.”
• If the agent describes the change and asks you to confirm, that’s the safety gate working. Reply with an explicit go-ahead.

For analysis — and for anything running unattended — use a cak_ service key. Those are read-only by construction, so the agent cannot change anything even if your organization has writes enabled.

8. Ground answers in “as of when”

Cost data is ingested daily, not in real time, and provider billing exports lag 2-3 days on top of that. Ask the agent to cite the lastUpdated timestamp when precision matters (“as of what date is this?”), and don’t expect intra-day figures.

Better still, ask it to check first: “can I trust these numbers right now?” runs get_data_freshness, which returns a fresh / stale / degraded verdict and names any connection that is failing or behind. A number from a degraded organization is incomplete, and the agent should say so rather than round it off.

---

Quick reference

Goal	Say this
Period total	“Total AWS spend for May 2026”
Movers	“Top 3 services by growth vs. April”
Waste	“Savings over $100/mo in prod, top 10”
Anomaly	“Investigate the AmazonRDS spike on 2026-06-15”
Budget	“Which budgets are forecast to go over this period?”
Commitments	“Which RIs/SPs expire in the next 30 days?”
Allocation	“Spend by cost center, plus unallocated”
Discover filters	“What services/accounts can I filter on?”
The whole picture	“What should I look at this week?”
Specific resources	“Which resources are driving AmazonRDS on this account?”