Server Quality Checklist

Tool Scores

• b2_list_bucketsA
  4.1/5.0
  Behavior3/5

  Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

  Annotations already indicate readOnlyHint=true, so the description carries a lower burden. It adds the return format (JSON objects with specific fields) and the 'every bucket' scoping, but does not disclose other behaviors like pagination or authentication. This provides some value beyond the annotation.

  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-formed sentence that is front-loaded with the action and provides necessary details without any waste.

  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 simple list tool with no parameters and an annotation for read-only safety, the description is complete. It specifies the output shape, making it sufficient even 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?

  The tool has zero parameters, so the baseline is 4. The description correctly implies no inputs are needed by listing buckets without any filters or options, and the empty schema confirms this.

  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 'Lists' and the resource 'every bucket in the configured Backblaze B2 account', and it specifies the output format as JSON objects with bucketId, bucketName, and bucketType. This distinguishes it from sibling tools like b2_list_files which list files, not buckets.

  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 context is clear from the name and description—this tool is for listing buckets—but there is no explicit 'when to use' vs alternatives. With no parameters and a straightforward purpose, the usage is implied rather than directly stated.

  Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

• b2_list_filesA
  4.2/5.0
  Behavior4/5

  Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

  With readOnlyHint=true, the annotation already signals a safe read. The description adds valuable context: it returns a page, mentions the fields, and explicitly reveals pagination via 'truncated and nextFileName'. This goes beyond the annotation. However, it doesn't clarify whether 'current files' excludes hidden files, which is relevant given sibling hide/unhide tools, so a minor gap prevents a 5.

  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 concise sentences, front-loaded with the main purpose, then output details, then pagination behavior. Every sentence contributes new information with no waste. It is appropriately sized for a tool with three parameters and a simple output structure.

  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 core function, return format, filtering, and pagination, which is particularly important given no output schema exists. It doesn't mention error cases or auth, but readOnlyHint covers safety. The only notable omission is clarification of 'current files' regarding hidden files, but overall the description is adequate for a listing 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%, so the schema fully documents limit, prefix, and bucketName. The description adds minimal parameter meaning: it mentions prefix filtering and one page (which relates to limit), but these are already in the schema. Since the description doesn't clarify syntax or format beyond the schema, 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 the action ('Lists'), the resource ('files in a bucket'), and the scope ('one page', 'current files'). It also distinguishes from siblings like b2_list_buckets and b2_upload_file by specifying the exact JSON fields returned. This is a specific verb+resource+scope, providing high purpose clarity.

  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: it lists files in a bucket with optional prefix filtering and pagination. It doesn't explicitly name alternatives or exclusions, but the sibling tools are distinct (e.g., b2_hide_file, b2_upload_file), so the intended use is fairly obvious. A full 5 would require explicit 'use this instead of X' guidance, but the context is sufficient.

  Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

• b2_unhide_fileA
  4.2/5.0
  Behavior4/5

  Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

  Beyond the annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false), the description adds that only the latest hide marker is removed and that the response includes a 'restored false' field when the file wasn't hidden. This provides additional behavioral nuance not present in the annotations.

  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 sentences with no wasted words. It front-loads the action ('Removes the latest hide marker') and includes a concise edge-case note, making it both efficient and well-structured.

  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 annotations and no output schema, the description sufficiently covers the purpose and the edge case of non-hidden files. It hints at the response shape via 'restored false' but doesn't fully specify return values, which is acceptable given the tool's simplicity.

  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 descriptions for both parameters (bucketName and fileName) with 100% coverage, so the description doesn't need to repeat them. It adds no extra parameter-level meaning, 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 ('Removes') and clearly identifies the resource ('B2 file') and action (unhiding). It distinguishes from the sibling b2_hide_file by stating it removes the hide marker, making the purpose unambiguous.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines4/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 (to reverse a hide operation) and adds that if the file was not hidden, it reports restored false rather than failing, which is useful context for safe invocation. It does not explicitly name alternatives, but the context is clear given sibling tool names.

  Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

