Server Quality Checklist

Tool Scores

• mdns_browse_servicesA
  3.9/5.0
  Behavior3/5

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

  Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds that it returns a list of discovered services and provides an example output, but does not elaborate on network dependencies or variability beyond the openWorldHint.

  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 well-organized with sections (intro, Args, Returns, Example), but the first two sentences are redundant, and the Args section largely duplicates the schema, making it slightly longer than necessary.

  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 purpose, parameters, return value (with example), and relationship to a sibling tool. It does not discuss error conditions or network prerequisites, but for a browse tool this is adequate.

  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 contains detailed descriptions for all parameters (service_type, timeout, response_format), so the description's 'Args' section adds minimal new information beyond restating 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 ('browse') and resource ('services of a specific type') and differentiates from sibling tools by mentioning that the results can be used with mdns_get_service_info for details, distinguishing it from related tools like mdns_list_service_types.

  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 when to use the tool (to browse for services of a given type) and implies that mdns_get_service_info is for detailed info, but does not explicitly exclude other use cases or provide guidance on when not to use it.

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

• mdns_register_serviceA
  3.9/5.0
  Behavior4/5

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

  Annotations provide readOnlyHint=false and destructiveHint=false. The description adds that the service will be advertised and host auto-detection is attempted. It does not contradict annotations and adds useful behavioral context beyond them.

  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 well-structured with a clear purpose sentence, an Args section, returns note, and example. It is front-loaded and reasonably concise, though the Args section could be trimmed without losing 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?

  Given the tool has a nested parameter object and output schema exists, the description covers registration parameters, return value, and includes an example. It lacks error conditions or network constraints, but is fairly complete for the complexity level.

  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 all parameters (name, service_type, port, host, text_records). The description repeats these in an Args section but adds minimal new meaning beyond summarizing them. With high schema coverage, 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 'Register a new service on the local network via mDNS' and 'registers a service so other devices on the network can discover it'. The verb 'register' is specific and distinct from sibling tools like mdns_browse_services, mdns_unregister_service, etc.

  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 registering mDNS services but does not explicitly state when to use versus alternatives, prerequisites like network permissions, or when not to use. No direct alternative mentions.

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

• mdns_get_service_infoA
  4.1/5.0
  Behavior4/5

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

  Annotations already indicate readOnlyHint, idempotentHint, destructiveHint=false. Description adds context that it retrieves 'complete information' with specific fields. No contradictions. Could mention network/timeout behavior but annotations cover safety.

  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?

  Description is well-structured with purpose first, then details, then args, then example. Slightly verbose with full Args section and example, but every part adds value. Could be trimmed but still good.

  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, description covers input parameters, return value (string with markdown example), and usage example. Annotations provide safety profile. Output schema not in input but described in text. Fairly complete given tool 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?

  Schema provides full descriptions for all parameters (service_type, service_name, timeout, response_format). Description includes a clear 'Args' section that restates and slightly augments (e.g., default timeout 10.0). Adds value by summarizing parameter purpose beyond schema, even though schema coverage is high.

  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 clearly states 'Get detailed information about a specific mDNS service' and lists specific data items (hostname, IP, port, TXT records). Distinguishes from sibling tools like mdns_browse_services (listing) and mdns_register_service (write operation).

  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?

  Description implies use after browsing (service name from browse results) but does not explicitly state when to use vs alternatives or when not to. No exclusions or alternative tool mentions. Usage context is implied but not explicit.

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

• mdns_unregister_serviceA
  4.2/5.0
  Behavior3/5

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

  The description adds context that the tool removes and stops advertisement, aligning with the destructiveHint annotation. However, it does not elaborate on potential side effects, error conditions, or permission requirements beyond what annotations already convey.

  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 well-structured with sections for purpose, arguments, returns, and an example. It is concise, though the Args section repeats information already present in the input schema.

  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 tool with one parameter, the description covers purpose, usage, parameter details, return value, and provides an example. It is contextually complete given the tool's low complexity and the presence of annotations.

  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?

  With schema description coverage at 0%, the description compensates by explicitly listing the parameter (service_name) with type and a clear example. This adds meaningful semantic value beyond the schema's minimal description.

  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 'unregister' and identifies the resource as 'mDNS service', clearly distinguishing it from sibling tools like mdns_register_service (opposite) and mdns_browse_services (browsing). It explains the effect of removing the service and stopping its advertisement.

  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 for removing previously registered services, which is a clear context. However, it does not explicitly state when not to use the tool or provide alternatives, but the sibling tool names are available for context.

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

• mdns_list_service_typesA
  4.4/5.0
  Behavior4/5

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

  Annotations already indicate readOnlyHint, idempotentHint, openWorldHint, and destructiveHint false. The description adds that it queries the local network and uses a timeout, with no contradictions.

  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 well-structured with a clear verb and resource first, followed by details. The example is helpful but adds length; still concise enough.

  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 annotations (read-only, idempotent) and presence of an output schema, the description is complete: it explains what the tool does, its parameters, and provides an example output, making it fully actionable.

  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 description explains both parameters (timeout and response_format) including defaults and example usage. Although the input schema also has descriptions, the description adds value by clarifying defaults and the example output.

  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 all service types advertised via mDNS, and the example with common types distinguishes it from sibling tools like mdns_browse_services or mdns_get_service_info.

  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 indicates when to use (to list mDNS service types) and implies context (local network), but does not explicitly state when not to use or suggest alternatives, though sibling names provide that context.

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

• mdns_resolve_hostnameA
  4.5/5.0
  Behavior4/5

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

  Annotations already indicate readOnlyHint=true, etc. The description adds behavioral context such as .local suffix requirement and default timeout, which is consistent with annotations. No contradictions.

  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 concise, well-structured with Args, Returns, and Example sections. Every sentence is necessary and adds value without 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?

  For a simple tool with one required parameter, the description covers all necessary aspects: purpose, parameters, return format, and an example. The output schema is implied and sufficient.

  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 provides descriptions for all parameters, so schema description coverage is high. The description adds value with examples and default values, enhancing understanding 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?

  The description clearly states the tool resolves .local hostnames to IP addresses, specifying the exact resource and action. It distinguishes from sibling tools that handle service browsing or registration, as this is solely for hostname resolution.

  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 explains it is useful for finding IPs of mDNS-registered devices without static IPs, but does not explicitly state when not to use it or mention alternatives. The context from sibling tools partially covers this.

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