Guides

Agent guide

How an AI agent should work with Airdash - finding what exists, setting up databases, keeping data clean, and checking in with the user.

This guide is written for AI agents connected to Airdash over MCP. People can read it too: it is how a good agent behaves.

The user sees everything

Every table you make shows up as a spreadsheet in the user's Airdash app. Treat it like a shared workspace, not a scratch database:

  • Use clear names: databases in plain words ("Job search"), tables and fields in lowercase snake_case (applications, applied_on).
  • Give tables and fields a short description. The user sees them in the app, and the next agent reads them in get_database.
  • Make the first field of every table its name or title. Links and relationships to the table show that field.
  • After you set something up or change a lot, give the user the database's url from get_database so they can look.

Before you create anything

  1. Call list_databases. The user may already track this, or something close to it.
  2. If a database fits, call get_database and work in it. Add a table or a field rather than starting a second database on the same topic.
  3. Only create a new database for a new topic. Several small databases (one per topic) are easier to understand than one large one.

Setting up a new database

  1. Sketch the tables first: what are the things (people, companies, applications), and how do they connect? See Designing a database.
  2. create_database, then one create_table per table, with all fields typed and select choices given up front.
  3. Mark natural keys unique (email, url, an external id) if you will add data more than once.
  4. Add a few real rows, then show the user the url and ask whether the shape is right before importing a lot.

For anything more than a simple list, briefly tell the user the tables you plan to make before making them.

Keeping data clean

  • Use the right field type. Dates in date fields, not text. Fixed categories in select fields, not free text.
  • Never put several values in one text field ("a, b, c"). Use multi_select, a list field or a separate table.
  • Before adding rows, check for duplicates with run_sql, or upsert with match_on on a unique field.
  • Keep select choices short and consistent. Add a choice with update_field rather than writing near-duplicates.

Things to confirm with the user first

  • Deleting rows, fields, tables or databases. delete_database cannot be undone; the others can only be undone by restoring the whole database.
  • restore_database, since it replaces everything written after the chosen moment.
  • Big changes to a schema the user already uses: renaming or removing fields, or changing a field's type.
  • Imports of more than a few hundred rows into a table that already has data.

When something goes wrong

Errors say what was wrong and how to fix it: read them before retrying. A write call is all or nothing, so a failed call wrote nothing. If you wrote wrong data, fix it with update_rows or delete_rows; if a lot went wrong, restore_database can roll the database back to just before (ask the user first).

More

Previous ← Free plan and limits Next Designing a database →