Prompting best practices

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

1. Be specific about what you want

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

• Avoid: “How’s our cloud spend?”
• Good: “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.

• Good: “Savings opportunities over $100/month in the prod account.”
• Good: “Cost by service for 2026-05-01 to 2026-05-31.”
• Good: “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.

• Avoid: “List every line item for last month.”
• Good: “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.

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

Write tools need admin:write and confirm: true. Make your intent unambiguous so the agent sets confirm:

• Good: “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.

Prefer connecting read-only for analysis and using a separate admin:write connection only when you intend to change something.

8. Ground answers in “as of when”

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

---

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?”