Read data from Excel worksheet with cell metadata including validation rules.

Args:
    filepath: Path to Excel file
    sheet_name: Worksheet tab name, NOT a native table name; list_tables maps tables to tabs
    start_cell: Starting cell (default A1)
    end_cell: Ending cell (optional, auto-expands if not provided)
    max_rows: Optional maximum number of rows to return from the starting row
    max_cols: Optional maximum number of columns to return from the starting column
    cursor: Optional continuation token returned by an earlier range read
    preview_only: Whether to return preview only
    compact: Whether to omit default validation metadata for smaller responses
    values_only: Whether to return a 2D value grid without per-cell metadata

Returns:  
JSON string containing either structured cell data with validation metadata
or a plain 2D value grid when values_only=True.

Read Excel data as a compact table with headers and rows or record objects.
sheet_name is a worksheet TAB, not a native table. For an approved named
table use read_excel_table(table_name=...); list_tables maps tables to tabs.
Much more context-efficient than read_data_from_excel for structured data,
with optional inferred schema hints for downstream steps.

Can return either array rows or object-shaped records, plus optional schema
hints inferred from the returned rows.
sheet_name is a worksheet tab, NOT a native table name. For named tables use
read_excel_table(table_name=...); list_tables verifies the containing worksheet.

Use the exact table_name from list_tables. Omit sheet_name when unknown;
if supplied, it must be the table's containing worksheet tab, not the table name.
Supports compact table payloads, object-shaped record output, and optional
inferred schema hints.

Write rows to a worksheet, starting at start_cell. Formulas are not evaluated.

dry_run serializes an isolated candidate and reports package_fidelity and
ready_to_commit without saving. Writes recheck protected XLSX content before
replacing the source. This is not a guarantee of full XLSX fidelity.

This is the preferred chart authoring entry point; explicit-series calls are
also still available via create_chart_from_series for backward compatibility.

Omit sheet_name to search the whole workbook, especially after a missing-tab
error. Table and worksheet names may differ; neither name implies the other.

Table inventory is not included. A missing table name in sheets does NOT mean
the table is absent. Use list_tables without sheet_name to verify named sources.

Each operation is {"tool": "name", "args": {...}}. Supported tool names are
create_worksheet, write_data_to_excel, format_range, format_ranges, freeze_panes,
set_autofilter, set_column_widths, set_row_heights, autofit_columns, create_table,
and create_chart. Assertions support sheet_exists, cell_equals, range_equals,
range_values_unchanged, table_exists, freeze_panes_equals, autofilter_equals,
chart_exists, and no_cell_ref_errors.

Call preview first. Commit the identical plan with expected_workbook_sha256 and
changeset_token from that preview. Snapshot creation defaults to enabled.
Inspect package_fidelity: custom XML or untouched formula-cache loss blocks
commit. The check is targeted, not a guarantee of full Excel round-trip fidelity.
save_mode="preserve" patches only literal cell writes in a restricted XLSX.
Unsupported workbook features or formulas block the save; no standard fallback.
Use the same save_mode in preview and commit.

scenario_set requires version=1, a Recipe v1 (only sum/count; output is never
written), key_fields, guards=[{metric, scope: overall|each_group, min?, max?}],
and scenarios=[{id, updates: [{key: {...}, values: {...}}]}]. Bounds are inclusive
exact comparisons. Each-group checks include all baseline/candidate groups;
missing baseline groups and empty coverage fail. No optimization or forecasting.
One native table, existing keys/literal updates only, no formulas/key changes.
Commit requires the identical set, selected_scenario id, scenario_token and
expected_workbook_sha256 from comparison; source drift requires a new comparison.
Full metric checks run again on the saved workbook under ChangeSet rollback.
Limits: 5 alternatives, 8 sum/count metrics, 20 guards, 50000 source cells,
1000 targets/49 column spans per alternative, 256KB JSON, sample_limit 1-5.

patch requires version=1, source={table_name, optional sheet_name}, nonempty
key_fields, explicit read_fields (use [] only for no extra dependencies), and
updates=[{key: {all key fields}, values: {literal field updates}}]. Write fields
must not be keys/read_fields. Checks complete unique keys and row-local read
dependencies; does not infer undeclared or cross-row dependencies. Existing
rows only, same exact headers with reordering allowed, no formula evaluation.
Conflicts/missing rows/changed premises block the entire batch. Commit requires
the identical patch/base and rebase_token/expected_workbook_sha256 from a fresh
preview. Reuses ChangeSet snapshots, exact-file checks and rollback. Limits:
1000 target cells, 50 contiguous column spans, 50000 table cells/64 columns per
source; sample_limit 1-10 bounds examples only. Tokens are not authentication.

