---
title: check_readiness
description: The first call of an authoring session. What Dashies knows about your account, and the single next step - including every way the answer can be "not yet".
updated: 2026-08-30
tools: [check_readiness]
---

Answers, in one round trip, everything Dashies already knows about your account:
which data connections exist, whether each one is usable right now, what is
readable behind it, which dashboards you already have, and the one thing to do
next.

It is the call an authoring session opens with. It runs no SQL, touches no
warehouse and changes nothing.

Behaviour hints for clients: read-only, not open-world.

## Parameters

This tool **takes no parameters**. Which space it reads is decided by how the
MCP connection was authorized, exactly as it is for
[`list_connections`](/reference/mcp-tools/list-connections).

## The field to act on

`next_step.action` is the answer. Everything else in the response is the
evidence behind it.

| `action` | What it means | What to do |
|---|---|---|
| `connect_a_warehouse` | There are no connections of your own in this space, and no ready shared sample. | Send the user to the link in `next_step.url`. |
| `fix_a_connection` | A connection's credential is not working, **and nothing else is ready**. | Say so **before** authoring anything, name the error, send them to the app. |
| `finish_setup_in_the_app` | A connection exists but was never tested. | Finish setting it up in the app, then call again. |
| `choose_data_in_the_app` | A connection is verified and exposes nothing readable. | Choose the schemas, datasets or databases to expose, and check the login can read them. Both are app settings; no query works around either. |
| `ask_which_connection` | More than one connection is ready. | **Ask the user.** Do not choose for them. |
| `start_authoring` | Exactly one of your own connections is ready - or you have none of your own and the shared "Dashies sample data" connection is ready, in which case the text names it. | Go. On the sample: say it is sample data and offer the connect link in the same message, as the text says. |

:::warning{title="A broken connection beside a working one still says start_authoring"}
`fix_a_connection` is the answer only when **nothing** is ready. If one
connection is ready and another's credential is failing, the action is
`start_authoring` and the broken one appears in `connections[]` with
`readiness: credential_failing`. So read the connection list before telling a
user everything is fine, rather than treating the action as the whole answer.
:::

`ready` says whether the account is **blocked**, not whether to start building:
it is true for `start_authoring` and `ask_which_connection`, false for
everything else. It is deliberately true in the two-connection case, where you
must still ask before writing a query, so branch on `next_step.action` to decide
what to do and read `ready` only to know whether anything is in the way.

## Returns

```text
Readiness for the "acme" workspace:

NEXT STEP (ask_which_connection): There is more than one connection ready in the "acme" workspace (Analytics Postgres [7a1e...], Snowflake Prod [0c22...]). Ask which one this dashboard should be built from before writing any query - do not pick for the user.

Data connections (2):
- Analytics Postgres [7a1e...] | engine: postgres | state: ready | readable: 41 tables
- Snowflake Prod [0c22...] | engine: snowflake | state: ready | readable: 3 databases

Existing dashboards (1):
- Weekly revenue [weekly-revenue] https://acme.dashies.ai/weekly-revenue | updated 2026-08-28T09:14:00Z
Check these before creating a new one: editing an existing dashboard is usually what a user means.

BEGIN_JSON
{"ready":true,"next_step":{"action":"ask_which_connection","text":"..."},"space":"the \"acme\" workspace","connections":[...],"readable_objects_unavailable":false,"dashboards":{"has_more":false,"items":[...]}}
END_JSON
```

### Per connection

| Field | Meaning |
|---|---|
| `id` | The connection id you pass as `connection` elsewhere. |
| `label` | The name you gave it in the web app. |
| `engine` | `postgres`, `bigquery`, `snowflake`, `redshift`, `databricks` or `mssql`. |
| `readiness` | `ready`, `credential_failing`, `not_verified_yet` or `no_readable_data`. |
| `detail` | The classified error token, or the app-side explanation. Never raw driver text. |
| `readable_objects` | How much Dashies may read behind the connection. **Read it with `readable_objects_unit`, never alone** - see below. |
| `readable_objects_unit` | What that number counts on this engine, plural: `tables` on Postgres, `datasets` on BigQuery, `databases` on Snowflake and Redshift, `schemas` on Databricks and SQL Server. `null` whenever there is no count. |
| `shared_sample` | `true` on the shared "Dashies sample data" connection. It is judged **after** your own connections, never beside them: it never turns one working connection of yours into `ask_which_connection`, and it is named as a way forward only when you have nothing of your own, or as an aside when everything of your own is blocked. |

### Existing dashboards

A bounded sample, newest first, with `has_more` set when there are more. There
is deliberately no count beside it: it would only ever be `items.length`, while
reading as "how many dashboards this account has" - the very thing `has_more`
exists to deny. A dashboard whose URL is not known carries `url: null` rather
than a placeholder string. This is
an orientation call, not a listing tool: use
[`list_dashboards`](/reference/mcp-tools/list-dashboards) for the full list.

Look at these before creating anything. A user asking for "the sales dashboard"
usually means the one that already exists.

## `readable_objects` distinguishes "nothing" from "we could not tell"

:::warning{title="null is not zero"}
`readable_objects: 0` is a **measurement**: Dashies has been given nothing it may
read on that connection, which is why the connection reads `no_readable_data`
and blocks.

`readable_objects: null` means **no statement is being made**. The connection is
not blocked and nothing here says anything about your data. Reporting a fault on
our side as emptiness in your warehouse would be a claim nothing measured.
:::

A separate top-level `readable_objects_unavailable: true` says the readability
check itself did not answer, in which case every `readable_objects` is `null`
and the human text says so in a sentence.

## The number is in a different unit per engine, and `readable_objects_unit` is that unit

:::warning{title="never read the count as a table count"}
What Dashies counts behind a connection is what it has been given permission to
read, and that is a different KIND of thing per engine: the IMPORTed tables its
read-only role may `SELECT` on Postgres, the allowlisted datasets on BigQuery,
databases on Snowflake and Redshift, schemas on Databricks and SQL Server.

So a Snowflake connection can report `readable_objects: 1` and
[`introspect_schema`](/reference/mcp-tools/introspect-schema) can then return
twenty-one tables. Both are right: one allowlisted database, twenty-one tables
inside it.

`readable_objects_unit` carries the noun, and the human line prints it
(`readable: 1 database`). Where the unit is not known the whole `readable:`
segment is omitted rather than printed bare.
:::

## Errors

| Condition | Behaviour |
|---|---|
| The connection read fails | The whole call refuses: `Could not read your data connections: <err>`. Every branch below it would be a guess. |
| The readability read fails | The call succeeds, `readable_objects_unavailable` is true, and no connection is reported as empty. |
| The dashboard listing fails | The call succeeds and says the list was unavailable, rather than reporting an empty account. |

## Scope

The read space comes from the grant alone, and every fact in the answer is
partitioned by it: the connections, their readability and the dashboards. A
workspace authorization reads that workspace, and `space` in the response names
which one you got. **A grant that names no workspace is refused**, with a sentence
telling you to re-authorize and choose one, because a connection that cannot
publish a dashboard has nothing to be ready for.

## Check it worked

Read `next_step.action` and do that. If it is `start_authoring`, the connection
named in `next_step.text` is the one to build against:
[`introspect_schema`](/reference/mcp-tools/introspect-schema) lists its tables
and columns, and [`explore_data`](/reference/mcp-tools/explore-data) answers the
questions that come before any design.

If a connection you expect is missing entirely, check which space you authorized
for - a connection belongs permanently to the space it was created in, and there
is no argument that overrides the grant.