Enhance GraphQueryTools and LogAnalyticsQueryTools documentation with detailed API usage examples and best practices for license optimization, M365 usage reports, and KQL patterns for FinOps tables.

Author: alfarahn

.github/copilot-instructions.md

@@ -178,7 +178,7 @@ When creating tools for the agent:
 - **ChartTools** (`RenderChart` / `RenderAdvancedChart`) returns a serialized JSON object with chart config — the frontend detects `tool_done` for `RenderChart` or `RenderAdvancedChart` and emits a separate `chart` SSE event. `RenderAdvancedChart` accepts raw ECharts option JSON for world maps, heatmaps, treemaps, radar, gauge, etc.
 - **FaqTools** (`PublishFAQ`) dynamically publishes useful public Q&As as SEO-indexable HTML pages at `/faq/{slug}`. Entries are stored in a JSON file on disk and auto-submitted to IndexNow for Bing indexing. The sitemap at `/sitemap.xml` is dynamically generated to include both static and community FAQ entries.
 - **PresentationTools** (`GeneratePresentation`) generates FinOps PowerPoint (.pptx) presentations using python-pptx + matplotlib (Charts are rendered as images via matplotlib and embedded in slides). The LLM passes structured JSON slide data (title, content, chart, two_column, section layouts). Returns a `__PPTX_READY__:{fileId}:{fileName}:{slideCount}` marker. The SSE handler emits a `pptx_ready` event, and the frontend shows a download button. Files are served via `/api/download/pptx/{fileId}` and auto-cleaned after 30 minutes.
