Airtable API Server with FastMCP and Structured Output
The Airtable MCP server has 5 tools with mixed quality. All tools have descriptions and input schemas visible in main.py. Naming follows the verb_noun convention (list_records, get_record, create_records, update_record, update_multiple_records). However, several critical issues reduce the score: (1) parameter descriptions are present but often minimal (e.g., 'The base ID' lacks context about format or how to obtain it); (2) output schemas are inferred from Pydantic models (Record, Field, Table, Base, View, Comment, User, Webhook, Enterprise) but not documented in tool docstrings; (3) no error handling guidance, error messages appear to be raw API errors without recovery hints; (4) create_records has an ambiguous 'fields' parameter that could conflict with 'records' parameter; (5) STDIO-only transport caps overall score at 50, but schema/naming quality pushes slightly higher. The code shows competent Airtable API integration but lacks agent-optimization patterns for tool discovery and error recovery.
Create one or more records
Retrieve a single record
List records in a table
Update multiple records
Update a single record
Parameter descriptions are minimal and lack actionable context. E.g., 'The base ID' does not explain format, how to find it, or whether it's required. Descriptions should state WHAT the parameter controls, the expected format, valid range, and any prerequisites (e.g., 'Base ID (alphanumeric, found in Airtable base URL after airtable.com/)')
Output schemas are not documented in tool docstrings. LLMs cannot determine what fields to expect in responses without explicit return type documentation. Code defines Pydantic models (Record, Field, Table, etc.) but tools do not document which model(s) they return or the structure of the response.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-22 | D | 51 | 2026-07-28+ | v2 |
| 2026-03-09 | F | 0 | - | v1 |
No error handling guidance or recovery hints. The handle_api_request function returns raw HTTP errors (e.g., 'HTTP 404: Not Found'). Errors should guide the LLM on next steps: categorize as retryable/user-fixable/fatal, include the invalid value, and suggest recovery actions (e.g., 'Table not found. Call list_tables() to see available tables.').
create_records parameter ambiguity: accepts both 'records' (array) and 'fields' (object) for a single record. This creates a confusing interface, LLMs must reason about which parameter to use for batch vs. single operations. Either split into create_record (single) and create_records (batch), or clarify mutual exclusivity in descriptions.
list_records returns a raw Airtable API response without pagination guidance. No documentation of maximum result size, result limit defaults, or how to handle large datasets. Should document: 'Returns up to X records per page. Use offset/page_size parameters for pagination. Total record count available in response metadata.'
Tool descriptions do not clarify when to use similar tools. E.g., list_records vs. get_record are both read operations but serve different purposes. Descriptions should include decision hints: 'Use list_records to find records matching criteria; use get_record when you already have a record ID.'
No documentation of required vs. optional parameters. While schema shows some parameters as optional, there is no guidance on common invocations. E.g., 'base_id and table_id_or_name are required; all other parameters are optional with sensible defaults.'
No tool annotations (readOnlyHint, destructiveHint, idempotentHint) provided. The MCP spec 2026-07-28 supports tool annotations to help LLMs reason about operation safety. create_records, update_record, update_multiple_records should be annotated with destructiveHint or idempotentHint.