Server Quality Checklist

Tool Scores

• list_releasesA
  4.2/5.0
  Behavior4/5

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

  With no annotations, the description carries the transparency burden. It discloses sort order (newest-first by release_date), the fields returned, and the filter semantics (substring, case-insensitive). It omits explicit statement of read-only nature, but the 'List' verb implies it and no side effects are expected for a list 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 three sentences long, front-loaded with the core purpose, followed by return fields and usage guidance. Every sentence serves a distinct function 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 no output schema, the description usefully lists returned fields and order. All four parameters are fully documented in the schema, so the description doesn't need to repeat them. Minor gap: the 'track + EP' terminology is not reconciled with the schema's 'single-track releases', but this is a minor ambiguity.

  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 baseline is 3. The description adds no substantive parameter meaning beyond the schema; it merely recounts the stage filter with slightly different common values. It does not mention limit, includeEps, or includeTracks, but the schema already documents these fully.

  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 track + EP releases from the Berbotu vault, with a specific resource and scope. It distinguishes itself from sibling list_demos by focusing on releases, and the verb 'List' is specific.

  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 explicit 'Use this when' triggers, including label catalog, scheduled releases, what's coming out, and 'anything about releases'. However, it does not explicitly mention when not to use it or compare to the sibling tool list_demos, so it falls short of full alternative guidance.

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

• list_demosA
  4.3/5.0
  Behavior4/5

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

  The description discloses sorting order, the exact fields returned, and the case-insensitive substring filtering behavior for the stage argument. While no annotations are provided, this covers the most important behavioral traits for a read/list 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?

  Four concise, front-loaded sentences cover purpose, output fields, usage triggers, and a filter parameter without wasted words. Each sentence earns its place, making it easy to parse quickly.

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

  Completeness5/5

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

  Since there is no output schema, the description correctly enumerates the item fields (artist, title, status, date, score), explains sorting, and gives usage scenarios. The schema already handles parameter details, so nothing essential 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 schema description coverage is 100%, so the baseline is 3. The description adds minor redundancy with examples ('listening', 'interested', 'pass') but does not meaningfully enhance understanding beyond the schema's existing parameter 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 opening sentence specifies the exact function: 'Lists demo submissions from the Berbotu vault, sorted newest-first by received_date.' This includes a specific verb, resource, and sorting detail, clearly distinguishing it from siblings like list_releases and add_demo.

  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 explicitly states when to use: 'Use this when the user asks about incoming submissions, the demo pipeline, A&R inbox, or anything like...' This provides strong contextual guidance, though it does not name alternatives or state when not to use it, so it falls 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.

• pingA
  4.4/5.0
  Behavior4/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 states the exact return fields and that the tool is a health check, which implies read-only behavior and no side effects. It does not cover error cases or response format, but for a ping tool this is adequate.

  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, front-loaded with the return value and purpose. Every word is functional 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?

  Given the tool's simplicity (no params, no output schema, no annotations), the description adequately covers the purpose and return values. It does not specify response format or error scenarios, but those are minor gaps for a basic health check.

  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 adds nothing about parameters because there are none, and no parameter explanation is needed.

  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 returns 'OK' plus server metadata and explicitly identifies its purpose as confirming the MCP server is reachable. This specific verb + resource scope distinguishes it from sibling tools that list or add demos/releases.

  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 says 'Use this to confirm the Berbotu MCP server is reachable and configured correctly', providing clear guidance on when to use it. However, it does not mention alternatives or when-not-to-use cases, so it falls short of the top score.

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

• add_demoA
  4.7/5.0
  Behavior5/5

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

  The description discloses important side effects beyond the annotations: it commits a Markdown file to a GitHub repo, refuses to overwrite existing demos, and returns a GitHub commit permalink. This adds meaningful behavioral context, especially clarifying that the destructiveHint=true annotation does not imply overwriting existing 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 information-dense with no filler. Each sentence serves a distinct purpose: defining the action and repo path, giving use-case examples, listing requirements/defaults, explaining conflict handling, and describing return values.

  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 5 parameters and no output schema, the description covers all necessary context: trigger, constraints, defaults, conflict behavior, side effects, and return values. It fully prepares an agent to invoke the tool correctly and interpret the result.

  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% description coverage for all 5 parameters with detailed semantics, so the baseline is 3. The description mostly restates the required/optional fields and defaults, adding only the path formula (artist + title) but no substantially new parameter meaning.

  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 ('Creates'), a concrete resource ('Berbotu vault by committing a Markdown file'), and an exact repository path, making the tool's purpose unmistakable. It clearly distinguishes this tool from the sibling read/list tools (ping, list_demos, list_releases).

  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?

  The description explicitly states when to use the tool: 'Use this when the user wants to log a fresh submission', with concrete examples. It also provides a when-not-to-use alternative: if a demo already exists, the user should edit via admin.berbotu.com instead, since this tool refuses to overwrite.

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