pocketbase-mcp

Server Quality Checklist

Profile completionA complete profile improves this server's visibility in search results.

Latest release: v1.0.0
Disambiguation4/5
Most tools pair a clear action with a distinct resource, and even similar prefixes like request_/confirm_ target clearly different auth workflows. The main ambiguity is between list_records, get_full_record_list, and get_first_record, which all retrieve records and differ only in pagination or convenience.
Naming Consistency4/5
The API is overwhelmingly consistent verb_noun snake_case, following list_, get_, create_, update_, delete_, request_, and confirm_ patterns. A few outliers like health_check, batch, auth_info, and impersonate break the pattern, but they are minor deviations in an otherwise coherent naming scheme.
Tool Count1/5
At 55 tools, this is an extremely large MCP surface for an agent to reason over, crossing the threshold where tool selection becomes a burden. Even though PocketBase is broad, this would be better split into focused servers for records, admin/settings, backups/logs, and auth.
Completeness5/5
The tool set covers collections, records, auth, superusers, settings, logs, backups, cron, and file handling with full CRUD and lifecycle coverage. The send_raw_request escape hatch also eliminates dead ends for any PocketBase endpoint not otherwise exposed.
Average 4.1/5 across 55 of 55 tools scored. Lowest: 3.4/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 4 commits in the last 12 weeks
- Last stable release on July 14, 2026
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is failing
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.

To manually sync the server, click the "Sync Server" button in the MCP server admin interface.

How is the quality score calculated?

The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).

Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.

Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).

Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.

