Supports configuration through environment variables loaded from .env files, enabling customization of PocketBase URL, credentials, environment settings, and logging levels.
Integrates with ESLint for code quality checks and linting, with commands for running linting and automatically fixing issues.
Provides testing integration with Jest framework, supporting various testing modes including standard tests, watch mode, and coverage reporting.
Integrates with npm for package management, installation, and running scripts for development, building, testing, and linting.
Provides comprehensive integration with PocketBase backend services, enabling user authentication, collection and record management, file operations, and administrative functions including user management, settings configuration, and system operations like health checks, logs, backups, and email testing.
Built with full TypeScript support including strict type checking, type definitions for PocketBase and MCP tools, and type validation commands.
Uses Zod schemas for parameter validation across all tools, ensuring proper input validation and providing detailed error messages.
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 users in the system"
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.
A comprehensive Model Context Protocol (MCP) server for PocketBase, providing both user and superuser functionality through a rich set of tools.
User login/logout with email and password
User registration with validation
Password reset workflows
Token refresh functionality
Current user information retrieval
Superuser authentication
User management (create, read, update, delete)
User impersonation for testing
Application settings management
Full CRUD operations for collections
Collection schema management
Record creation, reading, updating, and deletion
Advanced filtering and pagination
Bulk record operations
File upload to records
File URL generation with thumbnail support
File deletion and management
Private file access tokens
Health checks
System logs retrieval and analysis
Backup creation and management
Email testing functionality
Server information retrieval
Related MCP server: PocketBase MCP Server
Clone and setup the project:
cd pb_mcp
npm installConfigure environment variables:
The .env file should contain:
POCKETBASE_URL=http://10.69.100.111:8090
SUPER_USER_LOGIN=your-admin@email.com
SUPER_USER_PASSWORD=your-admin-password
NODE_ENV=development
LOG_LEVEL=infoBuild the project:
npm run buildnpm run devnpm run start# Run all tests
npm test
# Run tests in watch mode
npm run test:watch
# Run tests with coverage
npm run test:coverage# Run linting
npm run lint
# Fix linting issues
npm run lint:fix
# Type checking
npm run typecheckpb_auth_loginAuthenticate a user with email and password.
Parameters:
email (string, required): User email address
password (string, required): User password
options (object, optional): Additional auth options
Example:
{
"email": "user@example.com",
"password": "securepassword",
"options": {
"expand": "profile",
"fields": "id,email,username"
}
}pb_auth_registerRegister a new user account.
Parameters:
email (string, required): User email address
password (string, required): Password (minimum 8 characters)
passwordConfirm (string, required): Password confirmation
username (string, optional): Username
name (string, optional): Display name
pb_auth_refreshRefresh the current authentication token.
pb_auth_logoutLogout the current user and clear authentication.
pb_auth_get_userGet information about the currently authenticated user.
pb_auth_request_password_resetRequest a password reset email.
Parameters:
email (string, required): Email address for password reset
pb_auth_confirm_password_resetConfirm password reset with token.
Parameters:
token (string, required): Reset token from email
password (string, required): New password
passwordConfirm (string, required): Password confirmation
pb_admin_loginAuthenticate as superuser/admin.
pb_admin_list_usersList all users (admin only).
Parameters:
page (number, optional): Page number (default: 1)
perPage (number, optional): Items per page (default: 30)
sort (string, optional): Sort criteria
filter (string, optional): Filter criteria
pb_admin_create_userCreate a new user (admin only).
pb_admin_update_userUpdate an existing user (admin only).
pb_admin_delete_userDelete a user (admin only).
pb_admin_impersonate_userImpersonate a user for testing (admin only).
Parameters:
recordId (string, required): User ID to impersonate
duration (number, optional): Token duration in seconds
pb_admin_get_settingsGet application settings (admin only).
pb_admin_update_settingsUpdate application settings (admin only).
pb_collections_listList all collections (admin only).
pb_collections_getGet a specific collection by ID or name (admin only).
pb_collections_createCreate a new collection (admin only).
Parameters:
name (string, required): Collection name
type (string, required): Collection type ("base", "auth", "view")
schema (array, optional): Field definitions
listRule (string, optional): List access rule
createRule (string, optional): Create access rule
etc.
pb_collections_updateUpdate an existing collection (admin only).
pb_collections_deleteDelete a collection (admin only).
pb_records_listList records from a collection with filtering and pagination.
Parameters:
collection (string, required): Collection name or ID
page (number, optional): Page number
perPage (number, optional): Items per page
sort (string, optional): Sort criteria
filter (string, optional): Filter criteria
expand (string, optional): Relations to expand
fields (string, optional): Fields to return
pb_records_getGet a specific record by ID.
pb_records_createCreate a new record.
pb_records_updateUpdate an existing record.
pb_records_deleteDelete a record.
pb_records_bulk_createCreate multiple records at once.
pb_files_get_urlGet the URL for a file attached to a record.
Parameters:
collection (string, required): Collection name
recordId (string, required): Record ID
filename (string, required): File name
thumb (string, optional): Thumbnail size
pb_files_uploadUpload a file to a record field.
Parameters:
collection (string, required): Collection name
recordId (string, required): Record ID
fieldName (string, required): Field name
fileData (string, required): Base64 encoded file data
fileName (string, required): Original file name
mimeType (string, optional): File MIME type
pb_files_deleteDelete a file from a record field.
pb_files_get_tokenGet a file access token for private files.
pb_files_list_record_filesList all files attached to a record.
pb_health_checkCheck the health status of the PocketBase server.
pb_server_infoGet PocketBase server information and configuration.
pb_logs_listGet system logs (admin only).
pb_logs_statsGet log statistics (admin only).
pb_backups_createCreate a new backup (admin only).
pb_backups_listList all available backups (admin only).
pb_system_test_emailSend a test email (admin only).
pb_mcp/
āāā src/
ā āāā server.ts # Main MCP server
ā āāā pocketbase-service.ts # PocketBase client wrapper
ā āāā tools/ # Individual MCP tools
ā ā āāā auth.ts # User authentication tools
ā ā āāā admin.ts # Superuser/admin tools
ā ā āāā collections.ts # Collection management
ā ā āāā records.ts # Record CRUD operations
ā ā āāā files.ts # File management
ā ā āāā system.ts # Health, logs, backups
ā āāā types/ # TypeScript definitions
ā ā āāā pocketbase.ts # PocketBase types
ā ā āāā mcp.ts # MCP tool types
ā āāā utils/ # Utility functions
ā āāā config.ts # Environment configuration
ā āāā logger.ts # Logging utility
āāā tests/ # Test files
āāā package.json
āāā tsconfig.json
āāā .eslintrc.js
āāā jest.config.jsType Safety: Full TypeScript implementation with strict type checking
Error Handling: Comprehensive error handling with proper error types
Authentication: Dual client support for user and admin operations
Validation: Parameter validation using Zod schemas
Logging: Structured logging for debugging and monitoring
Testing: Comprehensive test coverage for all functionality
Define the tool schema in the appropriate file under src/tools/
Implement the handler function with proper error handling
Add parameter validation using Zod schemas
Export the tool and handler from the module
Register the tool in src/server.ts
Write tests for the new functionality
The server uses environment variables for configuration:
POCKETBASE_URL: PocketBase server URL
SUPER_USER_LOGIN: Superuser email
SUPER_USER_PASSWORD: Superuser password
NODE_ENV: Environment (development/production/test)
LOG_LEVEL: Logging level (debug/info/warn/error)
The server implements comprehensive error handling:
PocketBaseError: Custom error class for PocketBase-specific errors
Parameter validation: Zod schema validation with detailed error messages
Graceful degradation: Proper error responses for all failure cases
Logging: All errors are logged with context information
The project includes comprehensive test coverage:
Unit tests: Individual component testing
Integration tests: Full workflow testing
Mock tests: External dependency mocking
Coverage reports: Code coverage analysis
Run tests with:
npm test # Run all tests
npm run test:watch # Watch mode
npm run test:coverage # With coverageEnvironment variables: Sensitive credentials stored in environment variables
Authentication tokens: Proper token management and refresh
Parameter validation: All inputs validated before processing
Error messages: No sensitive information leaked in error responses
Admin operations: Proper authentication checks for admin-only functions
Connection errors: Verify PocketBase URL and server availability
Authentication failures: Check superuser credentials in .env
Permission errors: Ensure proper collection access rules
Type errors: Run npm run typecheck to identify type issues
Set LOG_LEVEL=debug in your .env file for detailed logging.
Use the pb_health_check tool to verify server connectivity and status.
Fork the repository
Create a feature branch
Implement your changes with tests
Run linting and type checking
Submit a pull request
MIT License - see LICENSE file for details.
For issues and questions:
Check the troubleshooting section
Review the test files for usage examples
Create an issue in the repository
Create a new user (admin only)
| Name | Required | Description | Default |
|---|---|---|---|
| Yes | User email address | ||
| emailVisibility | No | Whether email is visible to other users | |
| name | No | Optional display name | |
| password | Yes | User password | |
| passwordConfirm | Yes | Password confirmation | |
| username | No | Optional username | |
| verified | No | Whether the user is verified |
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' implies a write/mutation operation, the description doesn't address important behavioral aspects like what happens on duplicate email, whether the operation is idempotent, what permissions are required beyond 'admin', what the response contains, or error conditions. For a user creation 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 extremely concise at just 5 words, front-loading the essential information ('Create a new user') and adding the critical constraint ('admin only') efficiently. Every word earns its place with zero waste or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a user creation tool with no annotations and no output schema, the description is incomplete. It doesn't explain what the tool returns, what happens on success/failure, or important behavioral constraints. While concise, it lacks the necessary context for an agent to understand the full implications of invoking this administrative 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 description coverage is 100%, so the schema already fully documents all 7 parameters with their types, formats, defaults, and constraints. 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 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 clearly states the action ('Create') and resource ('new user'), making the purpose immediately understandable. It also adds the important constraint 'admin only', which provides valuable context about permissions. However, it doesn't explicitly differentiate from sibling tools like pb_auth_register or pb_admin_update_user, which would require more specific scope information.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context through 'admin only', suggesting this is for administrative user creation rather than self-registration. However, it doesn't provide explicit guidance on when to use this versus alternatives like pb_auth_register (public registration) or pb_admin_update_user (modifying existing users). The guidance is present but incomplete.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a user (admin only)
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | User 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. It states the tool deletes a user and is admin-only, but lacks critical behavioral details: whether deletion is permanent or reversible, what happens to associated data (e.g., records, files), any confirmation steps, error messages for invalid IDs, or rate limits. For a destructive operation 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āa single phrase with no wasted words. It's front-loaded with the core action ('Delete a user') and includes a crucial constraint ('admin only') efficiently. Every part earns its place, 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 (destructive admin operation), lack of annotations, and no output schema, the description is incomplete. It misses details on behavioral outcomes, error handling, and return values. For a high-stakes tool like user deletion, more context is needed to ensure safe and correct usage 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%, with the parameter 'id' clearly documented as 'User ID to delete'. The description doesn't add any meaning beyond thisāit doesn't specify ID format, validation rules, or examples. Since the schema already fully describes the parameter, 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 ('Delete') and resource ('a user'), making the purpose immediately understandable. It distinguishes from siblings like 'pb_admin_update_user' by specifying deletion rather than modification. However, it doesn't explicitly mention the admin-only nature distinguishes it from non-admin user management tools, which slightly reduces specificity.
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 includes 'admin only' which provides some context about permissions, but it doesn't specify when to use this tool versus alternatives like 'pb_admin_update_user' for deactivation or 'pb_collections_delete' for other resources. No explicit guidance on prerequisites, error conditions, or when-not-to-use scenarios is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get application settings (admin only)
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
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 mentions 'admin only', indicating permission requirements, but lacks details on rate limits, response format, or any side effects. This is insufficient for a 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 that directly states the tool's purpose and key constraint ('admin only'). It's front-loaded with no unnecessary words, making it highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (0 parameters, no output schema), the description is minimally adequate. However, with no annotations and no output schema, it should ideally provide more behavioral context (e.g., what settings are returned, format) to be fully complete for an admin 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?
The tool has 0 parameters, and schema description coverage is 100%, so no additional parameter information is needed. The description doesn't add param details, but this is acceptable given the lack of parameters, warranting a baseline score of 4.
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 resource ('application settings'), making the purpose understandable. However, it doesn't differentiate from sibling tools like 'pb_admin_update_settings' or 'pb_server_info' beyond the admin-only aspect, which is why it's not a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context with 'admin only', suggesting it's for administrative tasks. However, it doesn't explicitly state when to use this tool versus alternatives like 'pb_admin_update_settings' or 'pb_server_info', leaving some ambiguity for the agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Impersonate a user (admin only)
| Name | Required | Description | Default |
|---|---|---|---|
| duration | No | Token duration in seconds (optional) | |
| recordId | Yes | User ID to impersonate |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It mentions 'admin only' which hints at permissions, but doesn't disclose what impersonation entails (e.g., temporary token generation, session switching, security implications), rate limits, or what the tool returns. For a sensitive admin operation, this is inadequate.
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's front-loaded with the core action ('Impersonate a user') and includes a critical constraint ('admin only').
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 sensitive admin tool with no annotations and no output schema, the description is insufficient. It doesn't explain what impersonation does, what the output is (e.g., a token or session), security considerations, or how it differs from login tools. This leaves significant gaps for 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 parameters are documented in the schema. The description doesn't add any meaning beyond the schema (e.g., how 'duration' affects token validity or what 'recordId' represents). Baseline 3 is appropriate as the schema handles parameter documentation.
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 ('Impersonate') and resource ('a user'), and specifies it's for admin use only. However, it doesn't differentiate from sibling tools like pb_admin_login or pb_auth_login, which also involve user authentication/access.
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 mentions 'admin only' which provides some context about permissions, but doesn't specify when to use this tool versus alternatives like pb_admin_login or pb_auth_login, nor does it mention prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all users (admin only)
| Name | Required | Description | Default |
|---|---|---|---|
| filter | No | Filter criteria | |
| page | No | Page number | |
| perPage | No | Items per page | |
| sort | No | Sort criteria (e.g., "created", "-updated") |
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 mentions the admin requirement which is useful, but doesn't describe what 'List all users' actually returns, whether it's paginated (though schema hints at this), what format the results are in, or any rate limits. For a tool with 4 parameters and no output schema, this leaves significant behavioral questions unanswered.
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 - just 5 words. It's front-loaded with the core purpose. However, it might be too brief given the tool's complexity (admin tool with 4 parameters and no output schema), potentially sacrificing completeness for 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?
Given this is an admin tool with 4 parameters, no annotations, and no output schema, the description is insufficiently complete. It doesn't explain what the tool returns, how results are structured, what admin permissions are required, or how this differs from other user-related tools. The minimal description leaves too many contextual questions unanswered for proper tool selection and 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 already fully documents all 4 parameters (filter, page, perPage, sort). The description adds no additional parameter information beyond what's in the schema. The baseline of 3 is appropriate when the schema does all the parameter documentation 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 action ('List') and resource ('all users'), making the purpose immediately understandable. It also includes the important constraint 'admin only' which clarifies the required permissions. However, it doesn't differentiate this tool from similar list tools like pb_collections_list or pb_records_list beyond mentioning it's for users.
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 minimal guidance - only that it's 'admin only' which indicates permission requirements. It doesn't explain when to use this versus other user-related tools (like pb_auth_get_user for single users) or other list tools. No explicit alternatives, exclusions, or context for choosing this tool are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Authenticate as superuser/admin
| Name | Required | Description | Default |
|---|---|---|---|
| Yes | Admin email address | ||
| password | Yes | Admin password |
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 this is for authentication but doesn't describe what happens after login (e.g., session creation, token return, permissions granted), whether it has rate limits, what errors might occur, or any security considerations. For an authentication 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 phrase that immediately conveys the core purpose without any wasted words. It's appropriately sized for a simple authentication tool and front-loads 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?
For an authentication tool with no annotations and no output schema, the description is insufficient. It doesn't explain what the tool returns (e.g., session token, admin permissions), what happens on failure, or how the authenticated state should be used with other tools. Given the complexity of authentication and the lack of structured data, more behavioral 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?
Schema description coverage is 100%, so the schema already fully documents both parameters (email and password). The description doesn't add any parameter-specific information beyond what's in the schema, such as format requirements beyond 'email' format or password complexity rules. 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 action ('Authenticate') and the role ('as superuser/admin'), distinguishing it from the non-admin 'pb_auth_login' sibling tool. However, it doesn't specify what resource or system this authentication applies to (e.g., 'PocketBase admin panel'), leaving some ambiguity about the exact scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this should be used for admin-level authentication, but doesn't explicitly state when to use it versus the regular 'pb_auth_login' tool or other auth tools. It provides basic context (admin role) but lacks explicit guidance on prerequisites, alternatives, or exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update application settings (admin only)
| Name | Required | Description | Default |
|---|---|---|---|
| settings | Yes | Settings object to update |
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 mentions the admin-only restriction, which is useful context, but fails to describe critical behaviors such as what types of settings can be updated, whether changes are reversible, potential side effects, or authentication requirements beyond the implied admin role. For a mutation tool with zero annotation coverage, this leaves significant gaps in understanding its 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 extremely concise with just one phrase ('Update application settings (admin only)'), which is front-loaded and wastes no words. Every part of the sentence earns its place by specifying the action, resource, and access restriction efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity as an admin mutation tool with no annotations and no output schema, the description is incomplete. It lacks details on behavioral traits, return values, error handling, or specific use cases, which are crucial for safe and effective tool invocation. The admin hint is helpful but insufficient for full contextual 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?
The schema description coverage is 100%, with the single parameter 'settings' documented as a 'Settings object to update'. The description adds no additional parameter details beyond what the schema provides, such as examples of settings fields or format expectations. Since the schema handles the parameter documentation adequately, a baseline score of 3 is appropriate, but no extra value is contributed by 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 clearly states the action ('Update') and resource ('application settings'), making the purpose understandable. It also specifies the admin-only restriction, which distinguishes it from non-admin tools. However, it doesn't explicitly differentiate from sibling tools like pb_admin_update_user or pb_collections_update, which also perform updates in different 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 implies usage context by stating 'admin only', suggesting it should be used when administrative privileges are required. However, it doesn't provide explicit guidance on when to use this tool versus alternatives like pb_admin_get_settings (for reading) or other admin update tools, nor does it mention prerequisites or exclusions beyond the admin requirement.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing user (admin only)
| Name | Required | Description | Default |
|---|---|---|---|
| No | User email address | ||
| emailVisibility | No | Whether email is visible to other users | |
| id | Yes | User ID to update | |
| name | No | Display name | |
| password | No | New password (optional) | |
| passwordConfirm | No | Password confirmation (required if password is set) | |
| username | No | Username | |
| verified | No | Whether the user is verified |
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 'admin only' hints at permission requirements, it doesn't describe what happens during the update (e.g., whether all fields must be provided or only changed ones, validation rules beyond schema, error conditions, or side effects). For a mutation tool with zero annotation coverage, this is inadequate.
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 5 words, with zero wasted language. It's front-loaded with the essential information (update operation, target resource, permission constraint). Every word 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?
For a mutation tool with 8 parameters, no annotations, and no output schema, the description is insufficient. It doesn't explain what the tool returns, error handling, or important behavioral aspects like whether partial updates are supported. The 'admin only' hint is helpful but doesn't compensate for the missing context needed for safe and effective 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 already documents all 8 parameters thoroughly. The description doesn't add any parameter-specific information beyond what's in the schema. The baseline of 3 is appropriate when the schema does all the parameter documentation 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 ('Update') and resource ('existing user'), making the purpose understandable. It distinguishes from sibling tools like 'pb_admin_create_user' and 'pb_admin_delete_user' by specifying it's for updates rather than creation or deletion. However, it doesn't specify what fields can be updated beyond the generic 'update' term.
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 includes 'admin only' which provides some context about permissions, but doesn't explicitly state when to use this tool versus alternatives. It doesn't mention when to choose this over 'pb_records_update' (which might handle user records differently) or provide guidance on prerequisites like authentication requirements.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Confirm a password reset with the reset token
| Name | Required | Description | Default |
|---|---|---|---|
| password | Yes | New password (minimum 8 characters) | |
| passwordConfirm | Yes | New password confirmation | |
| token | Yes | Password reset token from email |
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 mentions the reset token but doesn't describe what happens after confirmation (e.g., whether the token becomes invalid, if the user is automatically logged in, or what errors might occur). For a security-sensitive operation 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, focused sentence that directly states the tool's purpose with zero wasted words. It's appropriately sized and front-loaded, 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?
For a password reset confirmation tool with no annotations and no output schema, the description is inadequate. It doesn't explain the security implications, what happens on success/failure, or how this integrates with the broader authentication flow. Given the complexity and sensitivity of the operation, 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 schema description coverage is 100%, with all parameters well-documented in the schema itself. The description doesn't add any meaningful parameter information beyond what's already in the schema, so it meets the baseline but doesn't provide 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 ('Confirm a password reset') and the required resource ('with the reset token'), making the purpose immediately understandable. However, it doesn't explicitly differentiate this tool from its sibling 'pb_auth_request_password_reset' beyond the obvious 'confirm' vs 'request' distinction, which prevents a perfect score.
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, prerequisites (like needing a token from 'pb_auth_request_password_reset'), or error conditions. It simply states what the tool does without contextual usage information.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get information about the currently authenticated user
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
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 does not cover critical aspects like authentication requirements, rate limits, error handling, or what specific user information is returned. This leaves significant gaps in understanding the tool's behavior beyond its 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?
The description is a single, clear sentence that efficiently conveys the tool's purpose without any wasted words. It is front-loaded and appropriately sized for a zero-parameter tool, making it highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of annotations and output schema, the description is incomplete for a tool that retrieves user information. It does not explain what data is returned, potential authentication needs, or error conditions, leaving the agent with insufficient context to use the tool effectively in complex scenarios.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has 0 parameters, and the schema description coverage is 100%, so there is no need for parameter details in the description. The description appropriately avoids redundant information, earning a baseline score of 4 for not adding unnecessary param semantics.
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 ('information about the currently authenticated user'), making the purpose specific and understandable. However, it does not explicitly differentiate from sibling tools like 'pb_admin_get_settings' or 'pb_server_info', which might also retrieve user-related or system information, leaving some ambiguity in 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, such as 'pb_admin_list_users' for broader user data or 'pb_auth_login' for authentication. It lacks explicit context, prerequisites, or exclusions, offering only a basic statement of function without usage instructions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Authenticate a user with email and password
| Name | Required | Description | Default |
|---|---|---|---|
| Yes | User email address | ||
| options | No | ||
| password | Yes | User password |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden but only states the basic action without behavioral details. It doesn't disclose what happens on success (e.g., returns session token), failure modes (e.g., invalid credentials), security implications (e.g., rate limits, password handling), or side effects (e.g., session creation). This is inadequate for an authentication 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 that front-loads the core purpose without unnecessary words. Every part ('Authenticate a user with email and password') directly contributes to understanding the tool, making it appropriately sized and well-structured for quick comprehension.
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 authentication (involving security, session management, and potential side effects), no annotations, no output schema, and incomplete parameter coverage (67%), the description is insufficient. It lacks details on return values, error handling, prerequisites, and behavioral context, making it incomplete for safe and effective tool invocation 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 67%, with the 'email' and 'password' parameters well-documented in the schema, but the 'options' object lacks detailed descriptions for its 'expand' and 'fields' properties. The description adds no parameter semantics beyond the schema, merely restating 'email and password' without explaining the optional 'options' or its use cases, so it meets the baseline for moderate 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 ('Authenticate') and target ('a user') with the method ('with email and password'), making the purpose immediately understandable. However, it doesn't explicitly differentiate from sibling tools like 'pb_auth_register' or 'pb_admin_login', which would require more specific context about authentication scope or user type.
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 be registered), exclusions (e.g., not for admin users), or comparisons to siblings like 'pb_auth_register' for new users or 'pb_admin_login' for administrative access, leaving the agent without contextual usage cues.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Logout the current user and clear authentication
| 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 the full burden. It mentions clearing authentication, which implies a mutation, but does not disclose behavioral traits such as whether this requires specific permissions, if it's reversible, what happens to active sessions, or any rate limits. For a mutation 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 waste. It is front-loaded with the core action and effect, making it appropriately sized and easy to understand.
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 (simple logout with no parameters) and lack of annotations or output schema, the description is minimally complete but could be improved. It covers the basic purpose but lacks details on behavioral aspects like side effects or response format, which are important 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?
The tool has 0 parameters, and schema description coverage is 100%, so no parameter information is needed. The description does not add parameter details beyond the schema, but with no parameters, the baseline is 4 as it adequately addresses the lack of inputs.
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 ('Logout') and the resource ('the current user'), while also specifying the effect ('clear authentication'). It distinguishes itself from sibling tools like pb_auth_login, pb_auth_refresh, and pb_auth_register, which handle authentication rather than termination.
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 a user needs to end their session, but it does not explicitly state when to use this tool versus alternatives (e.g., no guidance on prerequisites like being logged in first) or when not to use it. The context is clear but lacks explicit exclusions or comparisons.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Refresh the current user authentication token
| Name | Required | Description | Default |
|---|---|---|---|
| expand | No | Relations to expand | |
| fields | No | Fields to return |
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 lacks details on effects (e.g., invalidates old token, requires valid session), permissions, rate limits, or error conditions. This is inadequate for a tool that modifies authentication state.
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 wasted words. It's front-loaded with the core action and resource, making it efficient and easy to parse, which is ideal for 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?
For an authentication tool with no annotations and no output schema, the description is incomplete. It doesn't explain what happens to the old token, return values, error cases, or dependencies on other tools like pb_auth_login. Given the complexity of token management, 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?
Schema description coverage is 100%, so parameters 'expand' and 'fields' are documented in the schema. The description adds no parameter-specific information beyond implying token refresh, which doesn't clarify how these parameters affect the operation. Baseline 3 is appropriate as the schema handles parameter documentation.
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 ('refresh') and resource ('current user authentication token'), making the purpose understandable. However, it doesn't differentiate from sibling tools like pb_auth_login or pb_auth_logout, which are related authentication operations but serve different purposes.
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 token), timing (e.g., when tokens expire), or related tools like pb_auth_login for initial authentication, leaving usage context unclear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Register a new user account
| Name | Required | Description | Default |
|---|---|---|---|
| Yes | User email address | ||
| name | No | Optional display name | |
| password | Yes | User password (minimum 8 characters) | |
| passwordConfirm | Yes | Password confirmation | |
| username | No | Optional username |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden but only states the basic action without behavioral details. It doesn't mention authentication requirements (likely none for registration), side effects (e.g., email verification, account activation), rate limits, or what happens on success/failure. For a user creation 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, clear sentence with zero wasted words. It's appropriately sized for a straightforward registration tool and front-loads the essential information 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 user registration tool with no annotations and no output schema, the description is inadequate. It doesn't explain what happens after registration (e.g., returns user object, sends confirmation email), error conditions, or how this differs from admin user creation tools. The context signals show moderate complexity (5 parameters), but the description doesn't provide sufficient completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents all 5 parameters. The description adds no parameter-specific information beyond what's in the schema, meeting the baseline expectation but not providing additional context about parameter relationships or usage patterns.
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 ('Register') and resource ('a new user account'), making the purpose immediately understandable. However, it doesn't distinguish this from sibling tools like 'pb_admin_create_user' which might also create user accounts, missing explicit 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 'pb_admin_create_user' or 'pb_auth_login'. There's no mention of prerequisites, target users (e.g., self-registration vs admin creation), or context for choosing this specific registration method.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Request a password reset email for a user
| Name | Required | Description | Default |
|---|---|---|---|
| Yes | Email address to send password reset 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. It states the action but does not cover critical aspects like whether this triggers an email, potential rate limits, error conditions (e.g., invalid email), or the expected response format. This leaves significant gaps in understanding the tool's 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, efficient sentence that directly states the tool's purpose without any unnecessary words. It is front-loaded and wastes no space, making it easy to understand at a glance while being appropriately sized for its simple 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?
For a tool that performs a mutation (requesting a password reset) with no annotations and no output schema, the description is incomplete. It lacks details on behavioral traits, error handling, and what happens after the request (e.g., email sent, success response). Given the complexity and lack of structured data, more context is needed for 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, with the 'email' parameter clearly documented. The description adds no additional meaning beyond what the schema provides, such as format details or usage context. Given the high schema coverage, a baseline score of 3 is appropriate, as the schema adequately handles parameter documentation.
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 ('Request a password reset email') and the target ('for a user'), which is specific and unambiguous. However, it does not explicitly differentiate from its sibling 'pb_auth_confirm_password_reset', which handles confirmation of the reset process, leaving room for slight confusion about the distinct roles.
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, such as 'pb_auth_login' for authentication or 'pb_auth_confirm_password_reset' for completing the reset. It lacks context on prerequisites, like whether the user must exist or be active, or any exclusions for usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new backup (admin only)
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Optional backup name/basename |
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 mentions 'admin only' (implying permission requirements) but fails to describe other critical traits: whether the backup is immediate or scheduled, what data it includes, potential impacts on system performance, or the response format. 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 extremely conciseāa single sentence with no wasted words. It front-loads the core action and constraint efficiently, 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 as a mutation operation with no annotations and no output schema, the description is insufficient. It omits details on what the backup entails, how it behaves, what it returns, or error conditions, leaving the agent with significant gaps in 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?
The schema description coverage is 100%, with the single parameter 'name' documented as 'Optional backup name/basename'. The description adds no additional parameter details beyond this, 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 ('Create') and resource ('new backup'), making the purpose understandable. However, it doesn't differentiate from sibling tools like 'pb_backups_list' beyond the basic verb difference, missing an opportunity to clarify scope or uniqueness.
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 includes a usage constraint ('admin only'), which provides some context, but it lacks explicit guidance on when to use this tool versus alternatives (e.g., no mention of sibling 'pb_backups_list' for viewing backups). No prerequisites or exclusions are detailed, leaving gaps in operational context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all available backups (admin only)
| 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 the full burden. It mentions 'admin only', which hints at permission requirements, but lacks details on behavioral traits such as pagination, rate limits, or what 'list all' entails (e.g., format, sorting). This leaves significant gaps in transparency for a tool with no 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 that front-loads the key information ('List all available backups') and adds a crucial constraint ('admin only') without any wasted words. It's appropriately sized for a simple 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 tool's simplicity (0 parameters, no output schema), the description is adequate but minimal. It covers the purpose and admin restriction but lacks details on output format or behavioral context, which could be helpful for an AI agent despite the low complexity. This meets the minimum viable threshold.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has 0 parameters with 100% schema description coverage, so the schema fully documents the inputs. The description doesn't need to add parameter details, and it appropriately doesn't mention any, earning a baseline score of 4 for not introducing confusion or redundancy.
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 ('all available backups'), making the purpose unambiguous. However, it doesn't differentiate from potential siblings like 'pb_backups_create' or 'pb_logs_list' beyond the admin restriction, which is a minor gap.
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 includes 'admin only', which provides some context for when to use this tool (i.e., requires admin privileges). However, it doesn't explicitly state when to use this versus alternatives like 'pb_backups_create' or 'pb_logs_list', leaving usage implied rather than fully guided.
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 (admin only)
| Name | Required | Description | Default |
|---|---|---|---|
| createRule | No | Create access rule | |
| deleteRule | No | Delete access rule | |
| listRule | No | List access rule | |
| name | Yes | Collection name (alphanumeric and underscores only) | |
| options | No | Additional collection options | |
| schema | No | Collection schema fields | |
| type | Yes | Collection type | |
| updateRule | No | Update access rule | |
| viewRule | No | View access rule |
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 mentions 'admin only' which hints at permission requirements, but doesn't describe what 'Create' entails behaviorallyāwhether it's idempotent, what happens on conflicts, rate limits, or what the response looks like. For a mutation tool with zero annotation coverage, this leaves significant gaps in understanding the tool's 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 extremely concise with just 5 words, front-loading the essential information ('Create a new collection') and adding the critical constraint ('admin only') efficiently. Every word earns its place with zero waste or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given this is a mutation tool with 9 parameters, no annotations, and no output schema, the description is insufficiently complete. It doesn't explain what 'Create' returns, how to handle the complex parameters like schema arrays or options objects, or what behavioral constraints exist beyond admin requirements. For a tool of this complexity, 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?
Schema description coverage is 100%, so the schema already documents all 9 parameters thoroughly with descriptions, patterns, enums, and types. The description adds no additional parameter information beyond what's in the schema. According to guidelines, 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 clearly states the action ('Create') and resource ('new collection'), making the purpose immediately understandable. It distinguishes from sibling tools like pb_collections_list or pb_collections_get by specifying creation rather than listing or retrieval. However, it doesn't fully differentiate from pb_collections_update, which also modifies collections.
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 some guidance with '(admin only)', indicating this tool requires administrative privileges. However, it doesn't explicitly state when to use this versus alternatives like pb_collections_update for modifying existing collections or pb_backups_create for different resource types. The usage context is implied but not comprehensive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a collection (admin only)
| Name | Required | Description | Default |
|---|---|---|---|
| idOrName | Yes | Collection ID or name 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. While 'Delete' implies a destructive operation and 'admin only' hints at permission needs, it lacks details on whether deletion is reversible, what happens to associated data, rate limits, or error conditions. For a destructive 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 extremely concise and front-loaded with essential information in just four words. Every word earns its place by specifying the action, resource, and permission requirement without any 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 destructive tool with no annotations and no output schema, the description is incomplete. It doesn't explain what 'Delete' entails (e.g., permanent vs. soft deletion), what is returned, or potential side effects, leaving significant gaps for an AI agent to understand the tool's behavior fully.
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 the parameter 'idOrName' clearly documented in the schema. The description adds no additional parameter information beyond what the schema provides, 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 ('Delete') and resource ('a collection'), making the purpose immediately understandable. However, it doesn't differentiate from sibling tools like pb_collections_get or pb_collections_update, which would require more specificity about what distinguishes this deletion operation.
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 explicit context with 'admin only', indicating when to use this tool based on permission requirements. However, it doesn't specify when to choose this over alternatives like pb_records_delete or provide exclusions for 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.
Get a specific collection by ID or name (admin only)
| Name | Required | Description | Default |
|---|---|---|---|
| idOrName | Yes | Collection ID or 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 mentions 'admin only' which is useful for permissions, but doesn't disclose other behavioral traits like whether it's read-only (implied by 'Get'), error handling, rate limits, or what happens if the ID/name doesn't exist. For a tool with zero annotation coverage, this leaves significant 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 waste. It's front-loaded with the core purpose and includes essential context ('admin only') without unnecessary details.
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 and no output schema, the description is minimal but covers the basic purpose and access control. For a simple retrieval tool with one parameter, it's adequate but lacks details on return values, error cases, or behavioral nuances that would make it more complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with the parameter 'idOrName' documented as 'Collection ID or name'. The description adds no additional meaning beyond this, such as format examples or constraints. Baseline 3 is appropriate since 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 ('Get') and resource ('a specific collection'), and specifies it can be retrieved by 'ID or name'. However, it doesn't explicitly differentiate from sibling 'pb_collections_list' which likely lists multiple collections, though the 'specific' wording implies targeting one.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context with '(admin only)', indicating it's for administrative use. It implies usage when you need a single collection rather than a list, but doesn't explicitly state when to use this vs. 'pb_collections_list' or mention prerequisites beyond admin access.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all collections (admin only)
| Name | Required | Description | Default |
|---|---|---|---|
| filter | No | Filter criteria | |
| page | No | Page number | |
| perPage | No | Items per page | |
| sort | No | Sort criteria (e.g., "name", "-created") |
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 mentions the admin-only requirement, which is valuable context about permissions. However, it doesn't describe other important behaviors: whether this is a read-only operation (implied by 'List' but not explicit), pagination behavior (though parameters suggest it), rate limits, or what the output looks like (no output schema exists). For a tool with no annotations, this leaves significant 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 extremely conciseājust four wordsāand front-loaded with the core purpose ('List all collections') followed by the critical constraint ('admin only'). There's no wasted language, and every word earns its place by providing essential information 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?
Given the tool's complexity (a list operation with 4 parameters, no output schema, and no annotations), the description is minimally adequate. It covers the purpose and admin requirement but lacks details on output format, error handling, or behavioral nuances like pagination limits. With no output schema, the description should ideally hint at return values, but it doesn't, leaving some context gaps for the 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?
The input schema has 100% description coverage, with all parameters well-documented (filter, page, perPage, sort). The description doesn't add any parameter-specific information beyond what's in the schema, such as examples of filter formats or sort options. With high schema coverage, the baseline is 3, as the description doesn't compensate but doesn't need to heavily.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List all collections') and identifies the target resource ('collections'), making the purpose unambiguous. It distinguishes itself from other collection tools (e.g., create, delete, update) by specifying it's for listing. However, it doesn't explicitly differentiate from other list tools like pb_records_list or pb_backups_list beyond the resource type.
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 includes a crucial usage constraint: 'admin only', which indicates this tool requires administrative privileges. However, it doesn't provide guidance on when to use this versus other list tools (e.g., pb_records_list for records instead of collections) or mention alternatives like pb_collections_get for a specific collection. The guidance is implied but not explicit about sibling differentiation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing collection (admin only)
| Name | Required | Description | Default |
|---|---|---|---|
| createRule | No | Create access rule | |
| deleteRule | No | Delete access rule | |
| idOrName | Yes | Collection ID or name to update | |
| listRule | No | List access rule | |
| name | No | New collection name | |
| options | No | Additional collection options | |
| schema | No | Updated collection schema fields | |
| updateRule | No | Update access rule | |
| viewRule | No | View access rule |
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 mentions the admin requirement but doesn't describe what 'update' entails - whether it's a partial or full update, what happens to unspecified fields, whether changes are reversible, or what the typical response looks like. For a mutation tool with 9 parameters and no annotation coverage, this leaves significant behavioral gaps unexplained.
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 5 words, with zero wasted language. It's front-loaded with the core action and immediately specifies the admin requirement. Every word earns its place, making this an excellent example of efficient documentation.
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 9 parameters, no annotations, and no output schema, the description is insufficiently complete. It doesn't explain what happens during an update operation, what permissions are needed beyond 'admin', what the typical response contains, or how to handle the various access rule parameters. The combination of complexity and lack of structured metadata requires more descriptive content than provided.
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%, meaning all parameters are documented in the input schema. The description doesn't add any parameter-specific information beyond what's already in the schema descriptions. It doesn't explain how parameters interact, which are optional versus required beyond the schema's indication, or provide usage examples. With complete schema coverage, 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 ('Update') and resource ('an existing collection'), making the purpose immediately understandable. It distinguishes from sibling tools like pb_collections_create and pb_collections_delete by specifying it's for updating existing collections rather than creating new ones or deleting them. However, it doesn't specify what aspects of a collection can be updated, which prevents a perfect score.
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 some usage context with '(admin only)', indicating this tool requires administrative privileges. However, it doesn't explicitly state when to use this tool versus alternatives like pb_collections_create for new collections or pb_collections_get for viewing collections. No guidance is given about prerequisites or when-not-to-use scenarios beyond the admin requirement.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a file from a record field
| Name | Required | Description | Default |
|---|---|---|---|
| collection | Yes | Collection name or ID | |
| fieldName | Yes | Field name that contains the file | |
| filename | Yes | File name to delete | |
| recordId | Yes | Record ID that owns the file |
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 is 'Delete,' which implies a destructive mutation, but doesn't specify if this is permanent, reversible, requires specific permissions, or has side effects (e.g., on related records). This is a significant gap 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 that directly states the tool's purpose without unnecessary words. It's 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?
Given the tool's complexity (a destructive mutation with 4 parameters), lack of annotations, and no output schema, the description is incomplete. It doesn't cover behavioral aspects like safety, permissions, or return values, which are critical for an AI agent to use this tool correctly in 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%, with all parameters clearly documented in the input schema (collection, fieldName, filename, recordId). The description doesn't add any additional meaning or context beyond what the schema provides, such as examples or constraints, so it meets the baseline for high schema coverage without compensating further.
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 target ('a file from a record field'), which is specific and unambiguous. However, it doesn't differentiate from sibling tools like pb_records_delete or pb_collections_delete, which handle different resource types, so it doesn't fully distinguish itself from all alternatives.
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. For example, it doesn't mention if this is for deleting individual files versus bulk operations or how it relates to pb_files_list_record_files for identifying files. The description lacks context about prerequisites or when-not-to-use scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a file access token for private files
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
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 mentions getting a token for private files but lacks details on authentication requirements, token expiration, rate limits, or what the token enables. This is inadequate for a tool that likely involves sensitive access control.
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 appropriately sized for a simple tool, 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 complexity of token-based access for private files, no annotations, and no output schema, the description is insufficient. It doesn't explain what the token is used for, how it's returned, or any security implications, leaving significant gaps for an AI agent to understand and invoke 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 input schema has 0 parameters with 100% coverage, so no parameter documentation is needed. The description doesn't add parameter details, which is acceptable here, but it could have clarified if any implicit inputs (like authentication context) are required, slightly reducing the score from a perfect 5.
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 resource ('file access token for private files'), making the purpose understandable. However, it doesn't differentiate from sibling tools like 'pb_files_get_url' or 'pb_files_list_record_files', which also involve file access, leaving some ambiguity about when to use this specific tool.
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, such as 'pb_files_get_url' for public files or 'pb_auth_login' for authentication tokens. The description implies it's for private files but doesn't specify prerequisites, contexts, or exclusions, offering minimal usage direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the URL for a file attached to a record
| Name | Required | Description | Default |
|---|---|---|---|
| collection | Yes | Collection name or ID | |
| filename | Yes | File name | |
| recordId | Yes | Record ID that owns the file | |
| thumb | No | Thumbnail size (e.g., "100x100", "0x100") |
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 does not mention whether this is a read-only operation, if it requires authentication, rate limits, or what the output format looks like. This is a significant gap for a tool that likely involves accessing resources.
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 appropriately sized and front-loaded, 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 lack of annotations and output schema, the description is incomplete. It does not address behavioral aspects like safety, authentication needs, or return values, which are crucial for an agent to use the tool correctly in context with its siblings.
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, so the schema fully documents all parameters. The description does not add any additional meaning beyond the schema, such as explaining relationships between parameters or usage examples. Baseline 3 is appropriate when the schema handles parameter documentation.
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 ('URL for a file attached to a record'), making the purpose understandable. However, it does not explicitly differentiate from sibling tools like 'pb_files_get_token' or 'pb_files_list_record_files', which also deal with files, 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, such as 'pb_files_get_token' or 'pb_files_list_record_files'. It lacks context about prerequisites or exclusions, leaving the agent to 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.
List all files attached to a record
| Name | Required | Description | Default |
|---|---|---|---|
| collection | Yes | Collection name or ID | |
| recordId | Yes | Record ID to list files for |
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 is a list operation, implying read-only behavior, but doesn't cover critical aspects like pagination, return format, error conditions, authentication requirements, or rate limits. This is inadequate for a 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 front-loaded with the core purpose and appropriately sized for a simple list operation, earning its place 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 no annotations and no output schema, the description is incomplete. It doesn't explain what the output looks like (e.g., list of file objects with metadata), behavioral traits, or error handling. For a tool with 2 required parameters and no structured support, this leaves significant gaps for 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%, with both parameters ('collection' and 'recordId') documented in the schema. The description adds no additional parameter semantics beyond implying these are needed to identify the record. Baseline 3 is appropriate since 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 ('List all files') and target resource ('attached to a record'), providing a specific verb+resource combination. However, it doesn't distinguish this tool from potential siblings like 'pb_files_get_url' or 'pb_files_upload' that also deal with files, missing explicit 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 (e.g., needing a valid record ID), exclusions, or comparisons to sibling tools like 'pb_files_get_url' for individual file access, 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.
Upload a file to a record field
| Name | Required | Description | Default |
|---|---|---|---|
| collection | Yes | Collection name or ID | |
| fieldName | Yes | Field name to store the file in | |
| fileData | Yes | Base64 encoded file data | |
| fileName | Yes | Original file name | |
| mimeType | No | File MIME type | |
| recordId | Yes | Record ID 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. It states the action is an upload, implying a write operation, but doesn't mention permissions required, rate limits, file size constraints, or what happens on success/failure. This leaves 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's appropriately sized and front-loaded, 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?
For a mutation tool with 6 parameters, no annotations, and no output schema, the description is incomplete. It doesn't cover behavioral aspects like error handling, return values, or usage constraints, leaving the agent with insufficient context to use 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 schema already documents all parameters thoroughly. The description adds no additional meaning beyond implying that 'record field' relates to parameters like collection, recordId, and fieldName, but this is redundant with 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 action ('Upload a file') and target ('to a record field'), which is specific and unambiguous. However, it doesn't differentiate from sibling tools like pb_files_list_record_files or pb_files_delete, which also deal with files but serve different purposes.
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 pb_files_list_record_files for listing files or pb_records_update for other record modifications. It lacks context about prerequisites, such as needing an existing record or specific permissions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check the health status of the PocketBase server
| 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 the full burden of behavioral disclosure. It states the action ('Check') but does not describe what the health check entails, what kind of status is returned, whether it requires authentication, or any side effects. This leaves significant gaps in understanding the tool's 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 that efficiently conveys the tool's purpose without any unnecessary words. It is front-loaded and wastes no space, making it highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (0 parameters, no output schema, no annotations), the description is adequate as a basic health check tool. However, it lacks details on what the health status includes or how to interpret results, which could be important for an agent. It meets the minimum viable standard but has clear gaps in completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has 0 parameters, and the schema description coverage is 100%, so there is no need for parameter details in the description. The baseline for such cases is 4, as the description appropriately focuses on the tool's purpose without redundant parameter information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with a specific verb ('Check') and resource ('health status of the PocketBase server'), making it immediately understandable. However, it does not explicitly differentiate from sibling tools like 'pb_server_info' or 'pb_system_test_email', which might also provide server-related information, so it falls short of a perfect score.
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 for usage, or comparisons to sibling tools such as 'pb_server_info' or 'pb_logs_stats', leaving the agent to infer usage based on the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get system logs (admin only)
| Name | Required | Description | Default |
|---|---|---|---|
| filter | No | Filter criteria (e.g., "level = 'error'") | |
| page | No | Page number | |
| perPage | No | Items per page (max 100) | |
| sort | No | Sort criteria (e.g., "-created", "level") |
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 mentions 'admin only' (a permission requirement) but lacks details on rate limits, pagination behavior beyond schema defaults, what 'system logs' includes, or error handling. For a tool with 4 parameters and no annotations, 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 extremely concise with just 4 words, front-loading the core purpose and a key constraint. Every word earns its place with zero waste, making it efficient 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 tool's complexity (4 parameters, no output schema, no annotations), the description is incomplete. It lacks details on return values, error cases, or behavioral nuances needed for effective use. The 'admin only' hint is helpful but insufficient for full contextual 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?
The schema description coverage is 100%, so the schema fully documents all parameters. The description adds no parameter-specific information beyond what's in the schema, meeting the baseline of 3 for high schema coverage without additional 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 ('Get') and resource ('system logs'), making the purpose understandable. However, it doesn't distinguish this tool from its sibling 'pb_logs_stats' which also deals with logs, 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 minimal guidance with 'admin only' indicating a permission requirement, but offers no explicit when-to-use advice, no exclusions, and no alternatives. It doesn't help an agent decide between this and 'pb_logs_stats' or other logging-related tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get log statistics (admin only)
| Name | Required | Description | Default |
|---|---|---|---|
| filter | No | Filter criteria for stats |
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 mentions 'admin only', which implies permission requirements, but doesn't cover other traits such as whether this is a read-only operation, potential rate limits, what the output format looks like, or any side effects. For a tool with no 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 ('Get log statistics (admin only)') that is front-loaded with the core purpose and includes essential context. There is no wasted verbiage, and every word earns its place, making it highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (admin tool with 1 parameter) and lack of annotations and output schema, the description is incomplete. It doesn't explain what statistics are returned, how the filter works, or any behavioral details. For a tool with no structured output and minimal input guidance, it should do more to compensate for these gaps.
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 1 parameter with 100% description coverage ('Filter criteria for stats'), so the schema already documents the parameter. The description doesn't add any meaning beyond this, such as examples of filter syntax or what criteria are supported. With high schema coverage, the baseline is 3, as the description doesn't compensate but doesn't detract either.
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 'Get log statistics' states a verb ('Get') and resource ('log statistics'), which provides a basic purpose. However, it lacks specificity about what kind of statistics (e.g., counts, summaries, trends) and doesn't distinguish from sibling tools like 'pb_logs_list', which might retrieve raw logs instead of aggregated data. This makes it vague but not tautological.
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 includes 'admin only', which clearly indicates the required context (administrative privileges) for using this tool. However, it doesn't specify when to use this tool versus alternatives like 'pb_logs_list' or other admin tools, nor does it mention any exclusions or prerequisites beyond admin access. This provides clear context but lacks explicit guidance on alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create multiple records in a collection at once
| Name | Required | Description | Default |
|---|---|---|---|
| collection | Yes | Collection name or ID | |
| records | Yes | Array of record data objects to create |
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' implies a write operation, the description doesn't address permissions required, whether this is atomic/all-or-nothing, rate limits, or what happens on partial failures. It provides minimal behavioral context 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 extremely concise at just 7 words, front-loading the core functionality with zero wasted words. Every element ('Create multiple records', 'in a collection', 'at once') contributes essential information about the tool's 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?
For a write operation with no annotations and no output schema, the description is insufficient. It doesn't explain what the tool returns, error conditions, or important behavioral aspects like whether records are created transactionally. The presence of a clear sibling tool ('pb_records_create') makes the lack of differentiation particularly problematic.
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 both parameters thoroughly. The description adds no additional parameter semantics beyond what's in the schema - it doesn't explain record format expectations, validation rules, or collection naming conventions.
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 multiple records') and target resource ('in a collection at once'), providing a specific verb+resource combination. However, it doesn't distinguish this bulk operation from the sibling 'pb_records_create' tool, which appears to be a single-record creation alternative.
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 the sibling 'pb_records_create' tool for single-record creation, nor any context about batch size limits, performance considerations, or error handling for bulk 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 or ID | |
| data | Yes | Record data to create | |
| expand | No | Relations to expand in response | |
| fields | No | Fields to return in response |
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 it's a creation operation, implying mutation, but doesn't cover critical aspects like required permissions, whether it's idempotent, rate limits, error handling, or what the response looks like (e.g., success/failure indicators). This leaves significant gaps for an agent to understand how to use it safely and effectively.
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 and resource, 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 complexity of a creation tool with no annotations and no output schema, the description is insufficient. It doesn't explain behavioral traits (e.g., side effects, authentication needs), response format, or error conditions, leaving the agent with incomplete information to invoke the tool correctly in a real-world context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters (collection, data, expand, fields) with clear descriptions. The description adds no additional semantic context beyond implying 'data' is used for creation, which is already evident from 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 clearly states the action ('Create a new record') and target resource ('in a collection'), which is specific and unambiguous. However, it doesn't differentiate from sibling tools like pb_records_bulk_create or pb_collections_create, which would require mentioning it's for single-record creation versus bulk operations or collection-level 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. It doesn't mention sibling tools like pb_records_bulk_create for multiple records or pb_collections_create for creating collections themselves, nor does it specify prerequisites such as needing an existing collection or authentication context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a record from a collection
| Name | Required | Description | Default |
|---|---|---|---|
| collection | Yes | Collection name or ID | |
| id | Yes | Record 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. While 'Delete' implies a destructive mutation, the description does not specify whether this action is irreversible, what permissions are required, or how errors are handled. It misses critical details like confirmation prompts or effects on related data, which are essential for safe tool 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 wasted words, efficiently conveying the core action and target. It is front-loaded and easy to parse, making it highly effective for quick comprehension 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 tool's destructive nature and lack of annotations or output schema, the description is insufficiently complete. It does not address behavioral risks, error handling, or return values, leaving gaps that could lead to incorrect or unsafe usage by an AI agent in a real-world 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 input schema has 100% description coverage, clearly documenting both parameters ('collection' and 'id') with their types and requirements. The description adds no additional semantic context beyond what the schema provides, such as examples or constraints on valid values, so it meets the baseline for adequate but not enhanced parameter understanding.
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 target ('a record from a collection'), making the purpose immediately understandable. However, it does not differentiate from sibling tools like pb_records_update or pb_collections_delete, which handle related but distinct operations on records or collections.
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, such as pb_records_update for modifying records or pb_collections_delete for deleting entire collections. It lacks context about prerequisites, permissions, or typical use cases, leaving the agent to 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 a specific record by ID from a collection
| Name | Required | Description | Default |
|---|---|---|---|
| collection | Yes | Collection name or ID | |
| expand | No | Relations to expand (e.g., "author,category") | |
| fields | No | Fields to return (e.g., "id,title,created") | |
| 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 full burden but lacks behavioral details. It doesn't specify if this is a read-only operation, what permissions are required, error handling, or response format, which are critical for a tool that fetches data by ID.
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 wasted words, front-loading the core action and resource. It's appropriately sized for a simple retrieval tool, 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 no annotations and no output schema, the description is incomplete. It doesn't cover behavioral aspects like safety, permissions, or return values, which are essential for a tool that interacts with a database or API, leaving gaps in 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 parameters are well-documented in the schema. The description adds minimal value by implying 'ID' and 'collection' are key inputs but doesn't explain semantics beyond what the schema already provides, 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 clearly states the action ('Get') and resource ('a specific record by ID from a collection'), making the purpose understandable. However, it doesn't differentiate from sibling tools like pb_records_list (which lists multiple records) or pb_collections_get (which gets collection metadata), missing explicit 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?
No guidance is provided on when to use this tool versus alternatives. For example, it doesn't mention using pb_records_list for multiple records or pb_collections_get for collection details, 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.
List records from a collection with optional filtering and pagination
| Name | Required | Description | Default |
|---|---|---|---|
| collection | Yes | Collection name or ID | |
| expand | No | Relations to expand (e.g., "author,category") | |
| fields | No | Fields to return (e.g., "id,title,created") | |
| filter | No | Filter criteria (e.g., "status = true") | |
| page | No | Page number | |
| perPage | No | Items per page | |
| sort | No | Sort criteria (e.g., "created", "-updated", "title") |
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 mentions 'optional filtering and pagination' which hints at list behavior, but fails to disclose critical details like authentication requirements, rate limits, error conditions, or what the output looks like (e.g., JSON array with metadata). For a read operation with 7 parameters, 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 that front-loads the core purpose ('List records from a collection') and adds key capabilities ('with optional filtering and pagination'). Every word earns its place with zero redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (7 parameters, no output schema, no annotations), the description is insufficient. It doesn't explain the return format, error handling, or authentication needs. While the schema covers parameters well, the lack of behavioral context and output information makes this incomplete for an AI agent to use confidently.
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 all parameters are documented in the schema itself. The description adds no specific parameter semantics beyond implying filtering and pagination capabilities, which are already covered by the 'filter', 'page', and 'perPage' parameters in the schema. Baseline 3 is appropriate when 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 ('List') and resource ('records from a collection'), making the purpose immediately understandable. It distinguishes this as a read operation from siblings like pb_records_create or pb_records_delete, though it doesn't explicitly contrast with pb_records_get (which likely retrieves a single 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 mentions 'optional filtering and pagination' which implies usage for retrieving multiple records, but provides no explicit guidance on when to use this tool versus alternatives like pb_records_get (for single records) or pb_collections_list (for collections themselves). No prerequisites or exclusions are 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 collection
| Name | Required | Description | Default |
|---|---|---|---|
| collection | Yes | Collection name or ID | |
| data | Yes | Record data to update | |
| expand | No | Relations to expand in response | |
| fields | No | Fields to return in response | |
| id | Yes | Record ID to update |
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 this is an update operation, implying mutation, but doesn't cover critical aspects like required permissions, whether changes are reversible, error handling, or rate limits. For a mutation tool with zero annotation coverage, this leaves significant gaps in understanding its 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, efficient sentence that directly states the tool's purpose without unnecessary words. It's appropriately sized and front-loaded, with every word contributing to clarity. No fluff or redundancy is present.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given this is a mutation tool with no annotations and no output schema, the description is insufficient. It doesn't explain what happens on success/failure, return values, or side effects. The agent lacks context about how this tool behaves in practice, making it incomplete 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 5 parameters. The description adds no parameter-specific information beyond what's in the schema (e.g., it doesn't clarify data format, expand syntax, or field selection). This meets the baseline for high schema coverage but doesn't enhance understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Update') and resource ('an existing record in a collection'), making the purpose immediately understandable. It distinguishes this as an update operation rather than creation or deletion, though it doesn't explicitly differentiate from sibling tools like pb_records_create or pb_records_delete beyond the basic verb.
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), compare to similar tools like pb_records_create or pb_records_bulk_create, or specify use cases. 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.
Get PocketBase server information and configuration
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
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 tool retrieves information, implying a read-only operation, but doesn't specify authentication requirements, rate limits, or what specific data is returned (e.g., version, config details). This is inadequate for a 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 that directly states the tool's function without any wasted words. It's front-loaded and appropriately sized for a simple, parameter-less tool, earning a top score for 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 tool's simplicity (0 parameters, no output schema, no annotations), the description is minimally adequate but lacks depth. It doesn't explain what 'server information and configuration' includes or how it differs from sibling tools, leaving gaps in contextual understanding despite the low complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has 0 parameters, and schema description coverage is 100%, so there's no need for parameter details in the description. The baseline for this scenario is 4, as the description appropriately avoids redundant information while clearly indicating the tool's purpose without parameter confusion.
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 resource ('PocketBase server information and configuration'), making the tool's purpose understandable. However, it doesn't differentiate from sibling tools like pb_admin_get_settings or pb_health_check, which also retrieve server-related data, so it falls short of a perfect score.
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 such as pb_admin_get_settings (for admin settings) or pb_health_check (for server health status). There's no mention of prerequisites, context, or exclusions, leaving usage unclear relative to siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Send a test email (admin only)
| Name | Required | Description | Default |
|---|---|---|---|
| Yes | Email address to send test email to | ||
| template | Yes | Email template to test |
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 mentions the admin restriction, it doesn't describe what 'send a test email' actually does - whether it triggers a real email, what content it contains, whether it's rate-limited, what happens on success/failure, or what the response looks like. For a 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 extremely concise at just 5 words, with zero wasted language. It's front-loaded with the core action and immediately follows with the critical admin restriction. Every word serves a clear purpose 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 tool with no annotations and no output schema, the description is insufficiently complete. It doesn't explain what 'test email' means operationally, what the expected outcome is, or provide any behavioral context beyond the admin restriction. For a tool that presumably sends actual emails, more context about the operation would be 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 schema description coverage is 100%, with both parameters well-documented in the schema itself. The description doesn't add any parameter-specific information beyond what's already in the schema (email address and template selection). This meets the baseline expectation when schema coverage is complete.
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 ('send a test email') and resource ('email'), making the purpose immediately understandable. However, it doesn't differentiate this tool from potential siblings like 'pb_auth_request_password_reset' or other email-related tools, which would require explicit comparison to achieve a score of 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context with '(admin only)', indicating this is restricted to administrative users. This helps the agent understand when it's appropriate to use this tool versus general user tools. However, it doesn't explicitly mention when NOT to use it or name specific alternatives among the sibling tools.
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. Dates show when Glama detected each change.
v1.0.0pb_admin_create_userpb_admin_delete_userpb_admin_get_settingspb_admin_impersonate_userpb_admin_list_userspb_admin_loginpb_admin_update_settingspb_admin_update_userpb_auth_confirm_password_resetpb_auth_get_userpb_auth_loginpb_auth_logoutpb_auth_refreshpb_auth_registerpb_auth_request_password_resetpb_backups_createpb_backups_listpb_collections_createpb_collections_deletepb_collections_getpb_collections_listpb_collections_updatepb_files_deletepb_files_get_tokenpb_files_get_urlpb_files_list_record_filespb_files_uploadpb_health_checkpb_logs_listpb_logs_statspb_records_bulk_createpb_records_createpb_records_deletepb_records_getpb_records_listpb_records_updatepb_server_infopb_system_test_emailEvery tool has a clearly distinct purpose with no ambiguity. The tools are organized by resource type (admin, auth, backups, collections, files, health, logs, records, server, system) and action (create, delete, get, list, update, etc.), making it easy to distinguish between them. For example, pb_records_create and pb_records_update are clearly different operations on the same resource.
The naming follows a highly consistent pattern throughout: all tools use a prefix 'pb_' followed by a resource category (e.g., admin, auth, collections), an underscore, and a verb_noun combination (e.g., create_user, get_settings, list_records). This snake_case convention is applied uniformly across all 38 tools, making them predictable and easy to parse.
With 38 tools, the count is borderline high for a typical MCP server, which might feel heavy and overwhelming for agents. However, given PocketBase's comprehensive scope (covering admin, authentication, backups, collections, files, logs, records, and system operations), the number is somewhat justified, but it could benefit from consolidation or better scoping to reduce complexity.
The tool set provides complete CRUD/lifecycle coverage for the PocketBase domain, with no obvious gaps. It includes operations for user management, authentication, backups, collections, files, health checks, logs, records, server info, and system tests, ensuring agents can handle all core workflows without dead ends. For example, records have create, get, list, update, delete, and bulk create tools.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yoā¦
Model Context Protocol server for the Apideck Unified API. Connect any MCP-compatible agent framework to 100+ accounting systems, HRIS platforms, file storage providers, and more through one integration. More information https://www.apideck.com/mcp-server
MCP server for interacting with the Supabase platform
A Model Context Protocol (MCP) server for Selise Blocks Cloud integration
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/paullippert/pb_mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
