​

Data Operations

​

Reading Data

• read_values – Retrieves cell values (and formulas) for a specific range. Responses include:
  • values – 2D array mirroring the requested range.
  • formulas – Optional formula text when available.
  • address – Range address for auditing.
• read_format – Gathers formatting attributes (font, colour, alignment, number formats, borders). Powered by FormatManager and per-attribute readers such as BoldFormatReader.
• Usage Tips
  • Provide explicit workbookName, worksheet, and range to avoid ambiguity.
  • Use wildcards like entire columns (A:A) or rows (3:3) when reading large sections—ExcelSelection can handle them efficiently.

​

Writing Data

• write_values – Writes tabular data using a 2D array. Key behaviours:
  • Dimensions must match the target range; the tool validates before writing.
  • Supports formulas (e.g., =SUM(A2:A10)). Use relative references for patterns, absolute references for constants.
  • Returns oldValues and newValues so changes can be inspected or reverted.
• write_format – Applies styling across a range. Payloads can include:
  • Font properties (bold, italic, fontSize, fontName).
  • Colours (hex strings or RGB).
  • Borders, alignment, number formats.
  • The backend optimises changes using FormatWriter to reduce redundant operations.

​

Best Practices

• Batch large updates into a single tool call to reduce Excel automation overhead.
• For append operations, combine read_values to find the next empty row with write_values to insert data.
• When altering formats, explicitly include only the properties you want to change; the formatter leaves unspecified attributes untouched.
• Use View mode to preview writes before approving. Revert data is generated automatically, enabling quick rollbacks if the outcome isn’t correct.

​

Error Handling

• Invalid ranges or protected sheets trigger detailed error messages from the Excel API. The tool reports them back to the UI as tool:error.
• If the workbook changes while a tool is pending (e.g., the user edits cells manually), re-run read_values to ensure the latest context before approving writes.