edit-workbook

name	edit-workbook
description	Use whenever the user wants to read, write, format, or chart data in the Excel workbook open in the side pane. Routes user intent to the single right office_excel_* tool so the model picks one high-leverage call instead of probing then chaining many low-level reads and writes.
license	MIT
metadata	{"category":"office-routing","primary-interface":"office_excel_* tools"}
triggers	["Excel","workbook","表格","工作表","sheet","chart","图表","formula","公式","pivot"]

Edit Workbook

This Excel workbook is open in the side pane. You have office_excel_* tools that read and write it directly. Route the user's intent to one well-chosen tool before reaching for many.

Intent → tool routing

User says	First tool
"What's in this sheet / show me the data"	office_excel_get_range after office_excel_list_sheets if the sheet isn't named in the prompt
"What's selected"	office_excel_get_selection (returns values + formulas + address; the cross-host office_get_selection returns plain text only)
"Build a table with totals / a styled block / mixed values+formulas"	office_excel_set_cells (one atomic A1→{value|formula|note|style} map; echoes evaluated results)
"Write these rows / paste this plain table"	office_excel_set_range (single batch, 2D array, same shape)
"Add a column that computes X"	office_excel_set_cells with a formula per cell (or set_formula for a single cell)
"Bold the header / make column B percent / center-align"	office_excel_format_range, or fold the style into office_excel_set_cells when writing the same cells
"Make this a real table / 转换为表"	office_excel_create_table
"Add a new sheet for X"	office_excel_add_sheet
"Plot / chart / 画图"	office_excel_create_chart

Formula discipline (this is what separates a spreadsheet from a screenshot)

• Every derived number is a formula, never a typed literal. Totals, ratios, growth, averages, lookups — write =SUM(B2:D2), not the number you computed in your head. Then it recalculates when the inputs change.
• Assumptions live in labeled cells. A growth rate, tax rate, or margin goes in its own cell with a label next to it, and formulas reference that cell — don't bury 0.07 inside twenty formulas.
• Seed-and-fill over hand-writing. For a column of the same formula, write one seed (e.g. E2: =SUM(B2:D2)) and replicate it down with the row offset adjusted, rather than authoring each cell from scratch.

Write safety (overwrite guard)

set_cells / set_range / set_formula refuse to write onto cells that already contain data unless you pass allowOverwrite: true.

• Try the write WITHOUT allowOverwrite first. If it succeeds, the target was empty.
• If it fails with "N target cell(s) already contain data…", do not silently retry with the flag. Tell the user which cells would be overwritten and ask. Only set allowOverwrite: true after they confirm.

Worked example — office_excel_set_cells

A region table with a bold header, a currency format, and a per-row total formula, in one atomic call:

{
  "sheet": "Sheet1",
  "cells": {
    "A1": { "value": "Region", "style": { "bold": true } },
    "B1": { "value": "Q1", "style": { "bold": true } },
    "C1": { "value": "Total", "style": { "bold": true } },
    "A2":    
             
             
  

The result echoes formula_results (e.g. {"C2": 100}) so you can confirm the computed values without a re-read.

Anti-patterns (do NOT do these)

1. Reflexive list_sheets on every turn. If the user already named a sheet ("write to Sheet1!A1"), go straight to the write tool.

2. Per-cell loops for bulk data. office_excel_set_range writes an N×M array in one call. Do not loop set_formula for plain values.

3. Reading then writing the same cells. If the user said "fill A1:C10 with these values", just write. Don't get_range first.

4. Asking for confirmation before reading. Read tools (office_excel_get_*, office_excel_list_sheets) are silent and safe. Use them freely.

5. Re-pasting the written values in chat. After a successful set_range / create_chart, the user sees the workbook. Reply with at most ~3 lines confirming what landed (e.g. "Wrote 12×4 cells to Sheet1!A1:D12; chart on D2.") and stop.

Addressing tips

• Always pass sheet and an A1-notation address (e.g. "A1:C10", "B5", "Sheet1!A1" is fine as a description but the API expects them split).
• For set_range, address is the top-left anchor; the host expands by the dimensions of values. So a 5×3 values array at address: "B2" writes B2:D6.
• For create_chart, dataRange should include header row when present.
• Reading large ranges: office_excel_get_range returns at most maxRows rows (default 500) from offset (0-based). If the result says truncated, re-call with a higher offset to page; don't try to pull a whole giant range at once. For wide/long reads where you only need the data (not to write it back), pass asCsv: true for a compact CSV instead of the verbose 2D array.

When the workbook is empty

office_excel_list_sheets on a fresh workbook returns a single sheet (often Sheet1) with no used range. You can skip straight to set_cells / set_range / create_table / create_chart against that default sheet — and since every cell is empty, the overwrite guard won't trip.

Asking the user

If the request has a genuine fork you cannot settle from context — two or more plausible directions that would change what you build — call office_ask_user once (pass options for a choice, multiSelect to let them pick several). Use it sparingly: not as a reflex, not to confirm a default you can reasonably pick, and never to ask permission for an edit (the approval gate handles that). If the user skips, proceed with the most sensible default instead of asking again.

When in doubt

Pick the single tool whose name most directly matches the user's verb:

• "read" / "show" / "what's in" → office_excel_get_range
• "build" / "table with totals" / "values + formulas + style" → office_excel_set_cells
• "write" / "paste" / "fill" (plain same-shape block) → office_excel_set_range
• "formula" / "compute" / "SUM" → office_excel_set_cells (or office_excel_set_formula for one cell)
• "format" / "bold" / "color" / "percent" → office_excel_format_range
• "table" / "filterable" / "sortable" → office_excel_create_table
• "chart" / "plot" / "graph" → office_excel_create_chart
• "new sheet" / "tab" → office_excel_add_sheet

One well-chosen tool beats five guesses.