Read Excel Workbook
xl_readInspect Excel workbooks read-only before editing: view grids, read cells, query and find data, read tables, and run audits/checks without changing the file, even while it is open in Excel.
Instructions
Read-only: look at a workbook before changing it (grid view, cells, queries, find, tables, audits, checks). Never changes a file, and works while it is open in Excel. To change anything use xl_edit, xl_format, xl_structure, xl_workbook or xl_app. Ops, one per line, as name(required; opt optional): what it does. path, backup and verify_com are not repeated; xl_help shows them:
get_workbook_metadata(): Read sheets, true used ranges, names, tables and a hazard summary; the call to orient before editing.
get_grid_view(opt location sheet max_rows max_cols values): Show a sheet or range as a compact A1 table with formula and merge markers, plus an anchor token for later edits.
read_range(location; opt values sheet): Read a cell or range by location; values='displayed' gives the text Excel shows, 'both' labels each value.
get_cells(cells; opt values sheet): Read many individually addressed cells in one call, the scatter complement to the rectangular read_range.
query_range(opt location sheet header columns where match order_by aggregate group_by limit offset distinct records values): Filter, sort, page and aggregate a range on the server, so only the rows and columns needed come back.
find_cells(query; opt look_in match match_case sheet location limit offset): Find every cell whose value or formula matches (exact, contains or regex), with its address; pages with limit and offset.
get_table(name; opt columns values records): Read a table's data by its name (case-insensitive).
diagnose_workbook(): Scan for fragile parts (pivots, slicers, shapes, macros, queries) a file save would drop, and recommend the route.
validate(opt checks): Run read-only checks (default structure, references, calc_staleness) and return one report.
audit_formulas(opt location sheet): Audit formulas in a range, sheet or workbook: external references, volatile functions, missing cached values, errors. More ops follow, in the same format, in the op parameter's description.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| op | Yes | The operation to run: an op listed in this tool's description, or one of these, in the same format: - audit_styles(opt top): Count the workbook's cell formats against Excel's 64,000 limit and rate the bloat risk (ok, elevated or critical). - get_pivot(opt sheet): Describe existing pivot tables (source, fields, last refresh); creating or refreshing one is xl_app com_manage_pivot. - get_connections(): List data connections and Power Query presence; connection strings can hold credentials, so treat them as sensitive. - get_external_links(): List links to other workbooks with their cached values, which are copies of other files' data, so treat them as sensitive. - inspect_vba(): Report whether the workbook carries VBA, with module names and sizes; this server never writes or runs macros. - get_workflows(opt task): Recommended tool sequences for common multi-step spreadsheet tasks, each step naming the tool and op to call and the rationale. - get_server_info(opt include_licensee): Report version, edition, license status, tool and op counts, launch-settings narrowing and platform; needs no workbook. - com_status(): Report whether Excel is available to this server and what its hidden Excel is doing; never starts Excel. | |
| args | No | The op's arguments as an object. Include path (the workbook file) unless the op's line names other paths or the op reads no workbook; unknown keys are refused. xl_help lists every argument. |