Return workbook metadata including sheet names, active sheet, dimensions, and named ranges.

Args: file_path: Path to the workbook to inspect.

Returns: WorkbookMetadata: Pydantic model containing sheet list, active sheet, named ranges, and other metadata.

Notes: - Read-only operation. Underlying implementation may use a lightweight reader for speed.

Create a new Excel workbook at file_path with optional initial sheets.

Args: file_path: Destination path for the new workbook. sheet_names: Optional list of sheet names to create. sheet_name: Optional single sheet name (legacy convenience).

Returns: WorkbookCreatedResult: Contains file path and sheet information.

Notes: - Mutates filesystem by creating a new .xlsx. Parent directory will be created if permitted by utils.

Return a brief summary of a sheet: header row, used range, row/column counts and detected headers.

Args: file_path: Workbook path. sheet_name: Worksheet to summarise.

Returns: SheetSummary: Pydantic model with summary fields.

Notes: - Read-only.

Create or overwrite a workbook with multiple sheets, headers and data in a single call.

Args: file_path: Destination workbook path. sheets: List of SheetDefinition (name, headers, rows, column widths, etc.).

Returns: WriteMultiSheetResult: Result model with file path and any warnings.

Notes: - Destructive when targeting existing files — document overwrite semantics in higher-level docs.

Manage sheets within a workbook (rename, delete, copy, hide/unhide, set tab color, move order).

Args: action: One of "rename", "delete", "copy", "hide", "unhide", "tab_color", "move". - "rename": requires new_name. - "delete": deletes the sheet; destructive. - "copy": requires new_name for the copy. - "hide": hides the sheet (cannot hide all visible sheets). - "unhide": unhides the sheet. - "tab_color": requires color (6-char hex) to set or "000000" to clear. - "move": requires offset (int) to shift position. file_path: Workbook path. sheet_name: Target sheet name for the action. new_name: New name for rename/copy. color: Tab color hex string for "tab_color". offset: Position offset for "move" (positive = right).

Returns: str or dict: Operation result or metadata.

Raises: ValueError: When required arguments for an action are missing.

Notes: - Dispatch mapping: "rename"→tools.workbook.rename_sheet, "delete"→tools.workbook.delete_sheet, "copy"→tools.workbook.copy_sheet, "hide"→tools.workbook.hide_sheet, etc. - Deletions and moves are destructive operations and should be annotated in external docs and UIs.

Read cell data from a worksheet.

Args: mode: One of "single", "range", or "chunked". Determines the behaviour and required parameters. - "single": returns a single cell value. Requires cell_ref. - "range": returns a rectangular range. Requires start_cell and end_cell. - "chunked": returns a chunked reader result for large sheets. Optional: start_row, chunk_size. file_path: Path to the workbook (validated by utils). sheet_name: Worksheet name. cell_ref: Cell reference for single-cell reads (e.g. "A1"). start_cell: Top-left cell for range reads. end_cell: Bottom-right cell for range reads. include_formula: If True, include formula text when available. include_metadata: If True, include additional metadata (styles, comment presence, etc.). show_formula: For range reads, include formulas instead of values when True. show_style: For range reads, include style information when True. output_format: Format for range output; typically "json". max_cells: Maximum cells to return for range reads (to avoid huge payloads). start_row: For chunked reads, starting row index (0-based). chunk_size: Number of rows per chunk for chunked reads.

Returns: dict or ChunkReadResult: Single value, range payload, or chunked reader object depending on mode.

Raises: ValueError: If required parameters for the chosen mode are missing or mode is unknown.

Notes: - Read-only: this function only reads workbook data and should not mutate files. - Dispatch mapping: "single"→tools.cell_ops.read_cell, "range"→tools.cell_ops.read_range, "chunked"→tools.cell_ops.read_file_chunked.

Write data or operations to worksheet cells.

Args: mode: One of "single", "range", "series", "merge", or "unmerge". - "single": write a single cell. Requires cell_ref and value. - "range": write a 2D array starting at start_cell. Requires start_cell and data. - "series": fill a series from start_cell. Requires start_cell and count. - "merge": merge a cell range. Requires range_string. - "unmerge": unmerge a cell range. Requires range_string. file_path: Path to workbook to mutate. sheet_name: Target worksheet name. cell_ref: Single-cell reference for "single" and some formula operations. value: Value to write for single-cell writes. start_cell: Top-left cell for range/series writes. data: 2D array of values for "range" mode. series_type: Series type for "series" (e.g. "number"). count: Number of series entries to write (required for "series"). step: Increment for numeric series or string step expression. direction: "down" or "right" for series growth. start_value: Optional starting value for series. range_string: Range string for merge/unmerge (e.g. "A1:D1").

