Server Quality Checklist

Tool Scores

• get_collections_in_scopeA
  3.5/5.0
  Behavior2/5

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

  The annotations already include readOnlyHint=true, and the description only restates the operation as a read (Get). No additional behavioral traits are disclosed, such as potential errors, permission requirements, or limitations beyond what the annotations convey.

  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?

  Single sentence, clear subject-verb-object, no unnecessary words. Perfectly concise for the tool's simplicity.

  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 two self-explanatory parameters and an existing output schema, the description covers the essential function. It could mention that it only returns names (not full collection details) but the title and context imply that. Slight gap in not specifying the output format, but acceptable.

  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 should compensate by explaining parameter semantics. However, it only repeats the parameter names ('given scope and bucket') without adding constraints, formats, or examples. The self-explanatory names partially mitigate this, but the description adds little value.

  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 explicitly states 'Get the names of all collections in the given scope and bucket.' This clearly identifies the action (get names) and the resource (collections filtered by scope and bucket), distinguishing it from siblings like get_scopes_and_collections_in_bucket which operates at a different granularity.

  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 when you need collections within a specific scope and bucket, but does not provide explicit guidance on when to use this tool versus alternatives like get_scopes_and_collections_in_bucket, nor does it mention any exclusions or prerequisites.

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

• explain_sql_plus_plus_queryA
  3.6/5.0
  Behavior3/5

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

  The annotations already indicate readOnlyHint=true, and the description confirms it runs the EXPLAIN statement and returns metadata, but adds no additional behavioral insights beyond the obvious.

  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, three sentences, front-loaded with purpose, and contains no extraneous information.

  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?

  While the output schema exists and the description mentions return values, the lack of parameter descriptions and usage context lowers completeness.

  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?

  With 0% schema description coverage, the description fails to explain the parameters beyond mentioning 'specified scope' and 'bucket', leaving their purposes ambiguous.

  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 it generates and evaluates an EXPLAIN plan for SQL++ queries, distinguishing it from the sibling 'run_sql_plus_plus_query' which executes queries.

  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 use for analyzing execution plans but lacks explicit guidance on when to use this tool versus executing the query directly, nor does it mention alternatives.

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

• get_document_by_idA
  3.7/5.0
  Behavior3/5

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

  Annotations already declare readOnlyHint=true. The description adds that an exception is raised if the document is not found, which is useful behavioral context beyond what annotations provide. No other behaviors are disclosed, but for a simple read, this is adequate.

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

  Conciseness5/5

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

  The description is extremely concise with two sentences. The first sentence states the core purpose, and the second adds an important behavioral note. No redundant or unnecessary words.

  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 document retrieval tool with an output schema (not shown but present), the description covers the essential action and a key edge case (exception on not found). It does not mention the output structure, but that is handled by the output schema. A minor improvement would be to clarify that it retrieves a single document, but overall it is sufficiently complete.

  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 input schema has 0% description coverage. The description only mentions scope and collection, partially explaining two of four parameters. Bucket_name and document_id are not explained, leaving the agent without full clarity on parameter roles. The description does not compensate adequately for the lack of schema 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 states the action (get a document) and the resources (by ID, from scope and collection). The tool name is explicit and distinguishes it from sibling tools which are about queries, indexes, and cluster info.

  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 retrieving a specific document but gives no explicit guidance on when to use versus alternatives or when not to use. Among siblings, no other tool directly retrieves a single document, so context is implied, but explicit guidelines are absent.

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

• get_queries_not_selectiveA
  3.8/5.0
  Behavior3/5

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

  Annotations already declare readOnlyHint=true, so the safety profile is known. The description adds that this reads from the system:completed_requests catalog, which is useful context, but it does not explain how selectivity is determined, ordering, or other behavioral details.

  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 with no filler. The main purpose is front-loaded, and the usage preference over run_sql_plus_plus_query is immediately actionable.

  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 catalog query with an output schema, the description is largely sufficient. It names the source and provides a clear usage preference, though a more precise definition of 'not very selective' would help differentiate among the many sibling query-analysis tools.

  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 only parameter, limit, is already fully described in the schema with default behavior. The description adds no additional parameter meaning, so the baseline score 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 states a specific action and resource: getting non-selective queries from system:completed_requests. It is clear even though 'not very selective' is not precisely defined, and it is distinguishable from the raw run_sql_plus_plus_query alternative.

  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 explicitly says to prefer this tool over writing a raw system:completed_requests query via run_sql_plus_plus_query. This gives clear guidance on the main alternative, though it does not discuss sibling get_queries_* tools.

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

