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

Annotations already mark the call read-only and idempotent. The description adds useful behavior beyond that: dates are inclusive, 'to' defaults to today, and deleted datastores are still included in the period. It does not describe response shape or pagination behavior, but the core behavioral caveats are disclosed.

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?

Three short sentences lead with the core purpose, then supply date behavior and the deleted-datastores caveat. Every clause earns its place; there is no filler or repetition of schema boilerplate.

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 an 8-parameter report with no output schema, the description covers the main returned metrics, the date-range inputs, and an important edge case (deleted datastores). It stops short of stating the result grouping/order or how limit/offset are reflected in the response, which would make it fully 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?

Schema description coverage is 100%, so the schema already explains all eight parameters. The description reinforces date semantics and the 'to' default, and implies the customer_id filter is optional via 'across all customers', but it adds no essential parameter-level detail beyond the 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 states exactly what the tool produces: per-datastore resource usage over a date range, with output metrics enumerated (instance hours, volume GiB-hours/IOPS, egress, backup counts). It also scopes the report to 'across all customers', which differentiates it from sibling datastore/user management tools such as ccx_admin_list_datastores. No ambiguity remains about what this tool is for.

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 makes the intended use clear: pull billing/resource usage for a date range across customers, including deleted datastores. It does not name specific alternatives or state when not to use it, but the billing scope is distinct enough that an agent can select it correctly.

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 and idempotentHint, and the description adds meaningful behavioral detail beyond that: it reports two distinct checks (basic-auth health check and admin session identity) and notes that the result depends on whichever credentials are configured. This gives the agent a clear sense of what the tool will actually do.

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 focused sentences with no wasted words. The main purpose is front-loaded, and the second sentence enumerates exactly what is reported, so 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 zero-parameter, read-only connectivity check, the description is largely complete: it states the purpose and the two reported results. It does not detail the exact response shape, but the low complexity and read-only/idempotent annotations reduce the need for that detail.

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 is empty, so baseline 4 applies. The description's mention of 'whichever credentials are configured' alludes to configuration rather than parameters, which is appropriate since no parameters exist.

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: verify connectivity and credentials against the CCX admin API. It then clarifies exactly what is reported, the admin REST health check and admin session identity, which clearly distinguishes it from sibling tools that operate on VPCs, datastores, users, or billing.

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 context of use is clear: run this tool to verify connectivity and credentials against the CCX admin API before other admin operations. It does not explicitly name alternatives or say when not to use it, but no genuine alternative exists among the siblings, which all perform different admin actions.

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 communicate readOnlyHint and idempotentHint, so the safety profile is covered. The description adds context about what is being queried (the controlling cmon process), but it does not disclose the response shape or any additional behavioral details. This is acceptable but not rich.

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?

One efficient sentence states the resource, the action, and the deployment scope without any filler. It earns its place and does not repeat the title verbatim, though it stays close to 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 zero-parameter, read-only version lookup, the description is complete: it states exactly what the agent will retrieve. The lack of an output schema is mitigated because the description names the return value (the cmon version).

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 is empty and has zero parameters, so there is nothing for the description to elaborate on. Per the baseline for zero-parameter tools, this is a strong score because no parameter ambiguity exists.

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 ('get') and names a precise resource ('version of the ClusterControl controller (cmon)') plus the deployment scope ('backing this CCX deployment'). This clearly identifies what the tool does and distinguishes it from the sibling admin tools, none of which are version-related.

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

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

The description gives clear context for when to use the tool: when you need the cmon version backing the current CCX deployment. It does not explicitly discuss alternatives or exclusions, but the tool's purpose is unique enough among the siblings that no alternative routing is necessary.

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 and idempotentHint, so the safety profile is covered. The description adds meaningful behavioral detail about dual execution paths depending on basic-auth configuration, which is not in annotations. This contextualizes how the count is obtained without contradicting any metadata.

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 crisp sentences: the first states the core function and scope, the second explains implementation variability. No fluff, and the purpose is front-loaded. 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 zero-parameter, read-only count tool with no output schema, the description is nearly complete. It clarifies what is counted and how the count is derived. The only minor gap is an explicit statement of the return type (a number), but 'total number' strongly implies it, so this is 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?

