Static source inference · medium confidence · detected: Logging
Deprecated protocol patterns detected
Summary
The Airtable MCP server provides 42 tools with generally consistent naming conventions (verb_noun structure like create, update, delete, list, query). However, significant quality gaps exist: (1) Parameter descriptions are minimal and often lack actionable constraints, e.g., 'filterByFormula' is described only as 'Airtable formula to filter records' without explaining format, syntax, or error recovery; (2) Output schemas are not documented anywhere in the provided source, callers cannot see what fields to expect from responses, violating the pattern:tool requirement that outputs be fully specified; (3) Error handling guidance is absent, no recovery instructions, no error categorization, no hints for retryable vs. fatal failures; (4) Parameter relationships and dependencies are undocumented (e.g., which combination of filter/view/sort is valid?); (5) Some descriptions are generic and under the 50-char baseline (e.g., 'Get information about the authenticated user' for whoami). Strengths: tool names are clear and action-oriented; most tools have basic descriptions; security is handled server-side (API key injection, not parameter-exposed); batch operations exist for composition. The 42-tool surface area is ambitious but creates cognitive load without comprehensive documentation. Average per-tool score: 58/100.
Output schemas are not documented. No tool returns a documented response schema, callers cannot predict what fields or structure to expect. This violates pattern:tool which mandates 'Document the output schema.' Agents cannot plan downstream tool calls without knowing what data is available.
Parameter descriptions lack actionable constraints. 'filterByFormula' is described only as 'Airtable formula to filter records' without explaining valid syntax, example format, or error recovery if formula is invalid. Parameters like 'options' (in create_field, update_field) are described generically without documenting what keys/values are valid. LLMs cannot construct valid calls without constraint documentation.
querysearch_recordslist_recordscreate_field
Recommendations
Document output schemas for every tool. Use JSON Schema (or TypeScript type definitions compiled to JSON Schema) to specify response structure, field names, types, and null/optional fields. Examples: query should return [{id, fields, createdTime}], create should return {id, fields, createdTime}. This is non-negotiable for agent planning.
Upgrade parameter descriptions to include validation constraints. Format: 'Description (type: valid_values | regex | min-max range). Example: "Filter records using Airtable formula syntax (string, no examples; see docs). Ignored if view is specified. Common errors: unclosed parentheses, undefined field names."'
For categorical parameters (view_type, field_type, sort_direction), replace free-text descriptions with enum definitions in JSON Schema. Document the enum values in the description. E.g., type: {enum: ['grid', 'form', 'calendar', 'gallery', 'kanban']}.
Add 'When to use' guidance to discovery tools (list_*, describe, get_*). Example: 'Call this FIRST to discover available tables and their schemas before running queries.' This helps agents understand tool sequencing.
Document error scenarios and recovery actions. For each destructive tool (delete_*, batch_delete_*), add: 'Errors: If confirmation is wrong, returns HTTP 403. If record/field/table does not exist, returns HTTP 404. Retry is not recommended; instead, verify the ID using describe or query and try again.'
Specify parameter relationships explicitly. For query, list_records, search_records: 'Parameters: view (string, name or ID) takes precedence over filterByFormula; if both are provided, filterByFormula is ignored. sort applies within the view. pageSize and offset enable pagination; defaults are pageSize=100, offset=0. maxRecords overrides pageSize and limits total results.'
Spec posture evidence
Inferred effective spec: 2026-07-28+.
Relies on Logging (deprecated) - log to stderr or use OpenTelemetry
Score history
Overall score trend
↑ 55 points across a rubric change (v1 → v2)
55/100
Scored
Grade
Overall
Spec posture
Rubric
2026-09-22
D
55
2026-07-28+
v2
2026-03-09
F
0
-
v1
create_fieldwriteauthsource verified65/100
Create a new field in a table
create_tablewriteauthsource verified65/100
Create a new table in a base
create_viewwriteauthsource verified65/100
Create a new view in a table
create_webhookwriteauthsource verified62/100
Create a new webhook for base change notifications
No error handling guidance. Tools provide descriptions but do not indicate what errors are possible, whether they are retryable, or what the LLM should do if a call fails. E.g., delete_table asks for a 'confirmation' parameter but does not explain what happens if it is wrong, what the error looks like, or how to recover.
Parameter relationships and dependencies are undocumented. When a tool accepts multiple optional parameters (e.g., query accepts view, filterByFormula, sort), there is no documentation of whether they can be combined, which take precedence, or what the valid combinations are. This forces LLMs to guess.
Generic and minimal descriptions under 50 characters on several discovery/utility tools. 'Get information about the authenticated user' (whoami), 'List exceptions from governance rule violations' (list_exceptions), 'List governance rules and configurations' (list_governance) do not explain WHEN to call these tools or what info they surface, making them hard for LLMs to prioritize.
No input validation or type constraint documentation. Parameters like 'maxRecords' (number), 'pageSize' (number) lack documented min/max bounds. LLMs may pass 0, negative, or extremely large values that violate Airtable API limits. No enum constraints exist for categorical parameters like view type, field type, or sort direction.
Batch operations do not document per-item error handling. batch_delete_records, batch_create_records, etc. do not specify whether a single failed record halts the batch or whether partial success is returned. LLMs cannot reason about failure modes.
Add minimum/maximum constraints to numeric parameters. Example: 'maxRecords (number, 1 - 100, default 20): limit result set size to avoid context overflow.' 'pageSize (number, 1 - 100): pagination chunk size.'
Document batch operation semantics. For batch_create_records: 'Atomicity: If any record fails validation, the entire batch is rejected (all-or-nothing). Responses: returns {successCount, failureCount, records: [{id, fields, error?}]}. Per-item errors let the LLM identify and retry specific records.'
For webhook tools, document the notification URL format and payload structure. Example: 'notificationUrl (string, HTTPS URL): Airtable will POST a JSON payload with {timestamp, actionMetadata, changedMetadata} when changes occur. Your URL must respond with 200 OK within 3 seconds or the webhook will be considered failed.'
Replace generic descriptions with LLM-optimized ones (50 - 200 chars). Current: 'Get information about the authenticated user.' Improved: 'Retrieve the current authenticated user's ID, email, and workspace(s). Use this to verify access before running tools that require user context.'
Reduce the 42-tool surface area into discoverable subsets. The toolset.ts already defines CORE_TOOLSET (18 tools). Document it prominently and encourage clients to start with the core set, reduce cognitive load and token spend for agents.
Add error handling patterns for common failures: 'User not found → try list_collaborators() first.' 'Invalid formula → return the formula syntax error from Airtable and suggest example formulas.'
For parameters accepting IDs or names (table, baseId, fieldId), document both formats. E.g., 'table (string): Table ID (e.g., 'tblXXXXXXXXXXXXXX') or table name (e.g., 'Contacts'). Names are matched case-insensitively.'
Document typecast behavior. For create, update, upsert: 'typecast (boolean, default true): If true, Airtable automatically converts input values to the field type (e.g., "123" → 123 for number fields). If false, type mismatches cause errors.'
Add chaining guidance. E.g., after create_record returns {id, fields, createdTime}, agents often call get_record to verify or create_comment to annotate. Document: 'Returns: {id, fields, createdTime}. Use id in subsequent get_record, update, delete, or create_comment calls.'
Implement per-request logging (io.modelcontextprotocol/logLevel in _meta) to enable agents to emit structured logs without relying on removed Logging capability.