This server provides full Baserow REST API access with automatic 2FA authentication, plus curated tools for managing databases, tables, fields, and rows.
Generic API client (baserow_api): call any Baserow endpoint via method/path/body/query, with automatic JWT/TOTP auth and non-blocking OpenAPI validation.
Database management: list databases in a workspace, create/list/delete tables.
Schema management: list, create, update, and delete fields/columns with support for many Baserow field types.
Row operations: list rows with pagination/search/sorting, create, update, and delete single rows.
Batch operations: batch create, update, and delete rows (up to 200 per call).
Authentication status (auth_status): check authentication state, token expiry, and user info.
Provides schema management (tables, fields) and data operations (row CRUD, batch operations) for Baserow, with automatic TOTP-based 2FA authentication.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@mcp-baserow-schema Add a number field 'budget' to the projects table"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
MCP server for Baserow: a generic Baserow API client with 2FA authentication (TOTP) and OpenAPI validation.
One tool, the entire Baserow REST API. Schema changes (tables, fields, views, filters), row CRUD, workspace admin — anything documented in the OpenAPI spec is callable, with JWT auth handled automatically.
Baserow's official MCP handles curated data CRUD but not the full API surface (schema changes, views, filters, admin endpoints). In 2026, plain password auth without 2FA is not acceptable. This MCP solves both:
Full API access: any endpoint from the bundled Baserow OpenAPI spec via one generic tool
2FA support: automatic TOTP-based authentication — no manual token management
OpenAPI guard: requests are validated against the spec; mistyped paths get a hint instead of a mystery 404
Designed for agents: AI agents can modify table structure without human intervention
Related MCP server: Enhanced Airtable MCP Server
baserow_apiGeneric HTTP client for any Baserow API endpoint.
Parameter | Type | Description |
|
| HTTP method |
| string | API path starting with |
| object, optional | JSON body for POST/PATCH/PUT |
| object, optional | Query params as string key-value pairs |
Examples:
GET /api/database/tables/database/123/ → list tables in database 123
POST /api/database/views/table/456/ {name, type} → create view
POST /api/database/views/789/filters/ {field, type, value} → create filter
DELETE /api/database/tables/456/ → delete table
PATCH /api/database/rows/table/456/11/ {status} ?user_field_names=true → update row
POST /api/database/rows/table/456/batch/ {items:[...]} → batch updateAuth is handled automatically: just provide method, path, and optional body/query. If the OpenAPI spec doesn't recognize the path/method, the response is prefixed with a warning (⚠️ OpenAPI spec: ...) including similar paths — the request still executes (validation is non-blocking).
auth_statusReturns the current authentication state: authenticated, token expiry, and remaining lifetime of access/refresh tokens. Useful for debugging the auth lifecycle.
The server bundles the official Baserow OpenAPI spec (v2.2.2, 275 paths, openapi.json at the repo root). Before each request:
Path + method found → request proceeds silently.
Path exists, method wrong → warning lists the available methods for that path.
Path unknown → warning plus up to 5 similar paths from the spec.
The spec is loaded lazily from dist/../openapi.json; if missing, validation is skipped gracefully and requests proceed unvalidated.
Supports Baserow's two-step 2FA flow:
POST /api/user/token-auth/ → temporary 2FA token (~60 s)
POST /api/two-factor-auth/verify/ (with TOTP code) → JWT access_token + refresh_token
POST /api/user/token-refresh/ → new access_token, silently (no 2FA needed)
Token lifecycle:
access_token: ~10 minutes (expiry read from the JWT exp claim, refreshed 2 min before expiry)
refresh_token: ~7 days (full 2FA re-login 5 min before expiry)
temp_token: ~60 seconds (only for the 2FA verify step)
Credentials are passed via environment variables — never hardcoded.
Node.js ≥ 20
Baserow account with 2FA enabled
Baserow TOTP secret (base32)
git clone git@github.com:aficiomaquinas/mcp-baserow-schema.git
cd mcp-baserow-schema
npm install
npm run buildSet environment variables (or use a .env file — see .env.example):
BASEROW_API_URL=https://your-baserow-instance.com
BASEROW_USERNAME=you@example.com
BASEROW_PASSWORD=your_password
BASEROW_TOTP_SECRET=YOUR_BASE32_TOTP_SECRETAdd to ~/.hermes/profiles/<profile>/config.yaml:
mcp_servers:
baserow-mcp:
command: node
args:
- /path/to/mcp-baserow-schema/dist/index.js
enabled: true
env:
BASEROW_API_URL: https://baserow.example.com
BASEROW_USERNAME: you@example.com
BASEROW_PASSWORD: your_password
BASEROW_TOTP_SECRET: YOUR_BASE32_TOTP_SECRETAdd to claude_desktop_config.json:
{
"mcpServers": {
"baserow-schema": {
"command": "node",
"args": ["/path/to/mcp-baserow-schema/dist/index.js"],
"env": {
"BASEROW_API_URL": "https://baserow.example.com",
"BASEROW_USERNAME": "you@example.com",
"BASEROW_PASSWORD": "your_password",
"BASEROW_TOTP_SECRET": "YOUR_BASE32_TOTP_SECRET"
}
}
}
}Since baserow_api is a pass-through client, every Baserow field type is supported — the JSON body just needs to match the API contract for the endpoint. Reference list of field types:
text, long_text, url, email, number, rating, boolean, date, last_modified, last_modified_by, created_on, created_by, duration, link_row, file, single_select, multiple_select, phone_number, formula, count, rollup, lookup, multiple_collaborators, uuid, autonumber, password, ai
Endpoint details: consult the bundled openapi.json or the Baserow API docs.
Since v2, this MCP covers data operations too (rows, batches, search, sort), so the official Baserow MCP is optional:
mcp-baserow-schema → everything: schema, data, views, filters, admin
Official Baserow MCP → curated row-CRUD UX, if you prefer it for data work
Running both side by side is fine; they don't conflict.
Maintainers: see docs/RELEASING.md. Releases are fully automated (release-it + GitHub Actions with OIDC trusted publishing) — never bump versions, tags, or server.json manually.
MIT
Check the current authentication state including email, user ID, and token expiry.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden for behavioral disclosure. It states it 'checks' state but does not explicitly confirm it is a read-only operation with no side effects. It also does not disclose error behavior (e.g., what happens when not authenticated) or whether the token might be refreshed. This lack of explicit non-destructive or failure-mode detail is a significant gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that front-loads the action ('Check') and the resource ('authentication state'), followed by what it returns. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with 0 parameters and no output schema, so the description lists the expected return contents (email, user ID, token expiry), which provides a reasonable picture. However, it omits potential error cases or unusual behavior (e.g., if not authenticated), making it slightly incomplete for a tool with no annotations or output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has 0 parameters, so the baseline is 4. The input schema is empty and the description adds nothing about parameters, which is fine because there are none to describe. Schema coverage is 100% vacuously.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Check' with a clear resource 'authentication state', and further details the contents (email, user ID, token expiry). This clearly distinguishes it from the sibling tools which are all data operations on databases, tables, rows, and fields.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool (when you need to know the current auth status) but does not explicitly state when to use it over alternatives or any exclusions. Since there are no sibling auth tools, the context is fairly clear, but the lack of explicit guidance like 'use this to verify authentication before other operations' leaves it at implied usage rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create multiple rows in a table at once (up to 200). Each item is a key-value object with field names.
| Name | Required | Description | Default |
|---|---|---|---|
| items | Yes | Array of row objects, each with field name keys. Example: [{"Name": "Alice"}, {"Name": "Bob"}] | |
| table_id | Yes | The table ID. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full responsibility for behavioral disclosure. It mentions the 200-row limit but omits critical details like atomicity, error handling, permissions, or return value. For a mutation tool, this is a significant gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences, front-loaded with the core action and limit, with no redundant wording. Every phrase adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with only two well-documented parameters, but the absence of an output schema and annotations leaves behavioral aspects unaddressed. It lacks information about results, error behavior, or partial failure, making it only minimally complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description's mention of 'key-value object' and 'field names' adds little beyond the already detailed schema. It does not introduce new parameter semantics beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Create multiple rows in a table at once (up to 200).' The verb 'create' plus resource 'multiple rows in a table' is specific and distinguishes it from sibling tools like create_row (single row) and batch_update_rows (update).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for batch row creation with a limit of 200, which effectively communicates when to use it. It does not explicitly name alternatives or state when not to use it, but the context is clear enough for a batch operation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete multiple rows at once (up to 200) by providing an array of row IDs.
| Name | Required | Description | Default |
|---|---|---|---|
| items | Yes | Array of row IDs to delete. Max 200. | |
| table_id | Yes | The table ID. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full responsibility for behavioral disclosure. It clearly signals a destructive delete operation and the 200-row limit. However, it omits details about handling non-existent row IDs, partial failures, atomicity, or return values—important for a batch mutation. The phrase 'at once' hints at atomicity but is not explicit.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that conveys the core operation, the batch nature, the limit, and the input format. Every word earns its place with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is relatively simple with two well-documented parameters, but the lack of an output schema and annotations leaves gaps. The description does not mention what the tool returns, whether deletion is atomic, or how errors are handled. For a batch operation, information about partial failure or success indication would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%: both table_id and items have descriptions. The tool description restates the array and max limit but adds no additional semantics beyond the schema. Since the schema already defines each parameter clearly, the description adds marginal value, meeting the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (Delete), resource (multiple rows), and mode (batch, up to 200). This distinguishes it from sibling tools like delete_row, which handles single rows, and batch_create_rows/batch_update_rows. The phrasing 'at once' clarifies the batch scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool: when deleting multiple rows in one operation. It provides clear context for batch deletion but does not explicitly exclude single-row deletion via delete_row or mention alternatives. The sibling tool list makes the distinction evident, but no explicit when-not guidance is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update multiple rows at once (up to 200). Each item must include an 'id' field with the row ID, plus any fields to update.
| Name | Required | Description | Default |
|---|---|---|---|
| items | Yes | Array of row objects. Each MUST have an "id" field. Example: [{"id": 1, "Status": "Done"}, {"id": 2, "Status": "Pending"}] | |
| table_id | Yes | The table ID. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses the id field requirement and the 200-row limit, providing useful operational context. However, it does not reveal behavior on partial failure, whether updates are atomic, any authentication needs, or return values. This is acceptable but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that immediately communicates the core action and constraint. Every word earns its place, and no redundant information is included.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has only two parameters and no output schema. The description clearly explains the purpose and the required item structure, which is enough for selection and basic invocation. It omits details about return values or error handling, but given the tool's simplicity and the schema's coverage, it is largely complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the schema already describes 'table_id' and 'items' with an example. The description adds a concise statement of the id requirement and allowed fields, but this mostly restates what the schema already conveys. No additional semantic depth is provided beyond the schema baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Update'), resource ('multiple rows'), and scope ('at once'). It also specifies the batch limit (up to 200) and distinguishes from the sibling tool 'update_row' (which handles single rows) and 'batch_create_rows' (which creates rather than updates).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'Update multiple rows at once' implies this tool is for batch updates, contrasting with the single-row 'update_row' sibling. The limit of 200 provides a clear boundary, though no explicit alternative or exclusions are mentioned. Context is clear but lacks direct when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new field (column) in a table. The 'type' parameter must be one of: text, long_text, url, email, number, rating, boolean, date, last_modified, last_modified_by, created_on, created_by, duration, link_row, file, single_select, multiple_select, phone_number, formula, count, rollup, lookup, multiple_collaborators, uuid, autonumber, password, ai.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | The name for the new field (max 255 chars). | |
| type | Yes | The field type. Common types: text, long_text, number, boolean, date, single_select, multiple_select, link_row, url, email, phone_number, formula, rating, duration, file, uuid, autonumber. | |
| table_id | Yes | The table ID to add the field to. | |
| field_options | No | Optional type-specific field configuration (e.g., {text_default: 'hello', description: 'desc'}). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description bears full responsibility for disclosing behavior. It adds the critical constraint that 'type' must be one of the listed enum values, which is valuable. However, it does not mention side effects such as altering the table schema, whether field_options is required for certain types, or what the response will contain.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that states the purpose before listing the allowed types. The list is lengthy but necessary since the schema does not enumerate all valid types. There is no redundant filler, so it is appropriately concise for the information conveyed.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is moderately complex due to the many field types and the field_options parameter, but the description does not explain how to configure type-specific options or what the API returns (no output schema). The schema covers parameter descriptions well, but the lack of behavioral context around field_options and response shape leaves the description incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers all four parameters, but the description adds essential semantics for the 'type' parameter by listing the complete set of allowed values, whereas the schema only provides a partial list of 'common types'. This extra information is necessary for correct parameter selection, going beyond the schema baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a new field (column) in a table' with a specific action and resource, distinguishing it from sibling tools like update_field and delete_field. The verb 'create' and the explicit mention of the resource and target make the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance is given regarding when to use this tool versus alternatives like update_field, delete_field, or list_fields. The purpose implies usage but the description does not mention prerequisites, exclusions, or alternative tools, leaving the agent to infer the use case from nomenclature.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new row in a table. Provide field values as a JSON object with field names as keys. Uses human-readable field names.
| Name | Required | Description | Default |
|---|---|---|---|
| data | Yes | Field values as key-value pairs. Keys are field names (when using user_field_names=true). Example: {"Name": "Alice", "Email": "alice@example.com"} | |
| table_id | Yes | The table ID to create the row in. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden for behavioral disclosure. It mentions human-readable field names but does not explain what happens after creation (return value), potential errors, authentication requirements, or idempotency. This is a significant gap for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three short sentences, front-loaded with the primary action, and every sentence adds relevant information. No wasted words or redundant elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description should explain return values, but it does not. For a simple create operation, it also lacks information about error handling or success indications. The tool has only two parameters, so the description is somewhat complete, but the missing return behavior hurts the overall completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds minimal value by repeating that field values are provided as a JSON object and noting human-readable names, which is already implied by the schema's example. It does not clarify the data object structure beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action ('Create a new row in a table') with a specific verb and resource. It distinguishes from sibling tools like update_row, delete_row, and batch_create_rows by emphasizing single-row creation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives some usage context (provide field values as JSON object, human-readable field names) but does not explicitly state when to use this tool versus batch_create_rows or other alternatives. There are no exclusions or alternative tool mentions, so usage is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new table in a database. Optionally provide initial data rows.
| Name | Required | Description | Default |
|---|---|---|---|
| data | No | Optional initial rows. Each row is an array of values in field order. | |
| name | Yes | The name for the new table (max 255 chars). | |
| database_id | Yes | The database ID to create the table in. | |
| first_row_header | No | If true, the first row of data is used as field names. Default: false. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It only states the action and optional data rows, but does not mention permissions, error behavior on duplicate names, whether the database must exist, or return values. This is insufficient for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core purpose, and includes only the essential optional capability. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite a clear purpose and complete schema descriptions, the tool has no annotations or output schema, and the description omits important contextual details like prerequisites, error handling, and post-creation behavior. This leaves the agent with gaps in understanding the full usage context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents all four parameters with descriptions. The description mentions 'Optionally provide initial data rows', which aligns with the 'data' property, but adds no additional meaning beyond the schema, so a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Create' and resource 'a new table in a database', which clearly distinguishes from sibling tools like create_field, create_row, and delete_table. It also mentions optional initial data rows, reinforcing the table creation scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for creating a table but does not explicitly state when to use this tool instead of alternatives like create_field or create_row. There are no exclusions or alternative suggestions, leaving the timing to the agent's inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a field (column) from a table. This will remove all data in that field.
| Name | Required | Description | Default |
|---|---|---|---|
| field_id | Yes | The field ID to delete. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It explicitly discloses the destructive effect: 'This will remove all data in that field.' This conveys irreversibility and data loss, though it does not mention permissions or failure conditions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, front-loaded with the action. Every word earns its place with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Simple single-parameter tool with no output schema. The description covers the core behavior (deletes field and its data) sufficiently for an agent to invoke it, though it could mention permanence or table-level impact more explicitly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers the only parameter (field_id) with a clear description ('The field ID to delete.'). Baseline 3 applies since schema coverage is 100%; description adds no extra parameter context but none is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clear verb+resource: 'Delete a field (column) from a table.' It explicitly specifies scope (field/column) and is immediately distinguishable from sibling tools like delete_table and delete_row.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied but not explicitly contrasted with alternatives. No guidance on when to choose delete_field over other delete/update tools, but the description clearly states what it does.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a single row from a table by row ID.
| Name | Required | Description | Default |
|---|---|---|---|
| row_id | Yes | The row ID to delete. | |
| table_id | Yes | The table ID. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the destructive action ('delete') but does not reveal whether deletion is permanent, whether it can be undone, or any side effects on related data. This is a significant gap for a mutation tool with no annotation support.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, tightly packed sentence with no filler or redundant information. It conveys the essential information (action, resource, method) efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete tool with two well-documented parameters and no output schema, the description covers the core function. However, it lacks any note about the permanence of deletion or how it differs from the sibling batch_delete_rows, leaving room for improvement in completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%: both row_id and table_id have clear descriptions. The tool description adds no additional meaning beyond what the schema already provides, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action ('Delete') and resource ('a single row from a table'), with the specific method 'by row ID'. The phrase 'single row' distinguishes it from batch deletion and other row operations, making its purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for deleting a single row via the word 'single', but it does not explicitly state when to use this tool versus alternatives like batch_delete_rows. No exclusions or alternative tools are mentioned, leaving usage guidance to be inferred from the description and sibling names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a table by ID. This action is irreversible and will delete all fields and rows.
| Name | Required | Description | Default |
|---|---|---|---|
| table_id | Yes | The table ID to delete. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses that the action is irreversible and will delete all fields and rows, which is critical behavioral information. It does not mention permissions or error handling, but the core destructive consequences are clearly stated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences. The first states the action, the second adds the essential warning about irreversibility and cascading deletion. No filler words or redundant information are present.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete tool with one parameter and no output schema, the description adequately covers the purpose and important side effects. It lacks mention of error conditions or required permissions, but these are not strictly necessary given the straightforward nature of the operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for the single parameter table_id ('The table ID to delete'). The description adds no additional semantic detail beyond this, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Delete' with a clear resource 'a table by ID', which precisely identifies the operation. It differentiates from sibling tools like delete_row and delete_field by targeting the table itself.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies when to use this tool: when you need to permanently delete a table by its ID. It provides clear context for the operation, though it does not explicitly name alternative tools or state when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all databases (applications) in a workspace. Returns database id, name, and type. Use workspace_id=1 for the default workspace.
| Name | Required | Description | Default |
|---|---|---|---|
| workspace_id | Yes | The workspace ID to list databases from. Use 1 for the default workspace. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It states the output (returns database id, name, type) and implies a read-only list operation, which is helpful. However, it does not disclose whether any side effects occur, whether authentication is required, or any other behavioral traits beyond listing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the core action and resource. Every clause earns its place: the action, the workspace scope, the return fields, and a usage tip. There is no redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with one parameter and no output schema, the description is complete. It explains the purpose, the workspace scope, the return fields, and even provides a default parameter value. No additional information is necessary for an agent to invoke this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% coverage, with the parameter description already explaining 'workspace_id' and default value. The tool description repeats this hint ('Use workspace_id=1 for the default workspace') without adding new meaning, so it does not elevate beyond the schema baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List') and the resource ('all databases (applications)'), and scopes it to a workspace. This distinguishes it from sibling tools like list_tables and list_fields, which target different resource types. Mentioning the return fields (database id, name, type) further clarifies the tool's purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a concrete usage tip ('Use workspace_id=1 for the default workspace') but does not explicitly state when to use this tool versus alternatives like list_tables or list_rows. The differentiation is implied by the name and description, but there are no explicit exclusion or alternative recommendations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all fields (columns) in a table with their types and options.
| Name | Required | Description | Default |
|---|---|---|---|
| table_id | Yes | The table ID to list fields for. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. The verb 'list' implies a read-only, non-destructive operation, and the description adds what is returned (types and options). However, it does not disclose potential limitations, permission requirements, or error behavior, leaving some transparency gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded, efficient sentence that conveys the core purpose and output without any filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with one well-described parameter and no output schema, the description adequately communicates the return content (types and options). It could mention error cases or schema limitations, but overall it is sufficient for the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has full coverage (100%) for the single parameter table_id, with a clear description in the schema itself. The description adds no additional parameter-specific semantics, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List all fields (columns) in a table') and specifies the output content ('with their types and options'). It distinguishes from sibling tools like list_tables and list_rows by targeting fields specifically.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies when to use the tool: when you need to inspect the schema of a table. It doesn't explicitly mention alternatives or exclusions, but the context of sibling tool names provides sufficient differentiation for a straightforward read operation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List rows from a table with pagination, search, and sorting. Returns field values using human-readable field names by default.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number (1-indexed). Default: 1. | |
| size | No | Number of rows per page. Default: 100. | |
| search | No | Search query to filter rows. Uses full-text search. | |
| order_by | No | Comma-separated field names to sort by. Prefix with - for descending. Example: "Name,-Created On". | |
| table_id | Yes | The table ID to list rows from. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of disclosing behavior. It adds the useful trait that field values are returned using human-readable names by default. However, it does not explicitly state that the operation is read-only or describe pagination limits/response structure, which are relevant behavioral details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that conveys the core action and key features with no redundant phrases. It is highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Without an output schema, the description should explain return values. It mentions human-readable field names but does not describe the overall response structure (e.g., whether pagination metadata is included). The absence of annotations also leaves safety/read-only expectations implicit, so the description is only partially complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers all 5 parameters with descriptions, so the baseline is 3. The description mentions pagination, search, and sorting, which map to parameters, but adds no additional semantic detail beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the operation (list rows from a table) and specific capabilities (pagination, search, sorting). This distinguishes it from sibling tools like list_tables and list_fields, which deal with different resources.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool: when needing to read rows with optional filtering/sorting. However, it does not explicitly mention alternatives or when not to use it, leaving room for ambiguity relative to other row operations like create_row or update_row.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all tables in a database. Returns table id, name, order, and other metadata.
| Name | Required | Description | Default |
|---|---|---|---|
| database_id | Yes | The database (application) ID to list tables from. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description is the sole source of behavioral disclosure. It indicates a read-only operation (list) and describes the return content, which is useful. However, it does not mention what happens if the database_id is invalid, whether the result is sorted, or any pagination behavior. For a simple list operation, the added return metadata partially compensates for the lack of annotations, but not richly.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is only two sentences, front-loaded with the core action. Every word earns its place: the first sentence states what it does, the second clarifies the return data. No filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a straightforward list tool with one parameter and no output schema, the description is nearly complete: it states the purpose and the return fields. It could benefit from explicitly saying it returns an array of objects, but the phrasing 'Returns table id, name, order, and other metadata' adequately conveys the result. The absence of annotations and output schema is compensated by the explicit return field list.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the parameter 'database_id' is already described as 'The database (application) ID to list tables from.' The tool description does not add any additional meaning about the parameter, so it relies entirely on the schema. Baseline for high schema coverage is 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List all tables in a database') and specifies the resource (tables within a database). It distinguishes itself from sibling tools by focusing on tables, not databases, fields, or rows. The mention of return fields ('table id, name, order, and other metadata') adds clarity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies its usage: to retrieve tables from a database. However, it does not explicitly compare with alternatives like list_databases or list_fields, nor does it state conditions such as 'use this before listing fields' or 'for database info, use list_databases'. The context is clear but not expanded with exclusions or when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing field's name, type, or type-specific options.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | New name for the field (optional). | |
| type | No | New field type (optional). | |
| field_id | Yes | The field ID to update. | |
| field_options | No | Optional type-specific options to update. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full disclosure burden. It states what is updated but does not mention potential side effects (e.g., data loss when changing type), required permissions, reversibility, or return value. This is a minimal transparency gap for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, succinct sentence front-loaded with the key action and scope. No filler or redundant information, making it easy to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is a mutation with no output schema and no annotations, so the description should explain return behavior and side effects. It only lists updatable fields, leaving gaps around expected response, error conditions, and consequences of type changes. This is inadequate for a tool with nested options.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for all four parameters, so the schema provides full parameter meaning. The description merely restates the same updateable attributes without adding syntax, format, or relationship details (e.g., how field_options depends on type). Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (update), the resource (existing field), and the attributes modified (name, type, type-specific options). This distinguishes it from sibling tools like create_field (new field) and delete_field (remove field).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for modifying an existing field, but it does not explicitly mention when to choose this over alternatives or any prerequisites (e.g., field must exist). No exclusions or alternative references are provided, so guidance is only inferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing row in a table. Provide the row ID and the field values to update.
| Name | Required | Description | Default |
|---|---|---|---|
| data | Yes | Field values to update as key-value pairs. Example: {"Status": "Done"} | |
| row_id | Yes | The row ID to update. | |
| table_id | Yes | The table ID. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It does not mention permission requirements, error behavior if the row does not exist, whether the update is partial or full, or what the response contains. For a mutation tool, this is a significant gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences, front-loaded with the primary action and immediately followed by the essential input requirement. Every word earns its place, with no unnecessary fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 3 parameters (including a nested object), no annotations, and no output schema. The description does not explain return values, error scenarios, partial vs full update behavior, or any operational context. It is too minimal to be complete for an agent to correctly anticipate outcomes.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The tool description repeats the schema's information ('row ID and field values') without adding extra semantics like data format details or edge cases. It neither improves nor worsens the schema's already adequate parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action ('Update an existing row in a table') with a clear verb and resource. It distinguishes from sibling tools like create_row, delete_row, and batch_update_rows by implying a single-row update.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context ('existing row' and 'row ID'), but does not explicitly provide when-to-use guidance or name alternative tools such as batch_update_rows. The instruction to provide row ID suggests when it applies, but no exclusions or alternatives are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.0auth_statusbatch_create_rowsbatch_delete_rowsbatch_update_rowscreate_fieldcreate_rowcreate_tabledelete_fielddelete_rowdelete_tablelist_databaseslist_fieldslist_rowslist_tablesupdate_fieldupdate_rowScored across 16 tools
Each tool targets a distinct resource (databases, tables, fields, rows, auth) with clear verb prefixes like list, create, update, delete. Batch operations are clearly variants of row operations, and auth_status is uniquely separated.
All tool names follow a consistent lowercase snake_case pattern with a verb_noun structure (e.g., list_databases, create_field, delete_row). The only outlier, auth_status, remains consistent in style and clearly indicates a status check.
With 16 tools, the set is slightly above the typical 3-15 range but each tool serves a clear purpose, covering databases, tables, fields, rows, and authentication. The batch operations add some redundancy but are justified for efficiency.
Rows and fields have full CRUD coverage, and tables have create/delete/list but no update operation (e.g., rename table). Databases are only listed, not managed, which is reasonable for a schema-focused server but leaves minor gaps.
Your Supabase account in natural language: run SQL, apply migrations, manage tables, storage, edge f
Safe, read-only Postgres and MySQL access for AI agents. Audit log + column-level controls.
PostgreSQL, MySQL, OpenAPI/Swagger, and shared Agent Memory with scoped access.
Butterbase MCP server — manage your backend: schemas, auth, functions, storage, RAG, deploys.