-- **AzureQueryTools** (`QueryAzure`) is a **read-only** tool that queries Azure ARM REST APIs (GET and allowlisted POST only) using the user's delegated token from `UserTokens.AzureToken`. Returns raw JSON for the LLM to interpret. **Security**: PUT, PATCH, and DELETE methods are rejected at the code level. POST requests are restricted to an allowlist of known read-only endpoints (`/query`, `/forecast`, `/resources`, `/generateCostDetailsReport`, `/generateReservationDetailsReport`, `/calculatePrice`, `/calculateExchange`, `/validatePurchase`, `/carbonEmissionReports`, `/getEntities`, `/summarize`). Mutating POST actions (e.g., `/deallocate`, `/start`, `/restart`, `/return`) are blocked with HTTP 403. Covers Cost Management (queries, forecasts, cost details report, reservation details report, exports, scheduled actions, views), Budgets, Billing, Consumption (pricesheets, reservation summaries/recommendations/transactions, lots, credits, balances, charges), Reservations, Savings Plans, Advisor, Resource Graph, Monitor, Activity Log, Compute/VMs/VMSS, AKS, Network (ExpressRoute, VPN, public IPs, App Gateways, NAT Gateways), Storage, SQL, SQL Managed Instances, App Service, Azure ML (workspaces, compute instances, GPU clusters, endpoints), Databricks (workspaces, pricing tiers), Cosmos DB (accounts, throughput/RU analysis), Redis Cache, Data Factory, Synapse (SQL pools, Spark pools), Container Apps, Resource Health, Defender for Cloud (security assessments, secure scores), RBAC (role assignments), Locks, Quota, Carbon, Policy/PolicyInsights, Management Groups, Tags, Migrate, and Support. Note: Consumption usageDetails/marketplaces are deprecated — prefer Cost Details API (2025-03-01) or Exports. Consumption reservationDetails is deprecated — prefer generateReservationDetailsReport (Microsoft.CostManagement).
+- **AzureQueryTools** (`QueryAzure`) is a **read-only** tool that queries Azure ARM REST APIs (GET and allowlisted POST only) using the user's delegated token from `UserTokens.AzureToken`. Returns raw JSON for the LLM to interpret. **Security**: PUT, PATCH, and DELETE methods are rejected at the code level. POST requests are restricted to an allowlist of known read-only endpoints (`/query`, `/forecast`, `/resources`, `/generateCostDetailsReport`, `/generateReservationDetailsReport`, `/calculatePrice`, `/calculateExchange`, `/validatePurchase`, `/carbonEmissionReports`, `/getEntities`, `/summarize`). Mutating POST actions (e.g., `/deallocate`, `/start`, `/restart`, `/return`) are blocked with HTTP 403. Covers Cost Management (queries, forecasts, cost details report, reservation details report, exports, scheduled actions, views), Budgets, Billing, Consumption (pricesheets, reservation summaries/recommendations/transactions, lots, credits, balances, charges), Reservations, Savings Plans, Advisor, Resource Graph, Monitor, Activity Log, Compute/VMs/VMSS, AKS, Network (ExpressRoute, VPN, public IPs, App Gateways, NAT Gateways), Storage, SQL, SQL Managed Instances, App Service, Azure ML (workspaces, compute instances, GPU clusters, endpoints), Databricks (workspaces, pricing tiers), Cosmos DB (accounts, throughput/RU analysis), Redis Cache, Data Factory, Synapse (SQL pools, Spark pools), Container Apps, Resource Health, Defender for Cloud (security assessments, secure scores), RBAC (role assignments), Locks, Quota, Carbon, Policy/PolicyInsights, Management Groups, Tags, Migrate, and Support. Note: Consumption usageDetails/marketplaces are deprecated — prefer Cost Details API or Exports. Consumption reservationDetails is deprecated — prefer generateReservationDetailsReport (Microsoft.CostManagement). **Latest API versions** are embedded in the tool description and include: CostManagement 2025-03-01, Consumption 2024-08-01, Billing 2024-04-01, Capacity 2022-11-01, BillingBenefits 2022-11-01, Advisor 2025-01-01, ResourceGraph 2022-10-01, Insights/metrics 2023-10-01, Compute VMs 2025-04-01, Compute Disks 2025-01-02, Compute SKUs 2021-07-01, ContainerService 2026-01-01, Network 2025-05-01, Storage 2025-06-01, Sql 2025-01-01, Web 2024-04-01, OperationalInsights 2025-07-01, MachineLearningServices 2025-12-01, Databricks 2026-01-01, DocumentDB 2025-10-15, Cache 2024-11-01, DataFactory 2018-06-01, Synapse 2021-06-01, App 2026-01-01, ResourceHealth 2024-02-01, Security 2020-01-01, Authorization/RBAC 2022-04-01, Authorization/Policy 2023-04-01, Authorization/Locks 2020-05-01, PolicyInsights 2024-10-01, Management 2020-05-01, Resources 2021-04-01 (subscriptions 2022-12-01), Quota 2025-09-01, Carbon 2025-04-01, Migrate 2024-01-15, Support 2024-04-01. **Spot/GPU Quota**: Spot vCPU quota is a single regional bucket called `lowPriorityCores` (not per VM family). H100 standard quotas are per-family: `standardNDSH100v5Family`, `StandardNCadsH100v5Family`. The Quota RP scope is `/subscriptions/{subId}/providers/Microsoft.Compute/locations/{region}/providers/Microsoft.Quota/quotas`.
 - **GraphQueryTools** (`QueryGraph`) is **read-only** — GET only. calls Microsoft Graph API using `TokenContext.GraphToken`. Used for license inventory, M365 usage reports (Exchange, Teams, OneDrive, SharePoint), M365 Copilot seat usage, M365 app-level usage, Intune device management, directory objects, org structure for FinOps chargebacks.
 - **LogAnalyticsQueryTools** (`QueryLogAnalytics`) is **read-only** — runs KQL queries (POST to query API only) against Log Analytics workspaces or App Insights using `TokenContext.LogAnalyticsToken`. Used for VM/container metrics, diagnostics, cost attribution (AzureActivity table), and ingestion cost analysis.
 - **TokenContext** (`TokenContext.cs`) provides per-user mutable token storage via `UserTokens` — one instance per user in a `ConcurrentDictionary<long, UserTokens>`. Token fields use `volatile` for cross-thread visibility. A `SemaphoreSlim RefreshLock` serializes token refresh operations within a user session. `UserTokens` instances are passed to tool constructors via closure, so tools always read the latest tokens via direct reference.