---
name: Excel Creation — Data Tables & Reports
priority: 5
keywords: excel, exel, excell, xlsx, xls, spreadsheet, spreadshet, sheet, workbook, اكسل, إكسل, اكسيل, إكسيل, جدول بيانات, ورقة عمل, sales report, financial table, kpi sheet, monthly report, data export
---

# Excel Creation — جداول البيانات والتقارير

## When to use
The user wants a tabular data file (sales, KPIs, customer list, monthly summary, budget, comparison) — anything that belongs in rows + columns. Triggers in Arabic ("سويلي ملف اكسل", "ابي جدول بمبيعات الشهر", "تقرير شهري excel") and English ("excel sheet of last quarter's sales", "spreadsheet comparison").

## Iron Rules (do not violate)

1. **Use the `create_excel` tool. Never `zatca_invoice`.** ZATCA is a Saudi VAT-invoice tool with hard regulatory output. Generic data tables go through `create_excel`. The v2.5.4 disaster was Qwen picking ZATCA for "show me iPhone sales in Excel" — it produced a 632M SAR fake VAT invoice. Do not repeat that.

2. **Real data only — never fabricate numbers.** If the user asks for "iPhone Pro sales last 5 years" and you don't have authoritative data:
   - First: call `internal_knowledge_search` to check tenant memory
   - Then: call `research_topic` ONCE (not 6 times — the per-tool cap kicks in at 3-4)
   - If still no data: ASK the user. Don't guess.
   - Synthesized estimates are acceptable IF clearly labeled and sourced (e.g. "تقديري — بناءً على نسبة Pro من إجمالي مبيعات iPhone").

3. **Structure first, content second.** Decide columns + sheets BEFORE calling the tool. Don't make 1 messy sheet; split into logical worksheets if the data has multiple dimensions.

4. **Auto-display.** After `create_excel` succeeds, the brain's auto-display hook will open the file. Don't call `open_file` manually — it'll double-open.

## Procedure

1. Confirm the data scope with the user (period, columns, source) — but only if essential. Don't ask permission for obvious choices.
2. Gather data via the appropriate tool (`internal_knowledge_search`, `get_customer`, `research_topic`, etc.).
3. Plan the structure:
   - **Sheet 1:** Raw data (one row per record)
   - **Sheet 2:** Aggregates / pivots (if multi-dimensional)
   - **Sheet 3:** Chart-ready summary (optional)
4. Call `create_excel` with:
   ```json
   {
     "filename": "<descriptive_name>.xlsx",
     "sheets": [
       {
         "name": "البيانات",
         "headers": ["العمود 1", "العمود 2", ...],
         "rows": [[...], [...], ...]
       }
     ]
   }
   ```
5. Confirm in one sentence to the user (don't recite the whole table — the auto-display hook will show it inline).

## Saudi context

- Arabic column headers RIGHT-to-LEFT — most users expect this. The `create_excel` tool handles RTL automatically when headers are Arabic.
- Currency: SAR (ر.س) — not USD unless the data is foreign.
- Date format: dd/mm/yyyy hijri-aware where relevant (call `hijri_date` if asked for hijri).
- Decimals: comma-separator on display ("12,500.50") but pure numbers in cells so Excel can sum.

## Examples

**User:** "اعمللي شيت اكسل بمبيعات الشهر مقسمة على الموظفين"
**You:** Call `internal_knowledge_search` for this month's orders → group by employee → `create_excel` with `[{name:"حسب الموظف",headers:["الموظف","عدد الطلبات","قيمة المبيعات (ر.س)"],rows:[...]}]`. Reply: "تم. الملف فوق ☝️"

**User:** "comparison sheet of our top 5 competitors"
**You:** `internal_knowledge_search` for competitor entities → if data thin, ONE `research_topic` call → `create_excel` with columns [Competitor, Pricing, Strengths, Weaknesses, Market Share]. Reply: "Comparison sheet ready — see attachment."

**User:** "show me Apple's iPhone Pro sales for the last 5 years"
**You:** `research_topic` (ONE call) → if you only get total iPhone sales, NOT per-model splits: tell the user honestly. "Apple لا تنشر مبيعات الـ Pro منفصلة — مصادر السوق (Counterpoint/IDC) تقدرها بـ 28-32% من إجمالي مبيعات iPhone. هل تبيني أعطيك تقدير مبني على هذه النسبة، أم نوقف الموضوع؟" Then either call `create_excel` with clearly-labeled estimates, or stop.

## Anti-patterns (do NOT do these)

- ❌ Calling `zatca_invoice` for a non-VAT data table.
- ❌ Calling `research_topic` more than 3 times paraphrasing the same question — the per-tool cap will block you, but more importantly you're burning tokens for no gain.
- ❌ Inventing numbers to fill cells. Better to ask the user than fabricate.
- ❌ Re-opening the file with `open_file` after `create_excel` — auto-display already did it.
- ❌ Putting everything in one sheet when the data has multiple natural dimensions.
