Tools Reference

The MCP server exposes the tools below. Most are read-only against a file argument. The file-writing exceptions are convert (writes a new output file), write_table (writes model-supplied rows to a new file), edit_table (edits an existing file in place), transform_columns (rename / cast / drop columns, writes back), anonymize (mask / scramble columns, writes the result), hash_columns (adds a hash column, writes the result), partition_table (writes one file per group), and write_workbook (writes one .xlsx holding several tables). The live-database write tools (write_db_table, copy_db_table) and run_sql's write_to are gated the same way. All of these are dropped when the server is started with --mcp-read-only.

Which tools reach the model, and when

All of the tools below exist in every build. What differs is how many of them are described to a model at any one time, because those descriptions are not free: together they are about 39,000 tokens of text and JSON schema, and a model has to be told about a tool before it can call one.

There are three separate switches, for three different jobs:

Switch	Where	What it is for
--mcp-read-only	MCP flag	Safety. Nothing can change a file, a tab or a database. Wins over everything else.
--mcp-tools / --mcp-without	MCP flag	Context size. The client reads the tool list once and carries it in every request to its model, so a smaller list is cheaper.
Assistant tools	Settings, GUI only	Preference. Which tools Octa's own assistant may use at all, on this machine.

Why an MCP flag rather than a setting: an MCP server is launched by its client, from that client's own config file, and different clients want different surfaces from the same Octa install. A flag lives in exactly that config; a global setting would apply to all of them at once.

Why the assistant gets an extra trick: Octa builds the assistant's requests itself, so it can send the core group up front and load a group during the conversation when a job needs it. Over MCP the client owns the tool list and decides what reaches its model, so a static filter is the only lever that works. See Token count for how the assistant side behaves.

The groups, with roughly what each costs a request:

Group	Tools	Approx. tokens	For
core	12	~6,700	reading, schemas, counting, search, profiling, SQL
quality	13	~6,400	duplicates, outliers, PII, rules, correlations
compare	7	~4,100	schema and row differences, drift, merging versions
combine	7	~4,900	unions, joins, join keys, reconciling column names
reshape	12	~8,000	pivot, resample, dedupe, impute, mask, forecast
databases	10	~4,000	live database connections, APIs, their tables and queries
cloud	4	~1,200	objects in S3, Azure, GCS, SFTP and WebDAV
write	6	~3,900	writing files, converting, reports and workbooks

Those totals are measured from the descriptions and schemas the server sends (bytes divided by three), so they move a little as tools are documented. The Settings > Chat / Assistant > Assistant tools list shows the current number per tool. The assistant has four more tools that exist only inside the GUI and have no MCP equivalent: read_text (in core), and write_text, edit_open_tab and create_chart (in write).

At-a-glance

The tools grouped the way --mcp-tools and --mcp-without name them (see Advertising fewer tools).

core

Reading, schemas, counting, search, profiling, sql.

Tool	Group	Purpose	Mutates files?
read_table	core	Load schema + rows from a file	No
tail	core	Last N rows of a file	No
sample	core	Reproducible random N-row sample	No
schema	core	Schema only (no rows)	No
list_tables	core	List tables in a multi-table source	No
count_rows	core	Row count for a table	No
run_sql	core	DuckDB SQL against the file	No *
profile	core	Per-column statistics (SUMMARIZE)	No
value_frequency	core	Per-column value counts	No
search	core	Match cells across every column	No
describe_file	core	One-shot orientation snapshot	No
grep_files	core	Grep a value across files in a directory	No

quality

Duplicates, outliers, pii, rules, correlations.

