Server Quality Checklist

Tool Scores

• mcp.tool.databaseC
  2.6/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 description need not restate safety. It does add that only three actions are currently callable and that legacy async actions are unavailable via mcp.help. This is useful context but lacks details on what each action returns or any side effects 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.

  Conciseness2/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is short but poorly structured. It reads as a code snippet with repeated 'mcp.tool.database(action=...)' lines, which are redundant with the tool name and schema. There is no clear prose introduction or hierarchy. While it is concise in length, it wastes space with invocation examples rather than explaining behavior, so it does not earn its place.

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

  Completeness2/5

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

  The tool has three actions and a complex nested payload schema, but no output schema. The description does not explain how the payload fields apply to each action, what outputs to expect, or the distinction between 'current' and 'focused' profiles. The note about legacy actions is helpful but incomplete. Given the complexity, the description is under-specified.

  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 all payload parameters. The description adds no extra meaning about how parameters relate to specific actions—for example, whether get_active accepts a payload or what type/format do for list. It only notes that required fields depend on the action, which is already in the schema. Baseline 3 is appropriate.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose3/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description lists three specific actions (list, get_active, get_focused) with brief descriptions, giving a general sense of the tool's purpose. However, it does not clearly state what the tool overall does (e.g., 'manage database profiles') or differentiate it from sibling tools like mcp.tool.collection or mcp.arango. The action names are self-descriptive but the tool's scope is vague.

  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?

  The only usage guidance is 'Use mcp.help get for explicit unavailable pages for legacy async actions,' which directs users to another tool for legacy actions. There is no explanation of when to use list vs get_active vs get_focused, nor any mention of alternatives within the current tool or across sibling tools. This is minimal guidance.

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

• mcp.tool.atlasC
  2.7/5.0
  Behavior3/5

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

  Annotations declare the tool read-only and idempotent, and the description adds that each action returns a specific profile kind (listing, keyword matches, contract, projection result). However, it does not explain what an Atlas profile is or disclose additional behavior like pagination or output defaults beyond what the schema already provides.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness3/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is concise and each line serves a function, but it is formatted as a terse command help block without an introductory sentence. It is not overlong, but the lack of prose makes it less readable and less front-loaded with purpose.

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

  Completeness2/5

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

  Given the tool's complexity (four actions, nested parameters, no output schema), the description is insufficient. It provides action examples but omits context about how actions relate, the semantics of targets like 'atlas.types' or 'atlas.index', and how it fits with sibling tools, leaving an agent with gaps in understanding.

  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 documents all payload parameters and nested fields with descriptions. The description's example payloads illustrate common combinations (e.g., keywords for search, target and params for call), but they do not add significant meaning beyond the schema's existing descriptions.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose3/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description is a list of action examples (list, search, describe, call) with sample payloads, implying the tool queries Atlas profiles. However, it lacks a concise statement of what the tool does and does not differentiate it from sibling tools like mcp.arango or mcp.tool.database.

  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?

  There is no explicit guidance on when to use this tool or how to choose among the four actions. The examples show usage patterns but do not mention alternatives, prerequisites, or when to prefer another tool.

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

• mcp.mcpB
  3.1/5.0
  Behavior2/5

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

  Annotations include destructiveHint=true and readOnlyHint=false, but the description adds no context about side effects, especially for 'unload' which likely has destructive consequences. The phrase 'Unload request result' is vague and does not disclose what unloading entails or any irreversible actions. The description neither contradicts the annotations nor enriches them, leaving the destructive behavior unexplained.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness3/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is a compact list of three action-example pairs, but each line repeats the tool name and invocation pattern (e.g., 'mcp.mcp(action=..., payload=...)'), which is redundant. The structure is not front-loaded with a clear overall purpose; the key information is distributed across lines. It is concise in word count but could be better organized with a summary line first and examples as illustrations.

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

  Completeness2/5

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

  For a metadata/discovery tool with three distinct operations and no output schema, the description is thin. It does not explain what 'list_by_category' returns, how the 'format' parameter affects output, or what an 'unload request result' looks like. The relationship to sibling tools like mcp.help is unaddressed, and the destructive nature of unload is not elaborated. Given the tool's complexity, the description is incomplete.

  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 coverage is 100% for parameters, and the description adds concrete examples for payload structures (e.g., 'payload={"keywords":["collection"],"limit":5}') for search_tools, and shows the format of unload's payload. These examples clarify parameter syntax and expected shapes beyond the schema's generic descriptions. The action enum is semantically mapped to each example, aiding correct invocation.

  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 clearly enumerates three distinct actions (search_tools, list_by_category, unload) with brief functional tags ('Filtered tool/action catalog matches', 'Tool categories listing', 'Unload request result'). It distinguishes actions from each other, though it lacks a single overarching statement like 'Tool discovery and metadata' which only appears in the schema description. The resource is the mcp tool catalog, and verbs are search/list/unload.

  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 contexts for each action (e.g., 'search_tools' for finding tools by keywords, 'list_by_category' for listing categories, 'unload' for unloading tools), but it does not explicitly state when to use this tool versus alternatives like mcp.help or when not to use it. No exclusions or alternative tool references are provided, so guidance is only implicit.

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

