This server lets you manage a PocketBase instance through MCP tools, covering records, collections, files, logs, cron jobs, backups, settings, SQL, and migrations.
Records: fetch, list, create, update, delete, and batch transactional record operations with filtering, sorting, pagination, and relation expansion.
Collections: list collections, inspect schemas, get collection scaffolds, and validate view queries.
Files: upload file content to record fields and generate download URLs for stored files.
Logs: list, fetch, and get stats for API request logs, plus delete all logs with explicit confirmation.
Cron jobs: list registered cron jobs and trigger individual jobs.
Backups: list, create, and restore backups (restore is destructive and requires confirmation).
Settings: read all app settings and update them with partial payloads.
SQL: run arbitrary raw SQL against the instance when explicitly enabled via POCKETBASE_ENABLE_SQL=true.
Migrations: set the migrations directory, create empty/collection/field migration files, list migrations, and apply or revert individual or batch migrations.
Provides tools for interacting with a PocketBase instance, including record management (fetching, listing, creating, updating), file operations (uploading, downloading), collection management (listing, schema retrieval), log management, and migration management for database schema changes.
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., "@PocketBase MCP Server list the last 10 users created in the users collection"
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.
This is an MCP server that interacts with a PocketBase instance. It allows you to fetch, list, create, update, and manage records and files in your PocketBase collections.
Component | Version |
PocketBase server | >= v0.23 required ( |
| ^0.28.1 |
| ^1.30.0 |
Node.js | >= 18 |
Notes for newer PocketBase servers:
v0.27+: the geoPoint field type and the geoDistance() filter function are fully supported by list_records / batch_records — see Filter examples with geoPoint.
v0.40.x: Log.Data may be truncated by the server (~16KB) and marked with "__pb_truncated__": true; log messages are limited to 8KB. list_logs / get_log output passes this through as-is.
v0.38+: a superuser IP whitelist can be enabled in PocketBase Settings. When active, requests from IPs outside the whitelist (including this MCP's token) are rejected with HTTP 403 — see Troubleshooting.
v0.33+: collection/record ids may not contain . / \ | " ' ` < > : ? * % $ or Windows reserved names. The migration generators validate this up front.
v0.28+: the json field type has a default maximum size of 1MB; larger payloads fail validation on create_record / update_record.
Related MCP server: PocketBase MCP Server
To install PocketBase MCP Server for Claude Desktop automatically via Smithery:
npx -y @smithery/cli install @mabeldata/pocketbase-mcp --client claudeClone the repository (if you haven't already):
git clone <repository_url>
cd pocketbase-mcpInstall dependencies:
npm installBuild the server:
npm run buildThis compiles the TypeScript code to JavaScript in the build/ directory and makes the entry point executable.
Test suite (vitest, 3 layers — full guide in tests/TESTS.md):
npm test — unit + contract tests (207: 195 passing + 12 documented known-bug markers; hermetic: no PocketBase instance or network required). The contract layer locks the tools/list MCP contract via snapshot (33 tools: the 22 original + 11 additive PR-3 tools, each group snapshotted separately), a real Client↔Server handshake over InMemoryTransport, and a stdio smoke of the built build/index.js.
npm run test:integration — integration tests against a real PocketBase binary (56 tests): auto-downloads/caches the binary (POCKETBASE_VERSION to pin, POCKETBASE_BIN for a local binary, PB_BIN_DIR for an alternative cache), boots an ephemeral instance on an OS-assigned port with a unique superuser identity, and validates generated migration files with the official migrate up/down runner. The PR-3 suite (pr3-tools.test.ts) boots its own dedicated instance (admin-scope endpoints — SQL, batch, backups, settings, log clear — must not race siblings on the shared server; see the file header).
npm run test:all — the full suite (263 tests).
npm run typecheck — tsc over src + tests.
SKIP_KNOWN_BUG_TESTS=1 npm test — green baseline where known-bug marker tests are skipped instead of run.
End-to-end smoke scripts (drive the built server over stdio against a real PocketBase instance, 53 checks):
npm run smoke:contract — contract-only smoke (tools/list over stdio, no PocketBase needed).
npm run smoke — full smoke: starts an ephemeral server from the binary at $POCKETBASE_BIN (default /tmp/pb-bin/pocketbase), creates a superuser, then exercises every tool category (records, collections, files, logs, crons, migrations) over the stdio JSON-RPC channel.
CI (.github/workflows/ci.yml) runs build + typecheck + hermetic tests + integration tests + smoke on a matrix of Node 18/20/22 × PocketBase v0.39.11/v0.40.3.
This server requires the following environment variables to be set:
POCKETBASE_API_URL: The URL of your PocketBase instance (e.g., http://127.0.0.1:8090). Defaults to http://127.0.0.1:8090 if not set.
POCKETBASE_ADMIN_TOKEN: An admin authentication token for your PocketBase instance. This is required. You can generate this from your PocketBase admin UI, see API KEYS.
POCKETBASE_ENABLE_SQL: Optional, default disabled. Gates the run_sql tool (raw SQL execution). See SQL Execution (run_sql) below — only set it to true if you understand the risks.
These variables need to be configured when adding the server to Cline (see Cline Installation section).
The server provides the following tools, organized by category:
fetch_record: Fetch a single record from a PocketBase collection by ID.
Input Schema:
{
"type": "object",
"properties": {
"collection": {
"type": "string",
"description": "The name of the PocketBase collection."
},
"id": {
"type": "string",
"description": "The ID of the record to fetch."
}
},
"required": [
"collection",
"id"
]
}list_records: List records from a PocketBase collection. Supports pagination, filtering, sorting, and expanding relations.
Input Schema:
{
"type": "object",
"properties": {
"collection": {
"type": "string",
"description": "The name of the PocketBase collection."
},
"page": {
"type": "number",
"description": "Page number (defaults to 1).",
"minimum": 1
},
"perPage": {
"type": "number",
"description": "Items per page (defaults to 30, max 500).",
"minimum": 1,
"maximum": 500
},
"filter": {
"type": "string",
"description": "Filter string for the PocketBase query."
},
"sort": {
"type": "string",
"description": "Sort string for the PocketBase query (e.g., \\"fieldName,-otherFieldName\\")."
},
"expand": {
"type": "string",
"description": "Expand string for the PocketBase query (e.g., \\"relation1,relation2.subRelation\\")."
}
},
"required": [
"collection"
]
}create_record: Create a new record in a PocketBase collection.
Input Schema:
{
"type": "object",
"properties": {
"collection": {
"type": "string",
"description": "The name of the PocketBase collection."
},
"data": {
"type": "object",
"description": "The data for the new record.",
"additionalProperties": true
}
},
"required": [
"collection",
"data"
]
}update_record: Update an existing record in a PocketBase collection.
Input Schema:
{
"type": "object",
"properties": {
"collection": {
"type": "string",
"description": "The name of the PocketBase collection."
},
"id": {
"type": "string",
"description": "The ID of the record to update."
},
"data": {
"type": "object",
"description": "The data to update.",
"additionalProperties": true
}
},
"required": [
"collection",
"id",
"data"
]
}delete_record: Delete a record from a PocketBase collection by ID (permanent).
Input Schema:
{
"type": "object",
"properties": {
"collection": {
"type": "string",
"description": "The name or ID of the PocketBase collection."
},
"id": {
"type": "string",
"description": "The ID of the record to delete."
}
},
"required": [
"collection",
"id"
]
}batch_records: Execute multiple record operations (create/update/upsert/delete) in ONE transactional batch — if any operation fails, the whole batch rolls back. Requires server-side batch enabled: on PocketBase >= v0.39 /api/batch is OFF by default; enable it via update_settings with {"batch": {"enabled": true}} (or Admin UI -> Settings), otherwise calls fail with HTTP 403 "Batch requests are not allowed".
Input Schema:
{
"type": "object",
"properties": {
"requests": {
"type": "array",
"items": {
"type": "object",
"properties": {
"collection": { "type": "string" },
"action": { "enum": ["create", "update", "upsert", "delete"] },
"id": { "type": "string" },
"data": { "type": "object", "additionalProperties": true }
},
"required": ["collection", "action"]
}
}
},
"required": ["requests"]
}get_collection_schema: Get the schema of a PocketBase collection.
Input Schema:
{
"type": "object",
"properties": {
"collection": {
"type": "string",
"description": "The name of the PocketBase collection."
}
},
"required": [
"collection"
]
}upload_file: Upload a file to a specific field in a PocketBase collection record.
Input Schema:
{
"type": "object",
"properties": {
"collection": {
"type": "string",
"description": "The name of the PocketBase collection."
},
"recordId": {
"type": "string",
"description": "The ID of the record to upload the file to."
},
"fileField": {
"type": "string",
"description": "The name of the file field in the PocketBase collection."
},
"fileContent": {
"type": "string",
"description": "The content of the file to upload."
},
"fileName": {
"type": "string",
"description": "The name of the file."
}
},
"required": [
"collection",
"recordId",
"fileField",
"fileContent",
"fileName"
]
}list_collections: List all collections in the PocketBase instance.
Input Schema:
{
"type": "object",
"properties": {},
"additionalProperties": false
}download_file: Get the download URL for a file stored in a PocketBase collection record.
Input Schema:
{
"type": "object",
"properties": {
"collection": {
"type": "string",
"description": "The name of the PocketBase collection."
},
"recordId": {
"type": "string",
"description": "The name of the record containing the file."
},
"fileField": {
"type": "string",
"description": "The name of the file field in the PocketBase collection."
}
},
"required": [
"collection",
"recordId",
"fileField"
]
}Note: This tool returns the file URL. The actual download needs to be performed by the client using this URL.
PocketBase >= v0.27 supports the geoPoint field type and the geoDistance() filter function. Both work transparently through list_records / create_record / update_record / batch_records (the filter string is passed to the server as-is):
// store a location: create_record data payload (location is a geoPoint field)
{ "title": "Office", "location": { "lat": -23.5505, "lon": -46.6333 } }
// geoDistance(lonA, latA, lonB, latB) returns KILOMETRES (verified on v0.40.3) —
// offices within 10 km of São Paulo center (list_records filter):
{ "collection": "places", "filter": "geoDistance(location.lon, location.lat, -46.6333, -23.5505) <= 10" }
// combine with other conditions:
{ "collection": "places", "filter": "active = true && geoDistance(location.lon, location.lat, -46.6333, -23.5505) < 5" }Arguments must be plain numbers or numeric field identifiers (location.lon / location.lat for a geoPoint field); a geometry-literal like {-23.55, -46.63} is NOT valid, and geoDistance() is currently not supported in sort. Official docs: https://pocketbase.io/docs/api-rules-and-filters/ (geoDistance section).
list_collections: List all collections in the PocketBase instance.
Input Schema:
{
"type": "object",
"properties": {},
"additionalProperties": false
}get_collection_schema: Get the schema of a PocketBase collection.
Input Schema:
{
"type": "object",
"properties": {
"collection": {
"type": "string",
"description": "The name of the PocketBase collection."
}
},
"required": [
"collection"
]
}get_collection_scaffolds: Get example collection schema payloads (server >= v0.37) — an object keyed by collection type (base, auth, view) with ready-to-edit templates for building new collections.
Input Schema: { "type": "object", "properties": {}, "additionalProperties": false }
dry_run_view_query: Validate a VIEW collection SQL query without saving the collection (server >= v0.37). Returns the resulting field definitions and a sample of rows, or a validation error.
Input Schema:
{
"type": "object",
"properties": {
"query": { "type": "string", "description": "The SQL SELECT statement backing the view collection." }
},
"required": ["query"]
}Note: The Logs API requires admin authentication and may not be available in all PocketBase instances or configurations. These tools interact with the PocketBase Logs API as documented at https://pocketbase.io/docs/api-logs/.
list_logs: List API request logs from PocketBase with filtering, sorting, and pagination.
Input Schema:
{
"type": "object",
"properties": {
"page": {
"type": "number",
"description": "Page number (defaults to 1).",
"minimum": 1
},
"perPage": {
"type": "number",
"description": "Items per page (defaults to 30, max 500).",
"minimum": 1,
"maximum": 500
},
"filter": {
"type": "string",
"description": "PocketBase filter string (e.g., \"method='GET'\")."
},
"sort": {
"type": "string",
"description": "PocketBase sort string (e.g., \"-created,url\")."
}
},
"required": []
}Note: on PocketBase >= v0.40 the server may truncate Log.Data (~16KB, marked with "__pb_truncated__": true) and limit log messages to 8KB.
get_log: Get a single API request log by ID.
Input Schema:
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "The ID of the log to fetch."
}
},
"required": [
"id"
]
}get_logs_stats: Get API request logs statistics with optional filtering.
Input Schema:
{
"type": "object",
"properties": {
"filter": {
"type": "string",
"description": "PocketBase filter string (e.g., \"method='GET'\")."
}
},
"required": []
}truncate_logs: Delete ALL API request logs (server >= v0.40). DESTRUCTIVE and irreversible — requires confirm: true.
Input Schema:
{
"type": "object",
"properties": {
"confirm": { "type": "boolean", "description": "Must be explicitly true to delete all logs." }
},
"required": ["confirm"]
}Note: The Cron Jobs API requires admin authentication and may not be available in all PocketBase instances or configurations. These tools interact with the PocketBase Cron Jobs API.
list_cron_jobs: Returns list with all registered app level cron jobs.
Input Schema:
{
"type": "object",
"properties": {
"fields": {
"type": "string",
"description": "Comma separated string of the fields to return in the JSON response (by default returns all fields). Ex.:?fields=*,expand.relField.name"
}
}
}run_cron_job: Triggers a single cron job by its id.
Input Schema:
{
"type": "object",
"properties": {
"jobId": {
"type": "string",
"description": "The identifier of the cron job to run."
}
},
"required": [
"jobId"
]
}Note: The Backup API requires superuser authentication (server >= v0.22). Docs: https://pocketbase.io/docs/api-backups/.
list_backups: List all backup files available on the instance (key, size, modified).
Input Schema: { "type": "object", "properties": {}, "additionalProperties": false }
create_backup: Queue a new database+storage backup. Optional name must end in .zip (letters, digits, _, - only); omitted → the server generates pb_backup_<timestamp>.zip. Backups are processed asynchronously — poll list_backups for the new key.
Input Schema:
{
"type": "object",
"properties": {
"name": { "type": "string", "description": "Optional backup filename ending in .zip." }
},
"required": []
}restore_backup: Restore the instance from an existing backup key. DESTRUCTIVE: replaces ALL current data. Requires confirm: true.
Input Schema:
{
"type": "object",
"properties": {
"key": { "type": "string", "description": "Backup file key from list_backups." },
"confirm": { "type": "boolean", "description": "Must be explicitly true." }
},
"required": ["key", "confirm"]
}Note: The Settings API requires superuser authentication. Secrets (SMTP password, S3 keys, OAuth2 client secrets) are returned by the server masked as
"******";update_settingsneeds the REAL new values for those fields (PATCH semantics — omitted fields keep their stored values).
get_settings: Fetch all app settings (sections: meta, logs, smtp, batch, backups, s3, rateLimits, ...).
Input Schema: { "type": "object", "properties": {}, "additionalProperties": false }
update_settings: Bulk-update settings with a partial payload.
Input Schema:
{
"type": "object",
"properties": {
"data": { "type": "object", "description": "Partial settings payload, e.g. { \"logs\": { \"maxDays\": 14 } }.", "additionalProperties": true }
},
"required": ["data"]
}run_sql executes arbitrary raw SQL against the PocketBase instance (server >= v0.39, endpoint POST /api/sql) with superuser privileges. Because an MCP server is typically driven by an LLM — and LLMs can be steered by prompt injection in the data they read — this tool is a much bigger blast radius than the record-level tools and is therefore:
DISABLED BY DEFAULT. The tool is always listed (stable contract), but every call returns an explanatory error unless the MCP process was started with POCKETBASE_ENABLE_SQL=true. No network request is made when the gate is closed.
All-or-nothing. There is no read-only mode: SQL statements that modify or drop data (UPDATE, DELETE, DROP, PRAGMAs, ...) are just as executable as SELECT. Only enable the gate on instances you fully trust and, ideally, on a copy of your data (PocketBase is a single file — back it up first with create_backup).
Auditable. SQL calls land in the PocketBase request logs (POST /api/sql), so list_logs can reconstruct what ran.
Enable explicitly, only if you accept the risks:
POCKETBASE_ENABLE_SQL=true node build/index.jsTypical (read-only) usage once enabled:
{ "name": "run_sql", "arguments": { "query": "SELECT COUNT(*) AS n FROM posts" } }set_migrations_directory: Set the directory where migration files will be created and read from.
Input Schema:
{
"type": "object",
"properties": {
"customPath": {
"type": "string",
"description": "Custom path for migrations. If not provided, defaults to 'pb_migrations' in the current working directory."
}
}
}create_migration: Create a new, empty PocketBase migration file with a timestamped name.
Input Schema:
{
"type": "object",
"properties": {
"description": {
"type": "string",
"description": "A brief description for the migration filename (e.g., 'add_user_email_index')."
}
},
"required": ["description"]
}create_collection_migration: Create a migration file specifically for creating a new PocketBase collection.
Input Schema:
{
"type": "object",
"properties": {
"description": {
"type": "string",
"description": "Optional description override for the filename."
},
"collectionDefinition": {
"type": "object",
"description": "The full schema definition for the new collection (including name, id, fields, rules, etc.).",
"additionalProperties": true
}
},
"required": ["collectionDefinition"]
}add_field_migration: Create a migration file for adding a field to an existing collection.
Input Schema:
{
"type": "object",
"properties": {
"collectionNameOrId": {
"type": "string",
"description": "The name or ID of the collection to update."
},
"fieldDefinition": {
"type": "object",
"description": "The schema definition for the new field.",
"additionalProperties": true
},
"description": {
"type": "string",
"description": "Optional description override for the filename."
}
},
"required": ["collectionNameOrId", "fieldDefinition"]
}list_migrations: List all migration files found in the PocketBase migrations directory.
Input Schema:
{
"type": "object",
"properties": {},
"additionalProperties": false
}apply_migration: Apply a specific migration file.
Input Schema:
{
"type": "object",
"properties": {
"migrationFile": {
"type": "string",
"description": "Name of the migration file to apply."
}
},
"required": ["migrationFile"]
}revert_migration: Revert a specific migration file.
Input Schema:
{
"type": "object",
"properties": {
"migrationFile": {
"type": "string",
"description": "Name of the migration file to revert."
}
},
"required": ["migrationFile"]
}apply_all_migrations: Apply all pending migrations.
Input Schema:
{
"type": "object",
"properties": {
"appliedMigrations": {
"type": "array",
"items": { "type": "string" },
"description": "Array of already applied migration filenames."
}
}
}revert_to_migration: Revert migrations up to a specific target.
Input Schema:
{
"type": "object",
"properties": {
"targetMigration": {
"type": "string",
"description": "Name of the migration to revert to (exclusive). Use empty string to revert all."
},
"appliedMigrations": {
"type": "array",
"items": { "type": "string" },
"description": "Array of already applied migration filenames."
}
},
"required": ["targetMigration"]
}The PocketBase MCP Server includes a migration system for managing database schema changes. This system allows you to:
Create migration files with timestamped names
Generate migrations for common operations (creating collections, adding fields)
Apply and revert migrations individually or in batches
Migration files generated by this MCP (create_collection_migration, add_field_migration) embed a machine-readable marker comment (// mcp-migration-meta: {...}) describing their operations as plain data. apply_migration, revert_migration, apply_all_migrations and revert_to_migration execute those operations through the PocketBase REST API (pb.collections.*), which is the only channel available to an MCP client.
Migration files without the marker — e.g. hand-written server-side JSVM migrations created with ./pocketbase migrate create — use the server JSVM API (migrate(), new Collection(), app.save()), which does not exist in a REST client. They cannot be applied through this MCP; the apply tools return an explanatory error pointing to ./pocketbase migrate up on the PocketBase host. (Previous versions tried to evaluate those files locally with new Function, which always failed at runtime.)
Applied-state tracking is not stored server-side: apply_all_migrations / revert_to_migration take an appliedMigrations array parameter (the server's _migrations table is not exposed to REST clients). Keep that list in your own tooling, or apply/revert individual files.
Generated files remain valid JSVM migrations, so the same file can also be applied on the host with ./pocketbase migrate up (in which case PocketBase tracks the state in its own _migrations table — do not mix both execution paths for the same file).
Migration files are JavaScript files with a timestamp prefix and descriptive name:
// 1744005374_update_transactions_add_debt_link.js
/// <reference path="../pb_data/types.d.ts" />
// mcp-migration-meta: {"ops":{"up":[...],"down":[...]}} <- only in MCP-generated files
migrate((app) => {
// Up migration code here
return app.save();
}, (app) => {
// Down migration code here
return app.save();
});Each migration has an "up" function for applying changes and a "down" function for reverting them.
Setting a custom migrations directory:
await setMigrationsDirectory("./my_migrations");Creating a basic migration:
await createNewMigration("add_user_email_index");Creating a collection migration:
await createCollectionMigration({
id: "users",
name: "users",
fields: [
{ name: "email", type: "email", required: true }
]
});Adding a field to a collection:
await createAddFieldMigration("users", {
name: "address",
type: "text"
});Applying migrations:
// Apply a specific migration
await applyMigration("1744005374_update_transactions_add_debt_link.js", pocketbaseInstance);
// Apply all pending migrations
await applyAllMigrations(pocketbaseInstance);Reverting migrations:
// Revert a specific migration
await revertMigration("1744005374_update_transactions_add_debt_link.js", pocketbaseInstance);
// Revert to a specific point (exclusive)
await revertToMigration("1743958155_update_transactions_add_relation_to_itself.js", pocketbaseInstance);
// Revert all migrations
await revertToMigration("", pocketbaseInstance);To use this server with Cline, you need to add it to your MCP settings file (cline_mcp_settings.json).
Locate your Cline MCP settings file:
Typically found at ~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json on Linux/macOS.
Or ~/Library/Application Support/Claude/claude_desktop_config.json if using the Claude desktop app on macOS.
Edit the file and add the following configuration under the mcpServers key. Replace /path/to/pocketbase-mcp with the actual absolute path to this project directory on your system. Also, replace <YOUR_POCKETBASE_API_URL> and <YOUR_POCKETBASE_ADMIN_TOKEN> with your actual PocketBase URL and admin token.
{
"mcpServers": {
// ... other servers might be listed here ...
"pocketbase-mcp": {
"command": "node",
"args": ["/path/to/pocketbase-mcp/build/index.js"],
"env": {
"POCKETBASE_API_URL": "<YOUR_POCKETBASE_API_URL>", // e.g., "http://127.0.0.1:8090"
"POCKETBASE_ADMIN_TOKEN": "<YOUR_POCKETBASE_ADMIN_TOKEN>"
},
"disabled": false, // Ensure it's enabled
"autoApprove": [
"fetch_record",
"list_collections",
"get_collection_schema",
"list_logs",
"get_log",
"get_logs_stats",
"list_cron_jobs",
"run_cron_job"
] // Suggested auto-approve settings
}
// ... other servers might be listed here ...
}
}Save the settings file. Cline should automatically detect the changes and connect to the server. You can then use the tools listed above.
HTTP 403 on every request: since PocketBase v0.38 you can enable a superuser IP whitelist (Admin UI -> Settings). If enabled, add the IP of the machine running this MCP server (or disable the whitelist).
FATAL: POCKETBASE_ADMIN_TOKEN environment variable is required: the token env var is not set; generate an API key in the PocketBase admin UI (superuser -> API keys) and set POCKETBASE_ADMIN_TOKEN.
Health-check warning on stderr at startup: the configured POCKETBASE_API_URL is unreachable (instance down or wrong URL). The MCP still starts so tools/list works, but tool calls will fail until the instance is reachable.
Cannot apply ...: This migration file does not contain MCP metadata: the file is a server-side JSVM migration; run ./pocketbase migrate up on the PocketBase host instead (see Migration System).
@modelcontextprotocol/sdk (^1.30.0)
pocketbase (^0.28.1)
typescript (dev dependency)
@types/node (dev dependency)
Create a migration file for adding a field to an existing collection.
| Name | Required | Description | Default |
|---|---|---|---|
| collectionNameOrId | Yes | The name or ID of the collection to update. | |
| fieldDefinition | Yes | The schema definition for the new field. | |
| description | No | Optional description override for the filename. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It states 'create a migration file' but does not disclose what that entails—e.g., where the file is created, whether it is applied immediately, or any side effects. The behavioral impact is minimally transparent.
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?
One short sentence, no wasted words. However, it could benefit from slightly more detail (e.g., type of file generated) without becoming verbose. Still good conciseness.
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?
Given the complexity (3 parameters, nested object, no output schema, many sibling tools), the description is incomplete. It does not explain the return value, the exact nature of the migration file, or how it relates to the migration workflow. An AI agent would lack full context to use the 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?
Schema description coverage is 100%, so baseline is 3. The description adds no additional parameter information beyond what the schema already provides (e.g., 'collectionNameOrId' as name/ID, 'fieldDefinition' with required name/type). No extra semantic value.
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 (migration file for adding a field to an existing collection). It clearly distinguishes from sibling tools like create_migration (generic) and create_collection_migration (likely creates collection), making the tool's 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 guidance on when to use this tool versus siblings such as create_migration or create_collection_migration. No prerequisites (e.g., collection must exist) or when-not-to-use conditions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Apply all pending migrations.
| Name | Required | Description | Default |
|---|---|---|---|
| appliedMigrations | No | Array of already applied migration filenames. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description must disclose behavioral traits, but it only states 'apply all pending migrations'. It does not mention if the tool is destructive (modifying database), reversible, or requires confirmation. The purpose of the 'appliedMigrations' parameter is unclear from the description alone.
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, short sentence with no fluff, appropriate for a simple tool. It is acceptably concise, though could benefit from slight expansion for clarity.
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?
Given the lack of output schema and annotations, and the tool's potential impact on the database, the description is too minimal. It omits return values, side effects, safety warnings, and best practices for usage, making it insufficient for an AI agent to use safely.
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% coverage for the single parameter, so the schema already describes it. The description adds no extra meaning beyond what the schema provides, hence baseline 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 'Apply all pending migrations' clearly states the action (apply) and the resource (all pending migrations). The name itself distinguishes it from sibling 'apply_migration', which applies a single migration.
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 when there are pending migrations, but it provides no guidance on when not to use this tool, prerequisites, or alternatives such as listing pending migrations first with list_migrations or applying individually with apply_migration.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Apply a specific migration file.
| Name | Required | Description | Default |
|---|---|---|---|
| migrationFile | Yes | Name of the migration file to apply. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It only says 'apply', implying a mutation, but omits details like destructiveness, required permissions, or side effects such as whether reversion is possible.
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 sentence of five words, which is efficient and front-loaded. However, it may be overly terse, lacking context that could help an agent.
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?
Given the tool's simplicity (one parameter, no output schema), the description is too sparse. It does not explain what 'applying' a migration entails, its effects, or how it fits with sibling tools like apply_all_migrations.
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% (parameter 'migrationFile' has a brief description). The tool description adds no additional meaning beyond repeating 'migration file', so 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?
Description states verb 'apply' and resource 'migration file', making the basic action clear. However, it does not differentiate from sibling tools like apply_all_migrations or revert_migration, which share similar verbs.
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 guidance on when to use this tool versus alternatives (e.g., apply_all_migrations) or what prerequisites exist. The description merely states the action without context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a migration file specifically for creating a new PocketBase collection.
| Name | Required | Description | Default |
|---|---|---|---|
| description | No | Optional description override for the filename. | |
| collectionDefinition | Yes | The full schema definition for the new collection (including name, id, fields, rules, etc.). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Does not disclose side effects (e.g., writes to disk, applies immediately, requires permissions). Missing behavioral traits beyond basic purpose.
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?
One sentence, front-loaded, no wasted words. Appropriately concise for a simple tool with clear purpose.
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?
No output schema, and description lacks details on what 'create migration file' means (e.g., file location, naming convention, whether it applies the migration). Missing critical context for agent to fully understand tool impact.
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 parameters have descriptions in schema. Description adds no extra meaning beyond schema, but baseline 3 is appropriate as schema already documents them.
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?
Description clearly states it creates a migration file for creating a new PocketBase collection. Specific verb+resource, and distinguishes from general 'create_migration' and other siblings like 'add_field_migration'.
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?
Implied usage: when creating a new collection via migration. But no explicit when-not-to-use or alternatives. Sibling tools like 'add_field_migration' and 'create_migration' exist, but description doesn't differentiate usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new, empty PocketBase migration file with a timestamped name.
| Name | Required | Description | Default |
|---|---|---|---|
| description | Yes | A brief description for the migration filename (e.g., "add_user_email_index"). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description should disclose behavioral traits. It mentions the file is 'empty' and 'timestamped', indicating no content is added and naming is automatic. However, it fails to mention side effects (e.g., whether existing files are overwritten) or required permissions, providing only moderate transparency.
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 sentence that immediately conveys the action and result. It is front-loaded, concise, and contains no superfluous information.
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?
Given the tool's simplicity (one parameter, no output schema), the description provides enough context: it creates a new empty migration file with a timestamped name. It is missing details like the file location or that the migration is not automatically applied, but these are minor for a straightforward creation tool.
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 documentation coverage is 100%, so the description need not elaborate further. The tool description adds no extra meaning beyond what the schema already provides for the 'description' parameter, meeting baseline expectations.
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 'Create' and the resource 'new, empty PocketBase migration file' with a 'timestamped name'. It distinguishes itself from siblings like add_field_migration or apply_migration by specifying it creates an empty file.
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 guidance on when to use this tool versus alternatives such as add_field_migration or apply_all_migrations. The description does not indicate prerequisites or scenarios where an empty migration is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new record in a PocketBase collection.
| Name | Required | Description | Default |
|---|---|---|---|
| collection | Yes | The name or ID of the PocketBase collection. | |
| data | Yes | The data for the new record (key-value pairs). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It only says 'create' implying mutation, but does not disclose side effects, permissions, return value, or behavior on duplicate entries.
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 sentence with no waste. However, it is too brief for the required detail, earning a 4 rather than 5.
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?
Given the simple tool with 2 parameters, the description lacks mention of return value (none in output schema) or error conditions. It is minimally complete but insufficient for effective tool selection.
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% with descriptions for both parameters. The description adds no extra meaning beyond the schema, so 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 clearly states 'Create a new record' which is a specific verb and resource. It distinguishes from siblings like update_record, but could be more precise by specifying 'Insert a new record into a PocketBase collection.'
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 guidance on when to use this tool versus alternatives like update_record or fetch_record. It does not mention that it is for creating new records only, not for updating existing ones.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the URL to download a file from a PocketBase collection record field.
| Name | Required | Description | Default |
|---|---|---|---|
| collection | Yes | The name or ID of the collection. | |
| recordId | Yes | The ID of the record containing the file. | |
| fileField | Yes | The name of the file field. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It only states 'Get the URL to download a file' without specifying whether the URL is temporary, requires authentication, or what happens if the file is missing. This lack of detail is a significant gap for a tool that interacts with a data store.
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 sentence, which is concise and front-loaded. However, it is overly minimal and could benefit from additional context (e.g., return value or usage example) without becoming verbose. Still, it earns its place as a succinct statement of purpose.
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?
Given the tool's low complexity (3 parameters, no output schema), the description should be nearly complete but falls short. It omits the return type (a URL string), possible error scenarios (e.g., file not found), and any prerequisites like authentication. The description is barely adequate for an agent to use the 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?
Schema description coverage is 100%, so the baseline is 3. The description adds no extra meaning beyond the schema's parameter descriptions (collection, recordId, fileField). It does not clarify constraints, formatting, or default behaviors for the parameters.
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 gets a URL to download a file from a PocketBase collection record field, specifying the verb 'Get' and the resource 'URL to download a file'. It distinguishes from sibling tools like 'fetch_record' (which retrieves the record) and 'upload_file' (which uploads a file).
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 downloading files but does not explicitly state when to use this tool versus alternatives (e.g., 'upload_file' or 'fetch_record'). No exclusions or prerequisites are mentioned, leaving the agent to infer context from the tool's name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch a single record from a PocketBase collection by ID.
| Name | Required | Description | Default |
|---|---|---|---|
| collection | Yes | The name or ID of the PocketBase collection. | |
| id | Yes | The ID of the record to fetch. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description must fully disclose behavior. It only states the basic action without mentioning authentication requirements, rate limits, return format, or error handling. Critical information is missing for a safe and informed invocation.
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, direct sentence with no extraneous words. It is optimally concise and front-loaded with the essential information.
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 its simplicity, the tool operates in a context with many sibling tools and no output schema. The description fails to specify the return structure (e.g., full record object, fields), handling of missing IDs, or any prerequisites. For a basic CRUD tool, more context is needed for reliable use.
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, with clear descriptions for 'collection' and 'id'. The description adds no further detail, but the schema itself is sufficient. Baseline score of 3 is appropriate since the description does not need to compensate.
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 explicitly states 'Fetch a single record from a PocketBase collection by ID,' with a specific verb ('Fetch'), resource ('single record'), and method ('by ID'). It clearly distinguishes from sibling tools like list_records (which fetches multiple records with filters).
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 guidance is provided on when to use this tool versus alternatives like list_records, update_record, or create_record. The agent is left to infer the appropriate context without explicit direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the schema (fields, rules, etc.) of a PocketBase collection.
| Name | Required | Description | Default |
|---|---|---|---|
| collection | Yes | The name or ID of the PocketBase collection. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description carries the full burden. It only states 'Get the schema' which implies a read operation, but gives no details about error handling (e.g., if the collection doesn't exist), the exact structure returned, or whether the response is comprehensive.
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 with no superfluous words. Every word serves the purpose of defining the tool's function.
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?
Given the lack of annotations and output schema, the description should provide more context about the response format or behavior. It is minimal and does not fully prepare an agent for using the 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 sole parameter 'collection' is described in the input schema, and the tool description does not add further semantic value. Since schema coverage is 100%, a score of 3 is appropriate per the 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 ('Get') and the resource ('schema of a PocketBase collection'). It effectively distinguishes from siblings like 'list_collections' (which lists collections) and 'fetch_record' (which gets a record's data).
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 guidance is provided on when to use this tool versus alternatives (e.g., 'list_collections' or 'fetch_record'). The description does not mention scenarios where this tool is appropriate or inappropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a single API request log by ID.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The ID of the log to fetch. |
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. However, it only states the action without mentioning side effects, authentication needs, error handling, or what happens if the ID is invalid. The description adds minimal transparent behavior beyond the purpose.
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 sentence with no wasted words. It efficiently conveys the core purpose without superfluous information.
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?
Given the tool's simplicity (one parameter, no output schema), the description is nearly complete. However, it lacks any information about return format or error behavior. Some context is missing, but the tool is straightforward enough that a 3 is reasonable.
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%, with the parameter 'id' already described well. The description repeats 'by ID' but adds no extra semantics (e.g., format, source, or constraints). Baseline score of 3 is appropriate as the schema does the heavy lifting.
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 'Get', the resource 'API request log', and the method 'by ID'. It effectively distinguishes the tool from siblings like 'list_logs' and 'get_logs_stats' by specifying that it retrieves a single log by its unique identifier.
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 have a specific log ID and want that single log. It does not explicitly mention when not to use it or provide alternatives, but for a simple getter, this implicit guidance is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get API request logs statistics with optional filtering.
| Name | Required | Description | Default |
|---|---|---|---|
| filter | No | PocketBase filter string (e.g., "method='GET'"). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description implies a read-only operation with no side effects, but lacks explicit disclosure of behavior beyond annotations (which are absent). It does not mention auth requirements or rate limits, but is adequate for a simple stats 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 a single sentence that front-loads the purpose. It is concise with 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?
Given the simplicity of parameters and no output schema, the description is minimally complete. However, it does not specify what statistics are returned (e.g., counts, error rates), leaving ambiguity about the output.
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 100% of parameters, so the description adds little value beyond stating 'optional filtering', which mirrors the schema. No additional semantic context is provided.
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 gets 'API request logs statistics' with optional filtering, distinguishing it from siblings that list or retrieve individual logs. However, it could be more explicit about the type of statistics (e.g., count, distribution).
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 guidance is provided on when to use this tool versus alternatives like list_logs or get_log. The description does not mention exclusions or specific contexts.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all collections in the PocketBase instance.
| 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. It states the operation is a list, implying read-only, but does not mention any behavioral traits such as safety, performance, or pagination beyond the obvious.
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 sentence that is direct and contains no wasted words. It is appropriately sized for the tool's simplicity.
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?
Given the tool is a simple list with no parameters and no output schema, the description is fairly complete. It clearly states what the tool does, though it could optionally mention response format.
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 zero parameters, so there is nothing to describe. The description does not add parameter semantics, but the baseline for zero parameters is 4 as schema coverage is trivially 100%.
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 lists all collections in the PocketBase instance. It uses a specific verb 'List' and resource 'collections', and it is distinct from sibling tools like 'get_collection_schema' which targets a single collection.
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 does not provide any guidance on when to use this tool versus alternatives. It implicitly suggests usage for retrieving all collections but lacks explicit exclusions or context compared to siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns list with all registered app level cron jobs.
| Name | Required | Description | Default |
|---|---|---|---|
| fields | No | Comma separated string of the fields to return in the JSON response (by default returns all fields). Ex.:?fields=*,expand.relField.name |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It only mentions it returns a list, but does not disclose any behavioral traits like pagination, sorting, or permissions. Minimal disclosure beyond the basic function.
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 one sentence, 9 words, efficient and front-loaded. Every word contributes to the purpose with no unnecessary information.
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 optional parameter and no output schema, the description is generally complete. Minor gaps exist, such as behavior when no cron jobs exist or default sort order, but these are not critical.
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 the single parameter 'fields', which already explains its purpose. The tool description adds no additional meaning beyond what the schema provides, so 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 clearly states it returns a list of app-level cron jobs, using a specific verb and resource. It distinguishes from siblings like 'run_cron_job' and other listing tools.
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 guidance on when to use this tool versus alternatives, such as 'run_cron_job' or other list tools. The description only states what it does without any context on when it is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List API request logs from PocketBase with filtering, sorting, and pagination.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number (defaults to 1). | |
| perPage | No | Items per page (defaults to 30, max 500). | |
| filter | No | PocketBase filter string (e.g., "method='GET'"). | |
| sort | No | PocketBase sort string (e.g., "-created,url"). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. Description lacks behavioral traits such as read-only nature or potential side effects, though listing logs is inherently non-destructive.
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?
Single sentence, concise, and front-loaded with the action. 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?
No output schema; description does not specify return format (e.g., paginated logs, fields included). Adequate for a list endpoint but incomplete for an agent.
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% with detailed parameter descriptions. The description only groups functionalities already present in the schema, adding no new semantic meaning.
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 lists API request logs with filtering, sorting, and pagination, distinguishing it from sibling tools like get_log and get_logs_stats.
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 listing logs with filtering/sorting/pagination but does not explicitly guide when to use this over other log tools or any prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all migration files found in the PocketBase migrations directory.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description provides minimal behavioral context. It states the action ('List') which implies read-only, but does not explicitly confirm non-destructiveness, auth needs, or error handling. Adequate 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?
A single, front-loaded sentence that conveys the essential purpose without extraneous words. Every part earns its place.
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 description is clear for a simple list tool but could be slightly more complete by indicating return format (e.g., file names/paths) or order. However, for zero-parameter tool, this is nearly 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?
No parameters exist, so the description need not add meaning. The 100% schema coverage and zero params make additional parameter information unnecessary.
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 ('List') and resource ('migration files'), with location ('PocketBase migrations directory'), clearly distinguishing it from sibling tools that create, apply, or revert migrations.
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 on when to use this tool vs alternatives (e.g., when to list before applying/reverting). No context about prerequisites or related operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List records from a PocketBase collection. Supports filtering, sorting, pagination, and expansion.
| Name | Required | Description | Default |
|---|---|---|---|
| collection | Yes | The name or ID of the PocketBase collection. | |
| page | No | Page number (defaults to 1). | |
| perPage | No | Items per page (defaults to 30, max 500). | |
| filter | No | PocketBase filter string (e.g., "status='active'"). | |
| sort | No | PocketBase sort string (e.g., "-created,name"). | |
| expand | No | PocketBase expand string (e.g., "user,tags.name"). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It discloses support for filtering, sorting, pagination, and expansion, which are behavioral aspects, but does not mention read-only nature, authentication requirements, or rate limits. The description is adequate but not comprehensive.
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 sentences with no wasted words. The most critical information (action and resource) is front-loaded, and the supporting features are listed concisely. This is an example of effective brevity.
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 read operation, the description covers the main features. However, it lacks information about the return format (e.g., list of records with pagination metadata) since there is no output schema. Minor gap given the tool's straightforward nature.
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 schema already documents all parameters. The description adds high-level context by grouping features (e.g., 'filtering' corresponds to 'filter' parameter), but does not provide additional meaning beyond what the schema provides. 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 'List records from a PocketBase collection' clearly states the action (list) and resource (PocketBase collection), and mentions supported features (filtering, sorting, pagination, expansion) that distinguish it from sibling tools like create_record or fetch_record.
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 does not explicitly state when to use this tool versus alternatives (e.g., fetch_record for a single record). The purpose is implied but no direct guidance on exclusions or context is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Revert a specific migration file.
| Name | Required | Description | Default |
|---|---|---|---|
| migrationFile | Yes | Name of the migration file to revert. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, and the description does not disclose behavioral traits such as destructiveness, required permissions, or side effects. The term 'revert' implies change but lacks detail.
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?
Single sentence, no fluff. Could incorporate more information without being overly long, but current conciseness is acceptable.
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 one-parameter tool, the description is adequate but lacks behavioral context and differentiation from siblings. Missing output schema and annotations reduce 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%, and the description does not add meaning beyond the schema's parameter description. 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?
Description clearly states it reverts a specific migration file. However, it does not distinguish from the sibling tool 'revert_to_migration', which likely involves reverting multiple migrations.
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 guidance on when to use this tool versus alternatives like revert_to_migration or apply_migration. No prerequisites or context provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Revert migrations up to a specific target.
| Name | Required | Description | Default |
|---|---|---|---|
| targetMigration | Yes | Name of the migration to revert to (exclusive). Use empty string to revert all. | |
| appliedMigrations | No | Array of already applied migration filenames. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description states it reverts migrations but omits critical details: the target is exclusive (per schema), no mention of destructive nature, safety, or prerequisites. With no annotations, the description fails to fully disclose behavior.
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, clear sentence with no waste. However, its brevity sacrifices clarity on details like exclusivity, earning a 4 rather than 5.
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?
Given no annotations or output schema, the description should provide more context. It omits the exclusive semantics of the target, how to interpret the appliedMigrations parameter, and the tool's relationship to sibling tools.
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?
Input schema coverage is 100%, so baseline is 3. The description adds minimal context ('up to a specific target') but does not explain how parameters like 'appliedMigrations' are used or the exclusive nature of 'targetMigration'.
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 verb+resource structure ('Revert migrations') and mentions 'up to a specific target', which clarifies scope. However, it does not differentiate from the sibling 'revert_migration' tool, which could cause confusion.
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 guidance is provided on when to use this tool versus alternatives. The description does not explain that it reverts multiple migrations to a target, unlike 'revert_migration' which reverts a single one.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Triggers a single cron job by its id.
| Name | Required | Description | Default |
|---|---|---|---|
| jobId | Yes | The identifier of the cron job to run. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It only states that the tool 'triggers' the job, but fails to disclose whether the execution is asynchronous, what happens on success/failure, or any side effects. This lack of behavioral details is inadequate for safe invocation.
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 sentence of 8 words, containing no redundant information. Every word earns its place, making it highly concise and front-loaded with the core action.
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?
Given the tool has one required parameter, no output schema, and no annotations, the description is incomplete. It fails to explain execution behavior (e.g., synchronous vs. asynchronous), return values, or error conditions, leaving significant gaps for an agent to safely use the tool.
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 description merely paraphrases the input schema ('by its id'). It adds no additional meaning or context beyond what the parameter description already provides, 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 'Triggers a single cron job by its id' uses a specific verb ('triggers') and resource ('cron job'), clearly stating the action and distinguishing it from sibling tools like list_cron_jobs. The method ('by its id') aligns with the required parameter, making 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?
The description lacks explicit guidance on when to use this tool versus alternatives (e.g., list_cron_jobs) or any preconditions. While the context of triggering a cron job is implied, no when-not or prerequisite information is provided, leaving the agent to infer usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set the directory where migration files will be created and read from.
| Name | Required | Description | Default |
|---|---|---|---|
| customPath | No | Custom path for migrations. If not provided, defaults to "pb_migrations" in the current working directory. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full behavioral disclosure burden. It only states that the tool sets the directory, without explaining persistence, side effects, or required permissions. For a configuration tool, more transparency about scope and impact is needed.
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 clear sentence of 11 words with no redundant information. It is optimally concise for the simplicity of the tool.
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?
Given the low complexity (one optional parameter, no output schema) and strong schema coverage, the description is minimally adequate. However, it lacks context about whether the setting is persistent or session-only, and how it interacts with other migration tools.
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 input schema already documents the customPath parameter including default behavior. The tool description adds no additional parameter meaning, 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 clearly identifies the tool's action ('Set') and resource ('directory where migration files will be created and read from'). It effectively distinguishes this configuration tool from sibling tools that perform migration operations like applying or reverting.
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 no explicit guidance on when to use this tool vs alternatives. There is no mention of prerequisites or context (e.g., set before creating migrations). Usage is implied but not stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing record in a PocketBase collection by ID.
| Name | Required | Description | Default |
|---|---|---|---|
| collection | Yes | The name or ID of the PocketBase collection. | |
| id | Yes | The ID of the record to update. | |
| data | Yes | The data fields to update (key-value pairs). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description only states 'update' without disclosing side effects, permissions, or error handling. Minimal transparency.
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?
Single sentence, no extraneous words, front-loaded with essential information.
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 full schema coverage, the description lacks details on return values, validation behavior, or what happens when fields are missing. Incomplete for a mutation tool.
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%; each parameter has a description. The tool description adds no extra meaning beyond the schema, so baseline 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?
Clear verb 'update', specific resource 'record', and method 'by ID'. Distinguishes from sibling tools like create_record and fetch_record.
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 guidance on when to use this tool versus alternatives, no prerequisites or exclusions mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Upload a file (provided as content string) to a PocketBase collection record field.
| Name | Required | Description | Default |
|---|---|---|---|
| collection | Yes | The name or ID of the collection. | |
| recordId | Yes | The ID of the record to attach the file to. | |
| fileField | Yes | The name of the file field in the collection schema. | |
| fileContent | Yes | The raw content of the file as a string. | |
| fileName | Yes | The desired name for the uploaded file (e.g., "report.txt"). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description must convey behavioral traits. It only says 'Upload a file' without details on overwrite behavior, file size limits, encoding (e.g., base64), or whether the file replaces existing attachments.
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?
Single sentence, no unnecessary words. Efficient, though could add slight additional context without reducing conciseness.
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?
Missing important context: record must exist, file size limits, format of fileContent (string vs base64), and effect on existing files. Incomplete for a mutation 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?
All 5 parameters are fully described in the input schema (100% coverage). The description adds no extra meaning, such as clarifying that fileContent should be base64-encoded. 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 'Upload a file' and the target resource 'to a PocketBase collection record field'. It distinguishes the tool from siblings like download_file and create_record.
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 on when to use this tool vs alternatives, nor prerequisites like the record must exist. The description does not mention 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.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.1.3list_cron_jobsrun_cron_jobv1.0.0add_field_migrationapply_all_migrationsapply_migrationcreate_collection_migrationcreate_migrationcreate_recorddownload_filefetch_recordget_collection_schemaget_logget_logs_statslist_collectionslist_logslist_migrationslist_recordsrevert_migrationrevert_to_migrationset_migrations_directoryupdate_recordupload_fileScored across 22 tools
Each tool targets a distinct operation on a specific resource (collections, records, migrations, logs, cron, files). No two tools have overlapping purposes; descriptions clearly differentiate them.
All tool names follow a consistent verb_noun pattern in snake_case (e.g., create_record, list_collections, apply_migration). No mixing of conventions or vague verbs.
22 tools is appropriate for a PocketBase server, covering collections, records, migrations, logs, cron, and file handling. Each tool serves a clear purpose without redundancy.
Significant gaps: no tool to delete a record or collection, and no direct create/update/delete for collections (only migration-based). This will likely cause agent failures when cleanup is needed.
MCP server for interacting with the Supabase platform
MCP server for AI dialogue using various LLM models via AceDataCloud
GibsonAI MCP server: manage your databases with natural language
Butterbase MCP server — manage your backend: schemas, auth, functions, storage, RAG, deploys.