• get_scopes_in_bucketA
  3.8/5.0
  Behavior3/5

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

  Annotations already declare readOnlyHint=true, so the description adds no extra behavioral context. It does not mention permissions, error handling, or prerequisites beyond the obvious 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?

  Single sentence that is front-loaded and contains no extraneous information. 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 read-only tool with one parameter and an output schema, the description is largely sufficient. It could mention that the bucket must exist, but overall it 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?

  With 0% schema description coverage, the parameter 'bucket_name' is self-explanatory from the tool name and description. However, no additional constraints or format details are provided.

  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 the action (Get) and resource (names of all scopes in a bucket), precisely distinguishing it from siblings like get_scopes_and_collections_in_bucket which returns both scopes and collections.

  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?

  No explicit guidance on when to use this tool vs alternatives; usage is implied by the name and description, but no when-not or mention of sibling tools like get_scopes_and_collections_in_bucket.

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

• get_schema_for_collectionA
  3.9/5.0
  Behavior4/5

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

  The annotations declare readOnlyHint=true consistently. The description adds behavioral context by specifying that it runs an INFER query and returns a dictionary with collection name and schema, which is beyond the annotation. 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?

  Two sentences, each serving a distinct purpose: first for action and resource, second for return value and implementation detail. No extraneous content.

  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 that an output schema exists, the description adequately explains the return value (dictionary with name and schema) and the underlying mechanism (INFER query). It lacks mention of prerequisites like bucket existence, but for a read-only schema tool, it is fairly complete.

  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 has 0% description coverage, but parameter names are self-explanatory (bucket_name, scope_name, collection_name). The description mentions 'specified scope' but doesn't explain each parameter's purpose or format. With low schema coverage, more compensation is needed.

  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 verb 'Get the schema' and the resource 'collection in the specified scope', and it directly contrasts with sibling tools like 'get_collections_in_scope' which return lists rather than schemas. The mention of 'INFER query' adds specificity.

  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 explains what the tool does but provides no guidance on when to use it versus alternatives like 'get_scopes_and_collections_in_bucket' or 'run_sql_plus_plus_query'. Usage context is implied but not explicitly clarified.

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

• get_queries_with_large_result_countA
  4/5.0
  Behavior3/5

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

  The readOnlyHint annotation already establishes the safety profile, lowering the bar for the description. The description adds the useful context that this reads from the system:completed_requests catalog, but it does not disclose ordering, limit behavior, or any performance implications of large result counts. It meets the minimum for a read-only convenience 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?

  Two short sentences, no wasted words. The purpose is stated first, followed by a clear usage directive. The structure is front-loaded and every sentence 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 read-only tool with one optional parameter and an output schema present, the description is nearly complete. It names the source catalog and provides routing context. It could go slightly further by clarifying the ordering or default behavior, but the schema and annotations cover most of what an agent needs.

  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%, with the 'limit' parameter fully documented in the schema. The description adds no additional parameter meaning, so the baseline 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 states a specific verb ('Get'), a precise resource ('queries with the largest result counts'), and the source catalog ('system:completed_requests'). It also differentiates this tool from the raw query tool by explicitly recommending it over writing a raw system:completed_requests query via run_sql_plus_plus_query.

  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 second sentence provides explicit usage guidance: prefer this over a raw system:completed_requests query. It names the alternative tool, but it does not mention when not to use this tool or which sibling to choose for other query-analytics concerns (e.g., response sizes or runtime).

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