Returns: str or dict: Success message or structured result depending on operation.

Raises: ValueError: If required parameters for the chosen mode are missing or mode is unknown.

Notes: - This route mutates workbook files (destructive operations). - Dispatch mapping: "single"→tools.cell_ops.write_cell, "range"→tools.cell_ops.write_range, "series"→tools.cell_ops.fill_series, "merge"→tools.cell_ops.merge_cells, "unmerge"→tools.cell_ops.unmerge_cells. - Recommend adding short examples in the underlying tools for common series patterns.

Clear values from a rectangular range of cells.

Args: file_path: Path to workbook. sheet_name: Worksheet name. start_cell: Top-left cell of range to clear. end_cell: Bottom-right cell of range to clear.

Returns: str: Success message.

Raises: (Propagates exceptions from the underlying tools on I/O or invalid ranges.)

Notes: - Destructive: clears cell values (but not necessarily styles) — mention in API docs.

Copy a range of cells to a destination range (same workbook or across sheets).

Args: file_path: Source workbook path (when copying within same workbook). source_sheet: Source worksheet name. source_range: Range to copy (e.g. "A1:B10"). dest_sheet: Destination worksheet name. dest_range: Destination top-left target (e.g. "C1"). copy_values: If True, copy values. copy_styles: If True, copy styles. paste_values_only: If True, read resolved values and write values (not formulas).

Returns: str: Success message.

Notes: - May open the workbook twice if paste_values_only is True (read-only pass then write pass).

Find and replace text across a worksheet.

Args: file_path: Path to workbook to modify. sheet_name: Worksheet name. find_text: Substring or pattern to find. replace_text: Replacement text. match_case: Case-sensitive search when True. match_entire_cell: Match entire cell contents exactly when True. search_formulas: Also search within formulas when True. regex: Treat find_text as a regular expression when True.

Returns: dict: {"count": int, "cells": ["A1", ...]} detailing replacements.

Notes: - Destructive: modifies cells in-place. - Consider returning per-cell before/after pairs for audit logging in high-risk contexts.

Transpose a source range (rows↔columns) and write starting at target_cell.

Args: file_path: Path to workbook. sheet_name: Target worksheet name (destination for transposed data). source_range: Range to transpose (on sheet_name by default). target_cell: Top-left cell for the transposed output. source_sheet: Optional source sheet name if different from sheet_name. paste_values_only: If True, paste only resolved values (no formulas).

Returns: dict: Summary including target range written and number of cells.

Notes: - Destructive: overwrites destination cells.

Apply font, fill, alignment, borders and number formats to a cell range.

Args: file_path, sheet_name: Target workbook and sheet. cell_range: Range to format. bold, italic, font_size, font_color, bg_color: Font and fill controls. number_format: Custom number format string. horizontal_alignment, vertical_alignment: Alignment enums. wrap_text, border_style, border_color, font_name, underline, strikethrough, text_rotation, indent, shrink_to_fit: Formatting options. top_border_style, bottom_border_style, left_border_style, right_border_style: Per-side border overrides. number_format_preset: Named preset from NUMBER_FORMAT_PRESETS. preserve_existing: If True, do not overwrite unspecified style attributes.

Returns: str: Result message.

Notes: - Mutates formatting in workbook; recommend documenting idempotency when called multiple times with same args.

Auto-fit column widths to their contents for a worksheet.

Args: file_path: Workbook path. sheet_name: Worksheet name.

Returns: str: Success message.

Notes: - Mutates column widths and may be expensive on large sheets.

Copy formatting from a single source cell to every cell in a target range.

Args: file_path: Workbook path. sheet_name: Worksheet name. source_cell: Reference of the cell to copy formatting from. target_range: Range to apply the copied format.

Returns: dict: Summary of changed cells.

Notes: - Mutates formatting; does not touch values.

Clear formatting from cells in range_str without altering cell values.

Args: file_path: Workbook path. sheet_name: Worksheet name. range_str: Range whose formatting should be reset.

Returns: dict: Summary of cleared cells.

Notes: - Non-destructive to cell values but destructive to formatting state.

Apply a named built-in Excel style to a range (e.g. 'Good', 'Heading 1').

Args: file_path: Workbook path. sheet_name: Worksheet name. range_str: Target range. style_name: Name of the named style to apply.

Returns: dict: Result metadata.

Notes: - Mutates formatting and depends on openpyxl named style availability.

Set, batch-set, fill or auto-sum formulas in cells.