• b2_download_fileA
  4.5/5.0
  Behavior5/5

  Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

  The description goes beyond annotations by disclosing the B2_DOWNLOAD_ROOT constraint, overwrite behavior, return payload (path, size, type, SHA-1), and explicitly stating file content is never returned. This is rich behavioral context that aligns with annotations.

  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?

  Four sentences, front-loaded with the core action, then essential constraints and edge cases. Every sentence adds value with no fluff 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?

  With no output schema, the description explains return values (path, size, type, SHA-1) and key constraints (root directory, overwrite semantics). It is complete for a download tool with good annotations, leaving no major operational 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%, and the schema already documents defaults and constraints for localPath and overwrite. The description adds no new parameter meaning beyond the schema, so 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 and resource: 'Downloads a file from a bucket to the local filesystem' and clarifies it returns metadata. This clearly distinguishes it from siblings like b2_upload_file or b2_list_files.

  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 is the tool for retrieving file content to local disk. It doesn't explicitly name when-not-to-use or alternative tools, but the operation is self-evident among the sibling list with no ambiguity.

  Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

• b2_upload_fileA
  4.5/5.0
  Behavior5/5

  Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

  The description adds substantial behavior beyond annotations: it says the tool returns the stored file id, name, size, and type, and explains versioning behavior (adds a new version instead of replacing). It also discloses the root-directory constraint. Annotations only indicate it is not read-only, not idempotent, and not destructive, so the description's extra detail is valuable.

  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 tight sentences: first states the core action and return value, second gives a critical path constraint, third explains versioning. No filler or redundancy; every sentence earns its place.

  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 4-parameter upload tool with no output schema, the description covers the essential return values, path constraint, and versioning behavior. It gives the agent enough context to invoke the tool correctly and understand consequences, especially since sibling tools are all unrelated to uploading.

  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 coverage is 100%, so the schema already documents all four parameters. The description repeats the localPath root restriction that appears in the schema and adds the versioning behavior relevant to fileName, but does not significantly extend parameter understanding beyond the structured definitions.

  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 ('Uploads a file from the local filesystem into a bucket') and the resource ('B2 bucket'), which distinguishes it from sibling tools like b2_list_files, b2_download_file, and b2_delete_file_version. The title and first sentence align, providing a specific verb+resource with no 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 provides clear context for when to use the tool: uploading a local file to a bucket, with an explicit prerequisite (path must be inside B2_UPLOAD_ROOT). It does not explicitly mention alternatives or exclusions, but among the sibling tools there is no other upload tool, so the purpose itself guides selection.

  Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

• b2_bucket_usageA
  4.7/5.0
  Behavior5/5

  Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

  While annotations already indicate readOnlyHint=true, the description goes far beyond that by explaining critical behavioral nuances: the calculation sums all file versions including old ones, excludes unfinished large upload parts, treats bytesUsed as a floor, and caps scans at 20 pages per bucket. These details are not available in annotations or schema, significantly enhancing the agent's understanding of side effects and limitations.

  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 sentences long, with no fluff. It front-loads the primary purpose, then adds caveats and cost implications. Each sentence provides essential information for correct usage and expectation-setting, making it appropriately sized for the tool's complexity.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness5/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  Given the absence of an output schema, the description compensates by explaining key output concepts (bytesUsed, unfinishedLargeFiles, truncated) and the operational context (scan cap, cost). It covers all critical aspects an agent needs to correctly invoke and interpret results, making it complete for this 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?

  The input schema already provides descriptions for all three parameters (100% coverage), establishing a baseline of 3. The description adds meaningful context beyond the schema, particularly for bucketName: omitting it scans every bucket and incurs the highest cost. It also clarifies the semantics of budgetBytes and thresholdPercent defaults, which are present in the schema but reinforced contextually.

  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 reports bytes stored per bucket against a budget and flags over-threshold buckets. This distinguishes it from sibling tools, which focus on file/bucket listing, upload/download, or deletion. The verb 'Reports' plus specific resource and outcome make the purpose unambiguous.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  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 the tool, such as noting that omitting bucketName triggers a full scan that is 'the most expensive call this server makes.' It does not explicitly name alternative tools, but the unique purpose among siblings makes the usage context clear. It lacks explicit when-not-to-use guidance, but the cost warning serves as a caution.

  Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