The tool has zero parameters and schema coverage is trivially 100%. Per the rubric, a baseline of 4 applies when there are no parameters. The description does not need to explain parameters, and it adds no irrelevant parameter information.

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 counts datastores (database clusters) across all CCX users. The verb 'count' and resource 'datastores' are unambiguous, and the global scope differentiates it from sibling tools like ccx_admin_list_datastores and ccx_admin_count_users.

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 the tool is for obtaining a total count rather than details, which separates it from list/get siblings. However, it does not explicitly state when to use it over alternatives (e.g., 'use this instead of listing datastores when you only need the number'). The context is clear but not exhaustive.

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 and idempotentHint, and the description adds meaningful behavioral detail beyond that: it excludes @severalnines.com / @s9s.io logins in production, includes deleted users, and behaves differently when an admin session is configured (client-side counting with breakdowns). This is transparent about side effects (none) and data scoping.

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, front-loaded with the core purpose ('Count CCX users'), and then provides necessary nuance in two additional sentences. Every sentence adds value, with no redundancy or fluff. It's appropriately sized 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?

Given the tool has no parameters, no output schema, and simple functionality, the description covers the key behavior: what is counted, exclusions, and the admin-session nuance. It doesn't explicitly state the return format (e.g., a number or object), but it implies counts are returned and can be reconciled. For a count tool, this 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?

The tool has 0 parameters, and the schema description coverage is trivially 100%. Per the calibration rules, a baseline of 4 is appropriate for zero-parameter tools. The description doesn't need to explain parameters since none exist, and it doesn't introduce confusion.

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 ('Count') and resource ('CCX users'), and distinguishes itself from siblings by explaining the specific endpoint and its behavior (excluding certain domains, including deleted users). This is a specific verb+resource with scope, making it easy for an agent to differentiate from list or management 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 explains when the tool is appropriate: it counts customer accounts and notes the nuance of the counter endpoint versus client-side counting when an admin session is configured. While it doesn't explicitly name alternatives, the context makes clear this is for counting rather than listing or modifying, and the reconciliation note suggests usage for verification.

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 destructiveHint annotation, the description discloses that the cluster and its data are destroyed irreversibly and that protection mode blocks execution. It also communicates that confirm is a mandatory safety gate. This is exactly the behavioral 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?

Three short sentences deliver the action, scope, consequences, and blocking conditions without redundancy. The most important information is front-loaded in the first sentence.

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 destructive tool with no output schema, this definition covers the essential operational facts: what is deleted, who can do it, irreversibility, required confirmation, and the protection-mode blocker. Nothing critical is missing for an agent to invoke it safely and 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?

