Reference / Authoring

check_readiness

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".

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.

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.

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

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 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"

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

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 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 lists its tables and columns, and 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.