Agents

Review and approve database questions

Approve the questions EchoNova drafts from your schema, test what a caller's wording would reach, and resync when the schema changes.

A database connection does not give the agent your schema. It gives the agent a fixed list of questions, each one a read-only query already checked against your database, with named parameters the agent fills in. EchoNova drafts that list from the schema when you connect, and nothing in it reaches a conversation until you approve it.

Connecting the database comes first: Connect a database.

What you need

  • A connection with the status Ready. A pending connection has no questions yet, and a failed one has none at all.
  • Membership of the workspace. Approving and editing ask for membership and no further permission.

Steps

Step 1: Open the connection

From the agent's Tools tab, open the database row. From the Tool Library page, use the row menu on the database. Either opens the same sheet, headed with the connection name and the host and database string under it.

The sheet shows the questions only when the connection is Ready. The heading counts them, in the form "12 questions EchoNova drafted from Orders database", and the counter on the right reads "3 of 12 approved".

Step 2: Read a drafted question

Each row carries the name the agent would call, the description it reads to decide when to call it, the parameters under Params with a red asterisk on the required ones, and example phrasings under Heard as.

A question that returns personal data carries a Personal data badge and a line under it naming the parameters a caller must supply. Those questions are drafted to need more than one matching detail, so a single leaked identifier cannot pull up a stranger's record.

The SQL is not shown, on any screen or in any response.

Step 3: Approve the ones the agent may use

Use the toggle at the right of the row. The label under it reads Approved when it is on and Off when it is not. Approving one question is a single request, and the counter moves as you go.

Approve as few as you can defend. An approved question is callable in every conversation on every agent that has this connection attached.

Step 4: Test what a caller's wording would reach

Open the connection's details, go to its Tests tab and press Test Tool. The dialog is headed "Test retrieval/" and explains itself: "Type what a caller might say. This runs the same search the agent runs each turn, so you can catch a template nobody will ever reach."

Type a sentence and press Run. Each hit shows the question name, a score as a percentage and the exact text that was matched. A score of 66% or more is a real match, and anything from 50% is a bare pass. A hit you have not approved is labelled Not approved, read from the approval itself, so the bench never tells you a question is live when it is not.

A run returns up to 5 hits, each scoring 0.5 or higher.

Step 5: Resync when the schema changes

Press Resync on the connection. EchoNova reads your schema again and drafts a fresh list.

The connection goes back to Reading schema… while that runs, so the question list empties until the new draft arrives. When it does, it replaces the old list outright, and each question's approved state comes from the new draft rather than from your earlier approvals. Check the "n of total approved" counter after every resync.

Get it right

A question is reached by matching the caller's words against its description and name. Both are drafted from your schema and from the Description you gave the connection when you registered it, so that description is where the words callers use belong. Write it in their words, not in the words your schema uses, and approve the drafted questions that read the same way.

Recommended

An online furniture shop. Callers ask where their parcel is, whether an order is
late, what a tracking number says, and whether a sofa is in stock.

Less effective

Postgres with orders, shipments and inventory tables joined on order_id.

What happens next

Only approved questions reach a conversation. Questions you left Off are not offered to the agent by any route.

Approving or un-approving a question can take up to a minute to reach a new conversation. Attaching or detaching a database applies to the next conversation at once. A conversation already running keeps what it started with either way.

How many questions reach a turn

On each turn the agent searches the approved questions of every database attached to it and is offered at most 5 of them, and only those scoring 0.5 or higher. Neither number is adjustable from the portal today.

The threshold of 0.5 is worth understanding. Scores have a high floor: unrelated text still lands around 0.30 to 0.41, while a real match lands around 0.66 to 0.72. That gap is why a bench score of 66% or more is a real match and one just above 50% is a bare pass.

Database questions and imported OpenAPI operations are searched in the same pass each turn, so an agent with both is choosing between them. OpenAPI tools describes that search and why a tool can be present and still never fire.

Editing a question

The review sheet approves and un-approves a question. Changing a question's name, description, parameters or SQL is not available from the portal today.

The description, together with the name, is the text a caller's wording is matched against. Run the retrieval test with the words callers actually use before you rely on a question in a conversation, and leave a question Off when the bench shows nobody's phrasing reaches it.

Limits

Limit Value Applies to
Bench sentence 500 characters The retrieval test
Bench hits Up to 5, each scoring 0.5 or higher The retrieval test
Questions offered Up to 5 per turn, each scoring 0.5 or higher The agent
Time for an approval to apply Up to a minute New conversations

Troubleshooting

"No questions drafted yet."

The connection is Ready but the draft came back with nothing. Check that the database user can actually see the tables you expect, then press Resync.

The bench returns nothing above the threshold

The dialog says which case you are in. A message reporting the closest template's score, and telling you "the wording callers use is missing from its description and sample utterances", means the question exists and is matchable but does not match the sentence you typed. Test again with the words callers actually use before you decide the question is unreachable.

"Nothing is indexed for this connection, so the agent can never reach a template. Re-sync it."

Drafting succeeded but nothing was made matchable, so no question can be reached no matter how well it fits. Press Resync.

"This connection has nothing indexed, so the search widened to the whole workspace. Re-sync the connection."

The search found nothing under this connection and widened, so the hits you are looking at may belong to another database. Resync the connection before you read anything into the results.

The agent answers from nothing, or says it cannot look that up

Work down the list: the database is attached to that agent, the connection is Ready, at least one question is approved, the bench reaches that question for the caller's wording, and the change is more than a minute old.

FAQ

Can I see or write the SQL myself?

No. The SQL is not shown on any screen, and writing or replacing it is not available from the portal today.

Does approving a question cost anything at rest?

No. An approved question is offered to the agent and matched during a conversation. It runs against your database only when the agent calls it.

What is the "Personal data" badge?

The draft marked that question as returning personal data. Those questions are drafted to need more than one matching detail before they answer, so read the parameters under Params before you approve one.

Why did my approvals reset?

A resync replaces the question list with the new draft, and the approval state comes back with it. Re-check the counter after every resync.

Do these questions apply to every agent?

The questions belong to the connection, and the connection is attached per agent. An agent that does not list the connection cannot reach any of its questions.