Args: action: "set", "batch", "fill", or "auto_sum". - "set": requires cell_ref and formula (is_array optional, target_range optional). - "batch": requires formulas dict mapping cell_ref to formula string, e.g. {"A1": "=SUM(B1:B10)", "A2": "=AVERAGE(C1:C10)"}. - "fill": requires cell_ref (source) and target_range. - "auto_sum": requires cell_ref (destination) and optional source_range. file_path, sheet_name: Workbook and sheet to modify. is_array: Whether the formula is an array formula. target_range, formulas, source_range: Operation-specific params.

Returns: str | dict: Success message or batch result.

Notes: - Writing formulas mutates the workbook. fill uses formula translation utilities; verify absolute/relative reference behaviour.

Inspect formulas: get cached value, list errors, find precedents/dependents, or list all formulas.

Args: action: "value", "errors", "precedents", "dependents", or "list". file_path, sheet_name: Workbook and sheet. cell_ref: Required for "value", "precedents", and "dependents". cell_range: Optional range filter for "errors".

Returns: dict or list: Action-dependent payload (e.g. value, list of FormulaErrorInfo, list of cell refs).

Notes: - Read-only.

Perform chart lifecycle and series/configuration operations on a worksheet.

Args: action: One of "create", "delete", "list", "add_series", "set_axes", "trendline", "combo", "data_labels", "legend", "update". - "create": create a chart from data_range at target_cell; optional categories_range overrides x-axis category labels. - "delete": remove a chart (optionally chart_index). Destructive. - "list": return list of charts (read-only). - "add_series": add a series to an existing chart (requires chart_index, data_range). - "set_axes": configure axis titles/ranges/number format; optional categories_range sets x-axis category labels. - "trendline": add a trendline to a series. - "combo": create a combo chart; requires bar_columns and line_columns. - "data_labels": configure data labels by chart_title. - "legend": configure legend by chart_title. - "update": update basic title/size/anchor of an existing chart. file_path: Workbook path. sheet_name: Worksheet name containing chart or data. chart_index: Optional index of target chart (default 0 or required for some actions). data_range: Range string used for chart creation or series. chart_type: Chart kind (e.g. "column", "line"). target_cell: Anchor cell for new chart. ... (other visual/series parameters)

Returns: str or list[ChartInfo]: Created chart id/string or list of ChartInfo for "list".

Raises: ValueError: If required parameters are missing for the selected action.

Notes: - Dispatch mapping: see function source; common destructive actions include "delete". - Chart creation mutates the workbook; consider documenting expected anchor and sizing units.

Toggle view-related settings such as freeze panes, auto-filter and gridlines.

Args: action: "freeze", "auto_filter", or "set_gridlines". file_path: Workbook path. sheet_name: Worksheet name. cell_ref: For freeze, the pane freeze cell (omit to unfreeze). cell_range: For auto_filter set/remove. remove: For auto_filter, remove filter when True. show: For set_gridlines, show/hide gridlines.

Returns: str: Result message.

Notes: - Usually non-destructive aside from toggling UI settings stored in workbook.

Perform row/column insert/delete, grouping, and size adjustments.

Args: action: One of insert/delete/group/ungroup/set_row_height/set_col_width. file_path: Workbook path. sheet_name: Worksheet name. row, col, count, start_row, end_row, start_col, end_col: Position arguments. outline_level, hidden, rows, cols_list, height, width: Operation-specific params.

Returns: str: Result message.

Notes: - Many actions are destructive (delete_rows/delete_cols) — document irreversible effects.

Configure print areas, page setup, print titles and manual page breaks.

Args: action: "set_print_area", "set_page_setup", "set_print_titles", "add_page_break", "remove_page_break". file_path, sheet_name: Workbook and worksheet. print_area, orientation, paper_size, fit_to_width, fit_to_height, title_rows, title_cols, row, col: params.

Returns: str: Result message.

Notes: - Mostly metadata changes to the sheet's print settings.

Cross-sheet and cross-workbook copy/merge/stack operations.

Args: action: "copy_range_across", "copy_sheet_across", "merge_workbooks", or "stack_sheets". file_path: Source workbook path (varies by action). source_sheet, source_range: Source identifiers for copy. target_sheet, target_start_cell: Destination identifiers. copy_values, copy_styles: Copy options. source_file, dest_file, dest_sheet_name: For copy_sheet_across. source_files, output_file, conflict_strategy: For merge_workbooks. sheet_names, dest_sheet, include_header, output_path: For stack_sheets.

Returns: str or dict: Result metadata.

Notes: - These operations can be expensive (many file opens) and destructive. Document conflict resolution strategies.

