Server Quality Checklist

Tool Scores

• validate_crab_holeA
  3.5/5.0
  Behavior3/5

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

  Annotations already declare readOnlyHint=true, idempotentHint=true, and destrctiveHint=false, so the bias is covered by structured data. The description adds a small behavioral detail by saying 'native' validators and 'list validators', indicating the tool uses Crab-hole's own mechanism and may produce a list of validators. It does not contradict the annotations, but it also does not reveal any significant new behavioral traits such as output format or system impact.

  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 a single concise sentence that front-loads the core action and the non-destructive guarantee. It contains no filler words. The only issue is grammar awkwardness in 'native configuration and list validators', which slightly reduces clarity but does not waste space.

  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 zero-parameter, read-only tool with supportive annotations, the description covers the essential operation and safety. However, it does not describe what the tool returns or how it relates to validate_posed_config, which is a relevant sibling. The ambiguity between 'list validators' and running them also leaves a small gap in completenes.

  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 the input schema has 100% description coverage. With no params, the description has no additional meaning to provide, so the baseline of 4 applies. The lack of param explanation is irrelevant here.

  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 states a specific verb 'Run' and a resource 'Crab-hole's native configuration and list validators', plus the key constraint 'without changing anything'. It clearly conveys that this validates the active state, and the title 'Validate Active Crab-hole State' reinforces the purpose. However, the phrasing 'configuration and list validators' is slightly awkward and could be misinterpreted as validating a list rather than running validators.

  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 'without changing anything' implies this is a read-only validation, but it does not explicitely state when to use this tool instead of alternatives like validate_proposed_config or get_crab_hole_config. No exclusion or alternative is named, so the usage context is implied rather than explicit.

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

• recent_logsA
  3.6/5.0
  Behavior3/5

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

  Annotations already fully cover safety (readOnlyHint, idempotentHint, destructiveHint=false). The description adds the 'recent' scope and optional error filtering, but it does not clarify what 'recent' means or describe the return format. This is modest added value beyond 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?

  A single front-loaded sentence with no filler. Every phrase adds meaning: the resource is identified first, and the optional errors restriction is appended as a secondary qualifier.

  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 adequate for selecting this tool among unrelated siblings, but gaps remain: 'recent' is undefined, the 'lines' parameter is unexplained, and there is no output schema or note about the response format. An agent can invoke it with defaults, but not with full understanding of the behavior.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters2/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Schema description coverage is 0%, so the description must compensate for parameter meaning. It explains 'errorsOnly' via 'optionally restricted to errors' but does not explain the 'lines' parameter or its numeric bounds/behavior. The description only partially compensates for the schema's lack of documentation.

  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 ('Read') and a clear resource ('recent Crab-hole service logs'), plus an optional error filter. This clearly distinguishes it from sibling tools, which are about config, validation, status, domains, rules, and blocklists—none involve reading logs.

  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 purpose implies usage when recent logs are needed, and the errors-only option hints at a debugging context. However, it does not explicitly name alternatives or state when not to use this tool, so the when-to-use guidance is only 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.

• list_custom_rulesA
  3.7/5.0
  Behavior3/5

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

  The annotations already declare `readOnlyHint: true`, `idempotentHint: true`, and `destructiveHint: false`, so the safety profile is covered. The description adds only a mild behavioral nuance with 'currently stored', implying a live snapshot, but it does not disclose response format, pagination behavior, or ordering semantics.

  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 redundant wording. Every word serves to identify the operation, scope, and object, making it highly efficient for an agent to parse.

  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-only listing tool, the description, schema, and annotations together are mostly sufficient: annotations cover safety, the schema covers the required and optional parameters, and the description states the object being listed. The main omission is the output shape and pagination behavior, especially since there is no output schema, but the risk of mis-invocation is low.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters2/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  Input schema description coverage is 0%, so the description should compensate for parameter meaning. It does relate the `kind` parameter through 'allow or block', but it says nothing about `limit`, its default of 200, or its effect on result size. The schema constraints help, but the description itself adds minimal parameter semantics.

  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'), a specific resource ('custom allow or block entries'), and the location/scope ('stored on the DNS server'). The word 'custom' helps differentiate from siblings like `list_blocklists`, and the allow/block wording maps directly to the required `kind` parameter.

  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 the tool should be used: whenever an agent needs to see custom allow or block rules on the DNS server. However, it provides no explicit guidance about when to use this tool instead of a sibling such as `list_blocklists`, and it does not mention any exclusions or alternative routing.

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

• check_domainA
  3.8/5.0
  Behavior3/5

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

  Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds that it operates against the live backend, implying real-time behavior, but does not disclose output format, potential errors, or rate/load implications. 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?

  The description is a single, front-loaded sentence with no filler. Every word contributes: it names the action, the backend, and the expected result.

  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, read-only tool with strong annotations, the description provides enough context to know what the tool does and what it returns ('whether it is blocked'). There is no output schema, so the description still leaves the exact response shape to inference, but a boolean-style result is reasonable for this use case.

  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 single parameter 'domain' is fully described in the schema ('A DNS name such as example.com'), so schema coverage is 100%. The tool description does not add any additional meaning about the parameter beyond what the schema already provides, 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 uses a specific verb ('Resolve') and names a concrete resource ('the live Crab-hole backend') with a clear outcome ('report whether it is blocked'). This distinguishes check_domain from sibling config/validation tools without requiring schema inspection.

  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 'live Crab-hole backend' implies this is for checking current blocking status rather than inspecting configs or validating proposed changes. However, it does not explicitly state when to use this tool versus siblings like validate_crab_hole or list_blocklists, nor does it provide any exclusions.

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

