Server Quality Checklist

Tool Scores

• invoke_toolA
  4.2/5.0
  Behavior4/5

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

  The description discloses that the tool can perform both read and write operations and recommends reviewing target tool annotations, adding nuance beyond the binary destructiveHint annotation. The safety guidance is actionable and does not contradict 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?

  Two sentences clearly state the core purpose and safety considerations without wasted words. The description is front-loaded and easy to scan.

  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 essential aspects: what the tool does, how to invoke it safely, and parameter usage is handled by the schema. Since an output schema exists, omitting return-value details is acceptable.

  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 already documents both toolName and arguments thoroughly. The description adds minimal extra meaning beyond using the phrase 'exact name', but with full schema coverage this is acceptable.

  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 invokes a proxy-visible Huly tool by exact name with arguments, using a specific verb and resource. This distinguishes it from siblings like get_tool_schema or search_tools, making its 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 mentions the tool can call read or write operations and advises checking get_tool_schema and target annotations when safety matters. This provides useful context for when to use it, though it could more explicitly contrast with alternative tools.

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

• list_tool_categoriesA
  4.3/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 the description adds little beyond purpose. It doesn't mention additional behaviors like pagination, permissions, or response format. The phrase 'available through this proxy' adds some context, but overall no significant extra 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 exactly two sentences, front-loaded with the core action, and every word earns its place. 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 zero-parameter, read-only listing tool with an output schema present, the description alone is sufficient. It covers what the tool does and when to use it, leaving no critical gaps 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 tool has zero parameters, so there are no parameter semantics to explain. The description doesn't need to compensate for schema gaps, and with 100% schema coverage and no params, a baseline 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 states a specific action ('Lists Huly tool categories') and identifies the resource ('available through this proxy'). It distinguishes itself from sibling tools like search_tools by focusing on a broad capability map rather than specific tool discovery.

  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?

  Provides explicit usage context: 'Use this first when you need a broad map of capabilities before searching for a specific Huly tool.' This clearly indicates when to invoke it, though it doesn't name alternatives directly or state 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.

• search_toolsA
  4.3/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, and the description adds meaningful context beyond them: the 'current proxy-visible' scoping constraint, the guarantee of 'exact tool names plus required and optional parameter names' output, and the single-call follow-up flow. It omits minor behavioral details like case-insensitivity or empty-result behavior, but with strong annotations the added context is well above baseline.

  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 exactly two sentences with zero filler: the first states the action and scope, the second states the output shape and the intended next steps. Every clause earns its place, and it adds no redundancy with the title, schema, or annotations.

  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 2-parameter search tool with a present output schema and comprehensive annotations, the description covers all material selection and invocation guidance: catalog scope (proxy-visible), match dimensions, result granularity, and follow-up flow. The output schema removes the need to document return values, and parameter syntax is fully covered by the schema, leaving no significant gap.

  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%: the 'query' parameter is fully documented as matching names, categories, descriptions, and parameter names, and 'limit' documents its default (10) and maximum (50). The tool description reinforces the query semantics and return shape but adds no new per-parameter detail, matching the high-coverage baseline of 3.

  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 specifies the verb 'Searches' with a precise resource ('Huly tool catalog') and search dimensions (tool name, category, description, parameter names). It distinguishes itself from siblings by describing the exact-name output and explicitly naming get_tool_schema/invoke_tool as follow-up destinations, clearly separating it from list_tool_categories and get_tool_schema.

  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 establishes clear context: it is the discovery entry point for the proxy-visible catalog, with explicit follow-up guidance to get_tool_schema or invoke_tool. However, it never states when not to use it or points to an alternative (e.g., going directly to get_tool_schema when the tool name is already known), so it has clear context but no exclusions.

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

• get_tool_schemaA
  4.5/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 adds context that the tool returns both input and output schemas and is scoped to proxy-visible tools, which provides value beyond the annotations. No contradiction exists.

  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 sentences that are front-loaded with the primary function and then give usage guidance. Every word contributes meaning, 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?

  For a one-parameter tool with a robust output schema and strong annotations, the description covers what is returned, when to use it, and where to get the parameter value. The output schema handles return structure, so the description is sufficiently complete.

  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 has 100% coverage with a well-described 'toolName' parameter that explains the source of the value. The description does not add additional parameter semantics beyond the schema, 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 the specific verb 'Returns' and explicitly names the resource 'exact input and output schema for one proxy-visible Huly tool.' It clearly distinguishes from siblings like search_tools (which discovers tools) and invoke_tool (which executes tools) by focusing on schema retrieval.

  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 'Use this before invoke_tool when you are not certain about required argument names or result shape,' providing a direct when-to-use and naming the alternative workflow. This is clear usage guidance within the tool's context.

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

• get_versionA
  4.5/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, so the safety profile is covered. The description adds that it queries npm for the latest version, which implies an external network call—a useful behavioral detail not captured in the annotations. It does not contradict any 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 a single sentence that front-loads the action ('Returns the current version') and the specific details. Every word earns its place, with no unnecessary 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?

  The tool is extremely simple with no parameters and a provided output schema, so the description fully covers the tool's purpose and behavior. The mention of npm as the source for the latest version adds necessary context beyond the 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 adds no parameter-specific information, but none is needed since the input schema is empty and the function is self-contained.

  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 the current version of the Huly MCP server and the latest version on npm, using the specific verb 'returns' with a concrete resource. This distinguishes it from sibling tools, none of which are version-related.

  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: use this tool when you need version information. It clearly states what it does but does not explicitly mention alternatives or when-not-to-use scenarios. Given the tool's simplicity and lack of competing tools, the context is clear enough to warrant a 4.

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

• get_huly_contextA
  4.7/5.0
  Behavior5/5

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

  Annotations already declare readOnly, idempotent, and non-destructive hints, but the description adds critical behavioral guarantees: it does not connect to Huly and never returns secrets (tokens, passwords, credential headers). This goes beyond the structured metadata and is highly valuable for an AI agent's safety reasoning.

  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 front-loads the primary purpose and contents, the second adds essential safety caveats. Every word earns its place; it is concise, structured, and free of 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?

  Given the tool's simplicity (no params, rich output list) and the presence of an output schema (mentioned in signals), the description sufficiently covers the return values and usage context. It also notes the lack of network interaction and secret exposure, making the tool's behavior fully predictable. Sibling tool differentiation is implicitly clear.

  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 description does not need to elaborate on parameter meaning. Baseline for 0 params is 4, and the description appropriately focuses on what the tool returns rather than input 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 clearly states the tool returns sanitized runtime and configuration context for the Huly MCP session, enumerating specific contents like version, transport, auth mode, etc. This distinguishes it from sibling tools like get_version (specific version only) and get_tool_schema (schema). The verb 'returns' plus resource makes 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 usage for retrieving session context without connecting to Huly, making it safe for preliminary checks. It does not explicitly contrast with alternatives (e.g., 'for version only, use get_version'), but the context is clear enough for an agent to infer when to call it.

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