Sort worksheet rows by one or more columns and write back the result.

Args: file_path: Workbook path. sheet_name: Worksheet to sort. sort_by: List of sort descriptors, each with 'column' (str) and optional 'ascending' (bool, default True). column: Convenience single-column sort (deprecated in favour of sort_by). ascending: Boolean default sort order when column is used. has_header: Whether the sheet has a header row.

Returns: str: Result message.

Notes: - Destructive: overwrites sheet rows.

Compute descriptive statistics for a numeric column (mean, median, std, min, max, sum).

Args: file_path: Workbook path. sheet_name: Worksheet name. column: Column name or letter to analyse. has_header: Whether the sheet has a header row.

Returns: ColumnStats: Pydantic model with statistical measures.

Notes: - Read-only.

Group rows by column(s) and aggregate values using the specified operation.

Args: file_path: Workbook path. sheet_name: Worksheet name. group_by: Column or list of columns to group by. value_column: Column to aggregate. operation: Aggregation operation (e.g. 'sum', 'mean', 'count'). has_header: Whether the sheet has a header row. aggfunc: Optional pandas-style aggfunc or mapping.

Returns: dict: Aggregated results (may be written to sheet if underlying tool provides an option).

Identify duplicate rows based on a list of columns.

Args: file_path: Workbook path. sheet_name: Worksheet name. columns: Columns used to determine duplicates. has_header: Whether the sheet has a header row.

Returns: dict: Duplicate groups and row indices.

Perform cross-file lookup akin to VLOOKUP with optional fuzzy matching.

Args: lookup_file: Workbook containing keys to look up. data_file: Workbook containing reference data. lookup_column: Column in lookup_file to match. data_key_column: Column in data_file to join on. data_return_columns: Columns from data_file to return. lookup_sheet, data_sheet: Sheet names. fuzzy: If True, perform fuzzy matching. fuzzy_threshold: Threshold for fuzzy confidence. output_file: Optional path to write augmented lookup results. header_row: 1-based header row index.

Returns: dict: Mapping rows to matched results and match scores.

Notes: - Read-only on inputs unless output_file is provided.

Filter rows using multiple conditions combined with AND/OR logic.

Args: file_path: Workbook path. sheet_name: Worksheet name. conditions: List of filter conditions, each with 'column' (str), 'operator' (str), and 'value'. logic: "AND" or "OR" to combine conditions. output_sheet: Optional sheet to write filtered output. header_row: 1-based header row index.

Returns: dict: Filtered rows or summary.

Insert SUBTOTAL formula rows after each group in a sorted sheet.

Args: file_path: Workbook path. sheet_name: Worksheet name. group_col: Column used to group rows. value_col: Column to subtotal. subtotal_func: Excel subtotal function code (9=SUM by default). include_grand_total: Whether to append a grand total row.

Returns: dict: Summary including ranges where subtotals were inserted.

Notes: - Destructive: modifies the sheet structure and inserts new rows.

Produce a data profile for a sheet or range listing types, null counts, unique counts and samples.

Args: file_path: Workbook path. sheet: Optional sheet name. data_range: Optional range to restrict profiling.

Returns: dict: Per-column profile metadata.

Notes: - Read-only.

Return frequency counts for a column as counts or normalized proportions.

Args: file_path: Workbook path. sheet_name: Worksheet name. column: Column name to analyse. normalize: If True return proportions instead of raw counts. top_n: If provided, return only the top N values. dropna: Exclude nulls when True. has_header: Whether the sheet has a header row.

Returns: dict: {"column", "total_rows", "normalize", "counts": [{"value", "count"}, ...]}.

Build a pivot table from a source sheet and optionally write it to output_sheet/output_file.

Args: file_path: Workbook path. sheet_name: Source data sheet. index_cols: List of column names to use as index (rows). value_cols: Columns to aggregate. aggfunc: Aggregation function or dict (e.g. "sum", "mean" or {col: "sum"}). output_sheet: Optional destination sheet for pivot output. output_file: Optional file to write the pivot output. column_field: Optional field used for pivot columns. date_freq: Optional date grouping alias (e.g. 'ME', 'YE', 'W').

Returns: dict: Details about output including created sheet and saved pivot metadata.

Notes: - Writes to workbook when output_sheet/output_file is provided. Stores pivot definitions in _mcp_pivots for refresh.

Refresh a previously created pivot table by re-running its stored definition.

Args: file_path: Workbook path containing stored pivot definitions. output_sheet: Name of the pivot output sheet to refresh. source_file_path, source_sheet: Optional explicit sources to override stored sources.

Returns: dict: Summary of refresh results.