Tool Scores

Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It only says it 'generates' a secret and requires superuser, but does not state whether the secret is returned, persisted, rotated, or revoked, nor any security side effects such as logging or expiration of previous secrets. This is a significant gap for a security-sensitive operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences with no filler. The action and resource are front-loaded, and the superuser restriction is a valuable qualifier. Every word contributes to the meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description should clarify what the tool returns and any side effects. It does not explain whether the generated secret is returned in the response, saved somewhere, or if it invalidates existing secrets. For a secret-generating tool, this missing information leaves an agent uncertain about how to use the output.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with all five parameters already meaningfully described. The description adds only high-level context about using 'Apple developer credentials' and does not improve per-parameter understanding, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Generate', the resource 'Apple OAuth2 client secret (JWT)', and the source 'Apple developer credentials'. It distinguishes itself from generic secret tools by specifying OAuth2 and JWT, and no sibling tool has the same function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description indicates a usage constraint ('Superuser only') but does not explicitly say when to use this tool versus alternatives, when not to use it, or what prerequisites are needed beyond credentials. The implied context is clear, but explicit guidance is missing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral transparency burden, but it only adds 'Superuser only.' It does not disclose whether the operation has side effects, what it returns, or how failures are reported.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence with the action and resource front-loaded, and the access restriction tacked on at the end. Every word earns its place; no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter tool, the description covers the core call essentials: what operation, which targets, and who may call it. However, with no annotations or output schema, it leaves the return behavior and failure semantics implied rather than stated.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already documents the single enum parameter and its default with 100% coverage. The description re-states the two filesystem options without adding new semantic detail, so the baseline score applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific action ('perform connection test'), the target resource ('S3 filesystem'), and the allowed scope ('storage' or 'backups'). This clearly distinguishes it from sibling tools like test_email.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no explicit when-to-use guidance or alternatives, though the S3-specific wording makes the context fairly clear. The superuser restriction is useful but does not explain when this tool should be chosen over others.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description must disclose behavior itself. It does specify the output scope (whether password/OTP auth is enabled and which OAuth2 providers are configured), which clarifies the read-only, config-inspection nature. However, it does not mention whether the operation is read-only, requires authentication, or what the exact response structure will be, leaving some burden unmet.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that front-loads the action ('List the available authentication methods') and then specifies the exact contents after a colon. Every clause contributes meaning and there is no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter, read-style list tool with no output schema, the description is largely complete: it names the resource, the parameter, and the returned content. It would be slightly stronger if it explicitly stated that it reads global collection auth settings rather than per-user external auths (a potential sibling overlap), but the current wording is sufficient for most agents to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter, 'collection', is already fully described in the schema as 'Auth collection (default 'users').' The description adds only the phrase 'for an auth collection,' which does not go beyond the schema. With 100% schema coverage, the baseline of 3 applies; the description provides no extra parameter-level detail.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'List' with a concrete resource ('authentication methods for an auth collection') and enumerates exactly what is included (password/OTP enabled status, OAuth2 providers). This distinguishes it from sibling tools like auth_with_password or auth_with_otp, which perform authentication actions rather than list configuration. No ambiguity remains about what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to choose this tool over siblings such as auth_info or list_external_auths. There are no exclusions, prerequisites, or alternative recommendations. The intended use is only implied by the name and purpose, so an agent must infer when this is the right call.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description bears full responsibility for behavioral clarity. It merely says 'Complete OTP authentication' but does not disclose what happens on success or failure, whether a session/token is created, if there are side effects, or any rate limiting/retry behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence that clearly communicates the core action and the origin of both required parameters. No fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is sufficient for basic invocation since it names the required parameters and their source. However, with no output schema and no annotations, it omits the result of the authentication (e.g., token, session) and does not mention failure modes or the optional collection behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters. The description adds minimal extra meaning beyond repeating 'otpId from request_otp' and 'code the user received', which are already in the schema. The optional collection parameter is not referenced.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Complete OTP authentication') and identifies the specific resources involved: otpId from request_otp and the user-received code. This distinguishes it from sibling tools like request_otp and auth_with_password.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage as the second step after request_otp by explicitly referencing 'otpId (from request_otp)'. However, it does not explicitly state when not to use this tool or compare it directly with auth_with_password or other auth methods.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description carries the full burden of behavioral disclosure. It indicates a state-changing action ('Set a new password') but does not disclose whether the token is single-use, whether authentication is required, whether the reset token becomes invalid, or how password conflicts are handled. This is a meaningful gap for a security-sensitive 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler. It communicates the action, the object, and the key prerequisite without wasting tokens.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple enough that the description plus fully documented parameters are minimally viable for calling it. However, with no annotations and no output schema, important behavioral context such as token consumption, auth requirements, and response shape is missing, making this adequate but not complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the parameter names and descriptions already document token, password, passwordConfirm, and collection. The description adds modest context by saying the token comes from the password reset email, but it does not add meaning beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Set a new password') with a specific resource and prerequisite ('using the reset token from the password reset email'). This clearly distinguishes it from sibling tools like request_password_reset, which would start the flow rather than complete it.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly places the tool in the password-reset flow: it is used after the user has received a reset token by email. It does not explicitly name alternatives or state when not to use it, but the usage context is strong enough for an agent to choose this over request_password_reset or confirm_verification.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of behavior disclosure. It adds a valuable behavioral fact: the tool includes internal system collections like _superusers and _authOrigins, which could surprise users. However, it does not mention that it is read-only, does not describe response shape, and omits potential performance or permission considerations, leaving gaps 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is four compact sentences with no filler. It front-loads the core action and scope, then adds the key system-collections behavior and two parameter examples, each earning its place. It is succinct yet informative.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description and schema together explain parameters and basic behavior well, but there is no output schema and the description does not state what the tool returns (e.g., a paginated list of collection objects). It also does not mention sibling tools or when to use a more specific alternative, leaving some contextual gaps for an agent deciding how to call it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 five parameters. The description adds concrete examples for filter and sort (e.g., 'type = "auth"' and '-created'), which slightly enriches understanding but does not substantially go beyond the schema's descriptions. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb ('List') and resource ('collections'), further clarifying them as 'database tables / schemas'. It explicitly notes that system collections are included, which distinguishes it from narrower list tools like list_superusers and from single-collection getters like get_collection.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for paginated, filterable, and sortable collection listing, but it does not explicitly state when to prefer this tool over alternatives such as get_collection or get_collection_scaffolds. It provides useful filter and sort examples, but no exclusion criteria or direct sibling comparisons, leaving selection somewhat to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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 adds a meaningful behavioral detail: the new superuser gets full administrative access. However, it does not disclose side effects like email uniqueness, verification requirements, or reversibility.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with no filler. The action, resource, and key consequence are front-loaded, and every sentence contributes real information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core purpose and the principal side effect (full admin access), which is sufficient for a simple creation tool. Minor gaps like duplicate email handling or confirmation flow are not addressed, but the schema covers parameter details and no output schema needs explanation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with each parameter already documented (email, password with minLength, passwordConfirm with default). The description only repeats that email and password are required, adding no new semantic details beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Create') and resource ('superuser (admin) account'), and adds that the account has full administrative access. This clearly distinguishes it from siblings like list_superusers, update_superuser, and delete_superuser.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use it (when creating a new superuser), but it does not explicitly mention alternatives, exclusions, or any prerequisites such as existing admin authentication. Usage context is mostly derived from the verb and resource.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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 plainly states the destructive action and adds a meaningful safety constraint, but it does not mention irreversibility, permission requirements, or what happens if the last superuser is targeted.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short, front-loaded clauses with no wasted words. It communicates the action, target, identification method, and an important constraint efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter delete operation with no output schema, the description is largely complete: it names the action, the target, how to identify it, and a key business rule. It could optionally note irreversibility or failure behavior, but the essential information is present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already fully documents the single required 'id' parameter with 100% coverage. The description's phrase 'by id' aligns with the schema but adds no substantive new meaning beyond what is already present.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Delete a superuser (admin) account by id.' It clearly distinguishes itself from the sibling superuser tools, which create, update, or list superusers rather than deleting them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies its use for removing a superuser account and provides an important guardrail: 'At least one superuser must always remain.' However, it does not explicitly state when to prefer this tool over alternatives like update_superuser, nor does it describe any prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description carries the full behavioral disclosure burden. It does disclose the superuser-only restriction and that a fresh superuser file token is used, which adds meaningful context. It does not mention whether the URL expires, whether a new token is generated as a side effect, or what failure modes exist, so transparency is partial rather than complete.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is only two short sentences. The first sentence states the operation and mechanism, and the second adds the essential authorization constraint. There is no redundant or filler content; every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter tool with no output schema and no annotations, the description is reasonably complete: it identifies the resource, the return concept, the token mechanism, and the authorization requirement. It could still mention URL expiration or how the fresh token is obtained, but those details are not necessary for basic correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully documents the only parameter, key, as 'Backup file key/name.' Since schema description coverage is 100%, the baseline is 3. The description does not add extra meaning about the key parameter beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'Build a download URL for a backup file.' This clearly differentiates the tool from siblings like download_backup, which implies direct file retrieval, and get_file_token, which presumably returns a token rather than a URL. It also states the key security constraint upfront.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'Superuser only' gives a clear access condition, and 'Build a download URL' implies the right use case: when an agent needs a URL rather than the file content itself. However, it does not explicitly mention when to prefer this over sibling tools such as download_backup or get_file_token, leaving some selection inference to the agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must convey behavior, and it does indicate a read-like fetch operation and the returned content ('full field schema, rules and indexes'). However, it does not disclose response shape, error behavior, authentication needs, or any side effects, so behavioral transparency is limited.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single clear sentence with the action and resource front-loaded. It contains no filler, redundant wording, or unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter tool with 100% schema coverage, the description covers the core purpose, selection criteria, and returned content. It lacks explicit return format or error-case guidance, but the tool's low complexity makes this a minor gap rather than a critical one.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already fully documents both parameters: idOrName and fields with descriptions. The description adds context about default returned contents but does not add new meaning beyond the schema, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Fetch'), a clear resource ('a single collection'), and a precise selection method ('by its id or name'). It also states the key contents that will be returned ('full field schema, rules and indexes'). This distinguishes it from siblings like list_collections and get_record.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool: when you need a single collection's full definition by id or name. However, it does not explicitly mention alternatives such as list_collections for listing all collections or when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. 'Fetch' signals a read operation, and the explicit '(superuser only)' requirement is valuable. However, it does not mention error behavior, response shape, or whether the entry may contain sensitive data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no filler. It front-loads the core action, object, lookup key, and access restriction in minimal, precise wording.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter fetch operation, the description covers the essential information: what to fetch, how to identify it, and the access restriction. It does not need an output schema or elaborate return documentation; the only minor gap is absence of guidance about alternatives or error cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the description essentially restates the id parameter's purpose ('by its id') without adding format, source, or usage details. Since the schema fully documents the parameter, the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb ('Fetch'), a specific resource ('single log entry'), and the lookup key ('by its id'). This clearly distinguishes it from sibling tools like list_logs and get_logs_stats.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool: when you need one log entry by ID, and it notes the superuser requirement. However, it does not explicitly contrast it with list_logs or get_logs_stats, so an agent must infer the boundary between single-entry and list/stats operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden of behavioral disclosure. 'Fetch' clearly indicates a read operation, and it mentions expand/select capabilities, but it does not disclose error behavior, return format, auth requirements, or what happens when the id is not found. Adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, well-structured sentence that front-loads the core operation ('Fetch a single record by id') and places optional capabilities at the end. There is no filler or redundant phrasing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read tool, the description captures the essential semantics and the schema fully documents parameters. However, with no annotations and no output schema, some additional detail about return behavior or failure cases would make it more complete. Still, an agent can correctly select and invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and all four parameters already have meaningful descriptions. The description's mention of expanding relations and selecting fields mirrors the expand and fields parameters without adding new detail, so it meets the baseline but does not exceed it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Fetch'), a clear resource ('a single record'), and identifies the key differentiators: by id, with optional relation expansion and field selection. This makes it easy to distinguish from sibling tools like list_records, get_full_record_list, and get_first_record.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this tool is for when you know a record's id and want a single record, but it does not explicitly state when to use it over alternatives like get_first_record or list_records. No exclusion criteria or alternative routing is provided, so usage guidance is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the full burden. It discloses filter operators, expand behavior, and the skipTotal performance trade-off, but does not mention the response envelope, authentication needs, or error behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The core purpose is front-loaded in the first sentence, with each following sentence adding concrete, non-redundant examples. It is compact without being terse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read tool with 8 parameters and no output schema, the description covers query mechanics well but omits the return shape and any guidance about when to prefer sibling listing tools. This leaves some ambiguity for an agent deciding how to handle the response.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds real value beyond the schema by showing exact filter expression syntax, operators, expand syntax, and the skipTotal optimization rationale.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('List records of a collection') and names the key capabilities: pagination, filtering, sorting, and relation expansion. This clearly distinguishes it from single-record siblings like get_record or get_first_record.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides practical usage tips (expand syntax, skipTotal for performance), which implies when the tool is useful. However, it never explicitly contrasts with alternatives like get_full_record_list or get_record, nor says when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the behavioral disclosure burden. The word 'List' clearly implies a read-only operation, and 'built-in _superusers collection' adds useful context, but the description does not disclose return format, pagination behavior, or any access requirements beyond what the schema already implies.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single focused sentence with no filler. It front-loads the action and target, then adds the useful source-collection detail, making it easy to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple paginated-list tool with no output schema, the description conveys enough to invoke it correctly: the action, the resource, and the source collection. It does not enumerate return fields, but 'List superuser accounts' reasonably implies the response contains those accounts.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already documents all four parameters with meaningful descriptions (page, sort, filter, perPage), achieving 100% schema description coverage. The tool description adds no additional parameter semantics, so the baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a precise verb ('List') and resource ('superuser (admin) accounts'), and clarifies the data source ('built-in _superusers collection'). This distinguishes it from sibling tools like create_superuser, update_superuser, delete_superuser, and list_external_auths.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied: the agent can infer that this tool should be used when superuser accounts need to be listed. However, there is no explicit guidance about when not to use it or which sibling tool to use for related operations such as creating or updating superusers.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It makes clear that this is a destructive/privileged operation ('Remove', 'superuser only'), but it does not mention side effects such as whether the provider-specific login is immediately revoked, whether it is reversible, or what the response is.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that leads with the action and immediately states the access constraint. No redundant wording or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple three-parameter tool with full schema coverage, the description provides enough to select and invoke it: the action, target object, and required privilege. The lack of output schema or response details is a minor gap, but not necessary for a straightforward unlink operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 provider, recordId, and collection. The description adds domain context by framing it as OAuth2 against a user record, but it does not elaborate on parameter syntax or defaults beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description states a specific verb ('Remove') and resource ('a linked OAuth2 provider from a user record'), and sets the scope with 'superuser only'. This clearly differentiates it from list_external_auths and other auth-related sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for removing OAuth2 links and imposes a superuser precondition, but it does not explicitly state when to prefer this over related tools such as list_external_auths, or when unlink should not be used.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of explaining behavior. It states the core action but does not disclose token expiration/single-use behavior, error handling, or what happens on invalid tokens. Basic transparency is present, but richer detail is absent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence with no wasted words. It is front-loaded with the action and includes the essential usage context in a compact form.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a simple tool with a complete schema, so the description is minimally viable. However, without annotations or an output schema, an agent still has to guess about success/failure behavior and token validity constraints.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already documents both parameters with 100% coverage. The description adds minimal value by noting the token comes from the verification email, but it does not clarify the 'collection' parameter's behavior or default.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Confirm') and resource ('a user's email verification'), and clarifies the token comes from the verification email. This clearly distinguishes it from sibling tools like confirm_password_reset or confirm_email_change.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The context is clear: this tool is used when a user has a token from a verification email. However, it does not explicitly name alternatives or state when not to use it, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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 discloses irreversibility ('Cannot be undone') and an access restriction ('Superuser only'), which are critical behavioral traits for a destructive operation. This goes beyond simple 'deletes' and prepares the agent for the consequence.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description consists of three short distinct sentences: action, warning, and permission. Every sentence carries unique, necessary information with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter destructive tool with full schema coverage and no output schema, the description covers the action, parameter identification, irreversibility, and access control. It could mention error behavior or whether the backup is permanently removed from storage, but nothing essential for correct invocation is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides 100% coverage for the single 'key' parameter, including the source ('as returned by list_backups'). The description's phrase 'by its key/name' adds no new semantic information beyond the schema, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Delete'), a clear resource ('backup file'), and a precise scope ('single... by its key/name'). This distinguishes it from sibling backup tools like list_backups, restore_backup, and get_backup_download_url, and from deletion tools for other resources.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied rather than explicit: the verb and resource make it clear this tool removes backups, but the description does not name alternatives or state when not to use it. 'Superuser only' provides an access condition but no comparative routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of disclosing behavior. It explicitly states the operation is permanent and cannot be undone, which is the most critical behavioral trait. It does not mention permissions, error behavior, or cascading effects, but for a simple record delete the irreversibility warning is strong.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with zero filler. The essential action and the critical warning are front-loaded, and every word contributes meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple, with two documented parameters and no nested objects. The description covers the core semantics and the irreversible destructive nature. It does not describe return values or error handling, but for a straightforward delete operation this is not a major gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both id and collection clearly documented in the schema. The description adds only 'by id', which aligns with the schema and does not introduce misleading or extra meaning. Baseline 3 is appropriate because the schema already carries the parameter documentation burden.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Permanently delete'), the resource ('a single record'), and the key identifier ('by id'). It is unambiguous and distinct from sibling deletion tools such as delete_collection or delete_backup.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'single record by id' implies when to use it, but there is no explicit guidance about alternatives, such as using truncate_collection for bulk deletion or delete_collection for whole collections. The usage context is implied rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the behavioral disclosure burden. It usefully states that the operation writes to the server-local filesystem and requires superuser privileges. However, it does not disclose potential side effects such as overwriting an existing file, whether intermediate directories are created, or what happens when the backup key does not exist.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tightly worded sentences, zero filler, with the core action and destination front-loaded before the permission constraint. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter tool with no output schema, the description covers purpose, destination, and access control. It could go further by mentioning error conditions or behavior when the file exists, but these are minor for a straightforward download operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%: both 'key' and 'destPath' have descriptive schema text. The description adds only a small clarification that destPath should be a '.zip' location, which the schema also mentions. With full schema coverage, the description does not need to compensate significantly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Download') and resource ('a backup file'), clearly distinguishing it from sibling tools like get_backup_download_url (which likely returns a URL) and upload_backup. It also specifies the destination ('local path on the machine running this MCP server'), making the scope unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear context: downloading backup files to a local filesystem path, and adds an explicit permission constraint ('Superuser only'). It does not explicitly name alternatives or when to prefer this over get_backup_download_url or download_file, but the sibling list and tool name make the intended use reasonably clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It does disclose an important constraint ('superuser only') and the targeted resource, but it does not describe return shape or error behavior. For a simple read-only list tool, this is acceptable but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence conveys the action, target, and access restriction without wasted words. The scope is front-loaded and the permission qualifier is placed clearly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter list tool, the description provides enough context to invoke it correctly: what it lists, for whom, and who may use it. The absence of an output schema is mitigated by the obvious meaning of 'List', though a bit more detail on the returned data would make it fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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. The description adds no extra parameter-level meaning, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description uses a specific verb ('List') and a precise resource ('OAuth2 providers linked to a specific user record'), which clearly distinguishes it from sibling tools like unlink_external_auth and list_auth_methods. The 'superuser only' qualifier adds a useful access scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context: use this to list external OAuth providers for a specific user, and only as a superuser. It does not explicitly name alternatives or exclusions, but its scope is clear enough to guide selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It discloses the key side effect (sends an email) and the prerequisite configuration, but it does not mention OTP expiration, rate limits, failure modes, or what happens if the email is invalid. This is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence delivers the action, output, and prerequisite without wasted words. The most important information is front-loaded, and the prerequisite is neatly parenthesized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter tool with no output schema, the description is largely sufficient: it explains what happens, what is returned, and what must be enabled. Minor gaps around OTP expiry and error behavior prevent a perfect score, but nothing critical is missing for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 adequately. The description adds no additional semantic detail beyond what the schema provides, meriting the baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Send'), a concrete resource ('one-time password email to a user'), and a clear output ('return the otpId needed to complete auth_with_otp'). It also implies differentiation from the sibling auth_with_otp by framing this as the initiation step rather than the completion step.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly indicates that this tool is the prerequisite for auth_with_otp and notes the required configuration ('requires SMTP and OTP auth enabled'). It does not explicitly mention when not to use it or compare it to alternatives like request_verification or request_password_reset, but the OTP-specific context is reasonably clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations present, the description carries the full burden and adequately discloses the side effect (sending an email) and an important operational requirement (SMTP configured). It does not detail behaviors like idempotency, rate limits, or what happens if the user is already verified, but the core action is clearly communicated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that states the action, target, and a critical prerequisite without any filler. Every word earns its place, and the key requirement (SMTP) is included up front.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter tool with a fully documented schema, the description is complete enough for selection and invocation: it explains what happens, to whom, and what must be configured. The lack of explicit return-value information is a minor omission given the absence of an output schema, but it does not block correct use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already documents both parameters with 100% coverage, so the baseline is 3. The description does not add parameter-level detail beyond the schema; it only reinforces the general context of sending to a user's email in an auth collection.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('send a verification email') and the target ('a user of an auth collection'), making the tool's purpose immediately understandable. It does not explicitly name sibling tools, but the specific 'verification email' resource distinguishes it from related tools like confirm_verification or request_password_reset.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context by noting this applies to auth collection users and explicitly requires SMTP to be configured, which is a useful precondition. It does not mention alternatives or when-not-to-use, but the prerequisite and target audience give enough situational guidance for most agents.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of behavioral disclosure. It usefully discloses that changing the password requires both 'password' and 'passwordConfirm' in data, but it does not mention permissions, response shape, partial-update behavior, or whether changes are immediately effective.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with no filler. The main purpose is front-loaded, and the second sentence adds an important edge-case instruction. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter update operation, the description covers the core calling requirements: id, data, and the special password-pairing rule. It does not describe return values or permissions, but given the absence of an output schema, it still provides enough context for a competent agent to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds value beyond the schema by explaining that 'data' can contain email or password fields and by highlighting the non-obvious constraint that password changes require both password and passwordConfirm together.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with a specific verb and resource, 'Update a superuser account,' and gives concrete examples of change email and reset password. This clearly distinguishes it from sibling tools like create_superuser, delete_superuser, and list_superusers.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool: when updating an existing superuser account. However, it does not explicitly contrast it with related flows such as request_password_reset or confirm_email_change, so an agent could confuse a direct password reset with an email-based reset flow.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the disclosure burden. It does disclose the authorization requirement ('Superuser only') and the expected input form (a local backup .zip file). It does not mention side effects, validation behavior, size limits, or what happens on upload, leaving some behavioral ambiguity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences: the first states the action and target, the second states the access requirement. There is no filler, no redundancy with the title/schema, and the key information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-parameter upload tool, the combination of the description and full schema coverage gives an agent the essential invocation details: what to upload, where it goes, and who may do it. It does not explicitly contrast with create_backup/restore_backup or describe the response, but these are relatively minor gaps given the tool's low complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the single 'path' parameter is already fully described as 'Local filesystem path to the backup .zip file to upload.' The tool description adds no additional parameter-level meaning beyond what the schema already provides, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear, specific action ('Upload') with a specific resource ('an existing local backup zip file') and destination ('into the instance's backups'). It is readily distinguishable from sibling tools such as create_backup (which creates a backup on the instance) and restore_backup (which restores a backup).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context: this tool is for uploading a pre-existing local zip into the instance's backups, and it explicitly restricts usage to superusers. However, it does not explicitly name sibling alternatives or state when not to use this tool, so it falls just short of full guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full behavioral burden and does well: it discloses atomicity/rollback semantics, the upsert edge case (id inside data, creates-if-missing/updates-if-present), and the operational prerequisite (Batch API must be enabled in Settings). It omits auth requirements and error reporting, but the critical behavioral traits for safe invocation are present.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences with every sentence earning its place: purpose, atomicity guarantee, operation envelope, upsert nuance, and settings prerequisite. The core purpose is front-loaded and the prerequisite is properly relegated to the end. Slightly dense, but well-organized and free of repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a nested-array tool with full schema coverage and no output schema, the description covers what an agent needs: the action vocabulary, per-action parameter requirements, the transactional behavior, and the enablement prerequisite. The only notable absence is guidance on failure response format, which is partially mitigated by the rollback guarantee.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds genuine value beyond the schema: it clarifies that id is required for update/delete, data is for create/update/upsert, and specifically resolves the ambiguous upsert case (id goes inside data, not as a top-level field). This compensates for the schema's terse per-field notes.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Execute multiple record operations in a single transactional request'), and the transactional qualifier clearly distinguishes it from single-operation siblings like create_record, update_record, and delete_record. The action enum ('create' | 'update' | 'delete' | 'upsert') reinforces the scope without ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The transactional promise ('All operations succeed or all are rolled back') implies the use case: atomic multi-record operations where partial success is unacceptable. However, it never explicitly names alternatives (e.g., 'use create_record/update_record/delete_record for single operations') or states when not to use it, leaving the routing decision largely to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden. It discloses a key behavior: the call throws if no matching record is found, and it clarifies that only the first match is returned. It does not specify the ordering that determines 'first,' which is a minor transparency gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences: the first states the operation and exception, the second gives a practical use case. No filler or redundant restating of the schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a low-complexity read tool with fully documented parameters, the description covers the core behavior, exception, and a usage example. The main missing piece is the ordering semantics behind 'first,' and there is no output schema to clarify the return shape, but the tool remains callable without further info.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All four parameters are already described in the schema, so the baseline is 3. The description adds value by giving a concrete filter expression example ('email = "a@b.com"') and by framing the filter as a lookup predicate, which clarifies expected usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb and resource: 'Return the first record matching a filter expression.' It also adds the throw-if-not-found behavior, making the operation's scope clear. It does not explicitly contrast with sibling tools like get_record or list_records, so it stops short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Convenient for lookups like...' gives a concrete use case, implying this tool is for retrieving a single expected match by filter. It does not state exclusions or name alternative tools, but the context is sufficient for an agent to choose it for simple lookups.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry behavioral disclosure; it does reveal hourly aggregation, optional filtering, and a filter syntax example. However, it does not state the output shape, default time window, or how filters behave beyond the one example, leaving important operational behavior unspecified.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences with no filler; the core action and scope lead, followed by a practical use case and a concrete example. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter tool with no output schema and no annotations, the description gives the essential purpose and a filter example, but omits the return format and any default/time-range behavior needed to chart statistics reliably. It is minimally viable rather than complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, setting a baseline of 3; the description adds value by clarifying that filtering is optional and by giving a concrete filter example ('level = 0'). It does not fully define the filter grammar, but the example plus schema description is enough for basic usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Return') and resource ('hourly aggregated log statistics'), and the aggregation qualifier distinguishes it from sibling list_logs/get_log. No ambiguity remains about what this tool produces.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives concrete use cases ('chart request volume or error rates') and a filter example, making intended scenarios clear. It does not explicitly say when to prefer it over list_logs or get_log, so it misses the 'when-not/alternatives' bar for a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and discloses important behavior: the token is non-refreshable, duration-limited, and superuser-only. It could say more about side effects or the exact response format, but the key behavioral traits are clearly communicated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences with no filler. It front-loads the core action and resource, then efficiently adds the non-refreshable, duration, and use-case details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a sensitive auth operation with no annotations and no output schema, the description covers the main intent and token behavior but lacks explicit return-format details and more concrete error/permission context. It is adequate but has clear gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description reinforces the meaning of duration and the target user but does not need to add much beyond the schema; collection is left to the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'Generate an auth token for an existing user'. It clearly distinguishes itself from normal password-based auth by noting 'without their password' and adds the superuser restriction, making it easy to differentiate from sibling tools like auth_with_password or create_superuser.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives clear context on when to use it: when you need to make API calls on behalf of a user without their password, and only as a superuser. It does not explicitly name alternatives or rule out other auth methods, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It does state the core action ('Manually trigger') and the superuser requirement, but it does not mention whether the job runs synchronously, is queued, or may have side effects. This leaves a meaningful gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences with no filler. The main action and id source come first, and the access restriction is clearly separated. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter tool the description covers purpose and id provenance well, but because there are no annotations and no output schema, it should also say something about expected outcomes or side effects of triggering a job. That context is missing, so it is not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already covers jobId fully, so the baseline is 3. The description adds useful meaning beyond the schema by telling the agent that the id is the one returned by list_crons, which helps the agent obtain a valid value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description is specific: 'Manually trigger a registered cron job by its id' names the exact verb and resource. The reference to list_crons as the source of the id further distinguishes it from the sibling listing tool, so there is no ambiguity about what this tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly states a prerequisite — the id comes from list_crons — and an access restriction ('Superuser only'). It gives enough context for when to use the tool, though it does not explicitly enumerate alternatives or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden. It discloses that only fields in `data` are changed, explains the `+`/`-` modifiers for multi-relation/file/select fields, and notes file uploads via `files`. This adds meaningful context, though it omits auth requirements and response behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with the core action, then compactly delivering the non-obvious behavioral details. Every sentence earns its place with no redundant filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given six parameters and no annotations, the description effectively covers the non-obvious semantics: partial updates, modifier syntax, and file uploads. It relies on the schema for standard parameters, and the missing response/error context is a minor gap for a mutation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds value beyond the schema by clarifying that `data` is a partial update object and by explaining the `+`/`-` key conventions and the `files` upload mechanism. Standard parameters like `expand` and `fields` are self-explanatory in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'update' and the resource 'existing record by id', and specifies the partial-update scope. It distinguishes itself from create/delete tools by saying 'existing record', but does not explicitly name sibling tools, so it falls just short of a top score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description conveys clear context for when to use the tool: updating an existing record with field-level changes. The partial-update semantics ('Only the fields present in data are changed') help an agent choose this over other operations, but it does not explicitly state alternatives or exclusion scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden of behavioral disclosure. It adequately covers return value (auth token and user record) and an important side-effect trait (does not affect the MCP's own superuser session). It does not disclose error behavior or rate-limit implications, but for an authentication operation this is reasonable and not misleading.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three crisp sentences: the first states the action and inputs, the second states the return and side-effect, the third states the use case. It is front-loaded, avoids filler, and every sentence contributes meaningfully to selection and invocation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a moderate-complexity auth tool with no output schema, the description is complete enough: it identifies the required inputs, what is returned, the intended use, and a key behavioral nuance. The schema handles parameter details. It could add explicit comparison with OTP auth, but that is a refinement rather than a necessity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All four parameters are already documented in the schema with 100% coverage, so the baseline is 3. The description only repeats identity/password at a high level and adds no parameter-specific detail beyond the schema. No extra credit is warranted.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Authenticate') with a clear resource ('end user against an auth collection') and explicit credentials ('identity (email/username) and password'). It also distinguishes itself from superuser-related tools by noting it does not affect the MCP's own superuser session, making it distinct among the many auth-related siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use the tool: 'to obtain a token to act on behalf of a user or to verify credentials.' It provides clear context, though it does not explicitly mention alternatives like auth_with_otp or state when not to use it. This is a minor gap rather than a critical one.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the behavioral transparency burden. It accurately indicates this is a state-changing confirmation action, but it does not disclose side effects such as invalidating the old email, session behavior, or error cases. This is acceptable but not fully transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, information-dense sentence with no filler. Every element adds value: the action, the resource, and the two required inputs.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with just two required parameters and no output schema, the description covers the core action and the purpose of both key parameters. It does not explain return values or failure modes, but these are less critical given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds extra meaning by specifying that the token comes from the confirmation email and that the password is the user's current password, which reinforces the schema descriptions and clarifies the token's origin.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb and resource: 'Confirm a user's email change.' It also explains the mechanism (token from confirmation email and password), which distinguishes it from sibling tools like confirm_password_reset or confirm_verification.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context: this tool is used when a user has a token from a confirmation email and needs to complete an email change. It does not explicitly name alternatives or exclusion conditions, but the context is specific enough to guide correct selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It does add useful behavioral context beyond the obvious mutation: auth fields required, file upload mechanism, and relation ID format. However, it does not disclose potential side effects, validation failures, permissions, or response behavior, leaving some uncertainty for a mutating tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded with the core purpose. Each sentence earns its place by addressing a distinct operational aspect (data, auth, files, relations) without extraneous wording or repetition of schema details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and five parameters (one required), the description covers the key invocation patterns needed to create records successfully. It explains the most complex parameter ('data'), special auth requirements, file uploads, and relation handling. Minor gaps exist around optional 'expand'/'fields' parameters and response format, but Schema descriptions already cover those names.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds meaningful semantics beyond the schema: it explains that 'data' holds field values, specifically requires 'password' and 'passwordConfirm' for auth collections, defines how 'files' maps fields to local paths, and clarifies relation ID formats. This enriches parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with a specific verb and resource — 'Create a new record in a collection' — which immediately distinguishes it from siblings like create_collection or update_record. It makes the tool's primary function explicit and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear practical context for when to use the tool, including how to handle auth collections, file uploads, and relation fields. It does not explicitly exclude alternatives (e.g., 'use update_record instead of...'), but the guidance is sufficient for an agent to understand this is the create-record operation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the behavioral burden. It discloses that the tool writes to a local filesystem path (side effect) and that requesting a token is handled internally for protected files (auth behavior). It does not mention overwrite behavior or error responses, but the core behavioral traits are clearly stated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no filler: the main action and destination come first, and the protected-file behavior is added in the second sentence. Every clause contributes useful information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is complete enough for selecting and invoking this straightforward download tool: it covers what is downloaded, where it is written, and how protected files are handled. It omits return-value details and filesystem edge cases like directory creation or file overwrite, but those are not essential for a basic download operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds value by clarifying destPath is on the MCP server machine and explaining the protected-file token handling, but it does not add meaning for thumb, filename, recordId, or collection beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific action ('Download'), a specific resource ('record file'), and a specific destination ('local path on the machine running this MCP server'), which clearly distinguishes it from siblings like get_file_url or get_file_token that return URLs/tokens rather than writing to server-local storage.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'local path on the machine running this MCP server' gives clear context that this tool is for server-side file writes, and 'handles protected files automatically' tells the agent it can be used for protected records without extra token plumbing. It does not explicitly name alternatives or exclusion cases, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the behavioral burden. It usefully reveals that the token is short-lived and must be used as a query parameter. Still, it does not mention authentication requirements, token expiration length, or any side effects, which would be valuable for a token-generating operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence. It front-loads the core action ('Generate a short-lived file access token') and immediately provides the essential usage detail, with no filler or redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple no-parameter tool, the description is largely complete: it states what is generated, its lifespan characteristic, and how it should be attached to a URL. It does not explicitly describe the return value format or error conditions, but the lack of an output schema and zero parameters reduce the need for that detail.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the baseline is 4. The description confirms there is nothing to configure and instead focuses on how the generated token is consumed, which is appropriate for a no-input tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Generate' and names the resource 'file access token', then explains its purpose by describing how it is used ('appending it as a ?token=... query parameter to a file URL'). This clearly distinguishes it from sibling tools like get_file_url or download_file, which focus on URLs or file content rather than token issuance.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool: when you need a short-lived token to access protected files. It also explains the exact usage pattern via query parameter. However, it does not explicitly mention when not to use it or name alternative tools for comparison.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden. It discloses the short-lived access token behavior for protected files and explains thumbnail syntax. It does not cover error cases or auth requirements, but the core behavior is well disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two focused sentences with no filler. The primary purpose is front-loaded, and the special cases are explained efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the tool's main purpose, thumbnail behavior, and protected-file handling. It does not mention the download parameter in prose, but the schema covers that. The return value is inferable as a URL, so its absence is not a significant gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds real value by giving concrete thumbnail size examples ('100x100t', '0x100') and clarifying when protected should be true (non-public file field).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'Build the public URL for a file stored in a record's file field.' It clearly distinguishes this URL-building tool from sibling tools like download_file or get_file_token.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides useful context for when to use thumbnail sizes and when to set protected, but it never explicitly names alternative tools or states when not to use this tool. The usage guidance is present but implied rather than contrasted with siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the disclosure burden. It states the operation is a listing (read-only by implication), specifies the returned fields, and adds the superuser-only permission requirement. This is sufficient for a simple list tool, though it does not detail side effects or pagination behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, compact sentence that front-loads the verb and resource, enumerates the output fields, and appends the permission constraint. Every word earns its place with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, list-only tool with no output schema, the description covers the essentials: the resource, returned metadata fields, and access restriction. It omits ordering or pagination details, but those are likely non-issues for a straightforward backup listing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and an empty input schema, so there are no parameter semantics to explain. The description adds no parameter-level detail, but none is needed; the schema already conveys that the tool takes no arguments.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'List' with a concrete resource, 'available backup files', and enumerates the returned fields (key, size, modified date). This distinguishes it clearly from backup mutation siblings like create_backup, delete_backup, and restore_backup.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear operational context and a superuser-only access restriction, but it does not explicitly mention when to use this tool vs alternatives such as download_backup or get_backup_download_url. Usage guidance is implied rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full behavioral disclosure burden. It does disclose the superuser-only access requirement, the default sort order, and gives a filter syntax example, which is useful. However, it does not mention response shape, pagination metadata, potential access errors, or any rate/volume considerations, so the behavioral picture is incomplete.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no filler. The first sentence states what the tool does and its key capabilities, and the second gives a concrete filter example and the default sort order. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that all parameters are optional, fully documented in the schema, and there is no output schema, the description is largely sufficient for an agent to make a correct call. The main gap is the lack of explicit alternative routing (e.g., when to use get_log or get_logs_stats instead), but the core invocation details are well covered.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already documents all four parameters at 100% coverage, so the baseline is 3. The description adds value beyond the schema by providing a concrete filter expression example ('level >= 4 && data.status >= 400') and clarifying the default sort behavior ('newest first'), which helps an agent construct valid and effective calls.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description states a specific verb ('List'), a clear resource ('application request/activity logs'), and the key operational features (pagination, filtering, sorting). It also adds the superuser restriction, which distinguishes access level from other list tools. This is unambiguous and effectively differentiates from siblings like get_log and get_logs_stats.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for when this tool is appropriate: listing logs with pagination, filtering, and sorting, with an example filter expression. It does not explicitly name alternative tools or state when not to use it, but the sibling tools (e.g., get_log, get_logs_stats) are implied by the 'list' framing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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 clearly discloses the side effect (sending an email) and the external dependency (SMTP). It does not detail error behavior or account existence handling, but the core behavior and prerequisite are transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence communicates the action, target, and precondition without any wasted words. The essential behavior is front-loaded and every phrase earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple action tool with one required parameter and no output schema, the description gives enough information for an agent to invoke it: what it does and a key prerequisite. It does not describe return values or failure modes, but those are less critical for a fire-and-forget email request; the guidance is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 the 'email' and 'collection' parameters. The description does not add parameter-specific details beyond the schema, which aligns with the baseline of 3 for fully documented schemas.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names the specific action ('Send a password reset email') and target ('to a user'), which clearly identifies the tool's function. It is distinguishable from siblings like confirm_password_reset and request_verification because it explicitly mentions the email-sending step.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description conveys the usage context: a user needs a password reset email. It also includes a clear prerequisite ('requires SMTP configured'). It does not explicitly list when not to use it or point to alternatives, but the use case is unambiguous and there are no misleading signals.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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 discloses that the tool performs a sending side effect, is superuser-only, and depends on SMTP being configured. It does not mention what the response looks like or any logging side effects, but the core behavior is made clear.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three short sentences with zero filler. It front-loads the core purpose, then gives required choices and constraints. The template list is slightly redundant with the schema, but it is useful context and does not hurt conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with full schema coverage, the description covers purpose, prerequisites, permissions, and template options. It does not describe the return value or confirm that an email is actually delivered, and there is no output schema to fill that gap, so a small completeness gap remains.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 toEmail, template, and collection. The description repeats the allowed template values but adds no additional semantic meaning beyond what the schema provides, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool sends a test email for the purpose of verifying SMTP configuration. It names the specific resource and action, and this differentiates it from the only structurally similar sibling, test_s3. The template choices are also explicitly enumerated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear usage context: use this to verify SMTP configuration, requires SMTP to be configured, and is restricted to superusers. It does not explicitly mention alternatives or when not to use it, but the context is specific enough for an agent to route correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It explicitly states the destructive scope ('Delete ALL records') and warns 'Cannot be undone,' which is the most critical side effect. It does not mention permissions, cascade/dependency effects, or whether auto-increment counters reset, but the core risk is disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences with no fluff; the destructive scope and irreversibility are front-loaded. Every sentence contributes essential information and nothing is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter destructive tool with no output schema, the description covers the core outcome and the key risk of irreversibility. It could be slightly more helpful by naming the alternative for deleting the whole collection, but that is not necessary for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter, idOrName, has a complete schema description ('Collection id or name to truncate'), and the tool description does not add additional parameter detail. Since schema description coverage is 100%, the description adds no extra meaning and the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Delete') and resource ('ALL records of a collection'), and clarifies that the collection/schema itself is preserved. This clearly distinguishes it from siblings like delete_collection and delete_record without needing to inspect them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly frames when this tool applies: removing every record while retaining the collection structure. It does not explicitly name alternatives or say when not to use it, but the contrast with delete_collection and delete_record is embedded in the wording. This is clear context, though not an explicit exclusion list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden, and it discloses the key operational facts: privileged access ("Superuser only"), the mutating nature of the operation ("Bulk update"), and the partial-update semantics (providing only changed sections implies unspecified ones are left intact). It omits the return value and error behavior, but the most decision-relevant traits are covered and nothing contradicts the (absent) annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The purpose is front-loaded in the first sentence, followed by the usage rule, examples, and permission note. The examples are lengthy but earn their place because the open schema would otherwise leave the agent guessing at valid payload structures; there is no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter tool with an open schema, no annotations, and no output schema, the description covers everything needed to invoke it correctly: what `data` should contain, the partial-update rule, and the superuser requirement. Minor gaps remain — no mention of the response format or whether changes take effect immediately — but nothing critical for a correct call is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema's only property, `data`, is described as "Partial settings object..." but is otherwise completely open (`additionalProperties: {}`), so the schema carries almost no structural meaning. The description's three concrete examples (meta, smtp, batch with nested fields) are the sole documentation of what sections actually exist and what shapes they take — an enormous addition beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
"Bulk update instance settings" states a specific verb (bulk update) and resource (instance settings), so an agent immediately knows what the tool does. It does not explicitly differentiate from siblings like get_settings or batch, relying on the name and verb to carry that distinction, which keeps it at 4 rather than 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The instruction "Provide only the sections you want to change in `data`" gives clear, actionable context on how a caller should construct a request, and the first sentence establishes when to use it (modifying instance settings). However, it never names alternatives or exclusions — e.g., it does not point to get_settings for reads — so it lacks explicit when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full transparency burden. It clearly discloses that the action is irreversible and that all associated records are destroyed, which is exactly the critical behavioral context an agent needs before invoking a destructive tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences deliver the essential action, scope, and irreversibility with no filler. Every sentence earns its place, and the warning is clear and prominent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With one required parameter, no output schema, and no nested objects, the description fully covers what the tool does and the consequences. Nothing needed to call it safely is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already covers the only parameter fully with 'Collection id or name to delete,' and schema description coverage is 100%. The description does not add new parameter-specific meaning beyond reinforcing the destructive consequence, so the baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Permanently delete'), a specific resource ('a collection'), and the full scope of the operation ('ALL of its records'). This clearly distinguishes it from record-level or content-level sibling tools such as delete_record and truncate_collection.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The wording implies this is for intentional, whole-collection removal, especially with 'cannot be undone.' However, it does not explicitly name alternatives or say when not to use it, such as pointing to truncate_collection when the collection itself should be preserved.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations available, the description carries the behavioral burden. It discloses a meaningful safety guarantee ('The raw token is never exposed') and clearly signals a read-only operation through 'Return information.' It doesn't explicitly state side-effect-free behavior or error handling for unauthenticated calls, but the listed output ('whether the token is valid') addresses the primary concern.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with no wasted words. The first sentence front-loads the purpose and output fields, and the second adds a useful security caveat. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple, zero-parameter, read-only tool with no output schema, the description provides enough information about what is returned and the security posture. It doesn't specify exact field names/types or failure modes, but these are minor given the low complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and schema coverage is effectively 100%, so parameter documentation is unnecessary. The baseline of 4 applies here; the description adds no param info because there is nothing to add.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Return information') tied to a clear resource ('current MCP authentication') and enumerates the exact fields returned. This clearly distinguishes it from siblings like auth_with_password, impersonate, or list_auth_methods, which perform different auth operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies a clear use case: when an agent needs to inspect the current MCP authentication context, token validity, or authenticated identity. It doesn't explicitly name alternatives or state when not to use it, but for a zero-parameter read-only status tool, the context is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the behavioral burden. It discloses auto-pagination, batched fetching, and the risk of huge responses. It does not mention error behavior, auth needs, or response format, but the read-only nature is clearly implied by 'Fetch'.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no filler. The purpose and key behavioral trait are front-loaded, and the usage guidance is packed into the second sentence without waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only fetch tool with fully documented parameters and clear usage boundaries, the description is mostly complete. The absence of an output schema is mitigated by the obvious return type (records), and the warning about large responses covers the main operational risk.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 six parameters. The description adds contextual hints about filters and batches but does not materially improve on the schema's per-parameter descriptions. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Fetch'), a clear resource ('ALL records'), and a distinguishing behavior ('auto-paginating in batches'). It also differentiates this tool from the paginated list_records sibling by emphasizing the 'ALL records' scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use this tool ('exports or small/medium collections') and gives a direct alternative ('Prefer list_records with pagination for large datasets'). This gives an agent clear selection criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the behavioral disclosure burden. It does a good job by explicitly warning that deleteMissing deletes collections not present in the import list and adding 'use with caution'. It does not mention atomicity or permission requirements, but the main destructive behavior is surfaced clearly.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences with no filler. The main action is front-loaded, the destructive warning follows immediately, and the recommended use case appears at the end. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutating bulk import with no annotations and no output schema, the description covers the operation, the dangerous side-effect, and the intended use case. It could additionally mention whether existing collections are updated or whether the import is transactional, but the essentials for safe invocation are present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds useful context beyond the schema by specifying that collection definitions are 'as exported from the PocketBase admin UI' and by reinforcing the deleteMissing conditional behavior. This is meaningful but not extensive.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Bulk import collections from an array of collection definitions', which clearly states the verb, resource, and bulk nature of the operation. It also distinguishes itself from per-collection create/update tools by noting this is the recommended way to apply a full schema in one call.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly frames the tool as 'the recommended way to apply a full schema in one call', giving a clear use case. It also warns about the destructive behavior of deleteMissing. However, it does not explicitly contrast it with when to use individual collection tools like create_collection or update_collection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the behavioral burden. It discloses the auth requirement ('Superuser only'), the read-only nature ('List all'), and what the caller will receive ('id and cron expression'). It omits details like pagination or response wrapping, but these are minor for a zero-parameter list tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
One front-loaded sentence with no filler. The parenthetical examples add useful context without bloating the definition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, no-output-schema tool, the description sufficiently covers purpose, output fields, authentication, and scope. It could be more explicit about the exact response shape or empty-list behavior, but nothing critical is absent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and schema description coverage is 100%, so there is no parameter documentation burden. The baseline for zero-parameter tools is 4, and the description adds nothing needed beyond that.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('List'), a clear resource ('all registered cron jobs'), and the returned fields ('id and cron expression'). The parenthetical examples further distinguish the scope from action-oriented siblings like run_cron.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear context by specifying 'Superuser only' and the exact scope of the listing, including custom jobs registered via hooks. It does not explicitly name alternative tools or exclusion conditions, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral disclosure burden. It clearly explains partial updates via `data`, the special requirement to pass the full `fields` array for schema changes, and warns that existing field ids must be preserved to keep data. This is valuable behavioral context, though it stops short of mentioning permissions or response details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: purpose first, then the most important usage caveat, then acceptable update targets. Every sentence contributes useful information and there is no redundant filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an update operation with no output schema, the description covers the main invocation details: target identifier, partial payload semantics, schema update requirement, and which collection aspects can be changed. It does not explain error behavior or permissions, but it is sufficient for selecting and invoking the tool correctly in most cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already describes both parameters fully, so the baseline is 3. The description adds meaningful semantics beyond the schema by explaining that `data` is a partial payload, that schema changes require the full fields array, and that rules, indexes, and options are also updatable.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Update an existing collection'), targets a clear resource (collection), and adds the key distinction of addressing it by id or name. This sets it apart from sibling tools like create_collection and delete_collection without ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description makes it clear this tool is for updating existing collections, which implies it is not for creating, deleting, or querying collections. It does not explicitly name alternatives or exclusion cases, but the context is strong enough to guide correct tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and discloses a non-obvious behavior: PocketBase 0.23+ does not add created/updated timestamps automatically, and shows exactly how to add them. It also explains how API rules and indexes are supplied. It could add error/conflict behavior, but the key behavioral caveat is covered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but well-structured: the core instruction comes first, followed by the payload details, a usage tip, an example, and a highlighted compatibility caveat. No sentence is filler; the length is justified by the complexity of the payload.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given a nested-object payload and no output schema, the description covers the required name, the type enum with defaults, the data sub-payload, an example field, and auth/view specifics. It provides enough context for an agent to call the tool correctly without external lookup.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description goes beyond the schema by elaborating the data object's subfields (fields, rules, indexes, viewQuery, auth options), giving a concrete field example, and explaining the timestamp workaround. This materially helps an agent construct a valid payload.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States the specific action 'Create a new collection' and immediately distinguishes collection types (base/auth/view). The payload description clarifies this is about creating a collection, not records or other resources, which separates it from siblings like create_record and update_collection.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Clear that the tool is for new collections only, and the explicit tip to call get_collection_scaffolds first gives an actionable prerequisite. It does not explicitly mention when to prefer update_collection or import_collections, but the create-scoped context is unmistakable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the behavioral burden. It states the read-only nature ('Return default collection templates') and the intended workflow with create_collection, which is sufficient for a zero-parameter read tool. It does not disclose output shape, but no output schema exists; the core behavior and side-effect-free nature are clear.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the action, and every clause earns its place. The workflow guidance (copy, adjust, create) is useful without adding bulk.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no parameters, no annotations, and no output schema, the description is complete: it defines what is returned, enumerates the result categories, and explains how the result should be used with create_collection. Nothing needed to invoke it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero properties and coverage is 100%, so there are no parameters whose meaning needs explaining. The description adds value by naming the three scaffold categories in the output, aligning with the 0-parameter baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description begins with a specific verb and object: 'Return default collection templates (scaffolds)' and enumerates the exact collection types (base, auth, view). This clearly separates it from siblings like get_collection or list_collections, which operate on existing collections, and ties it to create_collection.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives an explicit when-to-use signal: 'Useful as a starting point before calling create_collection' and describes the copy-adjust-create workflow. It does not explicitly list when-not-to-use or name an alternative tool, but the context is clear enough for the agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of behavioral disclosure. It transparently states that this is a fetch operation, that OAuth2 secrets are redacted, and that superuser authorization is required. This goes beyond the bare tool name and gives useful operational context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single front-loaded sentence with a compact but informative list of setting categories and a crucial redaction note. Every element earns its place, and there is no filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter read tool with no output schema, the description is complete: it states what is fetched, what sensitive data is redacted, and the required privilege level. An agent has enough information to call this tool correctly and set expectations about the response.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so there is nothing for the description to add about parameter meaning. The baseline of 4 applies because the no-parameter situation makes parameter documentation unnecessary.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource ('Fetch all instance settings'), enumerates the setting categories it covers, and notes that OAuth2 secrets are redacted. This clearly distinguishes it from sibling update_settings as a read-only snapshot tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The statement 'Superuser only' gives a clear access prerequisite, and the content makes evident this is the tool for retrieving the full settings snapshot rather than modifying it. It does not explicitly name alternatives or exclusions, but the context is clear enough for an agent to select it appropriately.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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 covers the auth requirement and outlines the return contents: server code, message, and health data. This is adequate for a simple, non-mutating health check, though it does not describe possible error or failure modes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences deliver all essential information with no waste. The main action is front-loaded, and the auth requirement plus return data are stated efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 0-parameter health check with no output schema or annotations, the description is complete enough for an agent to select and invoke the tool correctly. It explains purpose, auth needs, and return contents without requiring further elaboration.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the baseline is 4. There is no parameter information needed in the description, and the schema correctly reflects an empty parameter set.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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 and resource: 'Check the PocketBase API health status'. It also distinguishes itself from the many mutation/admin tools in the sibling list by signaling this is a read-only diagnostic operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides useful usage context by explicitly stating 'Does not require authentication', which helps an agent know this tool can be called without credentials. It does not explicitly mention alternatives, but for a 0-parameter health check this is acceptable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
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 explicitly states 'THIS OVERWRITES ALL CURRENT DATA and restarts the application,' which is a critical destructive side effect. It also discloses the privilege requirement ('Superuser only') and advises extreme caution.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and every sentence earns its place. The core function is stated first, followed by the critical destructive warning and the superuser restriction. No filler or redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter destructive tool with no output schema, the description covers everything needed for correct invocation: what it does, the key parameter meaning, the destructive consequence, the restart behavior, and the privilege requirement. There is no meaningful gap given the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the schema already describes 'key' as the backup file key/name. The description adds the notion that the backup file must already exist ('existing backup file'), but this is a minor extension. Since the schema handles the parameter semantics, the description provides only marginal additional value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'Restore the instance from an existing backup file.' This clearly distinguishes restore_backup from sibling backup tools like list_backups, create_backup, upload_backup, and delete_backup. The warning sentence adds scope and risk profile rather than obscuring the purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context on when to use the tool: when restoring from an existing backup. It also provides critical usage restrictions: 'Use with extreme caution. Superuser only.' It does not explicitly name alternatives, but the destructive nature and distinctive restore action make the appropriate use case unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations to fall back on, the description carries the full behavioral burden and does so well. It discloses that the backup is a zip snapshot of database and storage, that omitting basename yields a timestamped name, that the backup name is returned, and that superuser authorization is required.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is four short sentences, front-loaded with the core action, and every sentence adds meaningful functional content. There is no redundant or filler wording.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with one optional parameter and no output schema, the description provides all essential context: what it does, what it contains, how the parameter behaves, what is returned, and who can call it. An agent can invoke this tool correctly without additional information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% already, so the baseline is 3. The description goes beyond the schema by specifying that an omitted basename produces a timestamped name and that the tool returns the backup name, adding useful semantic detail for the single optional parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Create'), a clear resource ('a new backup'), and explains what it is ('zip snapshot of the database and storage'). It distinguishes itself from sibling backup tools like list_backups, restore_backup, upload_backup, and delete_backup by emphasizing that it creates a new backup.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description makes it clear this is the tool to use for creating a new backup and even notes the 'Superuser only' access restriction. However, it does not explicitly name alternatives or mention when not to use it, though the context is already strong enough for an agent to route correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the disclosure burden. It reveals that the Authorization header with a superuser token is attached automatically, that the path must start with '/api/', and that a parsed JSON response is returned. These are important behavioral facts beyond the schema, though it does not explicitly warn about the destructive potential of arbitrary DELETE/POST requests.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, with the purpose front-loaded first, then usage guidance, then key behavioral constraints. Each sentence adds distinct value with no redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a generic raw-request tool, the description covers selection criteria, authentication behavior, path constraints, and response format. Combined with the fully documented input schema, the agent has sufficient information to select and invoke the tool correctly without an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so all five parameters are already described structurally. The description adds meaningful context for `path` by specifying that it is relative to the server root and must start with '/api/', and it clarifies the return format, going beyond the schema's property descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'send an arbitrary authenticated HTTP request to any PocketBase API endpoint' with a specific verb and resource. It also brands itself as an 'escape hatch' for endpoints not covered by a dedicated tool, clearly distinguishing it from all the resource-specific sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly lists the use cases: endpoints not covered by a dedicated tool, custom routes added via hooks, and new API features. This gives the agent a clear selection rule and implicitly tells it to prefer a sibling tool whenever one exists.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

GitHub Badge

Glama performs regular codebase and documentation scans to:

Confirm that the MCP server is working as expected.
Confirm that there are no obvious security issues.
Evaluate tool definition quality.

Our badge communicates server capabilities, safety, and installation instructions.

Card Badge

Copy to your README.md:

[![pocketbase-mcp MCP server](https://glama.ai/mcp/servers/nestebe/pocketbase-mcp/badges/card.svg)](https://glama.ai/mcp/servers/nestebe/pocketbase-mcp)

Score Badge

Copy to your README.md:

[![pocketbase-mcp MCP server](https://glama.ai/mcp/servers/nestebe/pocketbase-mcp/badges/score.svg)](https://glama.ai/mcp/servers/nestebe/pocketbase-mcp)

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/nestebe/pocketbase-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server