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

Annotations only declare readOnlyHint=true, so the description carries the rest, and it does: offline operation while the cluster is unreachable, an unrecognized tool_name returning the registered-name list instead of failing, max_results being uncapped by the server, and score-based ranking with guidance on interpreting weak scores. It is consistent with the read-only annotation and adds substantial operational context.

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

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

The critical instruction (call before the target tool, don't guess) is front-loaded, and the two-call-mode breakdown is easy to scan. It runs long for a lookup helper and repeats the chapters-points-to-search idea in both the browse section and the closing sentence, which is mild redundancy rather than harm.

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

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

An output schema exists, so return values need no explanation, yet the description still summarizes the response shape (record_count, sample_records, chapters, next_step) precisely enough to tell an agent not to expect a full list from a browse call. For a five-parameter read-only lookup tool, nothing an agent needs in order to call it correctly is missing.

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

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

Schema coverage is 100% and the schema descriptions are already detailed, so the baseline is 3; the description earns an increment by explaining the mutually exclusive browse-vs-search call patterns and noting that tool_name is the only required argument. It stops short of adding anything new about min_score or max_results beyond what the schema already says.

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

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

The description uses a specific verb+resource formulation: find exact input values for a named tool from reference data bundled with the server. It also names the downstream consumer ("get_cluster_metrics") and the concrete payload (metric name, type, unit, version, description), so an agent can tell immediately this is a lookup tool, not a cluster query tool like its siblings.

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

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

It states the trigger explicitly ("Call this BEFORE calling a tool that needs an exact identifier you do not already know"), names two anti-patterns to avoid (guessing, browsing the Couchbase docs site), and explains the cost of getting it wrong (the target tool errors with no data). It also routes between its own two modes: tool_name alone to browse, tool_name plus search_keywords to search.

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

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.

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.

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.

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.

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.

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.

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

Beyond readOnlyHint=true, it discloses the per-node fan-out and merge behavior, the unreachable_nodes partial-failure shape, that Capella is rejected without a REST call, and the ro_admin RBAC requirement — exactly the operational context an agent needs.

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

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

Front-loaded with the purpose and actions, then caveats, then return shape; well organized, though the detailed return-value enumeration partly duplicates the existing output schema.

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

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

Given an output schema exists, the description still adds the unreachable_nodes semantics and the all-nodes-failed error case, and it covers environment constraints (7.6+, self-managed only) and permissions — nothing material is missing.

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

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

There is a single 'timeout' parameter with 0% schema description coverage, and the description never mentions it, so its units, default behavior, and effect on multi-node fan-out are left unexplained; the parameter is trivial enough that this is a moderate gap rather than a critical one.

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

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

States a specific verb and resource ('get all queries executing right now') plus scope ('across every query-service node'), and the returned fields (elapsed time, statement text, client, state) distinguish it from siblings like get_longest_running_queries and get_cluster_query_vitals.

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

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

Explicitly says when to use it ('find a runaway or stuck statement'), what to pair it with ('get_cluster_query_vitals to confirm the engine is actually under load'), and the follow-up action (pass requestId to delete_active_query).

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

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

Annotations only declare readOnlyHint=true, and the description goes far beyond it: REST endpoints used, 7.6+ self-managed-only constraint (Capella rejected without a call), ro_admin role requirement, raises-on-failure including 404 for unknown buckets, and the trap where a not-yet-joined node answers 200 with [] — turning a misleading empty result into a documented hazard.

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

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

Well front-loaded with a one-line summary followed by usage, parameter semantics, endpoint/auth notes, and a 'Reading the result' section. However, the 'returns the endpoint's response unchanged / nothing stripped or renamed / never reshapes what the endpoint returns' idea is restated three times, and the not-yet-joined-node paragraph is long for an edge case, so several sentences could be trimmed.

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

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

Covers everything an agent needs to call this correctly and interpret it: auth and version prerequisites, endpoint shapes, the false-vs-cluster-inherited autoCompactionSettings ambiguity, absent-field semantics for older servers, and payload-skew caveats. An output schema exists, yet the field-level interpretation notes add genuine value rather than duplicating it.

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

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

Schema coverage is 0%, so the description must carry parameter meaning — and it does for bucket_name: omitting it returns all buckets, passing "" is explicitly rejected rather than silently coalesced, and the return type differs (dict vs list) by that choice. The second parameter, timeout, is never mentioned, which is the only remaining gap.

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

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

States a specific verb+resource (get a bucket's configuration and live state, or all buckets when bucket_name is omitted) and enumerates the exact fields covered (RAM quota, replica count, eviction policy, durability, storage backend, stats). It explicitly contrasts with get_buckets_in_cluster ('lists bucket names via the SDK but exposes none of this'), so an agent can separate the two without opening a schema.

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

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

Gives concrete when-to-use triggers ('explain a bucket-level symptom that get_cluster_metrics or get_index_stats pointed at') and a pre-flight scenario before advising compaction/quota/durability changes. It also names the exclusion boundary ('create/edit/flush/delete stay CAO-owned'), leaving nothing to inference.

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

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.

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.

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.

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.

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.

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.

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

Annotations only declare readOnlyHint=true; the description adds substantially more — no network I/O is performed, the data is only as fresh as the last real contact with each node, no proactive detection of newly-down services, and no additional RBAC role is required beyond the initial cluster connection. The staleness caveat is exactly the kind of behavior an agent could not infer from structured fields.

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

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

Front-loaded with the core purpose and the alternative routing, with the caveats following in decreasing priority. Minor redundancy in restating the no-I/O point twice (once in the middle, once in the RBAC sentence), but nearly every sentence carries distinct information.

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

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

For a zero-parameter read-only diagnostic tool, the description covers purpose, cost, freshness limits, permission implications, and the per-endpoint fields returned. An output schema exists, and the brief Returns section is consistent with it rather than a substitute for it.

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

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

Zero parameters, so the baseline is 4, and the description goes further by explaining why there are none: filtering to specific services is impossible because no I/O occurs. That preempts an agent trying to pass a service filter argument.

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

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

States a specific verb and resource: check whether the client's connections were already broken and for how long. It immediately distinguishes itself from the named sibling get_cluster_health_and_services by contrasting cached state with live pings, so an agent can tell them apart without opening either schema.

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

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

Explicitly says when to use this tool (cheap, frequent, cached-state checks), when not to ("Use get_cluster_health_and_services instead when you need a live, right-now reachability check"), and notes the capability gap that no filtering is possible. Both directions of the routing decision are covered.

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

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.

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.

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.

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.

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.

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.

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

Annotations only say readOnlyHint=true, and the description carries substantial extra context: version and deployment-type gating, Capella being rejected without issuing a REST call, the required ro_admin role, and that the call raises on failure. It also pre-empts misinterpretation of results, e.g. orchestrator_known=false means safe_to_act_on is 'unknown' rather than 'yes', and recoveryType other than 'none' means in-progress rather than broken.

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

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

Well structured and front-loaded: purpose first, then the diagnostic questions, prerequisites, and a clearly delimited 'Reading the result' block. The result-reading section is long for a one-parameter read tool and partly re-states what the output schema already encodes structurally, but most of it adds interpretation (unhealthy vs inactive semantics, address selection) rather than restating field names.

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

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

For a diagnostic tool whose value is entirely in interpreting the returned payload, the description supplies prerequisites, failure behavior, and per-field semantics including the tricky orchestrator-unknown case and the rebalance_start vs rebalance_success counter signature. An agent could call this and correctly read the output without additional context.

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

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

There is one parameter (timeout, default 30) with zero schema description coverage, and the description says nothing about it at all — no unit, no guidance on when to raise it, no note on what happens when it expires. The parameter is largely self-explanatory, which keeps this at a minimum-viable 3, but the description makes no contribution here.

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

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 set: per-node service topology, membership, orchestrator and health, retrieved in one call. It goes further than most by naming the diagnostic question it answers (symptom to node/service, post-failover topology validation). The one gap is that it never distinguishes itself from the near-duplicate sibling get_cluster_health_and_services, so an agent must guess between two similarly named health tools.

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

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

Clear usage contexts are given (turning a symptom into a specific node, checking whether a topology change left a good state), plus an explicit hand-off: pair with get_cluster_tasks for what is running now. Prerequisites and hard exclusions are stated (self-managed Couchbase 7.6+ only, Capella rejected without a REST call, ro_admin role required). It misses only the direct comparison against the sibling get_cluster_health_and_services.

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

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

Beyond readOnlyHint=true, it discloses the underlying REST endpoint (POST /pools/default/stats/range), the Capella rejection behavior and extra REST call cost, the per-spec error behavior for unknown metric names, and that requests are unbounded so broad queries can return large payloads. That is substantive operational context the annotations cannot convey; only the timeout parameter's runtime effect is left unstated.

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

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

Front-loaded with purpose, then applicability caveat, then parameter contract, then metric-name discovery, then response shape — a logical order with no filler sentences. It runs long and the closing 'Returns {...}' block partially duplicates the existing output schema, a small redundancy.

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

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

For a read-only, single-endpoint metrics query with an opaque schema, the description supplies applicability limits, parameter defaults, error semantics, discovery path for metric names, and response envelope. Little an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 0% and the metrics schema is an opaque array of free-form objects, yet the description fully unpacks the request-body shape: required 'metric' as label/value pairs with a concrete example, optional nodes targets with the 'omit to cover every node' default, applyFunctions/nodesAggregation/alignTimestamps, start/end defaults of -60/now, and step default of 10. That is exactly the compensation needed for a fully undocumented schema.

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

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

Opens with a specific verb and resource plus scope: 'Get one or more cluster statistics over a historic time window in a single call.' It also distinguishes itself from the diagnostic siblings by positioning itself as the quantification step after get_cluster_health_and_services or get_client_connectivity_report, so an agent can pick it out of a 30+ tool list.

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

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

Explicit when-to-use with named upstream tools ('to quantify a suspected problem ... is a metric spiking, climbing, or stable'). It also states a hard applicability boundary (self-managed Couchbase Server 7.6+ only, rejects Capella) and routes to discover_tool_input_values for metric names instead of guessing.

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

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

Beyond readOnlyHint=true, the description discloses the endpoint called (GET /admin/vitals), the ro_admin RBAC requirement with a candid caveat that privilege requirements are undocumented, the Capella rejection path, and that results are per-node rather than cluster-wide. It also explains partial-failure semantics (unreachable_nodes omitted when all nodes answer) and the all-fail error case. Slight deduction only because failure behavior for a mid-call timeout is not spelled out.

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

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

Front-loads purpose, then differentiation, usage trigger, preconditions, per-node behavior, and return shape — a logical progression with no filler paragraphs. Some sentences (the RBAC hedging parenthetical) are longer than needed, and the return-shape example partially duplicates the output schema.

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

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

For a fan-out diagnostic tool it covers everything an agent needs: what it measures, when to call it, environment and role limits, per-node keying by host:port, and both partial and total failure outcomes. Even with an output schema present, the inline return description adds useful shape context.

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

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

Schema description coverage is 0% and the single parameter (timeout, default 30) is never mentioned in the description. It is unclear whether the timeout is in seconds, applies per node or to the whole fan-out, and whether it is per-request or total. The description therefore does not compensate for the schema gap, though the parameter is at least intuitively named.

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

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

States a specific verb and resource: fetch query-engine vitals from every query-service node, covering request rate, active/queued counts, memory, GC and uptime. It explicitly separates itself from get_cluster_metrics (node hardware) and get_cluster_health_snapshot, so an agent can route without opening other schemas.

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

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

Gives an explicit trigger condition: use it after get_cluster_metrics/get_cluster_health_snapshot show healthy infra but queries are still slow. It also states hard prerequisites (self-managed Couchbase Server 7.6+, Capella rejected) and the implied exclusion of hardware-level troubleshooting.

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

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

Annotations only supply readOnlyHint, but the description adds substantial behavior: version/platform gating (7.6+ self-managed, Capella rejected without a REST call), required roles (Full Admin or Cluster Admin), the underlying GET /events call, ring-buffer size (10,000 default) and the consequence that empty results may mean aged-out events, and that failures raise. This is far beyond what the annotation conveys.

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

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

Front-loaded with purpose, then platform/auth gate, then a clearly labeled ordering block and a labeled result-reading block. Each bullet carries a distinct operational fact, though the length is near the upper bound and a few clauses (e.g. naming summary.by_severity and by_component) restate fields the output schema already declares.

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

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

The tool is genuinely tricky (non-obvious ordering inverted by since_time, truncation subtleties, ring-buffer aging), and the description covers every trap an agent would fall into. An output schema exists, yet the description still explains the paging-relevant summary fields that the schema alone would not make actionable.

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

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

Schema coverage is 0%, so the description must carry the load, and it does for two of three parameters: since_time is explained in depth (inclusive boundary, dedupe on uuid, next_since_time paging, paging_blocked escape hatch) and limit is explained precisely (server picks most-recent vs earliest, raising it is the only recourse on a single-timestamp batch). timeout receives no mention at all, which is the only gap.

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

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

States a specific verb and resource ("Get the cluster's system event log — what changed on the cluster, and when") and immediately frames the role it plays: the RCA timeline. It is clearly differentiated from get_cluster_metrics (cross-check target) and from config-listing siblings like get_bucket_config.

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

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

Explicitly says when to use it ("once a symptom is confirmed"), how to window it ("Window it to the symptom's onset with since_time"), what to do next ("cross-check that timestamp against get_cluster_metrics"), and what not to do ("move the window rather than raising limit", "Do not re-sort or re-slice"). Alternatives are named rather than implied.

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

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

Goes far beyond the readOnlyHint annotation: names the underlying endpoint, the platform and role requirements, the unchanged-pass-through return behavior, and the empty-array case. The per-type field map and the interpretation notes (idle clusters still emit a 'notRunning' rebalance entry, 'statusIsStale' means unknown, progress is not comparable across types, poll no faster than recommendedRefreshPeriod, cancelURI is never invoked) are exactly the behavioral context an agent cannot infer from annotations or schema.

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

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

Front-loaded with the one-line purpose, then the usage pairing, then endpoint/preconditions, then a bulleted reading guide — well structured and scannable. It is on the long side, and the per-type field enumeration partially duplicates the available output schema, but each bullet is actionable rather than filler.

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

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

For a diagnostic single-sample read tool, everything an agent needs is present: scope, preconditions, sibling relationship, sampling/polling guidance, and stale-vs-stuck interpretation traps. The presence of an output schema makes the return-value detail optional, yet it is included and correctly hedged as per-type.

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

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

The single parameter is an optional 'timeout' with 0% schema description coverage, and the description never mentions it, so its units and effect remain undefined. The gap is mitigated somewhat because the schema supplies a default of 30 and a timeout is a conventional control, but the description does not compensate for the coverage hole.

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

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

States a specific verb and resource ('Get the cluster tasks running right now') and enumerates the task families it covers (rebalance, compaction, XDCR, index build). It also frames the question the tool answers ('what is this cluster doing?'), which separates it cleanly from the sibling get_cluster_metrics.

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

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

Explicitly says to pair a single call with get_cluster_metrics to distinguish 'slow but progressing' from 'flatlined', giving both the when-to-use and the named alternative. It also states prerequisites and exclusions: self-managed Couchbase Server 7.6+ only, Capella rejected without a REST call, and the ro_admin role required.

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

Annotations already declare readOnlyHint=true, and the description adds genuine context beyond that: it discloses the error behavior when the advisor cannot analyze the statement (e.g., syntax errors). However, the sentence 'The queries will be run on the specified scope in the specified bucket' is ambiguous for a read-only tool that accepts UPDATE/DELETE/MERGE — an agent could read it as execution rather than analysis, which is a real clarity risk. It stops short of a contradiction, but it is not a clean disclosure either.

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

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

The lead sentence is front-loaded and useful, and the supported-statement list earns its place. But a large block restates the return dictionary and per-index object fields even though an output schema exists, which duplicates structured data rather than adding meaning. Roughly half the text is redundant with the output schema.

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

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

For a three-parameter read-only analysis tool with an output schema and readOnlyHint annotation, the essentials are mostly covered: purpose, accepted query types, error behavior. Gaps remain around parameter semantics (0% schema coverage) and the ambiguous 'will be run' wording, and the return-value enumeration is redundant given the output schema. An agent could call it correctly but might hesitate over whether the query is executed.

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

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

Schema description coverage is 0%, so all three parameters (bucket_name, scope_name, query) are undocumented in the schema and the description must compensate. It does partially: the query is identified as a SQL++ statement and the bucket/scope are described as the execution context, which conveys their roles. It adds no format detail, such as whether the query must use fully qualified keyspace paths or how bucket/scope interact with the query text.

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

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

The first sentence names a specific verb and resource (index recommendations from the Couchbase Index Advisor) and scopes it to a given SQL++ query. It also enumerates supported statement types (SELECT, UPDATE, DELETE, MERGE), which sharpens the purpose further. It does not, however, distinguish itself from near-neighbors such as explain_sql_plus_plus_query, list_indexes, or get_queries_not_using_covering_index, so an agent must infer the boundary itself.

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

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

Usage is implied rather than stated: the agent learns the tool analyzes a query and works for four statement types, which suggests 'use when you want index advice for a specific query.' There is no explicit when-to-use/when-not, no mention of prerequisites (e.g., whether indexes must already exist or whether the collection must be loaded), and no routing to sibling tools that also deal with indexes or query explanation.

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

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

Annotations only declare readOnlyHint=true, and the description adds substantial behavior the agent could not otherwise know: partial results surface as nodes_failed, nodes_without_index is expected rather than an error, indexer is None on filtered calls, counters reset on indexer restart, and per-node numbers cannot be summed for num_requests on partitioned indexes.

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

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

Purpose and the sibling hook are front-loaded in the first two sentences, and the remaining paragraphs on return shape and stat interpretation are dense rather than padded. It is long overall — the 'Reading the stats' paragraph drifts into analytical advice — but nearly every sentence carries information an agent would otherwise get wrong.

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

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

For a five-parameter, filter-hierarchy diagnostic tool this covers everything needed to call and interpret it: filter preconditions, node-level semantics, failure visibility, and the skip_empty trade-off. An output schema exists, so the extra return-value detail is bonus rather than padding.

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

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

Schema description coverage is 0%, so the description must carry the load — and it does explain the non-obvious constraint that filters are hierarchical (scope requires bucket, index requires all three) and documents skip_empty's effect and caveat in detail. The individual name parameters are only covered via that hierarchy rule rather than individually, leaving a small gap.

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

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

States a specific verb and resource — per-index statistics (size, fragmentation, scan traffic) from the Index Service — and immediately frames the diagnostic question it answers (which index is responsible for disk/memory pressure). It also positions itself relative to the sibling get_cluster_metrics, so an agent can distinguish it from list_indexes/get_index_advisor_recommendations without opening a schema.

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

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

Gives an explicit trigger condition: call it after get_cluster_metrics shows a node's index disk climbing. It also supplies a usage branch on skip_empty ('leave it False when hunting unused indexes'), which is real when-to-use guidance rather than a restatement of the parameter.

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

Annotations already declare readOnlyHint=true, so the description's job is to add context, and it does add some: schema is produced by an INFER query and sample values default to 5 server-side. However, it says nothing about the cost or latency of inference on large collections, permission requirements, or whether the call blocks — meaningful behavioral facts for an inference-backed read that annotations alone do not convey.

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

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

The purpose sentence leads, followed by return description and then the optional-parameter nuance; nothing is padded. The middle sentence about the returned dictionary is somewhat redundant given an output schema exists, but it is short and not harmful.

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

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

For a four-parameter read-only tool with an output schema, the description covers what the tool does, how the schema is generated, and how the one optional parameter changes the result. The remaining gaps — hierarchical parameter semantics and inference cost — are secondary for correct invocation.

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

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

Schema description coverage is 0%, so the description must carry the parameter burden. It fully specifies num_sample_values (unset means server default 5, 0 omits samples while keeping structure and type), which is genuinely useful nuance. The three required addressing parameters (bucket_name, scope_name, collection_name) get no explanation of format or expected values beyond their names.

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

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

The description states a specific verb and resource (get the inferred schema for a Couchbase collection in a bucket/scope), and goes further to say the schema comes from an INFER query and is returned as a dictionary keyed by collection name. This clearly separates it from sibling tools such as get_document_by_id, get_bucket_config, or list_indexes, which touch the same hierarchy but return different artifacts.

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

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

Usage is only implied: the natural read is 'explore a collection's structure before writing queries.' There is no explicit guidance on when to choose this over get_document_by_id or get_bucket_config, and no stated prerequisites. The only explicit conditional advice concerns num_sample_values, not tool selection.

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

Annotations declare readOnlyHint=true, and the description adds genuinely new behavior: the both-or-neither parameter constraint with its rationale (same index name can exist in different scopes, so location must be explicit, not guessed) and the failure mode returning {'success': False, 'error': ...}. The enumerated return keys are somewhat redundant since an output schema exists, which keeps this below a 5.

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

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

Front-loaded with the one-line purpose, then the location rule, then the return contract. Well organized and mostly dense, though the long enumeration of return keys is low-value given a declared output schema and could be trimmed to the error case.

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

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

For a three-parameter read-only lookup with an output schema, the description covers everything an agent needs to call it correctly: what it fetches, how to specify location, what makes a call invalid, and how absence manifests. Nothing material is missing.

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

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

Schema description coverage is 0%, so the description must carry the parameter burden, and it largely does: it defines the semantics of bucket_name and scope_name as a coupled location pair, explains the 'omit both' default meaning cluster-level, and states that partial specification is invalid. index_name is only implicitly characterized (the index to look up) with no format hints, which is the main residual gap.

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

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

States a specific verb and resource ('Get the full definition of a single Search (FTS) index'), which cleanly separates it from list_search_indexes and the SQL index siblings. An agent knows immediately this is a single-object lookup, not a listing.

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

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

Gives an explicit, actionable rule for the alternative location modes: pass both bucket_name and scope_name for a scoped index, omit both for a cluster-level index, and only-one is invalid. It also points to list_search_indexes to confirm name and location before calling. What it lacks is a direct 'use X instead when' routing statement against the listing sibling, but the prescriptive confirmation step effectively covers that.

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

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.

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.

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.

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.

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.

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.

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

Beyond the readOnlyHint annotation, it discloses that results are RBAC-scoped via system:indexes on v8+ while older clusters fall back to an admin-level REST endpoint — a meaningful visibility difference the agent cannot learn from annotations. It also explains degradation behavior when fields are missing (warning + raw_index_stats) and what return_raw_index_stats actually yields.

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

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

Purpose and the filter hierarchy are front-loaded, and the version-dependent source note is placed last where it belongs. The enumeration of result fields (name, definition, status, isPrimary, etc.) is largely redundant given that an output schema exists and could be trimmed.

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

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

For a five-parameter listing tool it covers the important edges: RBAC scoping, cluster-version-dependent data source, and fallback result shape. The only real gap relative to the sibling set is the absence of a pointer telling the agent when to prefer this over search-index or index-stats tools.

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

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

Schema description coverage is 0%, so the description carries the burden, and it does well: it names return_raw_index_stats explicitly and states the hierarchical dependency binding bucket_name, scope_name, collection_name, and index_name. It could go further by naming each parameter literally or noting that all are optional and unfiltered calls list everything.

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

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

'List indexes in the cluster' is a specific verb+resource, and the mentioned filters (bucket, scope, collection, index name) pin down scope precisely. It does not, however, distinguish itself from close siblings such as list_search_indexes or get_index_stats, leaving the agent to infer that this covers query/index-service indexes rather than search indexes.

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

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

The description gives a concrete operational rule: filters must be supplied hierarchically, with scope requiring bucket, collection requiring both, and index requiring all three. What is missing is any statement of when to choose this tool over list_search_indexes or get_index_stats, so alternative selection is left to inference.

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

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 goes further by disclosing the invalid-input error path and the legacy-vs-scoped model distinction. It adds genuine context but nothing about result size, ordering, or limits for a list operation that could return many entries.

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

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

Front-loaded with the purpose, then organized into a bulleted filtering section and a follow-up-pointer paragraph, so structure is strong. It runs long and the entry-field enumeration plus the filter-reuse warning are dense, but nearly every clause carries actionable content.

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

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

For a two-parameter, zero-required list tool with an output schema, the description covers filtering semantics, the legacy/scoped distinction, error cases, and the exact handoff to get_search_index_definition. An agent has everything needed to call it correctly and interpret the entries.

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

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

Schema coverage is 0%, so the description must carry the full burden, and it does: bucket_name alone spans all scopes in the bucket, bucket_name+scope_name narrows to one scope, and scope_name alone is an error. Both parameters are given semantics the bare schema completely lacks.

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

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

States a specific verb and resource ("List Search (FTS) indexes") plus the filtering dimension, which cleanly separates it from list_indexes and get_search_index_definition in the sibling list. An agent can identify the tool's role without opening the schema.

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

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

Enumerates the four filter combinations explicitly, including the invalid scope-only case and its error behavior, and names the alternative tool (get_search_index_definition) with the condition that selects it. It even warns against reusing this call's filters for the follow-up call.

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

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.

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.

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.

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.

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.

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.

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

Annotations only supply readOnlyHint=true; the description adds substantial behavior the annotation cannot: the query body is passed through unvalidated, explain=True still executes and returns per-hit plans with limit defaulting to 1, skip/fields/sort/facets/highlight_fields/disable_scoring/raw are silently ignored in explain mode, and total_hits is capped by limit so metadata.metrics.total_rows must be read for the true match set.

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

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

Front-loaded with purpose and the SQL++ alternative, then parameter semantics, then return shape — a sensible ordering with no filler sentences. It is dense and long, but nearly every clause carries operational information; only mild trimming (e.g. the explanatory aside about dynamically mapped indexes) would tighten it.

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

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

For a 13-parameter tool with nested free-form objects, undocumented schema, and divergent explain-mode behavior, the description covers index location, query body form, mode-dependent defaults and ignored parameters, error cases, and return shape. Nothing material for correct invocation is missing.

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

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

With 0% schema description coverage, the description carries the full burden and does it: concrete FTS query body examples (match, conjuncts, query_string), the bucket_name+scope_name pairing rule and its invalid case, per-parameter mapping to SearchOptions, differential limit defaults (10 vs 1), and raw as the escape hatch for unexposed options like highlight_style.

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

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

States a specific verb and resource: run an FTS query against a Search index, or fetch its execution plan. It explicitly demarcates itself from run_sql_plus_plus_query's SEARCH() function and from vector search ('Vector search is NOT supported by this tool'), which is exactly the differentiation an agent needs among these siblings.

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

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

Gives explicit when-to-use (relevance scoring, fuzzy/phrase/wildcard, faceting, tracing) versus the SQL++ alternative, states prerequisites (confirm index with list_search_indexes, inspect mappings with get_search_index_definition, note that explain executes the query rather than dry-running), and covers the bucket_name/scope_name combination rule with the invalid single-argument case named.

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

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

Annotations are empty, so the description carries the full burden. It usefully discloses that scope context is auto-set, that named parameters prevent injection, and that results are a list of JSON values, but it never says whether mutating statements (INSERT/UPDATE/DELETE) are permitted, what permissions are required, or what limits/timeouts apply to arbitrary query execution.

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

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

The core behavior is front-loaded in the first sentence, and the remaining paragraphs each serve a routing or correctness purpose. It is somewhat long, but the example and sibling comparisons are not filler.

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

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

An output schema exists, so return-value explanation is unnecessary, and the description covers scope semantics and parameter binding well. However, for a tool that runs arbitrary SQL++, the absence of annotations leaves a real gap around read-only vs mutation behavior and permission requirements.

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

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

Schema description coverage is 0%, so the description must compensate, and it does: it explains the query parameter's scope-relative syntax with a concrete example, clarifies that bucket and scope are supplied separately, and documents named_parameters as the binding mechanism for $name placeholders.

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

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

States a specific verb and resource ('Run a SQL++ query on a scope') plus the return shape, and repeatedly distinguishes itself from siblings like create_query_index, list_indexes, and run_search. An agent can identify the tool without opening the schema.

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

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

Gives explicit routing rules: prefer create_query_index for index creation, list_indexes to verify index readiness, and run_search for relevance-scored/fuzzy/FTS work rather than SQL++ SEARCH(). It also states the scope-context convention that selects correct query syntax.

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

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

readOnlyHint=true is consistent with the stated 'this tool only ever emits a SELECT' and the explanation that no write-guard applies. Beyond annotations it discloses the two silent-fallback footguns (mismatched distance_metric and a `where` that misses the partial-index condition), the unconfigured-provider error shape, the pre-8.0 warning key, and the nested-document return rationale.

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

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

Paragraph-per-topic structure with bolded leads makes the long text scannable and front-loaded. It loses a point for repetition, repeating the 'this tool has no index_name to look that up' caveat three separate times, which could be said once.

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

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

For a 12-parameter tool with 0% schema coverage and silent-failure modes, the description covers prerequisites, parameter interactions, fallback behavior, and result shape. Return documentation is arguably redundant given the output schema, but the collision-explanation for the nested 'document' key adds real value.

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