Notes: - Mutates the workbook by overwriting the pivot output area.

Melt (unpivot) wide-form data to long-form using id_vars and value_vars.

Args: file_path: Workbook path. sheet_name: Source sheet. id_vars: Columns to keep as identifiers. value_vars: Columns to melt into variable/value pairs. var_name: Name for the variable column. value_name: Name for the value column.

Returns: dict: Result summary and destination range if written.

Join two sheets within the workbook similar to SQL join semantics.

Args: file_path: Path to workbook. sheet1, sheet2: Names of the two sheets to join. join_key: Column name(s) common to both sheets (shorthand for left_on/right_on). how: One of "left", "right", "inner", "outer". output_sheet: Optional sheet name to write merged results. left_on, right_on: Optional explicit join keys for differently named columns.

Returns: dict: Key counts and output information.

Add a computed column either via pandas-eval formula or as a cumsum/rolling operation.

Args: file_path: Workbook path. sheet_name: Worksheet name. new_column_name: Column name to add. expression: Expression string for pandas.eval when column_type=='formula'. has_header: Whether the sheet has a header row. column_type: One of 'formula', 'cumsum', 'rolling'. source_col: Required for 'cumsum' and 'rolling'. window: Integer window for rolling operations. rolling_func: Aggregation for rolling (default 'mean').

Returns: str: Message indicating success and destination column.

Notes: - Accepts user-provided expressions — underlying code performs AST checks; docstring should link to safety doc.

Remove duplicate rows from a sheet, optionally using a subset of columns.

Args: file_path: Workbook path. sheet_name: Worksheet name. columns: Optional list of columns to consider for duplicates. keep: Which duplicate to keep: 'first', 'last', or False (drop all duplicates).

Returns: str: Summary message and number of rows removed.

Notes: - Destructive: modifies the workbook unless an output_file variant is implemented upstream.

Find a variable cell value that makes an expression evaluate to a target and write the result.

Args: file_path: Workbook path. sheet_name: Worksheet containing the expression. variable_cell: Cell reference to adjust (e.g. "B2"). expression: Arithmetic expression referencing worksheet cells (string). target_value: Numeric target value for the expression. initial_value: Starting guess for the solver. tolerance: Convergence tolerance. max_iterations: Maximum solver iterations.

Returns: dict: Result with solved value, status, and iterations used.

Notes: - Destructive: writes the solved value back to the workbook. - Recommend adding a short example expression in docs.

Generate a loan amortization schedule for given principal, rate and term.

Args: principal: Loan principal amount. annual_rate: Annual interest rate (fractional, e.g. 0.05 for 5%). years: Term in years. payments_per_year: Payment frequency (default 12).

Returns: dict: Schedule rows and totals including payment amount, interest, principal breakdown.

Compute Discounted Cash Flow valuation with a Gordon Growth Model terminal value.

Args: cash_flows: List of cash flows (period-ordered), first item normally year 0 investment (negative). discount_rate: Discount rate as decimal. terminal_growth_rate: Perpetuity growth for terminal value. initial_investment: Optional initial outlay to include in NPV.

Returns: dict: NPV, terminal value, IRR and breakdowns.

Compare budget vs actual values in a sheet and return variances per category.

Args: file_path: Workbook path. sheet_name: Worksheet name. category_column, budget_column, actual_column: Column identifiers for the analysis. header_row: 1-based header row index. output_file: Optional path to write results.

Returns: dict: Per-category variance and status.

Notes: - Mutates workbook only if output_file provided.

Compute common financial ratios from raw financial metric inputs and compare them to benchmarks.

Args: financial_data: Dict of raw metric values keyed by component name. Valid keys: current_assets, current_liabilities, inventory, total_debt, total_equity, net_income, total_assets, revenue, gross_profit, operating_income, ebitda, interest_expense. E.g. {"current_assets": 500000, "current_liabilities": 250000}. industry_benchmarks: Optional dict of benchmark ratio values to compare against, e.g. {"current_ratio": 2.0, "roe": 0.15}.

Returns: dict: Computed ratios and optional benchmark comparisons.

Notes: - This function is pure math and does not touch files.

Calculate break-even units and revenue given fixed and variable costs.

Args: fixed_costs: Total fixed costs. price_per_unit: Selling price per unit. variable_cost_per_unit: Variable cost per unit.

Returns: dict: break_even_units and break_even_revenue.

Create a 1- or 2-variable sensitivity table in the workbook.

Evaluates expression over supplied value grids.

