The PocketBase MCP Server enables AI assistants to comprehensively manage PocketBase backends through 23 tools covering database operations, authentication, file handling, and developer utilities.
Collection Management: Create, delete, update, list, and migrate collections with full schema configuration including fields, indexes, and access control rules. Truncate collections to preserve structure while removing data.
Record Operations: Perform CRUD operations with advanced filtering, sorting, pagination, field expansion, and data analysis capabilities. Execute complex queries with aggregation support.
Authentication & User Management: Authenticate as admin or user with email/password, create accounts with email verification, check auth status, manage auth collections, and configure auto-refresh tokens.
File Operations: Upload files from content or URLs, download files from record fields, and manage file field types in collections.
Access Control: Configure API rules for collections (list, view, create, update, delete) with rule-based permissions for fine-grained access control.
Data Management: Create backups in JSON/CSV formats, import data with create/update/upsert modes, perform batch operations, and transform data during migrations.
Index Management: Create, delete, and list database indexes for performance optimization.
Developer Tools: Generate TypeScript interfaces from PocketBase collections and vice versa, with support for relation types and configurable timestamps.
Server Utilities: Check server health, access field schema documentation, and reference API rules syntax.
Provides integration with PocketBase databases, offering tools for collection management, record operations, schema generation, authentication, and data analysis. Enables bidirectional conversion between TypeScript interfaces and PocketBase schemas.
Supports bidirectional conversion between TypeScript interfaces and PocketBase schemas, allowing users to generate TypeScript interfaces from PocketBase collections and create collections from TypeScript definitions.
Click on "Install 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 all collections in my database"
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.
Dynamic Model Context Protocol (MCP) server for PocketBase. Connect your AI client once, then manage collections and records in any PocketBase project using runtime tools.
Many PocketBase MCP servers are static: they hardcode collection-specific behavior or require custom tool definitions per schema.
dynamic-pocketbase-mcp is dynamic:
Uses collection-agnostic tools (list_collections, list_records, create_record, etc.)
Works across existing and newly created collections without regenerating server code
Exposes live PocketBase collections as MCP resources
Related MCP server: PocketBase MCP Server
18 MCP tools for health, auth, collections, rules, and records
Collection lifecycle operations (create, update, delete, inspect)
Record CRUD with filters, sorting, pagination, and field selection
Session-based auth via tools (auth_admin, auth_user, get_auth_status, logout)
Built-in references for field schema, schema patch examples, and rules syntax
npm install dynamic-pocketbase-mcp
# or
bun install dynamic-pocketbase-mcpAdd to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):
{
"mcpServers": {
"dynamic-pocketbase": {
"command": "npx",
"args": ["-y", "dynamic-pocketbase-mcp"]
}
}
}If POCKETBASE_URL is not set, the server defaults to http://localhost:8090.
# Use default URL (http://localhost:8090)
npx -y dynamic-pocketbase-mcp
# Use custom PocketBase URL
POCKETBASE_URL=https://pb.example.com \
bunx dynamic-pocketbase-mcpAfter you configure your MCP client, open a chat and try prompts like this:
"Set PocketBase URL to https://pb.example.com."
"Check my PocketBase server health."
"List all PocketBase collections."
"Authenticate as admin with email <your-email> and password <your-password>."
"Create a collection named notes with a required title text field."
"Create a record in notes with title First note."
"Show all records in notes, newest first."
"Log out from PocketBase auth session."
If those steps succeed, your AI can now manage schema and data through this MCP server.
auth_admin or auth_user
get_auth_status
logout
health - Check PocketBase server health status
set_base_url - Update PocketBase URL for current MCP session and clear auth token
get_field_schema_reference - Get field types documentation plus create/update schema examples
get_rules_reference - Get API rules syntax reference
auth_admin - Authenticate as admin/superuser
auth_user - Authenticate as auth collection user (email/username)
get_auth_status - Check current authentication status
logout - Clear authentication session
list_collections - List all collections
view_collection - View collection by name or ID
create_collection - Create new collection (auto-adds created and updated autodate fields for base/auth collections unless provided)
update_collection - Update collection schema/settings (partial object updates allowed; use fieldUpdates/removeFields for MCP-side schema merging, or fields for direct full-array replacement; see get_field_schema_reference examples)
delete_collection - Delete collection
update_collection_rules - Update access control rules
list_records - List/search records with filtering, sorting, pagination
view_record - View single record by ID
create_record - Create new record
update_record - Update existing record
delete_record - Delete record
# Install dependencies
bun install
# Run in development mode
bun run dev
# Type check
bun run typecheck
# Run tests (builds dist first)
bun run test
# Run live integration test against a real PocketBase instance.
# This uses @fadlee/pocketbase-bin to provision PocketBase automatically.
bun run test:live
# Run all checks (typecheck + tests)
bun run check
# Interactive release helper (bump, check, publish, push tag)
bun run release
# Build for production
bun run buildVariable | Required | Description |
| No | PocketBase server URL (default: |
Additional live-test environment variables:
Variable | Required | Description |
| No | Admin email for live test bootstrap (default: |
| No | Admin password for live test bootstrap (default: |
MIT
Analyze data patterns and provide insights about a collection
| Name | Required | Description | Default |
|---|---|---|---|
| collection | Yes | Collection name to analyze | |
| options | No | Analysis options |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure but offers minimal information. It mentions 'analyze data patterns and provide insights' but doesn't specify what types of patterns or insights, whether it's read-only, if it requires specific permissions, or how results are returned. This leaves significant gaps for a tool that presumably performs data analysis.
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, efficient sentence that gets straight to the point without unnecessary words. While it could be more informative, it doesn't waste space and is appropriately sized for a basic description.
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 data analysis tool with no annotations and no output schema, the description is insufficient. It doesn't explain what 'insights' means, what format results come in, whether analysis is statistical or visual, or any limitations. Given the complexity implied by 'analyze' and the lack of structured metadata, more context is needed.
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 description adds no parameter-specific information beyond what's already in the schema, which has 100% coverage. It doesn't explain what 'analyze' means in terms of the collection parameter or what 'insights' might relate to the options. Since the schema does the heavy lifting, the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('analyze data patterns and provide insights') and resource ('about a collection'), making the tool's purpose understandable. However, it doesn't differentiate from sibling tools like 'query_collection' or 'get_collection_schema' that might also involve collection analysis, so it doesn't reach the highest clarity level.
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 guidance on when to use this tool versus alternatives. With siblings like 'query_collection' and 'list_records' that might overlap in data examination, there's no indication of when this analysis tool is preferred or what specific insights it provides that others don't.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Authenticate a user and get auth token
| Name | Required | Description | Default |
|---|---|---|---|
| autoRefreshThreshold | No | Time in seconds that will trigger token auto refresh before its expiration (default: 30 minutes) | |
| collection | No | Auth collection name (default: 'users') | |
| Yes | User email or identity field value | ||
| password | Yes | User password |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden for behavioral disclosure. It states the action ('authenticate') and outcome ('get auth token'), but lacks critical details: authentication method (e.g., password-based), error handling (e.g., invalid credentials), token properties (e.g., expiration), security implications, or rate limits. For a security-sensitive tool with zero annotation coverage, this is a significant gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with zero wasted words. It front-loads the core purpose ('authenticate a user') and immediately states the outcome ('get auth token'). Every word earns its place, making it easy for an agent to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an authentication tool with no annotations and no output schema, the description is incomplete. It doesn't cover behavioral aspects (security, errors, token usage), output details (token format, expiration), or integration context (how the token is used in subsequent calls). Given the complexity and security sensitivity, more guidance is needed for safe and effective 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?
Schema description coverage is 100%, so the schema fully documents all 4 parameters (email, password, collection, autoRefreshThreshold). The description adds no parameter-specific information beyond what's in the schema—it doesn't explain parameter relationships (e.g., email/password as credentials) or usage context. Baseline 3 is appropriate when the schema does all the work.
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 ('authenticate') and resource ('user'), and specifies the outcome ('get auth token'). It distinguishes from siblings like 'create_user' by focusing on authentication rather than user creation. However, it doesn't explicitly differentiate from potential login/credential-checking tools that might exist in other contexts.
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 guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., user must exist), when not to use it (e.g., for token refresh vs. initial auth), or how it relates to sibling tools like 'create_user' for user management workflows. Usage is implied only through the tool name and description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a backup of the PocketBase database
| Name | Required | Description | Default |
|---|---|---|---|
| format | No | Export format (default: json) |
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. While 'Create a backup' implies a write operation that generates output, it doesn't specify where the backup is stored, whether it requires admin permissions, if it locks the database during backup, what happens on failure, or any rate limits. These are critical behavioral aspects for a database operation.
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, efficient sentence that states exactly what the tool does without any unnecessary words. It's perfectly front-loaded with the core functionality and wastes no space on redundant 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 database backup tool with no annotations and no output schema, the description is insufficient. It doesn't explain what the backup output looks like, where it's stored, whether it's a full or partial backup, or any error conditions. Given the complexity of database operations and lack of structured metadata, more contextual information is needed.
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 enum values for the single parameter. The description doesn't add any parameter semantics beyond what's already documented in the schema. The baseline score of 3 is appropriate since the schema fully documents the parameter.
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 ('Create a backup') and resource ('PocketBase database'), making the tool's purpose immediately understandable. However, it doesn't distinguish this backup operation from potential sibling tools like 'download_file' or 'import_data' that might handle similar data operations.
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 guidance on when to use this tool versus alternatives. With sibling tools like 'download_file', 'import_data', and 'export_data' (implied by import), there's no indication of when database backup is preferred over other data extraction methods or what prerequisites might be needed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new collection in PocketBase
| Name | Required | Description | Default |
|---|---|---|---|
| createRule | No | Rule for creating records | |
| deleteRule | No | Rule for deleting records | |
| fields | Yes | Collection fields configuration | |
| indexes | No | Collection indexes | |
| listRule | No | Rule for listing records | |
| name | Yes | Collection name | |
| passwordAuth | No | Password authentication settings for auth collections | |
| type | No | Collection type (base, auth, view) | base |
| updateRule | No | Rule for updating records | |
| viewQuery | No | SQL query for view collections | |
| viewRule | No | Rule for viewing records |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure but only states the basic action. It doesn't cover critical aspects like required permissions, whether this is a destructive operation, rate limits, error handling, or what happens on success (e.g., returns a collection ID). For a creation tool with complex parameters, this is a significant gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with zero wasted words. It's appropriately sized and front-loaded, immediately conveying the core purpose without unnecessary elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (11 parameters with nested objects, no output schema, and no annotations), the description is inadequate. It doesn't explain the return value, error conditions, or behavioral nuances needed for a tool that creates collections with extensive configuration options. The agent would struggle to use this effectively without additional context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 100%, so the schema already documents all 11 parameters thoroughly. The description adds no additional parameter information beyond what's in the schema, but since the schema is comprehensive, the baseline score of 3 is appropriate as the description doesn't need to compensate for schema gaps.
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 ('Create') and resource ('new collection in PocketBase'), making the purpose immediately understandable. However, it doesn't differentiate this tool from sibling tools like 'migrate_collection' or 'generate_pb_schema' which might also involve collection creation or modification, leaving room for ambiguity.
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 guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., authentication), when not to use it (e.g., for updating existing collections), or refer to sibling tools like 'update_record' or 'migrate_collection' for related operations.
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 collection
| Name | Required | Description | Default |
|---|---|---|---|
| collection | Yes | Collection name | |
| data | Yes | Record data with field values matching the collection schema | |
| expand | No | Comma-separated list of relation fields to expand in the response (e.g. 'author,comments.user') | |
| fields | No | Comma-separated fields to return in the response (e.g. 'id,title,author') |
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 states it creates a record but doesn't mention permissions needed, whether it's idempotent, error handling, or what the response contains (especially with no output schema). This is inadequate for a mutation tool with zero annotation coverage.
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, efficient sentence with zero wasted words. It's appropriately sized and front-loaded, directly stating the tool's purpose without unnecessary elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with 4 parameters, no annotations, and no output schema, the description is incomplete. It doesn't explain what happens on success/failure, return values, or behavioral constraints, leaving significant gaps for agent understanding.
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 fully documents all 4 parameters. The description doesn't add any parameter-specific details beyond what's in the schema (e.g., format examples for 'data' or 'expand'), meeting the baseline for high schema coverage.
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 ('Create') and target ('new record in a collection'), providing a specific verb+resource combination. However, it doesn't differentiate from sibling tools like 'create_collection' or 'create_user', which also create resources but different types.
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 guidance on when to use this tool versus alternatives like 'create_collection' or 'update_record'. It doesn't mention prerequisites (e.g., collection must exist) or context for choosing this tool over siblings, leaving the agent with minimal usage direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new user account
| Name | Required | Description | Default |
|---|---|---|---|
| additionalData | No | Additional user data fields specific to your auth collection | |
| collection | No | Auth collection name (default: 'users') | |
| Yes | User email | ||
| emailVisibility | No | Whether the user email is publicly visible (default: false) | |
| password | Yes | User password | |
| passwordConfirm | Yes | Password confirmation (must match password) | |
| verified | No | Whether the user is verified (default: false) |
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. 'Create a new user account' implies a write/mutation operation, but the description doesn't mention authentication requirements, permissions, rate limits, whether the operation is idempotent, or what happens on success/failure. For a mutation tool with zero annotation coverage, this leaves significant behavioral gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with zero wasted words. It's appropriately sized and front-loaded with the core purpose. Every word earns its place, making it easy for an agent to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given this is a mutation tool (creating users) with no annotations, no output schema, and 7 parameters, the description is incomplete. It doesn't address authentication needs, error conditions, return values, or how it fits within the broader system context (e.g., relationship to 'authenticate_user' or 'create_record'). The description alone leaves too many gaps for reliable tool invocation.
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 fully documents all 7 parameters. The description adds no parameter-specific information beyond what's in the schema. According to scoring rules, when schema coverage is high (>80%), the baseline is 3 even with no param info in the description.
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 'Create a new user account' clearly states the verb ('Create') and resource ('user account'), making the purpose immediately understandable. However, it doesn't differentiate this from sibling tools like 'create_record' or 'create_collection', which also create resources but different types. The description is specific but lacks sibling differentiation.
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 guidance on when to use this tool versus alternatives. There's no mention of prerequisites, when not to use it, or how it differs from similar sibling tools like 'create_record' or 'authenticate_user'. The agent must infer usage from the tool name and parameters alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a collection from PocketBase
| Name | Required | Description | Default |
|---|---|---|---|
| collection | Yes | Collection name or ID to delete |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the action ('Delete') but lacks critical details: it does not specify if deletion is permanent or reversible, what permissions are required, how it affects associated data (e.g., records in the collection), or error handling (e.g., for non-existent collections). This is a significant gap for a destructive operation.
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 zero wasted words, efficiently conveying the core action and target. It is front-loaded and appropriately sized for a simple tool, making it easy for an agent to parse quickly without unnecessary elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive tool with no annotations and no output schema, the description is incomplete. It lacks essential context: it does not explain the consequences of deletion (e.g., data loss, irreversibility), required permissions, or what the response might include (e.g., success confirmation or error details). This leaves the agent under-informed for safe and effective 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 schema description coverage is 100%, with the parameter 'collection' clearly documented as 'Collection name or ID to delete'. The description adds no additional semantic context beyond this, such as format examples or constraints (e.g., case-sensitivity). Given the high schema coverage, a 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 action ('Delete') and the resource ('a collection from PocketBase'), making the purpose specific and unambiguous. It distinguishes itself from sibling tools like 'truncate_collection' (which removes data but not the collection) and 'delete_record' (which targets individual records).
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 guidance on when to use this tool versus alternatives. It does not mention prerequisites (e.g., needing authentication or admin rights), exclusions (e.g., not for system collections), or related tools like 'truncate_collection' for removing data without deletion, leaving the agent to infer usage from context alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a record
| Name | Required | Description | Default |
|---|---|---|---|
| collection | Yes | Collection name | |
| id | Yes | Record ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. While 'Delete' implies a destructive mutation, the description doesn't specify whether this operation is reversible, what permissions are required, whether there are confirmation prompts, what happens to related data, or what the response looks like. For a destructive tool with zero annotation coverage, this represents a significant gap in behavioral 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 extremely concise at just three words. Every word earns its place - 'Delete' specifies the action, 'a' indicates singular, and 'record' specifies the resource. There is zero waste or redundancy in this minimal description.
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 that this is a destructive mutation tool with no annotations and no output schema, the description is inadequate. It doesn't explain what happens after deletion (success/failure responses), whether the operation is atomic, what error conditions might occur, or how this differs from similar deletion tools. For a tool that permanently removes data, more contextual information is needed.
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 both parameters ('collection' and 'id') clearly documented in the schema. The description adds no additional parameter information beyond what the schema already provides. According to the scoring rules, when schema_description_coverage is high (>80%), the baseline is 3 even with no param info in the description, which applies here.
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 'Delete a record' states the verb and resource, making the basic purpose clear. However, it doesn't distinguish this tool from sibling tools like 'delete_collection' or 'truncate_collection' which also perform deletion operations on different resources. The purpose is vague about what type of record is being deleted (database record vs other types).
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 guidance on when to use this tool versus alternatives. There are multiple sibling tools that could be relevant for deletion operations (delete_collection, truncate_collection) or record operations (update_record, list_records), but the description offers no context about when this specific tool is appropriate versus those alternatives. No prerequisites or exclusions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Download a file from a record in PocketBase
| Name | Required | Description | Default |
|---|---|---|---|
| collection | Yes | The name or ID of the collection | |
| fileField | Yes | The name of the file field | |
| recordId | Yes | The ID of the record containing the file |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the action but doesn't cover critical aspects like authentication requirements, rate limits, error conditions, or what the download returns (e.g., file content, metadata). This leaves significant gaps for a tool that likely involves data retrieval.
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, efficient sentence that directly states the tool's purpose without unnecessary words. It's front-loaded and wastes no space, making it highly concise and well-structured for quick understanding.
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 of a file download operation with no annotations and no output schema, the description is incomplete. It lacks details on authentication, return format (e.g., binary data, download link), error handling, and how it differs from sibling tools, failing to provide adequate context for safe and effective 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, clearly documenting all three parameters. The description adds no additional meaning beyond what the schema provides, such as examples or constraints, so it meets the baseline for high schema coverage without compensating 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 clearly states the action ('Download a file') and the resource ('from a record in PocketBase'), providing a specific verb+resource combination. However, it doesn't differentiate from sibling tools like 'upload_file' or 'upload_file_from_url' beyond the obvious directionality, missing explicit distinction.
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 guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing an authenticated session), exclusions, or comparisons with related tools like 'upload_file', leaving usage context implied at best.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate a PocketBase schema based on TypeScript interfaces or database diagram
| Name | Required | Description | Default |
|---|---|---|---|
| options | No | Generation options | |
| sourceCode | Yes | TypeScript interface or database diagram to convert to PocketBase schema |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden but lacks behavioral details. It doesn't disclose whether this is a read-only generation or if it modifies the database, what permissions are needed, error handling, or output format. The description only states what it does, not how it behaves.
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, efficient sentence with zero waste. It's front-loaded with the core purpose and includes essential qualifiers about input sources. Every word earns its place without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a code generation tool with no annotations and no output schema, the description is incomplete. It doesn't explain what the generated schema looks like, whether it's returned as text or applied directly, error conditions, or dependencies. This leaves significant gaps for an AI agent to understand the tool's behavior.
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 fully documents both parameters. The description adds no additional parameter semantics beyond implying 'sourceCode' is the input to convert, which is already clear from the schema. Baseline 3 is appropriate when 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 specific action ('generate') and resource ('PocketBase schema'), and distinguishes from siblings by specifying the input source ('TypeScript interfaces or database diagram'). This differentiates it from tools like 'get_collection_schema' (retrieval) or 'create_collection' (manual creation).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by mentioning the input source, but doesn't explicitly state when to use this tool versus alternatives like 'create_collection' (for manual schema creation) or 'generate_typescript_interfaces' (reverse process). No guidance on prerequisites or exclusions is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate TypeScript interfaces from PocketBase collections
| Name | Required | Description | Default |
|---|---|---|---|
| collections | No | Collection names to generate interfaces for (empty for all) | |
| options | No | Generation options |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure but offers minimal information. It states what the tool does but doesn't describe output format (e.g., whether it returns code as a string or file), side effects (e.g., if it modifies the database), error conditions, or performance considerations (e.g., rate limits). This leaves critical behavioral traits unspecified for a code-generation 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, efficient sentence that directly states the tool's purpose without unnecessary words. It's front-loaded with the core action ('Generate TypeScript interfaces') and avoids redundancy, making it easy for an agent to parse quickly. Every part of the sentence contributes 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?
Given the tool's complexity (generating code interfaces) and lack of annotations or output schema, the description is insufficient. It doesn't explain what the output looks like (e.g., TypeScript code string), how errors are handled, or dependencies on other tools (e.g., requiring collection schemas first). For a tool with no structured output documentation, more descriptive context is needed to guide effective 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 schema description coverage is 100%, with clear documentation for both parameters ('collections' and 'options'). The description adds no additional parameter semantics beyond what's in the schema, such as examples of collection names or details on relation types. However, since the schema fully describes the parameters, the baseline score of 3 is appropriate as the description doesn't detract from the schema's clarity.
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 specific action ('Generate TypeScript interfaces') and the resource ('from PocketBase collections'), using precise technical terminology. It distinguishes itself from sibling tools like 'generate_pb_schema' (which likely generates schema definitions) and 'get_collection_schema' (which retrieves schema data), 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 provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., whether authentication is required), compare it to similar tools like 'generate_pb_schema', or specify scenarios where it's appropriate (e.g., for frontend development). The agent must infer usage from the tool name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get schema details for a collection
| Name | Required | Description | Default |
|---|---|---|---|
| collection | Yes | Collection name |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the action ('Get') but does not describe traits like whether it's read-only, requires authentication, has rate limits, or what the output format might be. This leaves significant gaps in understanding the tool's behavior beyond the basic action.
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, efficient sentence that directly states the tool's purpose without any wasted words. It is front-loaded and appropriately sized for the tool's complexity, making it easy to understand at a glance.
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 is incomplete. It does not address behavioral aspects like authentication needs or output details, which are crucial for a tool that interacts with collections. For a tool with no structured support, more context is needed to be fully helpful.
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 the parameter 'collection' clearly documented as 'Collection name'. The description adds no additional meaning beyond this, such as examples or constraints, but since the schema provides adequate information, the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Get') and resource ('schema details for a collection'), making the purpose specific and understandable. However, it does not distinguish this tool from potential siblings like 'generate_pb_schema' or 'generate_typescript_interfaces', which might also relate to schema operations, leaving room for ambiguity in sibling differentiation.
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 guidance on when to use this tool versus alternatives. It does not mention prerequisites, context, or exclusions, such as whether it should be used before creating records or after migrating a collection, nor does it reference sibling tools like 'list_collections' for obtaining collection names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Import data into a collection
| Name | Required | Description | Default |
|---|---|---|---|
| collection | Yes | Collection name | |
| data | Yes | Array of records to import | |
| mode | No | Import mode (default: create) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states 'Import data' which implies a write operation, but fails to describe critical traits like permissions required, whether it's idempotent, error handling, or performance impacts (e.g., rate limits). This is inadequate for a mutation tool with zero annotation coverage.
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, efficient sentence with no wasted words. It is front-loaded and appropriately sized for the tool's complexity, making it easy to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (a mutation operation with 3 parameters) and lack of annotations or output schema, the description is incomplete. It does not cover behavioral aspects like side effects, return values, or error conditions, which are crucial for safe and effective use by an AI 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 description coverage is 100%, so the schema already documents all parameters (collection, data, mode) with descriptions and enum values. The description adds no additional meaning beyond the schema, such as explaining data format constraints or mode implications, meeting the baseline for high coverage.
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 'Import data into a collection' clearly states the verb ('import') and resource ('data into a collection'), making the purpose understandable. However, it does not differentiate from sibling tools like 'upload_file', 'create_record', or 'update_record', which could involve similar data operations, so it misses full sibling distinction.
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 guidance on when to use this tool versus alternatives. It lacks context such as prerequisites (e.g., whether authentication is needed), when-not-to-use scenarios, or comparisons to siblings like 'upload_file' or 'create_record', leaving the agent without usage direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all collections with optional sorting
| Name | Required | Description | Default |
|---|---|---|---|
| sort | No | Sort order for collections (e.g., '-created', 'name') | -created |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden but lacks behavioral details. It doesn't disclose whether this is a read-only operation, if it requires authentication, how results are paginated, or what the output format is, leaving critical gaps for agent understanding.
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 extremely concise with a single, clear sentence that front-loads the core purpose ('List all collections') and efficiently notes the optional feature ('with optional sorting'). Every word earns its place without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no annotations, no output schema, and multiple sibling tools, the description is incomplete. It fails to address key contextual aspects like authentication needs, result format, pagination, or differentiation from similar tools, making it inadequate for full agent comprehension.
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 description mentions 'optional sorting', which aligns with the single parameter 'sort' in the schema. Since schema description coverage is 100%, the baseline is 3, and the description adds minimal value beyond what the schema already documents.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List') and resource ('collections'), making the tool's purpose immediately understandable. However, it doesn't differentiate itself from potential sibling tools like 'query_collection' or 'list_records' that might also list data, missing the highest clarity tier.
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 guidance on when to use this tool versus alternatives like 'query_collection' or 'list_records', nor does it mention prerequisites or exclusions. It only hints at optional sorting, which is insufficient for usage decisions.
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 collection with optional filters
| Name | Required | Description | Default |
|---|---|---|---|
| collection | Yes | Collection name | |
| expand | No | Comma-separated list of relation fields to expand (e.g. 'author,comments.user') | |
| fields | No | Comma-separated fields to return in the response (e.g. 'id,title,author') | |
| filter | No | Filter query using PocketBase filter syntax (e.g. 'status = true && created > "2022-08-01 10:00:00"') | |
| page | No | Page number for pagination (default: 1) | |
| perPage | No | Items per page (default: 50, max: 500) | |
| skipTotal | No | If set to true, the total count query will be skipped to improve performance | |
| sort | No | Sort field and direction (e.g. '-created,title' for descending created date followed by ascending title) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the action ('List records') but doesn't describe pagination behavior, rate limits, authentication needs, or what happens with invalid inputs. The mention of 'optional filters' hints at flexibility but lacks operational details, leaving significant gaps for a tool with 8 parameters.
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, efficient sentence that front-loads the core purpose ('List records from a collection') and adds the key feature ('with optional filters'). There is zero waste, and it's appropriately sized for the tool's complexity.
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 8 parameters, no annotations, and no output schema, the description is incomplete. It doesn't explain return values, error handling, or behavioral traits like pagination defaults. For a list operation with rich filtering options, more context is needed to guide effective use, especially with siblings like 'query_collection' present.
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 fully documents all 8 parameters. The description adds no specific parameter semantics beyond implying filtering capability. It meets the baseline of 3 since the schema does the heavy lifting, but doesn't compensate with additional context like examples or constraints not in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('List') and resource ('records from a collection') with the specific capability of optional filtering. It distinguishes from siblings like 'query_collection' by focusing on listing rather than querying, though the distinction could be more explicit. The purpose is specific and actionable.
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 guidance on when to use this tool versus alternatives like 'query_collection' or 'get_collection_schema'. It mentions optional filters but doesn't specify scenarios, prerequisites, or exclusions. Usage is implied through the name and parameters, but explicit context is missing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Manage collection indexes
| Name | Required | Description | Default |
|---|---|---|---|
| action | Yes | Action to perform | |
| collection | Yes | Collection name | |
| index | No | Index configuration (for create) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It doesn't disclose behavioral traits such as permissions required, whether operations are destructive (e.g., delete might remove data), side effects, or error conditions. 'Manage' is too generic to convey these details, leaving the agent with insufficient context 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, efficient phrase with zero waste, making it appropriately sized. However, it's not front-loaded with critical details like the available actions, which could improve structure. It earns a 4 for brevity but lacks depth.
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 complexity (3 parameters with nested objects, no output schema, and no annotations), the description is incomplete. It doesn't cover return values, error handling, or the scope of 'manage', leaving gaps that could confuse an agent. More detail is needed to compensate for the lack of structured data.
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%, with clear parameter descriptions and an enum for 'action'. The description adds no meaning beyond the schema—it doesn't explain what 'index configuration' entails, how fields are used, or the impact of actions. Baseline 3 is appropriate as the schema does the heavy lifting, but the description doesn't compensate with additional insights.
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 'Manage collection indexes' states the general purpose (verb+resource) but is vague about what 'manage' entails. It doesn't specify the three actions (create, delete, list) available or differentiate from sibling tools like 'create_collection' or 'list_collections' that handle collections themselves rather than their indexes.
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 doesn't mention prerequisites (e.g., needing an existing collection), exclusions, or comparisons to siblings like 'get_collection_schema' which might relate to index information. Usage is implied only through the action parameter.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add, remove, or modify fields from a collection
| Name | Required | Description | Default |
|---|---|---|---|
| collection | Yes | Collection name | |
| createRule | No | Optional new rule for creating records | |
| dataTransforms | No | Field transformation mappings for converting old field values to new ones | |
| deleteRule | No | Optional new rule for deleting records | |
| fields | Yes | New collection fields configuration | |
| listRule | No | Optional new rule for listing records | |
| name | No | Optional new collection name if you want to rename the collection | |
| updateRule | No | Optional new rule for updating records | |
| viewRule | No | Optional new rule for viewing records |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. While 'Add, remove, or modify fields' implies a potentially destructive mutation operation, it doesn't disclose critical behavioral traits like whether this operation requires specific permissions, whether it's reversible, what happens to existing data during migration, or potential downtime implications. For a complex schema migration tool with zero annotation coverage, this is a significant gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise at just 7 words, front-loading the core functionality with zero wasted language. Every word earns its place by communicating the essential action and target.
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 complex schema migration tool with 9 parameters, no annotations, and no output schema, the description is inadequate. It doesn't explain the migration process, data preservation implications, error handling, or what happens to existing records during field modifications. The description should provide more context about this potentially complex and impactful operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description mentions 'fields' but doesn't elaborate on what 'Add, remove, or modify' means in terms of the 9 parameters. With 100% schema description coverage, the schema already documents all parameters thoroughly. The description adds minimal value beyond what's in the structured schema, meeting the baseline expectation when schema coverage is high.
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 ('Add, remove, or modify fields') and the target resource ('from a collection'), providing a specific verb+resource combination. However, it doesn't explicitly distinguish this tool from sibling tools like 'update_record' or 'create_collection', which might also modify collection structures in different ways.
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 guidance on when to use this tool versus alternatives. With sibling tools like 'update_record' (for modifying individual records) and 'create_collection' (for creating new collections), there's no indication of when this schema migration tool is appropriate versus those other operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Advanced query with filtering, sorting, and aggregation
| Name | Required | Description | Default |
|---|---|---|---|
| aggregate | No | Aggregation settings | |
| collection | Yes | Collection name | |
| expand | No | Relations to expand | |
| filter | No | Filter expression | |
| sort | No | Sort expression |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden for behavioral disclosure. It mentions 'advanced query' but doesn't clarify if this is read-only, has side effects, requires authentication, or handles pagination/rate limits. For a query tool with complex parameters and no annotations, this leaves critical behavioral traits unspecified.
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, efficient sentence that directly states the tool's capabilities. It's front-loaded with the core purpose ('Advanced query') and lists key features without unnecessary words. However, it could be slightly more structured by explicitly mentioning the resource (collections).
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 (5 parameters, nested objects, no output schema) and lack of annotations, the description is incomplete. It doesn't explain return values, error handling, or provide enough context for an agent to use it effectively alongside siblings. For an advanced query tool in a data management system, more guidance is needed.
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 5 parameters adequately. The description adds minimal value by naming the capabilities (filtering, sorting, aggregation) that correspond to some parameters, but doesn't provide additional syntax, format details, or examples beyond what's in the schema. This meets the baseline for high schema coverage.
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 states the tool performs an 'advanced query' with specific capabilities (filtering, sorting, aggregation), which gives a general sense of purpose. However, it doesn't specify what resource is being queried (collections) or distinguish it clearly from sibling tools like 'list_records' or 'analyze_collection_data'. The purpose is somewhat vague about scope and differentiation.
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 guidance on when to use this tool versus alternatives. It doesn't mention prerequisites, when it's appropriate compared to simpler tools like 'list_records', or any exclusions. With multiple sibling tools for data operations, this lack of contextual guidance is a significant gap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete all records associated with the specified collection
| Name | Required | Description | Default |
|---|---|---|---|
| collection | Yes | Collection name or ID to truncate (delete all records) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. While it correctly indicates a destructive operation ('Delete all records'), it fails to mention critical aspects: whether this requires specific permissions, if the action is reversible, what happens to the collection structure itself, or any rate limits. For a high-impact mutation tool, this is insufficient.
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, efficient sentence that directly states the tool's function without any fluff. Every word earns its place, and the information is front-loaded with the core action and target. It's optimally concise for a simple, single-parameter 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 this is a destructive mutation tool with no annotations and no output schema, the description is incomplete. It doesn't address permissions, reversibility, effects on collection metadata, or return values. For a tool that permanently deletes all records in a collection, more contextual warning and behavioral detail are needed.
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 description adds meaningful context beyond the 100% schema coverage by clarifying that the parameter represents 'Collection name or ID to truncate' and specifying the effect ('delete all records'). This reinforces the schema's description while providing additional semantic understanding of what the parameter controls in the operation.
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 specific action ('Delete all records') and target resource ('associated with the specified collection'), distinguishing it from siblings like delete_collection (which likely deletes the collection itself) and delete_record (which deletes individual records). The verb+resource combination is precise and 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 provides no guidance on when to use this tool versus alternatives like delete_collection or delete_record. It doesn't mention prerequisites, exclusions, or comparative use cases, leaving the agent to infer usage from the name alone. This is a significant gap for a destructive operation among multiple related tools.
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
| Name | Required | Description | Default |
|---|---|---|---|
| collection | Yes | Collection name | |
| data | Yes | Updated record data with field values matching the collection schema. Can use field modifiers like fieldName+, +fieldName, fieldName-. | |
| expand | No | Comma-separated list of relation fields to expand in the response (e.g. 'author,comments.user') | |
| fields | No | Comma-separated fields to return in the response (e.g. 'id,title,author') | |
| id | Yes | Record ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. 'Update an existing record' implies a mutation operation, but it doesn't specify permissions required, whether changes are reversible, rate limits, error handling, or what the response contains. For a mutation tool with zero annotation coverage, this is a significant gap in 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, efficient sentence with zero waste—it directly states the tool's action without unnecessary elaboration. It's appropriately sized and front-loaded, making it easy for an agent to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of a mutation tool with 5 parameters, no annotations, and no output schema, the description is inadequate. It fails to address behavioral aspects like side effects, error conditions, or response format, leaving the agent with insufficient context to use the tool effectively beyond basic parameter passing.
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 5 parameters thoroughly. The description adds no additional meaning beyond implying that parameters are needed for the update, which is redundant. This meets the baseline score of 3, as the schema does the heavy lifting without requiring compensation from the description.
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 'Update an existing record' clearly states the verb ('update') and resource ('record'), making the purpose immediately understandable. However, it doesn't differentiate this tool from sibling tools like 'create_record' or 'delete_record' beyond the basic action, missing an opportunity to specify what distinguishes an update operation from other record modifications.
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 guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing an existing record ID), exclusions (e.g., not for creating new records), or comparisons to siblings like 'create_record' or 'delete_record', leaving the agent to infer usage from context alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Upload a file to a record in PocketBase
| Name | Required | Description | Default |
|---|---|---|---|
| collection | Yes | The name or ID of the collection | |
| fileContent | Yes | The raw content of the file as a string | |
| fileField | Yes | The name of the file field in the collection schema | |
| fileName | Yes | The desired name for the uploaded file (e.g., 'report.txt') | |
| recordId | Yes | The ID of the record to attach the file to |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure but only states the basic action. It fails to mention critical aspects like required permissions, file size limits, supported formats, error handling, or whether the operation is idempotent, leaving significant gaps for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that directly states the tool's purpose without unnecessary words. It is front-loaded and wastes no space, making it easy to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with 5 required parameters and no annotations or output schema, the description is insufficient. It lacks details on behavioral traits, error conditions, and practical usage context, leaving the agent under-informed about how to invoke it effectively.
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 input schema fully documents all 5 parameters. The description adds no additional semantic context beyond what's in the schema, such as examples or constraints, but doesn't need to compensate for gaps, resulting in a baseline score.
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 specific action ('Upload a file') and target resource ('to a record in PocketBase'), distinguishing it from sibling tools like 'upload_file_from_url' which handles URL-based uploads. It directly communicates the core functionality without ambiguity.
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 guidance on when to use this tool versus alternatives like 'upload_file_from_url' or 'download_file', nor does it mention prerequisites such as authentication or record existence. It lacks context for decision-making in a multi-tool environment.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Upload a file from URL to a record in PocketBase
| Name | Required | Description | Default |
|---|---|---|---|
| collection | Yes | The name or ID of the collection | |
| fileField | Yes | The name of the file field in the collection schema | |
| fileName | No | Optional custom name for the uploaded file. If not provided, will extract from URL | |
| recordId | Yes | The ID of the record to attach the file to | |
| url | Yes | The URL to download the file from |
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 but only states the basic action. It doesn't mention authentication requirements, rate limits, error conditions, file size limits, supported URL schemes, or what happens if the record doesn't exist. For a mutation tool with zero annotation coverage, this is insufficient.
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, efficient sentence that directly states the tool's purpose without unnecessary words. It's appropriately sized and front-loaded with the core functionality.
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 mutation tool with 5 parameters, no annotations, and no output schema, the description is incomplete. It should address behavioral aspects like authentication needs, error handling, and what the tool returns, given the complexity and lack of structured metadata.
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 5 parameters thoroughly. The description adds no additional parameter semantics beyond what's in the schema, meeting the baseline for high schema coverage but not providing extra 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 clearly states the action ('Upload a file from URL') and target ('to a record in PocketBase'), providing a specific verb+resource combination. However, it doesn't distinguish this tool from its sibling 'upload_file' (which likely uploads from local storage rather than URL), missing full differentiation.
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 guidance on when to use this tool versus alternatives like 'upload_file' or other file-related tools. It lacks context about prerequisites, appropriate scenarios, or exclusions, leaving the agent without usage direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Most tools have distinct purposes targeting specific resources and actions, but some potential confusion exists: 'list_records' and 'query_collection' both retrieve records, though 'query_collection' offers advanced features; 'upload_file' and 'upload_file_from_url' are closely related but differentiated by source. Overall, descriptions help clarify boundaries, but minor overlaps could cause occasional misselection.
Tool names follow a highly consistent verb_noun pattern throughout, such as 'create_collection', 'delete_record', and 'list_records'. All tools use snake_case with clear, descriptive verbs aligned with their actions, making the set predictable and easy to navigate without any deviations in style.
With 22 tools, the count is slightly high for a typical MCP server scope, but it is reasonable given the comprehensive coverage of PocketBase operations. It includes CRUD, schema management, data handling, and utilities, which justifies the number, though it might feel heavy compared to more focused servers.
The tool set provides complete coverage for PocketBase operations, including full CRUD for collections and records, user authentication, schema management, data import/export, file handling, and utilities like backup and analysis. There are no obvious gaps, ensuring agents can handle all core workflows without dead ends.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Hosted MCP server for AI-driven data ops. Create apps, manage schemas, and CRUD structured data.
MCP server for interacting with the Supabase platform
MCP-native open-source Notion alternative: read & write pages, databases and kanban boards.
Query, join, profile, clean and convert CSV/JSON/Parquet with server-side DuckDB over MCP.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/fadlee/dynamic-pocketbase-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