• mcp.tool.collectionB
  3.2/5.0
  Behavior3/5

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

  Annotations already declare readOnlyHint=false and destructiveHint=true, and the description lists destructive actions (drop, truncate, remove) without explicit warnings but with result hints like 'Dropped collection.' This adds some behavioral context by showing what each action returns, but it does not disclose permissions required, irreversibility, or side effects beyond the annotation flags. The schema description also mentions server-side enforcement of required fields, which is a mild behavioral note.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness3/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is long and repetitive, repeating 'mcp.tool.collection(action=' for every action, which adds bulk. However, it is organized as a clear list with action names and result descriptions, making it scannable despite its length. Each line earns its place by documenting a distinct action, but the repetition could be streamlined.

  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 combination of the action list and the input schema covers all 16 actions and all payload fields, and the schema explicitly states that required fields depend on the action. However, the description does not enumerate which fields are mandatory for each action beyond the examples, leaving ambiguity for less common actions like import/export. No output schema exists, so return-value completeness is not fully addressed, but the description hints at result types (e.g., 'Inserted document').

  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 has 100% field coverage, but the description enriches parameter meaning by providing example payloads for each action. For instance, it shows insert uses collection and document, while delete_index uses id_or_name, mapping the generic payload fields to specific operations. This helps the agent understand which parameters apply to which action, exceeding the schema's flat field descriptions.

  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 lists 16 distinct actions (insert, find, update, remove, etc.) with specific verbs and resources, making it clear that this tool handles collection operations. It differentiates from sibling tools (mcp.tool.database, mcp.tool.view) by focusing exclusively on collection actions. However, there is no explicit top-level statement like 'Manages ArangoDB collections,' so it slightly misses a clear overarching purpose.

  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?

  The description does not provide guidance on when to use this tool versus alternatives like mcp.tool.database or mcp.tool.view. The only hint is in the schema description: 'Use mcp.help get for explicit unavailable pages for legacy async actions,' which is a narrow fallback. No exclusions or contextual triggers are given.

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

• mcp.tool.graphA
  3.5/5.0
  Behavior3/5

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

  Annotations already declare readOnlyHint=false and destructiveHint=true, so the description need not repeat that. It adds context that required payload fields depend on action and are enforced by the 'graph owner,' plus notes about legacy actions being unavailable. However, it does not elaborate on specific side effects or error behavior beyond the examples.

  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 compact list of five examples, each on its own line, which is easy to scan. There is some redundancy in repeating 'mcp.tool.graph(action=..., payload=...)' for every line, but the overall length is reasonable and every line provides actionable example syntax.

  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?

  Given the tool's multi-action nature and lack of output schema, the description covers the five callable actions with examples but leaves some gaps. It does not explain return values in any detail (beyond result phrases like 'Graph listing'), nor does it discuss how to handle errors or which payload fields are required or optional for each action. The examples are helpful but not exhaustive.

  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 coverage is 100%, so baseline is 3, but the description adds value by showing concrete payload examples for each action, mapping parameters to their relevant actions (e.g., create uses name and edge_definitions; add_edge uses graph, collection, from_id, to_id). This compensates for the schema's broad parameter list and helps an agent construct correct payloads.

  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 opens with example actions ('create - Created graph. mcp.tool.graph(action=create, ...)'), making it clear this tool performs graph operations. It distinguishes from sibling tools by naming graph-specific actions (create, list, add_vertex_collection, add_edge_definition, add_edge), though it lacks a concise one-sentence purpose statement.

  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 via the listed callable actions and examples, but does not explicitly state when to choose this tool over siblings like mcp.tool.collection or mcp.tool.database. It does provide one alternative hint: 'Use mcp.help get for explicit unavailable pages for legacy async actions,' yet that is about availability, not usage context.

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