• b2_hide_fileA
  4.7/5.0
  Behavior5/5

  Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

  The description goes beyond the annotations by disclosing that the file data remains in version history, that the action is reversible via b2_unhide_file, and that hidden files no longer appear in list operations. This adds significant behavioral context beyond the readOnly, idempotent, and destructive hints. No contradiction with annotations.

  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 concise sentences, front-loaded with the primary action and effect, followed by reversibility and usage guidance. Every sentence earns its place with no redundant text.

  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 simple two-parameter tool with annotations and no output schema, the description is complete: it explains the action, its behavioral consequence, reversibility, and how it relates to sibling tools (delete and unhide). No critical gaps are apparent.

  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 provides complete descriptions for both required parameters (bucketName and fileName) with 100% coverage. The tool description does not add additional parameter-level meaning, 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 ('hides') and names the resource ('file') with a concrete effect: 'stops appearing in b2_list_files'. It clearly distinguishes from siblings like delete and unhide by stating reversibility and preference over deletion.

  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 states when to prefer this tool: 'Prefer this over deleting when the goal is to remove something from view.' It also names the alternative for restoration (b2_unhide_file), providing clear context for when to use this tool versus alternatives.

  Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

• b2_list_keysA
  4.7/5.0
  Behavior5/5

  Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

  Beyond the readOnlyHint annotation, the description adds critical behavioral context: it never returns key secrets, only reveals capabilities, and requires a specific capability. This is valuable transparency for a security-sensitive 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 three sentences, all dense with relevant information. It front-loads the core purpose, then appends security and permission details without wasted words.

  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 no-parameter, read-only listing tool, the description covers what the tool returns, what it doesn't reveal, and the required permissions. No output schema exists, so the description satisfies the need for return value context.

  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 schema trivially covers everything. The description adds no parameter info because none exists, and the baseline for 0 params is 4, which 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 lists application keys with specific attributes (capabilities, bucket restrictions, name prefix, expiry). It explicitly distinguishes from sibling tools by focusing on application keys and not files/buckets.

  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 prerequisite (requires listKeys capability) and warns about insufficient permissions. While it doesn't explicitly compare to alternatives, the sibling context and the tool's specific scope make when-to-use clear.

  Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

• b2_delete_file_versionA
  4.9/5.0
  Behavior5/5

  Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

  Beyond annotations (destructive, read-only false, idempotent), description discloses permanence ('B2 cannot undo this'), scope ('older versions... left in place'), environmental prerequisite (B2_AUDIT_LOG required), and conditional archiving (B2_ARCHIVE_ROOT copies locally). These are genuinely valuable behavioral details not present in annotations.

  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?

  Every sentence contributes new information: permanence, scope, prerequisite, audit requirement, archival behavior, and alternative. Dense but not bloated, front-loaded with the core function.

  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 destructive, environment-sensitive tool, the description covers what, why, when, prerequisites, side effects, and reversible alternatives. With no output schema, it appropriately focuses on operational requirements and consequences.

  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 already provides 100% coverage, so baseline is 3. Description adds meaningful nuance: the fileId is not interchangeable with fileName, and the fileId must come from b2_list_files. This clarifies parameter relationships beyond the schema's individual field 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?

  Description states 'PERMANENTLY destroys ONE version of a file' — a specific verb, resource, and scope. It clearly distinguishes from the reversible 'b2_hide_file' alternative, making the tool's purpose unmistakable.

  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 instructs to obtain exact fileId from b2_list_files first and guards against misuse by noting it will not look up by file name. Also names the reversible alternative (b2_hide_file) for different use cases.

  Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.