Manage Airtable Records Tool

​

What it does

• 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)

​

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

​

Shape of records[]

• 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": "jane@example.com", "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": "alice@example.com", "Status": "Lead" } },
  { "fields": { "Name": "Bob",    "Email": "bob@example.com",   "Status": "Customer" } }
]
typecast: true

​

Write linked records

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

• 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

• 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

• 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

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

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

• 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