• mcp.tool.adminA
  3.6/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 well covered. The description adds the list of callable actions and example payloads, and the schema notes that required fields depend on the action and are enforced by the admin owner. It does not disclose output format, error behavior, or action-specific required fields in detail, so transparency is average.

  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 compact list of three action-result mappings with examples, requiring only six lines. It is front-loaded with action names and avoids verbose prose, though the examples are somewhat repetitive with the schema content.

  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 schema is rich, but the description does not fully specify which payload fields apply to each of the three actions, and there is no output schema to clarify the result shape. The example payload covers the common 'query' field for all actions, and the note about legacy async actions adds context. Overall, minimally adequate but with gaps around action-specific required fields and return details.

  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 coverage is 100%, so the schema already describes the action enum and payload properties. The description's examples show the exact invocation shape with payload containing 'query', which reinforces parameter usage but does not add detailed semantics for optional parameters like bindVars, max_plans, or format. Baseline of 3 applies.

  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 enumerates three specific admin operations (aql_query, aql_explain, aql_profile) with concrete invocation examples, making the tool's purpose clear. It is not a tautology—it identifies the tool as an admin action dispatcher—but it does not explicitly contrast with sibling tools like mcp.arango or mcp.tool.collection, so it stops short of a 5.

  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 and schema note that only aql_query, aql_explain, and aql_profile are currently callable, which tells the agent when to use this tool for those operations. It also directs legacy async actions to mcp.help get, providing an exclusion/alternative. However, it does not provide explicit when/when-not guidance for other sibling tools, so it is not a perfect 5.

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

• mcp.tool.templateA
  3.7/5.0
  Behavior4/5

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

  Annotations already flag destructiveHint=true and readOnlyHint=false. The description adds useful context by stating that the 'call' action may result in 'catalog mutation' or 'validate report', which clarifies behavioral outcomes beyond the annotations. It does not contradict annotations, and the added detail about mutation and validation improves transparency.

  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 compact and uses a consistent line-per-action format, making it scannable. Each line includes a verb, a brief description, and an example call. It could be more readable with a summary sentence, but it avoids unnecessary words and is appropriately sized for the tool's complexity.

  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 tool has four distinct actions and no output schema, so the description must cover usage fully. It gives examples for all actions, but omits details about return values, error cases, and the full range of meta targets (e.g., meta.create) which are only in the schema. The schema covers some gaps, but the description alone is not fully self-sufficient for a complex tool.

  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 only 50% schema description coverage, the description compensates by providing concrete payload examples for each action, showing how to combine 'target', 'params', 'keywords', and 'limit'. This explains which parameters are relevant per action, which the schema alone does not. It adds practical meaning beyond the structured field definitions.

  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 clearly identifies the resource (template catalog) and four actions (list, search, describe, call) with example invocations. It distinguishes itself from sibling tools by focusing specifically on template ownership and catalog operations. However, it lacks a plain-language summary sentence, relying instead on terse examples, so it is clear but not maximally explicit.

  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 examples imply when to use each action (e.g., list to list, search to search), but there is no explicit guidance on when to choose this tool over sibling tools or when not to use it. The description does not mention alternatives or exclusions, so usage context is only implied.

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

