Skip to main content

​
Overview

When a user uploads a tabular file — a CSV or Excel/XLSX spreadsheet — as an input to a workflow or agent, MagOneAI gives the agent a SQL query tool scoped to that file’s data. The agent can then answer analytical questions about the file by writing and running real SQL, instead of trying to reason over thousands of rows of raw text. This is the “database tool” in MagOneAI. There is no connecting to external or live databases — the data the agent queries is the data your users provide as file inputs.
Database tools work on uploaded tabular files. To query a live PostgreSQL, MySQL, or other production database, build a custom MCP tool that wraps your database access.

​
How it works

1

A tabular file is provided as input

A CSV or XLSX file reaches the agent as a workflow input (for example at the Start node) or directly as an agent input. See Triggers and execution for how files enter a workflow.
2

The file is converted to a queryable table

Behind the scenes, MagOneAI reads the file and converts it to an efficient columnar format. The column names and types are detected automatically.
3

The agent gets a dedicated query tool

For each tabular input, the agent receives its own SQL query tool, named after the input field. The tool’s description automatically includes the table’s columns and schema, so the agent knows exactly what it can query.
4

The agent writes and runs SQL

During its reasoning loop, the agent writes a SELECT query, runs it against the file, and reads the results back — just like any other tool call.

​
The query engine

Queries run on DuckDB, an in-process analytical SQL engine. Two things matter for how you design prompts and workflows:
  • It is read-only. Only SELECT and WITH (CTE) queries are allowed. INSERT, UPDATE, DELETE, and any DDL (CREATE, DROP, ALTER, …) are rejected. The agent can read and analyze the uploaded data, but it can never modify it.
  • It speaks standard SQL. Aggregations, filters, GROUP BY, ORDER BY, window functions, and CTEs all work, so the agent can express genuinely analytical questions.
Example query an agent might run: 
SELECT region, SUM(revenue) AS total_revenue
FROM sales
GROUP BY region
ORDER BY total_revenue DESC;
Because the column list is in the tool description, the agent constructs queries against the real schema rather than guessing column names.

​
Querying multiple files

If several tabular files are supplied together as an array of inputs — up to 10 files — each becomes its own table, and the agent can JOIN across them in a single query. Example: joining two uploaded files: 
SELECT c.company_name, SUM(o.amount) AS lifetime_value
FROM customers c
JOIN orders o ON o.customer_id = c.id
GROUP BY c.company_name
ORDER BY lifetime_value DESC;
This lets an agent reconcile, enrich, or cross-reference datasets — for example matching an uploaded contacts list against an uploaded transactions export — without any pre-processing step.

​
What this is good for

Database tools shine whenever the answer lives in a spreadsheet and would be tedious or unreliable to reason over as plain text:
  • Aggregate questions — “What’s the total revenue by region?” or “What’s the average order value per month?”
  • Data quality checks — “Which rows are missing an email address?” or “How many duplicate IDs are there?”
  • Filtering and ranking — “List the top 10 accounts by spend” or “Show every order over AED 50,000.”
  • Cross-file analysis — join an uploaded list against another uploaded export to find matches, gaps, or totals.
By delegating the counting and filtering to SQL, the agent spends its reasoning on interpreting results rather than arithmetic over raw rows.

​
Using it in a workflow

Database tools are part of file handling and agent tooling — there’s no separate connection to configure.
1

Accept a tabular file input

Define a file input on your workflow trigger or agent. Provide a CSV or XLSX file at run time. See Triggers and execution.
2

Run an Agent node

When the Agent node executes, the per-file query tool is attached automatically. No tool needs to be enabled by hand.
3

Prompt the agent to answer from the data

In the agent’s instructions, tell it to answer questions by querying the file. The agent will choose when to call the query tool during its tool-calling loop.
Example agent instruction: 
You are a data analyst. The user has uploaded a sales spreadsheet.
Answer their questions by querying the data with SQL using the query
tool, then explain the results in plain language. Always base numbers
on what the query returns — never estimate.

​
Troubleshooting

Symptoms: The agent answers from guesswork or says it can’t see the data.Solutions:
  • Confirm the file was actually provided as an input to the workflow or agent.
  • Confirm the file is CSV or Excel/XLSX — other file types don’t get a query tool.
  • Make the instruction explicit: tell the agent to use the query tool to answer.
Symptoms: A query fails because it tried to modify data.Solutions:
  • The engine is read-only by design. Rewrite the request as a SELECT or WITH query.
  • There is no way to write back to the file — database tools are for analysis only.
Symptoms: Queries fail with unknown-column errors.Solutions:
  • Column names come from the file’s header row — make sure the spreadsheet has clear headers.
  • Avoid duplicate or blank header cells, which make columns ambiguous.
Symptoms: The agent can only see one table.Solutions:
  • Provide the files together as an array input (up to 10 files), so each becomes its own table.
  • Make sure the files share a column the agent can join on.

​
Next steps

Triggers and execution

Learn how files enter a workflow as inputs

Agents overview

Understand how agents call tools during reasoning

Tools overview

See all the tools your agents can use

Custom MCP tools

Wrap a live database with a custom tool