Tool	Group	Purpose	Mutates files?
find_duplicates	quality	Rows sharing key-column values	No
fuzzy_duplicates	quality	Near-duplicate row clusters (fuzzy)	No
validate_against_schema	quality	Validate columns against a JSON Schema	No
unique_columns	quality	Unique columns / key candidates	No
correlation	quality	Pairwise numeric correlation matrix	No
compare_distributions	quality	Whether two columns are shaped alike	No
detect_pii	quality	Find likely personal-data columns	No
detect_outliers	quality	Flag numeric outlier cells	No
check_rules	quality	Check values against a saved rules file	No
check_references	quality	Whether keys in one table exist in another	No
find_overlaps	quality	Rows whose time spans overlap inside a lane	No
value_shapes	quality	What a column's values look like, shapes folded	No
find_lookups	quality	Columns that always follow another column	No

compare

Schema and row differences, drift, merging versions.

Tool	Group	Purpose	Mutates files?
export_schema	compare	Render the schema as DDL / model / struct	No
compare_schemas	compare	Diff the column metadata of two files	No
diff_tables	compare	Row-level diff of two files	No
compare_folders	compare	Which files differ between two or more folders	No
schema_drift	compare	Which files in a folder disagree about columns	No
data_drift	compare	How a dataset changed between two versions	No
merge_tables	compare	Merge several edited versions of one table	No
cell_history	compare	The commits that changed one cell of a file in Git	No

combine

Unions, joins, join keys, reconciling column names.

Tool	Group	Purpose	Mutates files?
suggest_join_keys	combine	Rank the column pairs that would join two tables	No
union_tables	combine	Stack tables vertically	No
join_tables	combine	Join tables on key columns	No
harmonise_schemas	combine	Rewrite a folder of files to one schema	Writes into out_dir
fuzzy_join	combine	Join on similarity rather than equality	No
diagnose_join	combine	Why two key columns do not join	No
spatial_join	combine	Join by location: containing polygon or nearest point	No

reshape

Pivot, resample, dedupe, impute, mask, forecast.

Tool	Group	Purpose	Mutates files?
pivot	reshape	Reshape long <-> wide (PIVOT / UNPIVOT)	No
resample_timeseries	reshape	Group rows into time buckets and aggregate	No
rolling_window	reshape	Rolling aggregate over the previous N rows	No
transform_columns	reshape	Rename / cast / drop columns, write back	Writes the output path
anonymize	reshape	Mask / scramble columns, write the result	Writes the output path
hash_columns	reshape	Add a hash column (MD5 / SHA) over chosen columns	Writes the output path
fill_missing	reshape	Impute empty cells in a column	No
drop_duplicates	reshape	Remove duplicate rows	No
partition_table	reshape	One file per distinct column value	Writes one file per group
apply_recipe	reshape	Replay a recipe recorded in the GUI on a table	No
generate_test_data	reshape	Test data shaped like one or more real tables	No
forecast	reshape	Holt-Winters forecast of one column, with ranges	No

databases

Live database connections, apis, their tables and queries.

Tool	Group	Purpose	Mutates files?
sync_sql	databases	SQL that would make a server table match a file	No
list_db_connections 1	databases	List saved live-database connections	No
list_db_tables 1	databases	List schemas / tables on a live connection	No
db_relationships 1	databases	Foreign keys a live database declares	No
query_db 1	databases	Run SQL on a live database server	Mutations need Allow writes
list_api_connections	databases	List saved REST/JSON API endpoints	No
query_api	databases	Read a saved API endpoint as a table	No
write_db_table 1	databases	Write a table into a live database	Yes (server table)
copy_db_table 1	databases	Copy a table server-to-server through DuckDB	Yes (target server table)
export_db_tables	databases	Export a schema's tables to files, streamed	Yes (files)

cloud

Objects in s3, azure, gcs, sftp and webdav.

Tool	Group	Purpose	Mutates files?
list_objects	cloud	List a cloud bucket folder (S3/Azure/GCS)	No
copy_object	cloud	Copy a cloud object or folder to another location	Yes
move_object	cloud	Move a cloud object or folder (copy, then delete)	Yes
delete_object	cloud	Delete a cloud object or folder	Yes

write

