Manage Airtable Records Tool

Create, read, update, upsert, or delete records in an Airtable table — with batch support and typecast

What it does

The Manage Airtable Records tool performs all the write (and single-record read) operations on an Airtable table. It supports five actions:

• get — retrieve a single record by ID
• create — insert 1–10 new records in one call
• update — patch specific fields on existing records (requires each record’s id)
• upsert — batch insert-or-update, matching on fieldsToMergeOn
• delete — remove records by ID (single or batch up to 10)

All writes are capped at 10 records per call — that’s Airtable’s API limit, not ours. For larger batches, loop with pagination.

Key features

• Single action param covers five operations, keeping the tool surface small
• Optional typecast flag coerces human-readable strings into existing select options, numbers, and dates — agents don’t need to format values exactly
• Upsert matches on any field(s) you designate via fieldsToMergeOn (email, external ID, slug, etc.) and cleanly reports which records were created vs updated
• Single-record delete via recordId, or batch delete via records[].id

Parameters

Parameter	Type	Required	Description
action	string	Yes	One of get, create, update, upsert, delete
baseId	string	Yes	Airtable base ID (starts with app)
tableIdOrName	string	Yes	Table ID (starts with tbl) or display name
recordId	string	Conditional	Required for get. Optional shorthand for single-record delete
records	array	Conditional	Max 10. Required for create, update, upsert, and batch delete
typecast	boolean	No	If true, Airtable coerces string values to match existing select options, numbers, and dates. Recommended for create/update/upsert
fieldsToMergeOn	string[]	Required for upsert	Field names Airtable should match on to decide create vs update

Shape of records[]

Each entry is { id?: string, fields: { [fieldName]: value } }:

• create: each item needs fields only
• update: each item needs id + fields
• upsert: each item needs fields; id is optional (present = update that specific record; absent = match via fieldsToMergeOn)
• batch delete: each item needs id

Common use cases

Create a single contact

action: "create"
baseId: "appXXXXXXXXXXXXXX"
tableIdOrName: "Contacts"
records: [
  { "fields": { "Name": "Jane Smith", "Email": "[e-mail]", "Company": "Acme" } }
]
typecast: true

Batch update deal stages

action: "update"
tableIdOrName: "Deals"
records: [
  { "id": "recAAA", "fields": { "Stage": "Closed Won" } },
  { "id": "recBBB", "fields": { "Stage": "Closed Lost" } }
]

Upsert contacts by email (idempotent sync)

action: "upsert"
tableIdOrName: "Contacts"
fieldsToMergeOn: ["Email"]
records: [
  { "fields": { "Name": "Alice",  "Email": "[e-mail]", "Status": "Lead" } },
  { "fields": { "Name": "Bob",    "Email": "[e-mail]",   "Status": "Customer" } }
]
typecast: true

Airtable reports createdRecordIds and updatedRecordIds separately so the agent knows what happened.

Write linked records

Linked-record fields take an array of record IDs (not names):

action: "create"
tableIdOrName: "Deals"
records: [
  { "fields": {
      "Name": "Q2 Renewal",
      "Contact": ["recAliceID"],
      "Company": ["recAcmeID"]
  } }
]

Single-record delete

action: "delete"
tableIdOrName: "Contacts"
recordId: "recXXXX"

Batch delete

action: "delete"
tableIdOrName: "Contacts"
records: [
  { "id": "recAAA", "fields": {} },
  { "id": "recBBB", "fields": {} },
  { "id": "recCCC", "fields": {} }
]

What you get back

All responses include a status and an action-specific content:

• get → { id, createdTime, fields }
• create → { records[], count, message }
• update → { records[], count, message }
• upsert → { records[], createdRecordIds[], updatedRecordIds[], count, message }
• delete → { deletedIds[], count, message }

Best practices

• Pass typecast: true when writing to singleSelect, multipleSelects, number, date, etc. — agents don’t always produce the exact option strings or formats Airtable expects
• Use upsert for external-ID syncs. If your source system has a stable identifier (email, external ID), store it in a unique field and upsert on it — safer than guessing whether to call create or update
• Keep batches at or below 10. The Zod validator blocks larger batches locally; larger-than-10 writes need to be chunked by the caller
• For linked records, pass IDs — not names. Get IDs from airtable_search or airtable_get_schema
• For attachments, pass [{ url: "..." }] objects; Airtable fetches the files

Troubleshooting

“Unknown field name”

• Field names are case-sensitive; verify exact spelling with airtable_get_schema
• Computed fields (formula, rollup, lookup) are read-only — you can’t write to them

“Invalid value for field” (select/number/date)

• Add typecast: true so Airtable coerces string values to the right type or matches an existing option
• For multipleSelects, pass an array of option strings; for singleSelect, pass one string

“Airtable accepts at most 10 records per write request”

• Split the batch. Each action supports up to 10 in a single call — chain multiple calls for larger sets

“Record not found” on update/delete

• The record may have been deleted by another process
• The id must start with rec and belong to the same table

Upsert: “wrong record matched”

• fieldsToMergeOn fields must uniquely identify a record. If the match fields aren’t unique, Airtable picks one; add more fields (e.g., ["Email", "External ID"]) to tighten the match

Related tools

• Search Airtable — find the records you want to update, delete, or link to
• Get Airtable Schema — discover valid table + field names before writing