Server Quality Checklist

Tool Scores

• albyhub_list_channelsA
  4.3/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 explicitly mentions 'Hits GET /api/channels', indicating a read-only operation, and describes typical response fields. However, it omits details like pagination, error behavior, or authentication requirements, which would have made it more transparent.

  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 description is concise and front-loaded with the core purpose and field list. However, it includes a tangential comparison to nwc-mcp and an implementation detail ('Hits GET /api/channels') that, while informative, add minor clutter and could be trimmed without losing essential 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?

  For a simple parameterless list tool without an output schema, the description adequately covers what the tool does, what it returns, and its diagnostic use cases. It lacks explicit mention of limits, sorting, or response structure, but these are not critical for such a straightforward tool, so it is sufficiently 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 tool has zero parameters, so the schema coverage is trivially 100% and the baseline is 4. The description adds value by explaining what the returned data contains, which is the only relevant semantic here since there are no parameters to document.

  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 Lightning channels and enumerates typical fields (peer pubkey, capacity, local/remote balance, public/private flag, online status). It distinguishes from sibling tools like get_balances or get_node_info by focusing on channel-level data.

  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 context for when to use the tool, such as spotting offline channels or low inbound liquidity. It also contrasts with nwc-mcp, but does not explicitly list sibling alternatives or exclusions, so it stops short of full when/when-not guidance.

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

• albyhub_proxy_requestA
  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 burden of behavioral disclosure. It discloses the return format ('response status, headers, and (JSON-parsed when possible) body') and critical safety gating ('Non-GET methods are gated by ALBYHUB_READ_ONLY and ALBYHUB_REQUIRE_CONFIRM'). It does not cover error handling or rate limits, but the essential behavior is well 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 four sentences, each earning its place: purpose, usage guidance, return behavior, and relationship to siblings. It is front-loaded with the generic-purpose statement and contains no redundant phrases.

  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 generic proxy tool with no output schema and no annotations, the description covers the essentials: when to use it, what it returns, safety gating, and how to discover endpoints. It does not detail error cases or authentication setup, but those are less critical for a low-level catch-all proxy. Overall, it is sufficiently complete for its purpose.

  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 six parameters have descriptions in the schema, so the baseline is 3. The description adds no additional parameter semantics beyond what the schema already provides—for example, the gating on non-GET methods is already stated in the method parameter description. Thus, the description neither compensates nor detracts.

  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 'Generic HTTP proxy to your Alby Hub admin API', clearly stating a specific verb (proxy) and resource. It also distinguishes itself from siblings by explicitly saying 'Use this when no typed convenience tool exists' and naming the typed wrappers (get_node_info, list_apps, get_balances) as alternatives.

  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 provides explicit when-to-use guidance: 'Use this when no typed convenience tool exists for the endpoint you need.' It also recommends the typed wrappers as good defaults, giving clear direction on choosing 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.

• albyhub_list_appsA
  4.5/5.0
  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 explains the underlying API call ('Hits GET /api/apps') and discloses the typical returned fields, including a caveat that entries 'typically' include these, indicating possible variability. While it doesn't explicitly state read-only behavior, the verb 'List' and the lack of side effects implicitly convey this.

  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 core purpose and then enriched with field details and a use case. Every word earns its place; there is no redundancy or filler.

  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, parameterless list tool with no output schema, the description is complete. It specifies the endpoint, typical response contents, and the practical use case. The sibling tools are clearly different (get balances, list channels, etc.), so no further context is needed.

  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 details to clarify. The baseline for 0 params is 4, and the description adds value by describing the output data structure (fields like name, pubkey, scope, daily budget), which compensates for the absence of an output 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 clearly states the tool lists NWC connections/sub-wallets ('apps') on the Hub, using the specific verb 'List' and a precise resource. It also distinguishes itself from sibling tools by mentioning the included fields (name, pubkey, scope, daily budget, creation timestamp) and the use case of inventorying connections and budget caps.

  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 use case: 'Use this to inventory what's connected to your Hub and what each connection's budget cap is.' This implies when the tool is appropriate, though it does not explicitly mention alternatives or when not to use it. Still, it offers direct guidance on the tool's intended scenario.

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