• get_queries_not_using_covering_indexA
  4.1/5.0
  Behavior3/5

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

  Annotations declare readOnlyHint=true, so the safety profile is already covered. The description adds the source catalog and the preference over raw SQL, but does not disclose additional behavioral traits such as return format or performance characteristics. This is consistent with the annotation and adds only modest context beyond it.

  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 with no filler. The purpose is front-loaded, and the usage guidance is placed in a clear second sentence. Every sentence earns its place.

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

  Completeness5/5

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

  For a simple read-only tool with one documented parameter and an output schema, the description is complete. It identifies the data source, the specific filtering criterion, and the recommended way to use it relative to raw SQL. Nothing required to call the tool correctly is missing.

  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 'limit' is fully described in the input schema, including its default value. The tool description adds no 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?

  States a specific verb ('Get'), a specific resource ('queries that don't use a covering index'), and the exact source catalog ('system:completed_requests'). This clearly distinguishes it from the raw query tool and, by the phrase 'don't use a covering index', from sibling query-analysis tools with different criteria.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines4/5

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

  Explicitly says to prefer this tool over writing a raw system:completed_requests query via run_sql_plus_plus_query, giving the agent a clear routing instruction. It does not provide exclusions or compare to other sibling query-analysis tools, but the primary alternative is named and handled.

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

• get_queries_using_primary_indexA
  4.1/5.0
  Behavior3/5

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

  Annotations already declare readOnlyHint=true, so the description need not restate safety. It adds the source catalog and frames the tool as a safer or more convenient alternative to raw queries, but it does not disclose potential costs, limitations, or details about matching behavior 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?

  Two short sentences with no filler. The primary purpose is front-loaded, and the usage guidance is compact and immediately actionable.

  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 read-only tool with one optional parameter, an output schema, and a clear source catalog, the description is complete. An agent has enough to select and invoke the tool correctly.

  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?

  There is only one parameter, limit, and its schema description covers it fully (100% coverage). The tool description adds no extra parameter guidance, so the baseline 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 names a specific verb ('Get'), a clear resource ('queries that use a primary index'), and the source catalog ('system:completed_requests'). This distinguishes it from sibling query-analysis tools like get_queries_not_selective or get_longest_running_queries 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 Guidelines4/5

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

  The second sentence explicitly tells the agent to prefer this tool over writing a raw system:completed_requests query via run_sql_plus_plus_query. It names an alternative and gives a clear preference, though it does not enumerate exclusions or when to choose among the other query-inspection siblings.

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

• get_scopes_and_collections_in_bucketA
  4.2/5.0
  Behavior4/5

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

  The description adds value beyond the readOnlyHint annotation by detailing the return format (dictionary of scope names to collection lists). No behavioral 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 two short sentences with no unnecessary words, front-loading the action and return format.

  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 adequately covers the tool's purpose and output for a simple read operation. With an output schema likely defining details, it is moderately complete, though it omits error conditions.

  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?

  Despite 0% schema description coverage, the parameter bucket_name is self-explanatory and the description mentions 'in the bucket', which sufficiently clarifies its role.

  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 retrieves names of all scopes and collections in a bucket, distinguishing it from siblings like get_scopes_in_bucket (only scopes) and get_collections_in_scope (collections for a specific scope).

  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 does not explicitly state when to use this tool versus alternatives like get_scopes_in_bucket or get_collections_in_scope. Usage context is implied by the purpose, but no direct guidance is provided.

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

• get_buckets_in_clusterA
  4.3/5.0
  Behavior4/5

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

  Annotations indicate readOnlyHint=true and description adds that only 'accessible' buckets are returned. This is consistent and provides basic behavioral context beyond the annotation.

  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?

  Single sentence, 8 words, directly states purpose. No wasted words, front-loaded with the key action.

  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 has no parameters, an output schema exists, and the description mentions 'names', the description is complete for an agent to understand the tool's function and expected output.

  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 has zero parameters with 100% coverage, so the description does not need to add parameter details. The description adds no parameter info, which 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 the tool 'Get the names of all the accessible buckets in the cluster', specifying the resource (buckets), scope (accessible in the cluster), and output (names). It distinguishes from sibling tools like get_scopes_in_bucket and get_collections_in_scope.

  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 listing all accessible buckets, but does not explicitly mention when to use versus alternatives or provide conditions for use. With 19 siblings, more explicit guidance would improve clarity.

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

• get_index_advisor_recommendationsA
  4.3/5.0
  Behavior5/5

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

  Annotations indicate readOnlyHint=true, and the description reinforces this by stating the tool 'analyzes' and 'provides recommendations' without mentioning side effects. It also details the return structure, offering full transparency about what the tool does and returns.

  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 well-structured with front-loaded purpose and bullet points for return values. Every sentence adds value without redundancy, making it concise 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?

  Given three required parameters and no output schema in structured form, the description provides detailed return information and input constraints (query types, scope/bucket). It lacks error handling or prerequisites but is otherwise complete for the tool's domain.

  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 coverage is 0%, yet the description does not describe individual parameters (bucket_name, scope_name, query) beyond mentioning 'specified scope' and 'specified bucket'. It fails to compensate for the lack of schema descriptions, leaving parameter semantics vague.

  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 gets index recommendations from Couchbase Index Advisor for a SQL++ query. It specifies the verb 'get' and resource 'index recommendations', and distinguishes from siblings like 'explain_sql_plus_plus_query' and 'list_indexes' by focusing on recommendation generation.

  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 works with SELECT, UPDATE, DELETE, or MERGE queries and operates on a specified scope and bucket. However, it does not explicitly state when to use this tool versus alternatives like 'list_indexes' or 'explain_sql_plus_plus_query', so guidance is clear but incomplete.

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

• get_most_frequent_queriesA
  4.3/5.0
  Behavior3/5

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

  The annotations already declare readOnlyHint=true, covering the operation's safety profile. The description adds the data source and the aggregating nature of the tool, but does not define what 'most frequent' means precisely (e.g., execution count vs. duration) or whether a time window applies.

  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 short sentences with the core operation front-loaded and a useful routing hint in the second sentence. There is no redundant or filler content.

  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 single optional parameter, read-only annotations, and an existing output schema, the description provides enough context to correctly select and invoke the tool. It names the source catalog and tells the agent when to prefer this tool over the raw query alternative.

  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%, with the single limit parameter fully documented in the schema. The description does not add any syntax or format detail beyond 'N', so baseline 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 states a specific verb ('Get'), a specified resource ('N most frequent queries from the system:completed_requests catalog'), and differentiates from raw SQL querying via run_sql_plus_plus_query. This makes the tool's purpose and scope clear.

  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 tells the agent to prefer this tool over writing a raw system:completed_requests query via run_sql_plus_plus_query. This names the relevant alternative and provides a clear when-to-use directive.

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

• get_queries_with_largest_response_sizesA
  4.3/5.0
  Behavior3/5

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

  Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds that the data comes from system:completed_requests and that results are the largest response sizes, but it does not disclose details such as ordering ties, result semantics, or performance characteristics; these are minor given the read-only annotation.

  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 carry the core function and the routing preference with no filler. The purpose statement is front-loaded, and the sibling guidance follows immediately.

  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 a read-only annotation, a single documented optional parameter, and a provided output schema, the tool is simple enough that the source catalog and preference note make the description adequate. An agent can safely invoke it without further behavioral context.

  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 schema covers the single limit parameter fully with a default and description, so the description has little parameter burden to carry. The description adds no extra meaning about the limit beyond what the schema already provides, matching the baseline for high schema coverage.

  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 verb ('Get') and a precise resource ('queries with the largest response sizes from the system:completed_requests catalog'), which is more specific than the name alone and distinguishes this diagnostic from sibling query-analysis tools. It names the underlying catalog, making the tool's scope unambiguous.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines5/5

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

  It explicitly tells an agent to prefer this tool over writing a raw system:completed_requests query via run_sql_plus_plus_query. This names a concrete sibling alternative and gives clear guidance for when this tool should be selected.

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

• get_longest_running_queriesA
  4.5/5.0
  Behavior4/5

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

  The readOnlyHint annotation already establishes safety, and the description adds useful behavioral context: it reads from the completed_requests catalog, implying only completed query executions are considered. It does not spell out ordering or result format, but the output schema covers the return shape.

  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 purposeful sentences with no filler. The primary action is front-loaded and the preference note is brief and clearly actionable.

  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 single-optional-parameter, read-only tool with an output schema, this description is complete. It names the source catalog, gives a usage preference, and the surrounding schema/annotations fill in the remaining 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% and the only parameter, limit, already has a description and default value. The description does not need to add parameter-level detail; the schema carries that burden effectively.

  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 action ('Get'), the result ('N longest running queries'), and the data source ('system:completed_requests catalog'). This differentiates it from sibling query analytics tools by focusing on elapsed runtime rather than response size, frequency, or indexing concerns.

  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 says to prefer this tool over writing a raw system:completed_requests query via run_sql_plus_plus_query. This gives the agent a direct decision rule for at least one obvious alternative.

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

• get_server_configuration_statusA
  4.7/5.0
  Behavior5/5

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

  Beyond readOnlyHint annotation, it adds that no connection is established, which is a key behavioral trait. No contradiction.

  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, front-loaded with key action, no extra fluff.

  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 zero parameters, annotations, and output schema, the description fully covers the tool's purpose and 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?

  No parameters exist, so schema coverage is 100%. Baseline 4 applies as description adds no param info but none needed.

  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 it retrieves server status and configuration, and uniquely specifies 'without establishing connection', distinguishing it from siblings like test_cluster_connection.

  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?

  It indicates usage for verifying server running and checking configuration, providing context but not explicit when-nots or alternatives.

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

• list_indexesA
  4.7/5.0
  Behavior5/5

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

  Beyond the readOnlyHint annotation, the description discloses version-dependent source behavior (RBAC-scoped vs admin API), missing field handling with warnings, and output field details, offering comprehensive transparency.

  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 well-structured with clear front-loading, each paragraph adds essential information without redundancy. Concise yet complete.

  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 5 parameters, no required params, and an output schema, the description covers filtering hierarchy, return option, output fields, missing data handling, and version-dependent behavior—fully complete.

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

  Parameters4/5

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

  With 0% schema coverage, the description adds significant meaning: hierarchical filtering rule and raw stats option. It compensates well but could clarify parameter formats further, though schema types suffice.

  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 it lists indexes with optional filtering, using specific verb and resource. It distinguishes from sibling tools by focusing on index listing rather than schema or queries.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines4/5

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

  The description provides explicit hierarchical filtering rules and mentions the return_raw_index_stats option, but does not explicitly state when to use this tool over alternatives like get_index_advisor_recommendations.

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

• run_sql_plus_plus_queryA
  4.7/5.0
  Behavior4/5

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

  With no annotations present, the description carries the behavioral disclosure burden. It explains that the scope context is automatically set, that named parameters are the injection-safe binding mechanism, and that results are returned as JSON objects. It stops short of mentioning side-effect potential for mutating queries, but the inclusion of CREATE INDEX guidance implies mutability.

  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 well-structured and front-loaded: purpose, scoping rule, security guidance, example, and sibling tool routing. Every sentence contributes useful decision-making or invocation detail with minimal 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 that an output schema exists, return-value details are already covered. The description provides enough operational context for the agent to invoke the tool correctly, including naming rules, parameter binding, and when to use alternative 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 input schema has 0% description coverage, so the tool description must compensate. It explains the query parameter's naming convention, the role of named_parameters with $name placeholders, and the bucket/scope context. This covers most parameters indirectly, though bucket_name and scope_name formats are left to inference.

  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 starts with a specific action, 'Run a SQL++ query on a scope and return the results as a list of JSON objects,' which clearly identifies the verb and resource. It further distinguishes itself from sibling diagnostic and explain tools by emphasizing execution and result output.

  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 gives concrete usage guidance: use collection names without bucket/scope prefixes, bind parameters via named_parameters to prevent injection, and prefer create_index over raw CREATE INDEX. It also references list_indexes as a complementary tool, giving the agent explicit routing cues.

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

• test_cluster_connectionA
  4.7/5.0
  Behavior5/5

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

  Discloses it establishes connection if needed, returns status and cluster info. readOnlyHint annotation consistent.

  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, no unnecessary words, front-loaded with purpose.

  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?

  Simple tool with optional param and output schema; description covers key behavior and return info.

  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?

  Only one param with 0% schema coverage; description adds meaning by explaining behavior when bucket_name is null. Lacks format details but sufficient.

  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?

  Clearly states it tests connection to Couchbase cluster and optionally a bucket. Distinct from siblings that query data or indexes.

  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?

  Explains when to provide bucket name and behavior when omitted. Could explicitly contrast with sibling tools for when to use this first.

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

• get_cluster_diagnostics_reportA
  4.8/5.0
  Behavior5/5

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

  Annotations provide readOnlyHint=true, and the description adds substantial behavioral context beyond that: it performs no network I/O, is only as fresh as the last SDK contact, will not proactively detect a just-down service, and requires no additional RBAC role. This gives the agent a clear picture of what the call does and does not do.

  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 front-loaded with purpose and well-organized into behavioral context, output contents, and permission notes. However, the final 'Returns' bullet largely repeats the prior paragraph's description of per-endpoint and cluster state, adding minor 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?

  The description covers purpose, freshness/staleness caveats, the sibling alternative, permissions, filtering limitations, and output contents. With an output schema present and zero parameters, nothing an agent needs to select or invoke this tool correctly is missing.

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

  Parameters4/5

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

  The tool has zero parameters and the schema is an empty object with 100% coverage, so the baseline of 4 applies. The description correctly explains that no filtering is possible because no I/O occurs, which is the only parameter-like nuance an agent needs to understand.

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

  Purpose5/5

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

  The description opens with a specific check—whether client connections were already broken and for how long—and clearly states the tool's core behavior: reporting the SDK's cached connection state. It explicitly contrasts this with get_cluster_health_and_services, so an agent can immediately distinguish the two tools.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines5/5

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

  It explicitly says the tool is cheap and appropriate for frequently checking cached connection state, and directs the agent to use get_cluster_health_and_services instead when a live, right-now reachability check is needed. It also notes the filtering limitation relative to that sibling, leaving no ambiguity about when each tool should be chosen.

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

• get_cluster_health_and_servicesA
  4.8/5.0
  Behavior5/5

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

  The description goes well beyond the readOnlyHint annotation by disclosing that the tool performs live network round-trips, may silently skip KV services depending on Couchbase Server version, returns an error response for unrecognized service_types rather than raising, and is somewhat invasive. These are critical behavioral traits the agent could not infer from the schema or 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?

  Although lengthy, every section earns its place: scope selection, service_types values, version-dependent caveats, and invasiveness warnings all change caller behavior. The use of bolded headings and bulleted list keeps dense information scannable, and the most important purpose statement is front-loaded.

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

  Completeness5/5

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

  For a tool with two optional parameters, no schema descriptions, and an output schema present, the description covers all needed decision points: reachability check mechanics, per-service returned details, cluster versus bucket scoping, version caveats, valid service_types, invalid-input behavior, and safety advice. Nothing critical for correct invocation is missing.

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

  Parameters5/5

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

  Schema description coverage is 0%, but the description fully compensates. It explains that bucket_name changes scope from cluster-level to bucket-level and guarantees KV coverage, and it enumerates the exact valid service_types values plus behavior when omitted or invalid. This is far more informative than the bare 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 opens with a specific verb and resource: 'Check whether the cluster is reachable right now, and where it's broken.' It then distinguishes itself from a passive connection-state check and from sibling tools by emphasizing live ping behavior and service-level reporting. This makes it instantly clear what the tool does and how it differs from related cluster-status 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 gives explicit guidance on when to use cluster-level versus bucket-level pinging, explains the KV-service coverage tradeoff, and advises callers to prefer narrow service_types filters and avoid high-frequency polling. It contrasts with 'a passive connection-state check' but does not explicitly name the sibling tool to use instead, so the routing guidance is strong but not fully explicit.

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

• lookup_subdocumentA
  4.9/5.0
  Behavior5/5

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

  Beyond the readOnlyHint annotation, it discloses important runtime behavior: per-path errors do not fail the whole call, failed paths are reported individually as {"error": ...}, too many paths can cause a whole-call failure, and guessing wrong paths returns misleading 'not found' results. It also documents the exact response shape for success and failure, giving the agent a faithful model of how the tool behaves.

  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 long but every section earns its place: purpose, usage rules, parameter semantics, path-syntax examples, failure modes, and return format. It is front-loaded with the most decision-relevant information (when to use vs get_document_by_id) and uses clear structural signposts like the IMPORTANT warning and per-category bullet lists, making it easy for an agent to scan.

  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 complexity — multiple path categories, per-path failures, server-side limits, and a non-trivial response format — the description is exceptionally complete. It even includes the return dict shape and error behaviors despite an output schema being present, and it covers the only real prerequisite (known field paths) along with how to handle uncertainty. An agent has everything needed 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?

  With schema description coverage at 0%, the description carries the burden and largely delivers: get_paths, exists_paths, and count_paths are each explained with semantics, examples of path syntax, and guidance on limits and minimum requirements. The required identifiers bucket_name, scope_name, collection_name, and document_id are not individually elaborated, but their roles are strongly implied by their names and the tool's Couchbase context.

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

  Purpose5/5

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

  The description opens with a specific verb and resource ('Look up parts of a document without fetching the whole thing, using Couchbase sub-document operations') and immediately differentiates itself from the sibling get_document_by_id by stating exactly when to prefer it. The name and purpose align clearly, so an agent can identify the tool's role without reading the schema.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines5/5

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

  It explicitly says 'Use this instead of get_document_by_id when...' and gives concrete conditions: needing only a few fields, a presence check, or an array/object size, while already knowing exact field paths. It also provides a clear 'when not to use' instruction — do not guess paths, call get_document_by_id first — which is strong routing guidance with an explicit alternative.

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