The schema already provides 100% coverage with clear descriptions for both parameters. The description adds useful semantic scope by clarifying that datastore_id can refer to any user's datastore and reinforces confirm's mandatory role, though some of this restates schema information.

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 (FORCE-DELETE), a specific resource (any user's datastore), and an authorization scope (as admin). This clearly distinguishes it from the read-only admin tools like ccx_admin_get_datastore and ccx_admin_list_datastores.

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 states the preconditions: confirm must be true, and the operation is blocked while CCX_PROTECT protection mode is on, so an agent knows when the call will fail. It establishes clear admin-only scope, though it does not explicitly mention alternative tools or when a non-force path should be preferred.

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 annotations (destructiveHint=true, idempotentHint=false), the description adds crucial behavioral context: 'This cannot be undone' highlights irreversibility, and 'blocked while protection mode (CCX_PROTECT) is on' discloses a precondition. This goes well beyond the annotations and helps the agent understand side effects and constraints.

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 three sentences, each earning its place: the action, the key constraints, and the alternative. It is front-loaded with the core purpose and contains no redundant or promotional language.

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 (2 required params, no output schema) and the annotations, the description covers the essential information: irreversibility, confirmation requirement, and protection-mode blocking. It also suggests an alternative tool, making the context complete for an agent to call 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?

Schema description coverage is 100%, so the baseline is 3. The description does not add new meaning to the parameters beyond what the schema already states—confirm's 'Must be explicitly true' is restated, and user_id's format is left to the schema. No additional parameter semantics 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?

The description starts with a specific verb and resource: 'Delete a CCX user account.' This clearly states the tool's function and distinguishes it from siblings like ccx_admin_delete_datastore. It also names an alternative (ccx_admin_suspend_user), reinforcing the specific purpose.

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 provides explicit when-to-use guidance: it states the action, the requirement for confirm=true, and the protection-mode block. It also directs the agent to consider ccx_admin_suspend_user as an alternative, which clarifies the choice between delete and suspend.

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 idempotentHint=true, so the safety profile is covered. The description adds value by disclosing that the tool bypasses owner scoping ('regardless of owner') and that it returns the latest job including raw data, which implies potentially heavy or sensitive data. However, it doesn't mention pagination, size limits, or whether the raw job data could be large.

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?

A single, information-dense sentence that front-loads the core action and scope, then lists the returned fields. Every word earns its place; no filler or repetition of the 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 read-only, single-parameter tool with full schema coverage and readOnly/idempotent annotations, the description is nearly complete. It clearly states what is returned. The only minor gap is not describing the shape or size of the 'raw data' in the latest job, but since there is no output schema, an agent might not know what to expect from that field.

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%: the only parameter, datastore_id, is already described as 'Datastore UUID' with a pattern. The description adds the context that the UUID lookup is admin-scoped and owner-independent, but it doesn't add new parameter-level meaning beyond what the schema provides. 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 specific resource ('one datastore by UUID'), and a clear scope ('regardless of owner'). It also enumerates the exact fields returned (status, owner login, cmon internal cluster id, latest job with raw data, database nodes), which distinguishes it from sibling tools like ccx_admin_list_datastores and ccx_admin_get_datastore_audit.

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 clearly implies this is the tool to use when you need a single datastore by UUID with admin-level access regardless of owner. It doesn't explicitly name alternatives or state when not to use it, but the 'regardless of owner' phrasing and the detailed return fields provide enough context for an agent to select it over list or audit 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?

Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description adds useful behavioral context beyond annotations: results are ordered newest first, time bounds use RFC3339 format, and the log includes jobs and resource create/delete events. No contradictions with annotations.

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

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

Two sentences with no filler. The core action and ordering are front-loaded, followed by the essential time-format detail. Every word contributes to correct invocation.

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 schema richly documents all parameters, including the type-filtering caveat and limit constraints, and annotations cover safety. The description adds the key ordering and time-format context. Since there is no output schema, a bit more detail about the response shape could be helpful, but it is not necessary for invoking 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?

Schema coverage is 100%, so the baseline is 3. The description adds value by clarifying the time format with a concrete RFC3339 example and by enumerating the event types ('jobs, resource create/delete, info lines') that map to the 'type' parameter. This supplements the schema descriptions meaningfully.

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 ('Query'), a clear resource ('audit log of a datastore'), and the content scope ('jobs, resource create/delete, info lines'). This clearly distinguishes it from sibling tools like ccx_admin_get_datastore and ccx_admin_list_datastores, which serve different purposes.

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 when to use this tool: when you need a datastore's audit log. However, it does not explicitly mention alternatives or provide exclusion criteria, such as when to prefer ccx_admin_get_datastore or ccx_admin_list_datastores instead. The usage context is clear but not fully elaborated.

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 and idempotentHint, so the safety profile is covered. The description adds meaningful behavioral context beyond that: it reveals the API returns everything in one call and that filtering happens client-side, which is crucial for agents expecting server-side filtering or worrying about payload size. It also enumerates status values, which helps set expectations for the data returned. No contradiction with annotations.

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

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

Two sentences with zero waste. The first sentence front-loads the verb, resource, scope, and returned fields; the second sentence adds the critical client-side filtering behavior and a useful list of status values. Every clause earns its place, and the description remains compact despite the tool's 8 parameters.

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 8 parameters, no output schema, and no annotations beyond safety hints, the description covers the essential context: what the call returns (owner, status, latest job), the all-users scope, the client-side filtering, and possible status values. It omits explicit mention of pagination mechanics, but the schema already documents limit/offset, and the 'everything in one call' statement reasonably implies pagination is not server-side. For a list tool this is sufficient, though a brief mention of result ordering or size could push it to 5.

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%, so every one of the 8 parameters already has a meaningful description in the schema. The tool description adds no extra parameter semantics beyond implying that filters are applied client-side, which relates to how parameters are used but does not describe the parameters themselves. Baseline 3 is appropriate since the schema does the heavy lifting.

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 ('List'), a resource ('datastores'), and a clear scope ('across ALL CCX users'), while also naming the returned fields ('owner, status and the latest job'). This distinguishes it from sibling tools like ccx_admin_get_datastore (singular fetch) and ccx_admin_count_datastores (count), so an agent can tell them apart without inspecting 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?

The description gives clear context for when to use this tool: it lists all datastores across all users, and explicitly notes that 'the API returns everything in one call; filters are applied client-side.' This implies it is the go-to for broad listing and that filtering is local, but it does not name alternative tools or state when not to use it. A named sibling comparison would push this to 5.

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 and idempotentHint, covering the safety profile. The description adds useful details about the returned fields and status values, but it does not disclose pagination, limits, error behavior, or other operational characteristics.

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 a single, front-loaded sentence that states the resource, scope, and returned fields without unnecessary words. It is easy to scan and gives an agent the essential information 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?

For a one-parameter read-only list operation, the description covers the required identifier and the expected output contents. It omits minor operational details like pagination or result limits, but the combination of schema, annotations, and description is sufficient 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?

The single parameter datastore_id is fully documented in the schema with its type, pattern, and description, and schema coverage is 100%. The description does not add parameter-specific guidance, but none is needed because the schema carries the full semantics.

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 ('List') and identifies the exact resource: 'database and load-balancer nodes of a datastore'. It also enumerates the fields returned, making it clearly distinct from sibling tools like ccx_admin_list_datastores and ccx_admin_get_datastore.

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 makes the use case clear: use it to list the nodes of a specific datastore. However, it does not explicitly mention alternatives or state when not to use the tool, so it lacks full exclusion guidance.

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 and idempotentHint, so the safety profile is covered. The description adds meaningful behavioral context beyond annotations: the API returns everything and filters are applied client-side, which is important for understanding performance and result size.

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 core purpose and the key behavioral caveat are front-loaded, making the description easy to parse quickly.

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 covers the essential context: what is returned, that it is a read-only operation, and that filtering is client-side. With all parameters documented in the schema and annotations covering safety, nothing critical is missing, though an explicit note about output shape would make it fully 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?

Schema description coverage is 100%, so all six parameters are already documented in the schema. The description adds no additional parameter-level meaning beyond what the schema provides, so the baseline score of 3 is appropriate.

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

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

The description states a specific verb ('List'), a clear resource ('all CCX users'), and enumerates the returned fields. It distinguishes itself from sibling tools like ccx_admin_count_users by focusing on listing full user records rather than counts.

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 user lists and notes that filtering is client-side, which tells the agent not to expect server-side filtering. However, it does not explicitly name alternatives or state when to prefer this tool over siblings like ccx_admin_count_users.

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 and idempotentHint annotations, the description discloses key runtime behavior: the backend currently only populates ccx_num_vpcs/ccx_vpc_ids, may return zero even when VPCs exist, and empty results should be interpreted as 'unknown' rather than 'none'. It also states the auth requirement.

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?

Three short sentences front-load the purpose, then add the auth prerequisite and the critical empty-result caveat. No sentence is wasted.

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-parameter, read-only tool with no output schema, the description covers invocation requirements, current backend limitations, and interpretation of results. It is sufficient for an agent to call and correctly interpret the response.

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 single region parameter is already described in the input schema. The description only reiterates that this is for an AWS region and adds no new parameter-format or value constraints.

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: 'List VPC ids known to CCX for an AWS region'. It also scopes the operation by region and distinguishes it from sibling list tools for datastores, nodes, and users.

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 clearly implies this is the VPC-list operation among the sibling admin tools, and adds the prerequisite that basic auth credentials are required. It does not explicitly name alternatives or state when not to use it, but the resource-specific scope makes the usage context clear.

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 idempotentHint and destructiveHint, and the description adds valuable context: the effect on login/datastore access, reversibility, and the protection-mode failure condition. No contradictions with annotations.

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

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

Two sentences with no filler. The core action and consequence come first, followed by reversibility and the protection-mode constraint, all front-loaded and necessary.

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 two-param admin action with full schema coverage and meaningful annotations, the description covers purpose, effect, reversibility, and a precondition. Nothing essential is missing for an agent to invoke it correctly.

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

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

Schema description coverage is 100%, so both user_id and reason are already fully documented in the schema. The description adds no parameter-specific meaning beyond the schema, so the baseline of 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 and resource: 'Suspend a CCX user' with a concrete consequence ('no longer log in or use their datastores'). It also names the reversing sibling (ccx_admin_unsuspend_user), making the tool's role distinct from delete_user.

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 clear context: it is reversible via ccx_admin_unsuspend_user and is blocked while CCX_PROTECT is active. It does not explicitly contrast with permanent deletion via ccx_admin_delete_user, but the reversibility note implies the appropriate use case.

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 provide idempotentHint=true and destructiveHint=false. The description adds the outcome ('user can log in and use their datastores again') but does not disclose additional behavioral details such as behavior for non-suspended users or error cases. This is adequate but not rich.

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?

A single sentence that front-loads the action, states the resource, and gives the practical consequence. Every word earns its place with no 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 simple one-parameter tool with informative annotations and a fully documented schema, the description is complete enough for selection and invocation. It does not explain return values, but no output schema exists and the operation is straightforward.

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%, and the user_id parameter is already described as a UUID with a cross-reference to ccx_admin_list_users. The description adds no parameter-specific detail, so it meets the baseline but does not exceed it.

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 ('Lift a suspension') and names the resource ('CCX user'), with a clear outcome: the user can log in and use datastores again. It is immediately distinguishable from the sibling ccx_admin_suspend_user.

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 the tool is appropriate when a user is currently suspended and needs access restored. While it does not explicitly enumerate when not to use it, the context is clear and the opposite sibling tool is obvious.

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