• albyhub_confirm_requestA
  4.7/5.0
  Behavior5/5

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

  With no annotations, the description must disclose side effects, and it does: the token is 'consumed (single use)' and the safety pipeline re-runs. This gives important context about irreversibility and validation, going well beyond minimal descriptions.

  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 front-load the core action and add necessary conditions and side effects without redundancy. Every clause 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 simple single-parameter tool with no output schema, the description is adequately complete: it explains what the tool does, when it applies, and the key behavioral fact (token consumption). No critical gaps remain for an agent to invoke it 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?

  The input schema already provides a clear description for the token ('Confirmation token from a previous non-GET proxy_request'), giving 100% coverage. The tool description adds extra meaning by noting the token is one-time and tied to a previously-prepared request, enhancing 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 clearly states the tool's function with a specific verb ('Execute') and resource ('previously-prepared non-GET request'). It distinguishes itself from siblings by focusing on confirming/executing an already-prepared request, not on initiating proxy calls or reading node data.

  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?

  Explicitly states the requirement 'Only meaningful when ALBYHUB_REQUIRE_CONFIRM=true' and implies use after receiving a token from a previous proxy_request. However, it doesn't explicitly name the alternative tool (albyhub_proxy_request) or state when not to use it beyond the condition.

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

• albyhub_get_balancesA
  4.7/5.0
  Behavior4/5

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

  No annotations are present, so the description carries full behavioral disclosure burden. It clearly states the operation is a read ('Fetch'), describes what is included (on-chain + lightning), and mentions a specific error case (404) with a workaround. While it doesn't cover authentication or response format, it provides meaningful operational context beyond the bare action.

  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: first states the core function, second differentiates from a sibling tool, third offers a troubleshooting path. Every sentence adds value and is front-loaded with the most important 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 tool with no parameters and no output schema, the description fully covers the essential context: what it fetches, the scope (hub-wide), the difference from a similar tool, and what to do if it fails. Nothing critical 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 tool has zero parameters, so the input schema fully describes the interface, and the description need not explain parameter details. Per the baseline for 0 params, a score of 4 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' with a clear resource 'hub balances' and even names the endpoint 'GET /api/balances'. It also explicitly distinguishes itself from nwc_get_balance, making the tool's purpose immediately clear 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 Guidelines5/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  The description explicitly names an alternative (nwc_get_balance) and explains when to use which: this tool for hub-wide aggregate, that one for a single sub-wallet. It also provides conditional guidance for 404 errors, suggesting albyhub_proxy_request as a fallback, which helps the agent decide between tools.

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

• albyhub_get_node_infoA
  4.7/5.0
  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 reveals the dependent endpoint and warns about version-specific path differences. However, it does not explicitly state that this is a read-only operation (though 'fetch' implies it) or mention any potential side effects, but for a simple info getter 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: the first states the core action and result, the second provides fallback guidance. No wasted words, and the most important information is front-loaded.

  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 parameterless convenience wrapper, this is complete. It describes the endpoint, what info is fetched, and handles version discrepancies. No output schema exists, but the description enumerates the key fields (identity, network, version) so the agent knows what to expect.

  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 already fully documents that. The description adds context by indicating what data is returned (identity, network, version), which is useful even without parameters. Baseline for 0 params is 4, and this meets 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 clearly states the tool fetches Alby Hub node info (identity, network, version) via GET /api/info. It distinguishes itself from siblings by labeling it a convenience wrapper, making the purpose specific 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 Guidelines5/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  It explicitly says to use this tool for node info and provides a concrete fallback: if a 404 occurs, use albyhub_proxy_request to probe alternative endpoints. This gives clear when-to-use and when-to-use-alternative guidance.

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