• mcp.tool.viewA
  3.9/5.0
  Behavior3/5

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

  The annotations already declare readOnlyHint=false and destructiveHint=true, so the description does not need to repeat safety traits. It adds the action list and example payloads, which clarify that drop and update are destructive, but it does not disclose deeper behaviors like authentication requirements, rate limits, or exact effects on existing views. No contradiction with annotations.

  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 compact, line-per-action list with example invocations. It front-loads the action name and gives a clear pattern. While somewhat lengthy, every line adds concrete utility, and there is no filler or redundancy.

  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 multi-action tool with no output schema, the description provides example invocations that imply expected return messages (e.g., 'Created View.'). It also illustrates required payload fields for each action (e.g., create needs name/type, search needs query). Combined with the schema, it gives a solid understanding, though it does not explicitly describe return formats or error behavior.

  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 covers both parameters with descriptions, giving a baseline of 3. The description goes beyond by providing concrete JSON payload examples for each action, which clarifies how to structure the payload object and which fields are relevant per action. This practical guidance is valuable for correct invocation.

  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 enumerates each operation with a distinct verb and resource: create, drop, list, get, update, search. It explicitly focuses on ArangoSearch views, distinguishing from sibling tools like mcp.tool.collection and mcp.tool.graph. The examples provide concrete context for each action.

  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 by showing example invocations for each action, but it does not explicitly state when to prefer this tool over siblings (e.g., 'use this for view management and search'). No exclusions or alternative tool references are provided, so the guidance is only implicit.

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

• mcp.arangoA
  4.1/5.0
  Behavior4/5

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

  Annotations already flag destructiveHint=true, so the agent knows operations may be destructive. The description adds valuable behavioral detail by specifying the output type for each action: raw HTTP response for exec, summaries for list, matches for search, and contract for describe. It does not detail potential side effects or rate limits, but the annotation covers the safety profile.

  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 compact bullet-style list of five actions with examples, front-loading the action names and using a consistent pattern. It is efficient and without fluff, though an introductory line stating the overall purpose would make it slightly clearer and more self-contained.

  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 dispatcher tool with five nested actions and no output schema, the description provides per-action output descriptions and examples, covering discovery (list/search) and execution (exec/describe/call). It does not elaborate on pagination, error handling, or authentication, but the schema description adds context about exposing OpenAPI operations without hundreds of separate 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 schema already covers 50% of parameter descriptions (e.g., target required for describe/exec/call, query for search, limit). The description adds concrete payload examples for each action, such as payload={"target":"getServerAvailability","params":{}} for exec versus payload={"target":"getServerAvailability"} for describe, clarifying how parameters map to actions beyond the schema's generic field 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 description clearly enumerates each action with a specific verb and result: list returns 'summaries', search returns 'matches', exec returns 'Raw ArangoDB HTTP response', describe returns 'operation contract', and call is a 'compatibility alias for exec'. This distinguishes the sub-actions from each other and from sibling MCP tools, providing a precise purpose.

  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 via examples (e.g., search with query, exec with target), and the schema mentions 'Prefer search -> exec; call remains as a compatibility alias,' but the description itself does not explicitly state when to use the tool overall or when to choose one action over another. It lacks direct exclusions or alternative tool references.

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

• mcp.helpA
  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, aligning with the get/list actions. The description adds context that the help content is 'schema-owned' and sourced from the same schema powering tools/list, which helps set expectations about the nature of the returned data. It doesn't delve into error handling or edge cases, but this is a simple read-only introspection tool.

  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 extremely efficient: two lines, one for each action, each with a terse definition and a concrete call example. There is no filler or repetition. The format is scannable and immediately conveys the tool's interface.

  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 read-only help tool with a simple two-parameter interface and clear examples, the description fully covers what an agent needs to invoke it correctly. The nested payload structure is demonstrated, and the output format is managed by the schema. No additional context is necessary for a tool of this 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 description coverage is 100% and the schema already defines all parameters (action, payload, target, format). The description enriches understanding by providing inline examples of valid payload structures (e.g., payload={'target':'mcp.tool.collection','action':'insert'}) and by clarifying the relationship between target/action and the get/list operations. This goes beyond the schema's generic 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 description clearly identifies two distinct actions ('get' and 'list') with explicit verbs and resources ('Return the full schema-owned help page' and 'List schema-owned help actions'). It includes concrete examples that show exactly how to invoke each operation, making the purpose unambiguous and distinct from sibling tools.

  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 this tool (to retrieve help documentation) and provides usage examples for both actions. It doesn't explicitly exclude alternatives, but given the sibling tools are all domain tools, the help tool's role is self-evident. A small gap is not mentioning that this tool is for exploring schemas rather than executing actions.

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