• list_blocklistsA
  4/5.0
  Behavior3/5

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

  Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so safety behavior is covered. The description adds useful scoping context ('live and local'), but does not disclose details such as whether network calls are made, what the response structure looks like, or how 'live' vs 'local' differs.

  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, front-loaded sentence that states the action, resource, and scope without any filler. Every word earns its place and no unnecessary qualifiers are present.

  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, read-only list tool with comprehensive annotations, the description is nearly complete. It doesn't describe the return format, but the absence of an output schema makes that a minor gap; the core what and where are 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 tool has zero parameters, and schema coverage is vacuously 100%. The baseline for no parameters is 4; the description does not need to explain parameters, and it doesn't attempt to add irrelevant details.

  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 ('List'), a clear resource ('blocklist sources'), and adds scope ('live and local', 'configured in Crab-hole'). It is immediately distinguishable from siblings like list_custom_rules and list_config_backups, so an agent can tell them apart without opening schemas.

  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 purpose is clear enough that an agent can infer when to use it: to view blocklist sources. However, the description gives no explicit guidance on when not to use it or what alternative to choose, though the sibling names are distinct enough that confusion is unlikely.

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

• crab_hole_statusA
  4.1/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true and idempotentHint=true, and the description aligns with these by saying 'Inspect'. The description adds useful context by enumerating the specific status fields covered (health, version, block count, rule counts, memory, blocklist refresh). For a read-only status check, this is sufficient behavioral disclosure.

  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 front-loads the action verb and resource, then lists the key output areas. Every word earns its place with no redundancy.

  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 zero parameters, a clear read-only annotation set, and no output schema, the description fully compensates by listing the main data points returned. An agent can correctly infer what this tool provides and how it differs from config, validation, and listing tools.

  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 are no parameter semantics to clarify. The baseline is 4, and the description instead adds value by describing what the status output covers.

  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 ('Inspect') and a clear resource ('service health, version, current block count, rule counts, memory, and the latest blocklist refresh'), making its purpose as a status/diagnostic tool clear. It distinguishes itself from siblings like get_crab_hole_config and validate_crab_hole by focusing on health metrics rather than configuration or validation.

  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?

  No explicit guidance is given about when to use this tool versus the sibling tools. The context implies it is the go-to for a health/status overview, but it does not mention alternatives or exclusion conditions, leaving the agent to infer usage from the description alone.

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

• list_config_backupsA
  4.1/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description's 'List' wording is consistent with these annotations, and no additional behavioral disclosure is needed for such a simple read 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?

  A single, front-loaded sentence that states the purpose without any filler. 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 simple list tool with one optional parameter and strong annotations, the description is nearly complete. The only missing context is what exactly is included in the returned backup entries, but no output schema exists and the resource is already named.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters2/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  The schema description coverage is 0%, so the description carries the burden of explaining the 'limit' parameter. However, the schema already provides default, minimum, and maximum values, and the parameter name is self-explanatory, so this is a minor gap.

  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' and clearly identifies the resource: configuration and custom-rule backups created by this MCP. This aligns with the title and makes the operation 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 states these backups are 'created by this MCP', providing useful context. While it doesn't explicitly compare to alternatives, the simple read-only nature of the tool makes usage conditions fairly self-evident.

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

• validate_proposed_configA
  4.2/5.0
  Behavior3/5

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

  Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds a useful behavioral detail by explicitly confirming the tool does not install or activate, but it does not describe the validation result, error behavior, or whether it performs full semantic validation versus syntax-only validation.

  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 states the action, the object, and the key behavioral constraint in ten words, earning every word's 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 low-complexity, one-parameter, read-only validation tool, the description plus annotations are largely sufficient for an agent to select and invoke it correctly. The only meaningful omission is an explicit description of the return value or validation outcome, which is somewhat mitigated by the absence of 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 schema has 0% description coverage for the single 'toml' parameter, so the description must carry meaning. It does so by specifying the parameter should contain a 'complete proposed Crab-hole TOML' — adding the 'complete' and 'proposed' qualifiers that are not present in the schema. It could add more on formatting expectations, but the single simple parameter is adequately characterized.

  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 ('validate') with a clear resource ('complete proposed Crab-hole TOML') and immediately scopes the operation as 'without installing or activating it'. This distinguishes it from validating an active/installed configuration and from sibling tools like validate_crab_hole.

  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 implies when to use the tool: when an agent has a proposed TOML and wants to validate it before applying it. It also implies exclusion of install/activate behavior, but it does not explicitly name alternatives such as validate_crab_hole or get_crab_hole_config, so it stops short of full routing guidance.

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

• get_crab_hole_configA
  4.4/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint and idempotentHint, so the description does not need to restate safety. It adds useful behavior context beyond annotations by specifying that the returned data includes both the full active TOML config and its SHA-256 revision.

  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. Every word contributes meaning: scope ('complete active'), format ('TOML'), and additional result detail ('SHA-256 revision').

  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, strongly annotated read-only tool, this description communicates the key facts: what is read and what is returned. It lacks an explicit output shape, but the absence of an output schema is mitigated by the clear statement that the configuration and its SHA-256 revision are returned.

  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 is already exhaustive. Per the baseline for no-parameter tools, this is adequate; the description correctly avoids inventing parameter details that do not exist.

  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 ('Read') and identifies the exact resource ('complete active Crab-hole TOML configuration') plus the associated SHA-256 revision. This clearly distinguishes it from sibling tools like validate_crab_hole, list_config_backups, and crab_hole_status.

  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 establishes the usage context: it is the tool to call when you need the current, complete active configuration and its revision hash. It does not explicitly mention when to prefer alternatives, but the read-only scope is clear enough.

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