Tool Definitions Reference

The agentic layer exposes 13 tools in OpenAI function-calling format. These are used by both TRex and the MCP server.

list_tables

List all Iceberg tables in the catalog.

Parameters: None

Returns: {"namespaces": [...], "tables": [...]}

get_table_health

Analyze table health with file statistics and recommendations.

Parameter	Type	Required	Description
table	string	Yes	Fully qualified table name

Returns: {"snapshot_count": N, "data_file_count": N, "small_file_count": N, "recommendation": "..."}

get_schema

Get the schema of a table.

Parameter	Type	Required	Description
table	string	Yes	Fully qualified table name

Returns: {"columns": [{"name": "...", "type": "...", "nullable": bool}]}

compact_table

Run file compaction on a table.

Parameter	Type	Required	Default	Description
table	string	Yes	—	Fully qualified table name
strategy	string	No	"binpack"	Compaction strategy: binpack, sort, zorder

Returns: {"rewritten_files": N, "new_files": N, "rewritten_bytes": N}

expire_snapshots

Expire old snapshots to reclaim storage.

Parameter	Type	Required	Default	Description
table	string	Yes	—	Fully qualified table name
retain_last	integer	No	5	Number of snapshots to keep

Returns: {"expired_count": N, "remaining_count": N}

remove_orphan_files

Remove orphan data files not referenced by any snapshot.

Parameter	Type	Required	Default	Description
table	string	Yes	—	Fully qualified table name
dry_run	boolean	No	false	List files without removing

Returns: {"orphan_count": N, "removed_bytes": N}

table_history

Show snapshot history for a table.

Parameter	Type	Required	Description
table	string	Yes	Fully qualified table name

Returns: {"snapshots": [{"snapshot_id": N, "committed_at": "...", "operation": "..."}]}

rollback_to

Roll back a table to a previous snapshot.

Parameter	Type	Required	Description
table	string	Yes	Fully qualified table name
snapshot_id	integer	Yes	Target snapshot ID

Returns: {"rolled_back_to": N}

add_column

Add a new column to a table.

Parameter	Type	Required	Description
table	string	Yes	Fully qualified table name
name	string	Yes	Column name
type	string	Yes	Spark SQL type (e.g., STRING, BIGINT)
comment	string	No	Column comment

rename_column

Rename an existing column.

Parameter	Type	Required	Description
table	string	Yes	Fully qualified table name
old_name	string	Yes	Current column name
new_name	string	Yes	New column name

drop_column

Drop a column from a table.

Parameter	Type	Required	Description
table	string	Yes	Fully qualified table name
name	string	Yes	Column to drop

add_partition_field

Add a partition field to a table.

Parameter	Type	Required	Description
table	string	Yes	Fully qualified table name
field	string	Yes	Column name
transform	string	No	Transform: year, month, day, hour, bucket[N], truncate[N]

run_sql

Execute arbitrary SQL against the Spark session.

Parameter	Type	Required	Description
sql	string	Yes	SQL query to execute

Returns: {"columns": [...], "rows": [...], "row_count": N}