Writing files, converting, reports and workbooks.

Tool	Group	Purpose	Mutates files?
convert	write	Write a file in a different format	Writes only the new output path
batch_convert	write	Convert many files into one format	Yes
write_table	write	Write inline rows to a new file	Writes/replaces the output path
edit_table	write	Add columns / set cells / insert / delete rows in place	Yes (edits the file)
create_report	write	Write a self-contained HTML profiling report	Writes the output path
write_workbook	write	Write several tables into one .xlsx workbook	Writes the output path

* run_sql accepts mutation queries (INSERT / UPDATE / DELETE) but the in-memory DuckDB connection is discarded at the end of the call. Changes are not persisted back to the file, and the next tool call sees the original on-disk contents again. The mutation result is only useful for "what would this query produce?" probes.

Common parameters

All tools share two parameter conventions:

• path is required. Absolute or working-directory-relative path to the file. Octa parses based on the file extension. A cloud URL (s3://bucket/key, az://container/key, gs://bucket/key, sftp://user@host/path, davs://host/path) is also accepted: the object is downloaded to a temporary file and read as usual. The MCP/CLI server authenticates with ambient credentials (AWS_ env vars, a cached SSO session, Azure CLI login, or Google application-default credentials); Azure also needs AZURE_STORAGE_ACCOUNT. Use list_objects to browse a bucket first. Writing* to a cloud URL works too: the write tools (write_table, convert, transform_columns, anonymize, hash_columns, run_sql with write_to) accept a cloud URL as their output, building the file locally and uploading it. They use the same ambient credentials; run the server with --mcp-read-only to drop all write tools.
• table (optional): for multi-table sources (SQLite, DuckDB, GeoPackage), pick a specific table. Omit for single-table formats. If you don't know the available tables, call list_tables first.

Row-returning tools (read_table, tail, sample, run_sql, find_duplicates, search, diff_tables) also share:

• limit (optional): maximum rows / hits to return.
• Omit → use the server's configured default (1000 unless changed under Settings → MCP).
• 0 → unlimited (returns every row, so be careful with big files).
• Any positive integer → that many rows max.

Response shape

Tools return JSON content. The shape varies by tool (see each tool page for the specifics), but result-bearing tools always include these envelope fields:

Field	Type	Meaning
truncated	bool	True when more rows existed than were returned
total_rows_available	int	Total rows in the source (when known cheaply)
cell_truncated	bool	True when at least one cell was replaced with a [truncated: …] marker due to the per-cell byte cap

These flags let an AI client know when to ask for more, e.g. if truncated: true and total_rows_available: 50000, the model can re-call with limit: 0 (or a higher limit) when the user asks for "all of them."

Error handling

Errors come back as MCP tool error responses with a message and an error code:

Code	Meaning
invalid_params	The arguments couldn't be parsed or the file couldn't be opened
internal_error	Unexpected failure inside the tool's logic (rare)

Friendly examples:

{ "error": { "code": "invalid_params", "message": "read failed: no reader available for /tmp/data.unknown" }}
{ "error": { "code": "invalid_params", "message": "run_sql failed: syntax error at \"FOO\"" }}
{ "error": { "code": "invalid_params", "message": "convert failed: format SAS does not support writing" }}

The model sees the error and (in practice) usually responds with a clarifying question or corrected call.

See also

• Each tool page for input schema + worked examples.
• Limits & truncation for how truncated and cell_truncated are computed.
• Examples for end-to-end prompts that exercise the tools.

---

1. The live-database tools work on the connections saved under Settings -> Databases (loaded once at server startup) and are described in Database Connections. Every write is additionally gated on the connection's own Allow writes switch. On Trino, Snowflake, Databricks and BigQuery, which have a catalog level above the schema, list_db_tables and write_db_table take a catalog parameter and copy_db_table takes source_catalog and target_catalog; list_db_tables without a catalog returns the catalog list itself. ↩↩↩↩↩↩