Args: file_path: Workbook path. sheet_name: Worksheet containing the base formula or output cell. output_cell: Cell that contains or references the expression to evaluate. expression: Expression that will be evaluated relative to variable names. var1_name, var1_values: Name and values for variable 1. var2_name, var2_values: Optional name/values for a second variable (two-way table).

Returns: dict: Summary including output range and written values.

Notes: - Mutates workbook by inserting the table; confirm overwrite semantics when the target output area overlaps data.

Perform a variety of time-value-of-money calculations and depreciation methods.

Args: operation: One of "fv", "pv", "nper", "rate", "depreciation", "irr". rate, nper, pmt, pv, fv, when, guess: Parameters depending on operation. cost, salvage, life, method, period: Parameters for depreciation operations. cash_flows: For IRR, list of floats.

Returns: dict: Operation-specific outputs (e.g. numeric answer, schedule, irr value).

Raises: ValueError: If required args for the selected operation are missing.

Notes: - Pure calculations except for methods that may write results when integrated into workbook workflows.

Split a single text column into multiple columns using a delimiter.

Args: file_path: Path to workbook. sheet_name: Worksheet name. column: Column letter or header name to split. delimiter: Delimiter string (default ","). new_columns: Optional list of new column names. drop_original: If True, remove the original column after split. output_file: Optional path to write results instead of overwriting input. header_row: 1-based header row index.

Returns: dict: Summary of created columns and row counts.

Notes: - Destructive unless output_file is provided.

Run a pipeline of cleaning operations (trim, dedupe, fill missing, normalize, etc.) on a sheet.

Args: file_path: Workbook path. sheet_name: Worksheet to operate on. operations: Ordered list of operations to run (see tool docs for allowed names). columns: Optional subset of columns to target. preview: If True, return a preview without persisting changes. output_file: Optional path to write cleaned results. header_row: 1-based header index. fill_missing_strategy: Strategy name for filling missing values. fill_value: Literal value to use if strategy is "value".

Returns: dict: Summary including rows modified and operations applied.

Notes: - Document allowed operations strings in the route or underlying tool docs.

Parse varying date formats in a column and write normalized results to an output column.

Args: file_path: Workbook path. sheet_name: Worksheet name. column: Column to parse. output_column: Optional target column; if omitted, overwrites column. output_format: Strftime format for normalized output. dayfirst: Whether to parse day-first dates. header_row: 1-based header index.

Returns: dict: Summary including number of parsed rows and parse errors.

Notes: - Destructive by default when output_column targets existing column.

CSV helper operations: preview CSV, convert CSV→XLSX, and export XLSX→CSV.

Args: action: "preview", "to_xlsx", or "to_csv". - "preview": requires file_path (CSV path); returns a small preview as dict. - "to_xlsx": requires csv_path (or file_path) and xlsx_path (or output_path). - "to_csv": requires file_path (XLSX) and output_path (CSV destination). file_path, csv_path, xlsx_path, output_path: Path parameters as described above. sheet_name: Sheet to export when converting XLSX→CSV. rows: Number of preview rows to return. delimiter, encoding: CSV parameters.

Returns: dict or str: Preview dict for "preview" or destination path for conversions.

Raises: ValueError: If required path parameters are missing for the selected action.

Notes: - "to_xlsx" and "to_csv" perform file writes; document whether they overwrite existing files.

Run an OLS linear regression and optionally write results to a sheet/file.

Args: file_path: Input workbook path. sheet_name: Worksheet containing data. y_column: Dependent variable column name. x_columns: List of independent variable column names. header_row: 1-based header row index. output_sheet: Optional sheet name for regression output. output_file: Optional path to write results to a separate file.

Returns: RegressionResult: Contains coefficients, R-squared, residuals and diagnostics.

Notes: - Read-only unless output_file/output_sheet is provided (then mutates workbook/creates file).

Apply exponential smoothing (simple/Holt/Holt-Winters) to a time series column.

Args: file_path: Workbook path. sheet_name: Worksheet name. column: Column to smooth. alpha: Smoothing factor for simple smoothing. new_column_name: Optional name for output column; if omitted, a generated name is used. header_row: 1-based header index. output_file: Optional file to write output. method: One of "simple", "holt", "holt_winters". seasonal_periods: Required for Holt-Winters. forecast_steps: Number of out-of-sample forecast steps to produce. smoothing_trend, smoothing_seasonal: Optional fixed smoothing parameters.

Returns: dict: Summary and references to output column/sheet.

Notes: - May modify workbook if output_file/new_column_name provided.

Run constrained optimisation using scipy to minimise (or maximise) an objective built from cell references.

