Understand akko-mcp-trino in five levels

1 · Search

“Which customer segment holds the largest total account balance?”

The agent does not know the tables. It searches with four words from the question, in one tool call over every catalog it may see.

search_columns {"text": "customer segment account balance"}

2 · Word by word

No column holds all four words, so the server searches each word

Each result says which words found it, and "partial": true warns the agent. The marked columns are the ones its answer will use.

• crm.accounts.balanceaccountbalanceused
• crm.customers.segmentcustomersegmentused
• crm.accounts.customer_idcustomerused
• crm.transactions.account_idaccount
• crm.transactions.amountaccount

"partial": true,
"hint": "No table or column holds every word together, so these are partial matches, each found by the words it lists: pick the right one, or search again with a single word from a column or table name, then call describe_table on the table."

3 · A wrong join

The agent joins on c.customer_id, a column customers does not have

It writes the query straight away, without reading the customers table.

execute_query {"sql": "SELECT c.segment, SUM(a.balance) AS total_balance FROM demo.crm.customers c JOIN demo.crm.accounts a ON c.customer_id = a.customer_id GROUP BY c.segment ORDER BY total_balance DESC LIMIT 1", "max_rows": 1}

4 · The error guides

The error says which table to read

Since 0.7.0, an error carries a kind and, for a column that cannot be found, a hint that names the table to read.

{"error": "TrinoUserError(type=USER_ERROR, name=COLUMN_NOT_FOUND, message=\"line 1:105: Column 'c.customer_id' cannot be resolved\", query_id=20261101_211014_00019_85v63)", "kind": "column", "identifier": "c.customer_id", "hint": "Read the columns of demo.crm.customers with describe_table, then write the query again with a column it has."}

5 · Read the table

customers has an id column, not customer_id

The agent follows the hint and reads the columns of customers.

describe_table {"catalog": "demo", "schema": "crm", "table": "customers"}

{"columns": ["Column", "Type", "Extra", "Comment"], "rows": [["id", "integer", "", ""], ["full_name", "varchar", "", ""], ["email", "varchar", "", ""], ["country", "char(2)", "", ""], ["segment", "varchar", "", "Retail or business customer"]], "truncated": false}

6 · Fix and answer

The business segment, with a total balance of 17,620.75

The agent runs the query again with c.id = a.customer_id. Trino computes it over the customers Carol may see: the 17,620.75 is in EUR, Sofia Ruiz’s two accounts, because Carol’s row filter removes the business customers outside Europe. The agent cites the columns it used. The same path comes back in 4 of the 5 trials of this question.

execute_query {"sql": "SELECT c.segment, SUM(a.balance) AS total_balance FROM demo.crm.customers c JOIN demo.crm.accounts a ON c.id = a.customer_id GROUP BY c.segment ORDER BY total_balance DESC LIMIT 1", "max_rows": 1}

{"columns": ["segment", "total_balance"], "rows": [["business", "17620.75"]], "row_count": 1, "truncated": false}

The customer segment that holds the largest total account balance is the business segment, with a total balance of 17620.75.

The columns relied on are:
- demo.crm.customers.segment
- demo.crm.accounts.balance
- demo.crm.customers.id
- demo.crm.accounts.customer_id