Excel: Token-Saving Inspection Tools (High Priority)

[jwesleye]

Overview

Add memory-efficient inspection tools for Excel files to help agents avoid loading entire spreadsheets into context, similar to the CSV and JSON token-saving tools.

Motivation

Excel files can contain thousands of rows and dozens of columns. Agents often need to inspect structure and metadata before deciding what to process, but loading entire sheets wastes tokens and may exceed context windows.

Proposed Functions

High Priority - Inspection Tools

• get_sheet_info - Get metadata (row count, column count, file size) without loading data
• get_sheet_schema - Get column names and inferred data types by sampling
• preview_sheet_rows - Get first N rows without loading entire sheet
• get_sheet_names - List all sheet names in workbook

High Priority - Selective Reading

• select_sheet_columns - Read only specific columns, discard others
• filter_sheet_rows - Read only rows matching filter criteria (6 operators)
• get_sheet_row_range - Get specific range of rows (pagination support)
• sample_sheet_rows - Get representative sample (first/random/systematic)

Medium Priority - Statistics

• get_sheet_column_stats - Get statistics for a column (unique count, null count, sample values, min/max)
• count_sheet_rows - Count rows with optional filter
• get_sheet_value_counts - Get frequency distribution for column values

Design Principles

• Google ADK compliant (JSON-serializable types, no defaults)
• @strands_tool decorator
• Memory-efficient (stream processing where possible)
• Consistent with CSV/JSON token-saving patterns
• Process data without loading entire sheets

Related

• Similar to CSV tools: get_csv_schema, preview_csv_rows, select_csv_columns, etc.
• Related to issue Excel: Charts and Graphs (High Priority) #35 (Excel Charts), Excel: Conditional Formatting and Data Validation (High Priority) #36 (Conditional Formatting), Excel: Pivot Tables, Images, and Advanced Formulas (Medium Priority) #37 (Pivot Tables)
• Complements existing excel/reading.py functions

Module

excel/reading.py (or new excel/inspection.py)

[jwesleye]

Implemented all 10 Excel token-saving inspection tools in commit 8ef337c.

Added functions:

• get_sheet_info - Metadata without loading data
• get_sheet_schema - Infer column types by sampling
• preview_sheet_rows - First N rows preview
• select_sheet_columns - Read specific columns only
• filter_sheet_rows - Filter by criteria (6 operators)
• get_sheet_row_range - Pagination support
• sample_sheet_rows - 3 sampling methods
• get_sheet_column_stats - Column statistics
• count_sheet_rows - Row counts with optional filter
• get_sheet_value_counts - Frequency distribution

All functions use openpyxl's read_only mode, follow Google ADK standards, and include @strands_tool decorators. Excel module now has 18 reading functions (8 original + 10 new).