Args: file_path: Workbook path. sheet_name: Worksheet providing objective or referenced cells. objective_expression: Arithmetic expression using cell refs (e.g. "B2 * B3 - B4"). variable_cells: Mapping of cell_ref to bounds, e.g. {"B2": {"lower": 0, "upper": 100}}. constraints: Optional list of solver constraints, each with 'expression' and 'type' ('ineq' or 'eq'). maximize: If True, the objective is maximised instead of minimised. tolerance: Convergence tolerance. max_iterations: Maximum solver iterations.

Returns: SolverResult: Contains solution, status, and diagnostics.

Notes: - May write back solution values into the workbook depending on implementation — document write semantics.

Compute a Pearson correlation matrix for numeric columns.

Args: file_path: Workbook path. sheet_name: Worksheet name. columns: Optional list of column names to include. If None, all numeric columns are used. output_sheet: Optional sheet name to write the matrix. output_file: Optional file path to write results. header_row: 1-based header index.

Returns: dict: {"columns": [...], "matrix": [[float, ...], ...]}.

Notes: - Read-only unless output_sheet/output_file is set.

Sheet and workbook protection utilities.

Args: action: One of "protect_sheet", "unprotect_sheet", "protect_cells", "protect_workbook", "unprotect_workbook". file_path: Workbook path. sheet_name: Sheet name for sheet-scoped operations. password: Optional password string used for protection/unprotection. locked_range: Range to lock for "protect_cells". unlocked_ranges: List of ranges allowed for edits. allow_*: Flags controlling allowed operations on protected sheets.

Returns: str: Result message.

Notes: - Protect/unprotect modify workbook security. Warn users about lost passwords.

Add or remove data validation rules on a cell range.

Args: action: "dropdown", "numeric", "date", "remove", or "formula". file_path, sheet_name: Target workbook and sheet. cell_range: Range to apply validation. options: For dropdown lists, list of allowed values. source_range: Alternative dropdown source range. operator, value1, value2: Numeric operator and bounds for numeric validation. date1, date2: Date bounds for date validation. allow_blank, error_style, error_title, error_message, prompt_title, prompt_message: UX controls. formula: Custom formula when action=="formula".

Returns: str or dict: Result or validation metadata.

Notes: - "remove" is destructive for validation rules; this does not delete values, only rules.

Read document properties or set calculation mode.

Args: action: "get" or "set_calc_mode". file_path: Workbook path. calc_mode: "auto", "manual", or "autoNoTable" for setting calculation mode.

Returns: dict or str: Properties dict for "get"; status message for "set_calc_mode".

Notes: - Changing calc mode changes workbook behaviour for formula recalc; mention effect in docs.

Apply, list, or remove conditional formatting rules on a sheet.

Args: action: One of "apply", "highlight", "formula_rule", "remove", "top_bottom", "above_below_average", "list". file_path, sheet_name: Target workbook and sheet. cell_range: Range to apply/remove rules. format_type, start_color, mid_color, end_color, bar_color, icon_style: Visual rule parameters. operator, formula: Rule parameters for highlight/formula rules. font_color, bg_color, is_top, rank, percent, is_above, equal_average: Additional rule params.

Returns: str | dict | list: Depends on action.

Notes: - Removing rules is destructive to formatting state. - Consider documenting rule precedence and Excel-specific limitations.

Add, read, delete or list cell comments on a sheet.

Args: action: "add", "read", "delete", or "list". - "add": requires cell_ref and text; optional author. - "read": requires cell_ref; returns CommentInfo or None. - "delete": requires cell_ref; destructive. - "list": returns list of CommentInfo for the sheet. file_path: Workbook path. sheet_name: Worksheet name. cell_ref: Cell reference for single-cell operations. text: Comment text for "add". author: Optional author string.

Returns: str | CommentInfo | list[CommentInfo] | None: Depends on action.

Notes: - Deletions mutate the workbook.

Add, read, delete, or list hyperlinks attached to cells.

Args: action: One of "add", "read", "delete", "list". file_path: Workbook path. sheet_name: Worksheet name. cell_ref: Cell reference (required for single-cell ops). url: URL for "add". display_text, tooltip: Optional display and tooltip text.

Returns: str | HyperlinkReadResult | list[HyperlinkInfo] | None

Notes: - Deleting hyperlinks modifies the workbook.

Manage saved scenarios (what-if value sets) persisted in a hidden sheet.

Args: action: "add", "list", or "apply". - "add": requires name and cell_values — a nested dict mapping sheet name to {cell_ref: value}, e.g. {"Sheet1": {"A1": 100, "B2": 200}, "Sheet2": {"C3": "hello"}}. - "list": returns available scenarios. - "apply": requires name and will write stored cell values into the workbook (destructive). file_path: Workbook path. name: Scenario name for add/apply. cell_values: Nested dict mapping sheet_name → {cell_ref: scalar_value} for "add". description: Optional free-text description.