Contract v1 requires version=1, name, source={table_name, optional sheet_name},
row_grain (a declaration), key_fields (logical names), and fields=[{name,
headers: [approved exact alternatives], type: string|number|integer|boolean,
nullable?: false, meaning?, allowed_values?, min?, max?}]. Optional min_rows
defaults to 1; filters use logical field names and Recipe predicates. Missing
or multiple matching headers are unresolved, never automatically selected.
Checks all source rows BEFORE filtering, excluding native totals. Declared
meanings are not verified facts. No coercion, formulas, dates, joins or code.
Limits: 32KB JSON, 32 fields, 8 aliases/field, 8 key fields, 20 filters,
50000 table cells/64 columns; sample_limit 1-5 affects row examples only.
Pass the same contract as workbook_contract to run_workbook_recipe to enforce
it in preview/commit; this inspection alone does not guard other tools.
Recovery: omit sample_limit for default 3 (never use Recipe's 10 here).
recipe_input_fields lists the exact logical names to use in Recipe inputs;
bindings values are physical headers for inspection, not Recipe field names.
For {name: "net", headers: ["NetSales"]}, use metrics.field="net", not
"NetSales". For {name: "currency", headers: ["Currency"]}, use
group_by=["currency"]. Metric as="Revenue" is an output label, not remapped.
Follow next_action: unresolved/violated requires an owner decision, not a
changed contract or filtered-out violation. Reuse the supplied filepath;
do not construct an absolute path by prefixing the client working directory.

Recipe v1 requires version=1, source={table_name, optional sheet_name},
group_by=[exact header names], metrics=[{op, field, as}], and
output={sheet_name, range_ref, optional allow_overwrite=false}.
Optional filters use query_table operators; optional checks support unique_key
(fields), row_count (min/max), and sum_matches (source_field/output_field).
count metrics omit field. Other metrics: sum, avg, min, max, count_non_null,
count_distinct. Only literal finite JSON cells in referenced fields are supported.
Optional workbook_contract enforces Contract v1: source selectors must match,
ALL Recipe input references must use contract fields[].name, NEVER physical
fields[].headers. Copy names from inspection.recipe_input_fields (binding keys).
Example: net bound to NetSales -> metrics=[{op:"sum",field:"net",as:"Revenue"}];
currency bound to Currency -> group_by=["currency"]. The as label stays Revenue.
This also applies to filters.field, unique_key.fields and sum_matches.source_field.
Contract field errors return bounded details.examples with Recipe JSON-pointer
paths and exact replace_with names where known: fix the Recipe references only,
keep workbook_contract unchanged, then make a NEW preview before commit.
Contract filters are mandatory
AND predicates. All contract rows are checked before filtering and again on
the saved workbook. Repeat the identical contract on commit; changed contracts
invalidate recipe tokens. Declared meanings are not verified business truth.

Output is one reserved rectangle in the same workbook, fully replaced including
blank padding. Occupied output requires allow_overwrite=true; table/merge overlap
is rejected. Preview first, then commit the unchanged recipe with recipe_token
and expected_workbook_sha256 from preview. A verified snapshot is always enabled.
Limits: 50,000 source cells, 64 source columns, 10,000 output cells; sample_limit 1-10.

Recompute one shared Recipe v1 on two distinct .xlsx source versions. Requires
nonblank unique key_fields (exact headers) on every source data row, even if
excluded by recipe filters. Supports at most 8 metrics, all sum/count.
Returns added/removed/updated contributions, group changes and bounded physical
source-row examples. Numeric evidence uses exact decimal strings. Recipe float
differences are explicit numeric_adjustment values, not business explanations.

Optional metric selects one exact output alias; group must give all group_by
fields with exact literal values. All calculations/checks remain complete;
sample_limit (1-10) only bounds examples and omitted contributions are reported.
Pin both source sha256 values and recipe_sha256 from a previous response for
repeatable drilldown. The explanation_token is an integrity fingerprint, not
authorization or a commit token. Does not validate saved report cells, infer
historical recipe definitions, evaluate formulas or establish business causes.
Limits per source: 50,000 table cells, 64 columns, 10,000 recomputed result cells.

Get all data validation rules in a worksheet.

This tool helps identify which cell ranges have validation rules
and what types of validation are applied.

Args:
    filepath: Path to Excel file
    sheet_name: Name of worksheet
    
Returns:
    JSON string containing all validation rules in the worksheet