Surface KQL language rules to the query-writing agent plugins

[Roland Krummenacher (RolandKrummenacher)]

🛠️ Description

Follow-up to #2220 / #2223 / #2225. The KQL rules added to the coding guidelines in #2223 live in docs-wiki/Coding-guidelines.md and AGENTS.md — contributors and repo coding agents read those, but the shipped plugin agents never load them. The ftk-database-query agent generates ad-hoc KQL against Costs()/Prices()/etc. at runtime and would reproduce exactly the pitfall classes fixed repo-wide (bare join defaulting to innerunique and silently dropping rows, tolower() in comparisons, contains where has is meant, fullouter without key coalescing). #2225 fixes the example queries in the skill references, but examples don't immunize newly generated queries — the rules themselves need to be in the context the agent loads.

This PR puts a distilled, runtime-relevant subset of the rules where query-writing agents already look:

• src/queries/finops-hub-database-guide.md — new KQL language rules subsection under Query best practices: case-insensitive operators (never tolower() in comparison position), has vs contains by matching intent, explicit join kind= always, lookup for small-dimension enrichment with a take_any-deduped right side, leftanti for exclusions, key coalescing after fullouter, toscalar() for grand totals, plus a short Azure Resource Graph caveat (no lookup, no semi/anti flavors, 3-join limit). This file is what the finops-toolkit skill's task routing loads before writing any KQL, so the rules ride along with the schema.
• src/templates/claude-plugin/agents/ftk-database-query.md — new operational guideline pointing at that section, with the three highest-impact rules inlined.

Placement rationale

• The skills reference src/queries via links from both the current agent-skills structure and the restructured agent-plugin layout in feat(plugins): add FinOps Toolkit agent plugins #2167, so the rules survive the plugin move without duplication. cc Brett Wilson (@MSBrett) — when feat(plugins): add FinOps Toolkit agent plugins #2167 lands, the same one-line pointer belongs in ftk-database-query.agent.md.
• Stacked logically after Fix KQL join pitfalls and adopt lookup for dimension enrichment #2225: the guide's percent-of-total example still shows the old join on 1 == 1 pattern on dev; Fix KQL join pitfalls and adopt lookup for dimension enrichment #2225 replaces it with toscalar(). Until then the new rules section and that example briefly disagree — intentional, to avoid editing the same lines in two open PRs.
• No repo changelog entry: this changes agent guidance docs only; the changelog dev section is already being reshaped by Fix KQL join pitfalls and adopt lookup for dimension enrichment #2225 and would conflict.

📷 Screenshots

N/A — documentation only.

🙋‍♀️ Ask for the community

Review whether the distilled rule set is the right size — it's loaded into agent context on every query-writing task, so it's deliberately terse compared to the full guidelines in #2223.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR updates the FinOps hubs query guidance so shipped query-writing agents (not just contributors/coding agents) load a distilled set of KQL correctness rules alongside the hub schema, reducing the likelihood of known KQL pitfalls in newly generated ad-hoc queries.

Changes:

• Added a concise “KQL language rules” subsection to the hub database query guide under “Query best practices”.
• Updated the ftk-database-query agent operational guidelines to point to (and inline-highlight) the highest-impact KQL rules.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.

File	Description
src/templates/claude-plugin/agents/ftk-database-query.md	Adds an operational guideline directing the agent to apply the KQL rules from the query guide when generating queries.
src/queries/finops-hub-database-guide.md	Introduces a “KQL language rules” section and records the change in the guide’s changelog.

[Michael Flanakin (flanakin)]

🤖 [AI][claude] PR Review

Summary: Good idea and mostly solid, technically accurate rules (verified against Microsoft's KQL docs — join/lookup semantics, case sensitivity, and dedup guidance all check out). One example in the new content contradicts how has actually works and should be fixed before this ships into agent context; one small formatting issue and one imprecise ARG claim are worth a look too.

🚫 Blockers (1)

1. The has example in "String matching" uses a multi-segment path as the needle, but has only matches whole terms (alphanumeric runs) — this example won't work as described.

⚠️ Should fix (1)

1. Missing blank line before the "Azure Resource Graph is different" paragraph causes it to merge into the preceding bullet list on GitHub's renderer.

💡 Suggestions (1)

1. The ARG "at most 3 joins per query" claim is a bit imprecise per Microsoft docs.

[microsoft-github-policy-service]

All Contributors (@all-contributors) please add Roland Krummenacher (@RolandKrummenacher) for code

[allcontributors]

@microsoft-github-policy-service[bot]

Roland Krummenacher (@RolandKrummenacher) already contributed before to code