Returns: str | list[ScenarioInfo] | ScenarioApplyResult

Notes: - Scenarios are stored in a hidden _mcp_scenarios sheet — mention potential user-visible side-effects when users open the workbook.

List, create, delete, or update named ranges within a workbook.

Args: action: "list", "create", "delete", or "update". file_path: Workbook path. name: Named range name for create/delete/update. destination: Destination range string for create. scope: "workbook" or sheet-scoped identifier. new_destination: New range for update.

Returns: list[NamedRangeInfo] | str

Notes: - Creating/updating named ranges mutates workbook metadata but typically does not alter cell values.

Create, list, resize, toggle totals, read data, or convert tables to ranges.

Args: action: "create", "list", "resize", "totals", "data", or "convert_to_range". file_path: Workbook path. sheet_name: Worksheet containing the table. table_name: Table name for operations that require it. data_range: Range to use when creating a table. style_name: Named table style for creation. new_range: New range for resize. show_totals: Bool for toggling totals row. column_totals: Dict mapping column name to aggregation function name (e.g. {"Revenue": "sum", "Quantity": "count"}). Valid functions: sum, count, average, max, min, countNums, stdDev, var, none.

Returns: str | list[TableInfo] | dict

Notes: - Table creation/resizing mutates workbook structure.

Perform cross-workbook operations: aggregate, filter, validate schema consistency, compare two workbooks.

Args: action: "aggregate", "filter", "validate", or "compare". - "aggregate": requires file_paths and column; returns aggregated metric. - "filter": requires file_paths, column, operator, value; returns filtered rows or writes to output_file. - "validate": requires file_paths and key_column; checks schema/consistency across files. - "compare": requires file_a and file_b; returns diff summary and optionally writes a report. file_paths, file_a, file_b: File list / pair for relevant actions. column, operation, operator, value: Parameters for aggregation/filtering. output_file: Optional path to write the result.

Returns: dict: Operation-specific result (e.g. aggregation numbers, diffs, validation errors).

Notes: - When output_file is provided operations may write new files — document overwrite policy.

Insert an image into a worksheet anchored at a target cell.

Args: file_path: Workbook path to modify. sheet: Worksheet name. image_path: Path to image (PNG/JPG/GIF). cell: Anchor cell where image is placed. width: Optional width in Excel units. height: Optional height in Excel units.

Returns: dict: Metadata about the inserted image (anchor, size, file used).

Notes: - Mutates workbook and depends on Pillow. Document supported image formats and sizing behaviour.

Execute sandboxed Python/pandas code against a workbook or sheet and return result.

Args: file_path: Path to source workbook to load into the sandbox. code: Python code string. Sandbox exposes df (pandas.DataFrame), pd (pandas), np (numpy). sheet: Optional sheet name to load into df. If omitted, the first sheet or a default is used. output_file: Optional path to write results back to a workbook.

Returns: dict: Execution result, typically containing result (from user code), stdout and errors.

Raises: ValueError: If code fails safety checks in the sandbox.

Notes: - High-risk: sandbox uses AST checks — document the allowed AST nodes and forbidden names. - Recommend returning a short example snippet of a safe operation in the route docs.

Upload a file for server-side processing.

Accepts a base64-encoded file string or an HTTP/HTTPS URL. Returns a session_id and file_path that can be used with any other tool. The file is stored temporarily on the server and auto-deleted after 1 hour or when release_file is called.

Args: file_content: Base64-encoded file bytes OR an HTTP/HTTPS URL pointing to the file. filename: Filename hint used to determine the file extension (e.g. "data.xlsx", "report.csv").

Returns: dict: A mapping containing: - session_id (str): Opaque ID for this file session. - file_path (str): Server-side local path — use this as file_path in other tools. - message (str): Human-readable confirmation.

Download a file from the server as base64.

Use after tools that modify a workbook to retrieve the updated file content.

Args: file_path: Local path to the file (typically from upload_file or a tool that created a file).

Returns: dict: A mapping containing: - file_content (str): Base64-encoded file bytes. - filename (str): Basename of the file. - size_bytes (int): Size of the file in bytes.

Release a session file and delete it from the server.

Call this when you are done with a file to free server disk space.

Args: session_id: The session_id returned by upload_file.

Returns: dict: A mapping containing: - success (bool): Whether the file was successfully released. - message (str): Human-readable result description.