> For the full page index, fetch https://echonova.ai/llms.txt

# 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](/docs/agents/database-tools-connect).

## 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**

```text
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**

```text
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](/docs/agents/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.

## Related

- [Connect a database](/docs/agents/database-tools-connect): register the connection these questions come from
- [Database tool security](/docs/agents/database-tools-security): the user to create and what is kept
- [The retrieval bench](/docs/agents/tool-bench): the same test for imported APIs
- [Tools overview](/docs/agents/tools-overview): how databases differ from the other tool kinds