Control Plane

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

The description states 'Errors if a listener for that port number already exists', which implies a non-idempotent create operation (a second identical call fails). This directly contradicts the annotation idempotentHint=true. Aside from this error condition, no further behavioral traits (e.g., effects on domain status, LB requirements) are disclosed in the description itself.

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, front-loaded with the primary action, and each sentence earns its place: minimal payload, duplicate-port error with alternative, and recommended reading. No redundancy or 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?

Given the tool's complexity (nested objects, optional routes/cors/tls) and the presence of a rich output schema, the description covers key context: duplicate error handling, alternative tool usage, and a runbook pointer. The port-number caveat (only 443/80 without LB) is left to the schema, which is acceptable. However, the idempotency contradiction prevents a perfect score.

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 parameters are already thoroughly documented. The description adds only 'Minimal port is {number, protocol}; routes, cors, and tls are optional', which repeats what the schema's port.description already states. No new parameter-level insight is provided, 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 action ('Add a new port listener to a domain') and distinguishes from siblings like add_domain_route and remove_domain_port. It also clarifies the minimal required port structure, making the tool's purpose 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?

Explicitly tells the agent when NOT to use this tool: if a listener for that port number already exists, use route/CORS/TLS tools instead. It also recommends reading the domain runbook via get_cpln_skill('domain') before first use, providing clear alternative paths and 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?

The description contradicts the idempotentHint annotation. It states 'the new route must not collide with an existing one,' meaning that attempting to add the same route twice would fail on the second call, which is not idempotent behavior. This is a direct conflict with 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?

The description is three sentences with no filler. It front-loads the core action, includes the key constraint (collision), points to the alternative tool, and gives a practical recommendation. 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?

The description provides key contextual details: appending to an existing listener, the collision rule, matching behavior (prefix/default or regex), and a pointer to the runbook. It does not explicitly mention prerequisites like needing a created domain or port listener, though 'existing port listener' implies that. Given the tool's complexity and rich schema, the description is nearly 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 parameters are already well-documented. The description adds minimal extra meaning beyond the schema, such as 'omit prefix/regex to match /', but this is also present in the schema's route description. The description does not substantially enhance parameter understanding beyond the baseline.

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 and resource: 'Append a route entry to an existing port listener.' It clearly states what the tool does and distinguishes it from the sibling tool update_domain_route by explicitly noting that update replaces an existing entry while this appends.

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 states when to use this tool vs. alternatives: 'Use update_domain_route to replace an existing entry.' Also recommends reading the domain skill runbook before first use, providing clear context and a pointer to additional 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=true and destructiveHint=false, and the description reinforces safety by using 'List.' Beyond that, it discloses return details ('name, category, latest version, and whether it creates its own GVC') and mentions filtering behavior. It does not add rate limits or pagination, but with strong annotations the extra behavior is sufficient.

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 compact and front-loaded: the main action and resource appear in the first clause. Every sentence contributes—purpose, return summary, usage guidance, and next-step pointer. No filler or repetition.

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/filter tool with one optional parameter and an output schema, the description covers purpose, return fields, filter usage, and the follow-up tool. It also benefits from complete annotations and output schema, so nothing critical 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%, so the baseline is 3. The description only says 'Pass `filter` to narrow,' which adds no meaning beyond the schema's description of the filter as an optional case-insensitive substring. No additional parameter context is 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 opens with a specific verb+resource: 'List the Control Plane Template Catalog.' It immediately distinguishes the tool from siblings like get_template and list_installed_templates by clarifying it's the catalog, not installed templates, and explicitly says 'Reach for this first whenever the user wants a database, cache, queue, or other common service.'

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?

Provides explicit usage context: 'Reach for this first...' and contrasts with hand-authoring resources. It also names the next step: 'Then call get_template for versions and the example values.yaml.' This gives clear when-to-use and a direct 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?

Adds substantial behavioral context beyond the annotations: no Docker daemon involved, always produces linux/amd64, returns a buildId with the build running asynchronously, building an existing NAME:TAG replaces it, and private repos need one-time browser authorization. This complements the destructiveHint/openWorldHint annotations without contradicting them.

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?

Each sentence adds distinct information: action, no-docker, async, overwrite semantics, auth, local-folder alternative, and recommended reading. No fluff; the structure is logical and front-loaded with the core purpose.

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 complex, destructive, asynchronous tool with 7 parameters and an output schema, the description covers all key user-need areas: what it does, how it works, side effects, failure/alternative paths (local folder), and prerequisite reading. The existence of an output schema reduces the need to describe return values, and this description still mentions buildId.

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 detailed per-parameter descriptions, so the description is not required to compensate. It provides general build context (e.g., 'detects how to build it') but does not add parameter-specific meaning beyond what the schema already states for each field.

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: 'Build a container image on Control Plane from a GitHub or GitLab repository and push it to the org's private registry.' It clearly distinguishes from siblings like get_image_build by stating this is the build action and even clarifies 'ONLY repositories work here.'

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 states when not to use this tool: 'To build a LOCAL FOLDER, tell the user to run `cpln image build --remote --dir PATH --name NAME:TAG`... this server has no access to their filesystem.' It also directs the user to get_cpln_skill('image') for runbook guidance and explains the private-repo auth flow.

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 mark the tool as destructive (destructiveHint=true) and non-read-only. The description adds meaningful behavioral context: the listener reverts to platform defaults, and on 443 with http/http2 the platform re-injects a default TLS block. These details go beyond the annotation flags.

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 the action, and a concise note about the 443 edge case. Every sentence serves a purpose, with no redundant or ambiguous wording.

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 fully explains the operation's effect (revert to defaults) and an important platform-specific behavior (re-injection on 443). Combined with the rich schema descriptions and presence of an output schema, no critical contextual gaps remain for a tool of this complexity.

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

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

Schema description coverage is 100%, and each parameter (org, domain, portNumber) has its own detailed description, including guidance on org lookup behavior. The tool description itself does not add parameter-specific details, so the schema carries the burden effectively. 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 uses a specific verb and resource: 'Remove the TLS configuration from a port listener'. It clearly distinguishes from siblings like remove_domain_port (which removes the whole listener) and set_domain_tls (which adds/updates TLS). The phrase 'the listener reverts to platform defaults' clarifies the 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?

Provides clear context for when to use: clearing TLS from a listener, and includes an explicit caveat for port 443 with http/http2 where TLS cannot be disabled but only reset. However, it does not explicitly name alternatives like remove_domain_port or set_domain_tls, so it misses a direct when-not-to-use comparison.

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 explains the dry-run validation behavior before conversion, noting that invalid manifests return an error instead of HCL. This goes beyond the readOnlyHint annotation by describing a two-phase internal process and the return-value semantics. It also clarifies the `generateImports` behavior and prerequisites, which is valuable behavioral context not present in 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?

The description is three sentences long, tightly packed with essential information: purpose, validation behavior, conditional parameter guidance, and an explicit sibling alternative. Every sentence earns its place, with no fluff or repetition of structured fields.

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 (conversion + dry-run validation + optional imports) and a rich output schema, the description is complete: it covers input requirements, validation behavior, conditional parameters, and the workflow for generated imports. The presence of an output schema means return values don't need to be described, and the description still covers the key behavioral nuances 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 100%, so the schema already documents all parameters. The description adds meaningful context beyond the schema: it explains the dry-run validation interplay with `manifest`, the conditional need for `gvc` based on GVC-scoped kinds, and the operational purpose of `generateImports` (run after init, before apply, to adopt resources). This adds value on top of 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 a specific verb ('Convert') and resource ('Control Plane resource manifest') to Terraform (HCL), and clearly distinguishes from the sibling export_terraform by noting 'To convert an EXISTING resource instead of a manifest, use export_terraform.' This is a clear, specific purpose that differentiates it from related 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 explicitly states when to use the tool (converting a manifest) and provides an alternative (export_terraform for existing resources). It also gives command-level guidance: pass `gvc` for GVC-scoped kinds, set `generateImports` for import commands, and indirectly implies a safe dry-run validation workflow. This is explicit when/alternative 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 indicate readOnly=false, and the description adds behavioral context by saying the tool will 'capture DNS records required for validation' and by specifying minimal route/port requirements. It does not go into failure modes (e.g., non-80/443 ports leaving warning status), but those are detailed in the schema, so this is acceptable.

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 four sentences long, front-loaded with purpose, then minimal-input guidance, then ownership and runbook recommendations. Every sentence contributes valuable information with no redundancy, making it highly concise and well-structured.

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 complex input schema (100% covered) and the presence of an output schema, the description provides the necessary high-level purpose, critical input minimalisms, and a runbook pointer. It is complete enough for an agent to understand when and how to 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?

Schema description coverage is 100%, so the baseline is 3. The description's mention of 'minimal port item is {number, protocol}' and 'route items minimally need workloadLink' is a concise summary of what the schema already documents, adding no genuinely new parameter 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 opens with 'Provision a Control Plane domain, map routes to workloads, and capture DNS records required for validation,' which clearly states the create operation with specific resource and scope. It also gives minimal input shapes for ports and routes, thus distinguishing itself from sibling tools like add_domain_route and update_domain.

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 advises 'Run this in the organization that will own the domain' and recommends reading get_cpln_skill("domain") before first use, providing clear context on when to use the tool. However, it does not explicitly mention exclusions or alternatives (e.g., using add_domain_route for existing domains), which prevents a 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?

The annotations only provide flags (readOnlyHint: false, destructiveHint: false), so the description carries the transparency burden. It reveals that a GVC without placement cannot run workloads, that locationOptions is only geo-routing tuning and not placement, and that server-side resolution of location names occurs. It also warns against guessing regions. It doesn't detail side effects like cost or irreversible changes, but the immutability of names is covered in the schema. Overall, it adds meaningful behavioral context without 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?

The description is detailed but every sentence earns its place. It is front-loaded with the core purpose and placement requirement, then covers the domain separation and ask-first guidance. It is concise for the complexity of the tool, using clear, direct language without redundancy. The structure flows logically from purpose to key constraints.

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 (15 parameters, nested objects, output schema exists), the description covers the most critical aspects: placement is required, what to do if not specified, and what is not handled here (domains). It also references the alternative tool (list_resources) for user choices. The presence of an output schema means return values need not be explained in the description. The description is adequate for an agent to invoke this tool correctly in most scenarios.

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 adds semantic value beyond the schema by clarifying the interaction between `locations`, `locationQuery`, and `locationOptions`, and by explicitly stating that `locationOptions` is not placement. It also gives usage context for the `locations` parameter (e.g., 'never pick one silently'). This helps the agent understand parameter relationships and constraints beyond what individual descriptions provide.

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 ('Create') and resource ('GVC') and clearly defines what a GVC is: 'the deployment scope workloads live in.' It also explicitly differentiates from sibling tools by stating that custom domains are configured via create_domain, not on the GVC, and the placement guidance distinguishes it from other create 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 when-to-use and when-not-to-use guidance. It states that placement is configured through `locations` or `locationQuery`, and that `locationOptions` is not placement. It instructs the agent to ASK first if placement is not specified, referencing list_resources kind='location' as the alternative, and explicitly says 'never guess a region and never create an empty GVC.' It also notes that custom domains are handled by create_domain, not this tool.

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 discloses a significant side effect beyond the annotations: provider blocks can provision real resources in the connected cloud account (AWS IAM roles, GCP service accounts, Azure managed identities). It also adds useful behavioral context about optional networkResources and nativeNetworkResources, complementing the structured hints.

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 compact and front-loaded, with the core action first followed by a few high-value sentences about provider behavior, network resources, assignment, and prerequisite reading. Every sentence adds useful context with no 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 tool with 13 parameters, nested objects, and cloud-provider side effects, the description supplies the essential conceptual framing and points to an access-control runbook. It is complete enough for an agent to understand what creating an identity involves, though it does not spend time contrasting the update/delete lifecycle.

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 covers 100% of parameters with rich descriptions, so the baseline applies. The description adds high-level conceptual value — real cloud resource provisioning and the identity-to-workload link — but does not add per-parameter detail beyond the well-documented input 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 action and scope: "Create a new identity in a GVC." It clearly distinguishes this from update_identity and other sibling tools, and reinforces purpose by explaining that identities are later assigned to workloads via spec.identityLink.

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?

Guidance is implied rather than explicit: the description mentions provider-backed resources, optional network resources, and a recommended access-control runbook to read before first use. However, it does not name alternatives such as update_identity/delete_resource or state when not to use this tool.

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 meaningful behavioral context beyond the annotations: combining target scopes is legal, targetAll wins because target='all' applies to every resource, and addPermissions without a principal list is an-error. It also recommends get_cpln_skill('access-control') as the runbook before first use, which helps the agent anticipate prerequisite knowledge.

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 focused sentences: it fronts the primary purpose, then concisely covers high-risk constraints, and ends with a useful, specialized reference to get_cpln_skill. No redundant text fills the description.

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 13 parameters, nested targetQuery, another output schema, and nested objects, this description is strong because it efficiently highlights the most decision-heavy parts, points to get_cpln_skill for runbook context, and points to get_permissions for valid permission names. The generous schema coverage and output schema make additional detail unnecessary.

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?

Although the schema already covers 100% of the parameter descriptions, the description adds relationship-level semantics by grouping addPermissions with principal lists and explaining the mutual requirement. It also clarifies targetAll's precedence over other target scopes, which is not immediately obvious by reading the schema alone.

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 'Create a new policy' and specifies the core elements: target kind, target scopes, and principal bindings. This clearly distinguishes it from sibling update_policy and other resource-creation tools by naming both the verb, resource, and key 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 gives clear field guidance for when to use this tool and explains key constraints: target scopes may combine, targetAll wins, and principal bindings require addPermissions plus at least one principal list. It does not explicitly contrast using create_policy versus update_policy, but the 'Create a new policy' action and sibling context make that 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?

Discloses many behavioral traits beyond the sparse annotations (readOnlyHint=false, destructiveHint=false): performance class and filesystem type are immutable, snapshot defaults are injected (createFinalSnapshot=true, retentionDuration '7d'), and xfs/ext4 support snapshots while shared does not. These details give the agent essential expectations about side effects and constraints that the annotations do not cover.

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 front-loaded with the core purpose and every subsequent sentence earns its place by adding distinct, high-value information (immutability, snapshot defaults, encryption limitation, mounting guidance, reading recommendation). While long, the length is justified by the tool's complexity and no sentence is redundant.

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 (12 params, nested objects, output schema), the description covers key constraints, defaults, exclusions, and cross-references to related tools and documentation. It provides enough context for correct invocation and successful execution without needing to describe return values since an output schema exists.

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?

Although schema coverage is 100%, the description adds meaningful semantic context by highlighting which parameters are most important (performance class, filesystem type, initial capacity, snapshot policy, autoscaling) and by explaining immutability implications and default injection behavior. This goes beyond what the schema parameter descriptions already state.

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+resource: 'Create a new volumeset in a GVC with explicit performance class, filesystem type, initial capacity, snapshot policy, and (optional) autoscaling.' It clearly names the action and key settings, and differentiates from related tools by stating 'Mount separately via mount_volumeset_to_workload,' making the purpose unambiguous.

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

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

Provides explicit when-not-to-use guidance: customEncryption cannot be set here and requires `cpln apply` with a full manifest, plus it names the alternative tool for mounting (mount_volumeset_to_workload) and clarifies workload type restrictions (ext4/xfs need stateful or vm; shared mounts anywhere). Also recommends reading get_cpln_skill('stateful-storage') before first use, effectively explaining a prerequisite.

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 annotations (readOnlyHint=false, openWorldHint=true, destructiveHint=false), the description discloses that for cron workloads autoscaling/timeoutSeconds/debug are rejected, that type and name are immutable (changing = delete + recreate), and that deciding reachability must happen in this call (deny-by-default, don't patch later). It also mentions reading get_cpln_rules for production-grade defaults. 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?

The description is dense and front-loaded with the main workflow, but it's long and includes a fair amount of detail (e.g., 'the only way', 'do not create closed and patch the firewall afterward') that could be trimmed since it's partly repeated in the schema comments for containers[] and public. Not egregiously verbose, but borderline. It gets a 3 because it's a bit overlong for a tool that has a 100% schema-coverage and a rich 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 the high complexity (21 params, nested objects, many enums) and the 100% schema coverage, the description complements by pointing to get_cpln_rules and get_cpln_skill for runbook details, and covers the decision logic for cron vs other types and when to use templates. It doesn't repeat return values (output schema exists). It could mention error cases (except org-not-found which is in the schema's org param) but that's minor. Overall, complete enough.

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 baseline is 3. The description adds value by linking parameters to the goal: containers[] is the only way to define containers (no flat image/cpu/port fields), autoscaling is the only place to configure scaling, and public/firewallConfig decide reachability. For cron, it says schedule is required and autoscaling/timeoutSeconds/debug are rejected. It also references get_cpln_rules for defaults like minScale ≥ 2 for user-facing services. This slightly exceeds the baseline.

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 creates a workload covering serverless/standard/stateful and cron job types. It's specific about the resource (workload) and the action (create), and it distinguishes from siblings like update_workload, install_template, and build_image. Unlike the sister tools that handle domains or templates, this is the only creation tool for workloads. It also teases the cron type and points to helper tools (get_cpln_rules, get_cpln_skill) for guidance.

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 tells when NOT to use this tool: for databases/caches/queues/brokers/search/gateways/WAF/S3-compatible storage, propose the matching Template Catalog entry first. It also directs to get_cpln_rules and get_cpln_skill before first use, naming the runbook and skill. This contrasts with sibling tools (install_template, update_workload, create_gvc) and gives clear decision criteria.

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 adds critical behavioral context: deletion is permanent, the call triggers deletion immediately ('your client confirms the write first'), and it mandates a user-approval workflow before invoking. It also clarifies that secrets are managed elsewhere, preventing misuse. These details significantly enhance the agent's understanding of consequences.

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 compact yet information-dense. Every sentence contributes value: the core action, the exclusivity, the secrets exception, the immediate deletion behavior, the required pre-call procedure, permanence, and name accuracy. There is 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?

For a destructive tool, the description is exceptionally complete. It covers the action, scope, exclusions, procedural requirements, and permanence. The output schema exists, so not describing return values is acceptable. The combination of annotations, schema, and description leaves little room for ambiguity in a high-stakes delete operation.

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 provides 100% coverage with detailed descriptions for all parameters, including patterns and conditional requirements (e.g., gvc only for GVC-scoped kinds). The description reinforces the importance of 'name' with 'Never invent a name' but does not add substantial new semantics beyond the schema. Therefore, 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 clearly states the tool's function: 'Delete one Control Plane resource by `kind` + `name`'. It also positions it as the single delete tool for every deletable kind, distinguishing it from sibling tools that handle specific removal operations like remove_domain_port or uninstall_template. The exclusion of secrets further sharpens its 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 explicitly says when to use this tool: for any deletable Control Plane resource, and when not to: secrets are not deletable here. It provides a clear pre-call procedure: read the resource, inform the user of impacts, and proceed only on explicit approval. The 'Never invent a name' instruction adds practical safety 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?

Discloses significant non-obvious behavior beyond annotations: throttling of 4 expansions per volume per 24 hours, meaning of HTTP 429, that waiting briefly will not help, and no data loss. This is valuable context annotations cannot 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?

Each sentence is purposeful and informative, front-loading the core purpose, then key behaviors (live, throttling, filesystem support, reading). No redundancy or 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?

Covers live operation, safety, throttling behavior, filesystem compatibility, and recommended reading. Combined with a rich schema and output schema, nothing critical is left unexplained.

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 covers 100% of parameters with detailed descriptions, so the baseline is 3. The description adds no parameter-specific guidance beyond what the schema already provides.

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 'Increase the storage capacity of a volume in a volumeset' with a specific verb and resource, clearly distinguishing it from sibling tools like create_volumeset, update_volumeset, or mount_volumeset_to_workload.

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?

Provides clear usage context: live operation, no downtime/data loss, available for all filesystem types, and a recommended runbook. However, it does not explicitly name alternatives or state when not to use, so it stops short of a 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?

The description adds significant behavioral context beyond the annotations, revealing that secrets are never exported and that unsupported resource kinds are rejected with a list. It also explains the behavior of generateImports and includeDependencies, giving the agent a clear picture of edge cases and side effects.

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 moderately long but every sentence adds value: examples, bulk export behavior, flags, secret handling, error handling, alternative tool, and further reading. It is front-loaded with the core purpose and stays organized.

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 an output schema, the description covers purpose, usage alternatives, edge cases (secrets, unsupported kinds), and parameter guidance. It does not need to describe return values since the output schema covers that, making the description complete for the agent's selection and invocation 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?

The input schema already provides 100% description coverage for all three parameters, including examples and operational details. The tool description repeats much of this information without adding new semantic insights, so it meets the baseline but does not elevate 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 clearly states the tool's purpose: 'Generate Terraform (HCL) for EXISTING Control Plane resources from a self link.' It uses specific verbs and resources, and distinguishes itself from the sibling tool convert_to_terraform by noting the difference between existing resources and in-memory manifests.

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 guidance on when to use this tool, including bulk export scenarios based on path depth. It names an alternative (convert_to_terraform) and excludes secret-exporting cases, effectively covering when-not-to-use. It also directs users to a skill for further reading.

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, and the description adds useful behavioral context: it returns lifecycleStage, status messages, and full JSON, and covers operation types per kind. 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 pack purpose, examples, return info, and required params. The description is front-loaded and every clause adds value; no filler or 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?

With a highly detailed schema and annotations (readOnly, idempotent), the description covers all essential context: what it does, when to use, how to discover IDs, and what it returns. The output schema exists, so return details need not be exhaustive. No significant gaps.

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 each parameter fully documented, including guidance on never guessing org/gvc and discovering commandId via list_commands. The tool description merely summarizes these params without adding new semantics, 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 clearly states the tool fetches an asynchronous-operation command by UUID to check status of long-running operations. It provides examples (cron run, replica stop, volume operations) and mentions return content, distinguishing it from siblings like list_commands and get_workload_logs.

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 when to use the tool (to check status of long-running operations) and points to list_commands for discovering command IDs. It lacks an explicit 'when-not to use' clause, but the context and alternative reference are strong.

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 destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context by detailing what the guide contains and when to consult it, going beyond the annotations to explain the tool's role as a session-level reference.

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, no fluff. The first sentence lists the guide's contents; the second provides usage timing. Both earn their place and the description is front-loaded with the core purpose.

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 simplicity (no params) and the existence of an output schema, the description fully covers purpose, content, and when to use it. It leaves no ambiguity about the tool's role in the broader sibling set.

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 100%, so there is nothing to document. The baseline for 0 params is 4, and the description appropriately omits any parameter details since none 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 clearly states the tool returns the Control Plane operating guide and enumerates its contents (resource model, secrets/images/workloads/domains, defaults, verification, failure handling). This specific verb+resource structure distinguishes it from all sibling tools, which perform concrete operations rather than providing guidance.

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 instructs when to use: once per session before the first create/update/delete, and any time a multi-resource task spans unfamiliar ground. This gives clear, actionable context for the agent and implicitly differentiates it from operation-focused 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, idempotentHint, and destructiveHint, but the description adds rich behavioral context: the runbook includes 'platform constraints that are easy to miss', 'when it is the WRONG tool', and 'what to do with the result'. It also notes session-level reading, going beyond the annotations without contradicting them.

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, front-loaded with the core action, and every phrase earns its place. It efficiently conveys purpose, content, and usage timing without 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?

The tool has a single enum parameter, rich schema coverage, and an output schema exists to describe return values. The description fully addresses what the runbook covers and when to read it, making it complete for the tool's simple yet specialized scope.

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 a detailed enum description explaining 'Skill to read — tools name their skill as recommended reading'. The tool description adds little beyond the schema's own parameter description, so with high coverage a baseline 3 is appropriate; no extra meaning is 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 the tool 'Returns the runbook for one Control Plane task family' with a specific verb and resource, and enumerates the runbook's contents (correct usage, platform constraints, wrong-tool guidance, result handling). This distinguishes it from the many sibling operational tools by positioning it as a meta-resource for learning, not a direct operation.

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 context: 'Tools that belong to a family name their skill as recommended reading; read it once per session before the first such operation.' This tells the agent when to use the tool, though it does not explicitly name alternative tools or provide exclusion criteria beyond implying it is a prerequisite.

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, idempotentHint=true, and destructiveHint=false, so the description doesn't need to repeat that. It adds valuable context: statuses enumeration (queued/building/pushed/failed), automatic log behavior on failure, and the polling guidance. It doesn't describe output format, but that's covered by the output schema. Slight gap: no mention of potential errors or rate limits beyond 'never in a tight loop', but the guidance suffices for behavioral transparency.

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, dense paragraph of about 80 words. It front-loads the core purpose, then explains statuses, log behavior, polling cadence, and a prerequisite reading reference. Every sentence adds value; there is no fluff or repetition of schema details. Highly efficient.

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 that the tool has an output schema (not shown but existence is noted) and complete schema descriptions for all 5 parameters, the description covers the key operational context: status lifecycle, log retrieval conditions, polling guidance, and a pointer to the runbook. For a read-only, idempotent tool, this is comprehensive. No missing elements like error handling or auth are necessary given the existing annotations.

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%; every parameter has a detailed description in the schema. The tool description adds minimal extra insight: it explains the logOffset resume cursor concept ('Echo back nextLogOffset... Only NEW output') and emphasizes includeLog's default behavior, which complements the schema. However, the description doesn't significantly add beyond the schema—the schema already covers semantics. Thus 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 explicitly states: 'Read a build started by build_image: its status, its progress events, and its log.' It names the source tool (build_image) and clearly differentiates from sibling tools like get_workload_logs and get_workload_events by focusing on image build status and log. The verb 'Read' plus the resource 'build started by build_image' is specific and 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?

The description provides explicit usage guidance: 'Read on an interval, never in a tight loop' and 'Recommended reading before first use: get_cpln_skill("image") — the runbook for this tool family (read once per session).' It also explains when includeLog is needed and when it's not, contrasting with default behavior. No explicit exclusions of alternatives are needed because the purpose is so narrowly scoped.

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 (readOnlyHint, idempotentHint, non-destructive), the description discloses a significant behavioral requirement: the token must have `reveal` permission on the helm bookkeeping secret. It also states that values and manifests are never included, adding context that the annotations do not cover. 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?

Three sentences, each earning its place: first states the functionality, second states an exclusion, third states a permission requirement. The description is front-loaded with the verb 'Show' and contains no redundant 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?

An output schema is present, so the description does not need to explain return values. It covers purpose, scope, exclusions, and permission requirements, which is sufficient for a 2-parameter read-only tool. The description is complete for an agent to decide whether to invoke 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?

The input schema has 100% description coverage for both parameters, with detailed explanations (org pattern and release name immutability). The description adds no parameter-specific guidance beyond the overall action. According to the rubric, baseline 3 applies when schema coverage is high and the description does not add extra param 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 the specific verb 'Show' with a clear resource ('an installed release') and enumerates the returned data (status, revision, resources with kind, name, link). It also explicitly states what is excluded ('install values and manifests are never included'), which distinguishes it from sibling tools like get_template or list_installed_templates.

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 an explicit when-to-use: when needing an installed release's current status, revision, and created resources. It also gives a clear when-not-to-use by stating that install values and manifests are never included, signaling that the tool is not appropriate for those needs. This is an explicit exclusion criterion, though it does not name an alternative tool.

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, idempotentHint=true, and destructiveHint=false. The description adds the endpoint and a runbook reference but does not disclose additional behavioral traits such as error handling, auth requirements, or rate limits. It does not contradict 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?

The description is two sentences long and front-loaded: the first sentence states the purpose, the second gives a runbook pointer. No unnecessary words or repetition, making it highly concise and well-structured.

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 simple, with a rich schema, comprehensive annotations, and an output schema. The description covers the operation and points to a runbook for deeper context. It could have mentioned the return value format, but the output schema fills that gap, making it complete enough.

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 both org and kind having descriptive text. Org's schema description includes explicit guidance (e.g., NEVER guess, ask if missing, stop on org-not-found), so the tool description does not need to elaborate. Baseline 3 is appropriate since the schema carries the parameter 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 explicitly states 'Fetch available permissions for a resource kind' and names the endpoint, making the operation unambiguous. It also distinguishes itself from sibling tools like get_resource or get_resource_schema by focusing specifically on permissions retrieval.

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 includes a prerequisite: 'Recommended reading before first use: get_cpln_skill("access-control")', which is a usage preparation hint. However, it does not explicitly state when to use this tool vs alternatives or provide exclusions, so the usage context is implied from the purpose sentence rather than directly spelled out.

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 mark it as readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable behavioral detail: secrets return metadata only (API never includes data), and it returns a summary plus full JSON. This goes beyond annotations without contradicting them.

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 four sentences long, front-loaded with the core purpose, then adds usage guidance and a security caveat. Every sentence contributes actionable information without 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 single-resource fetch tool, it covers the essential operational details: resource selection (kind+name), org singular behavior, return format (summary + full JSON), secrets handling, and recommended usage (before update/delete). The output schema exists, so the description need not elaborate on return fields.

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 each parameter well-documented. The description reiterates the kind+name lookup and org exception, but does not add meaningful semantics beyond what the schema already 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 uses a specific verb ('Fetch') and resource ('Control Plane resource by kind + name'), immediately clarifying the operation. It explicitly states 'The single read-one tool for every resource kind,' which distinguishes it from sibling tools like list_resources and search_control_plane.

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 provides clear usage context: 'Call this before any update or delete to capture current state.' While it doesn't name alternatives or explicitly state when not to use, the phrase 'single read-one tool' strongly implies it should be used for individual reads, and the context is sufficient for an agent to differentiate.

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 (read-only, idempotent, non-destructive), the description discloses that large schemas return shallow maps with `{"_expand":"<path>"}` stubs, that server-managed fields are removed, and that `name` and `kind` are required at create. This adds meaningful behavioral context beyond what annotations provide.

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 appropriately sized, front-loaded with the core purpose, and every sentence delivers actionable guidance without redundancy. It balances length with density of useful 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?

Given the rich input schema, annotations, and output schema, the description is complete. It covers what the tool returns, when to use it, how to handle large schemas, and the requirements for creating resources, with no critical gaps.

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 provides 100% parameter descriptions, so the baseline is 3. The description adds value by explaining the `path` expansion behavior with an example ('spec.containers') and clarifying the `gvc` requirement for GVC-scoped kinds, slightly exceeding the baseline.

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 it returns 'the exact object schema and REST API endpoints for a Control Plane resource kind' with the purpose of authoring manifests for `cpln apply` or direct API calls. It distinguishes itself from sibling tools by positioning itself as the mandatory first step before any manifest creation.

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 provides explicit when-to-use instructions: 'ALWAYS call this FIRST whenever you are about to write a cpln apply YAML/JSON file, set up CI/CD... or build a request body.' It also states what not to do ('do not hand-write a manifest or guess field names from memory') and explains when to pass `gvc` and `path`.

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 readOnly, idempotent, and non-destructive, so the description does not need to restate the safety profile. It adds the 'chosen (or latest) version' default and the pre-install workflow, but no further behavioral context like auth requirements or rate limits.

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 the tool's function followed by a concrete next action. No filler or redundant qualification.

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 an output schema and read-only annotations present, the description fully covers the caller's workflow: what the tool returns and how to use it before installation. Nothing essential 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 100%, so the baseline is 3; the description echoes the version default ('latest') but adds little beyond what the schema already states. It connects the template and version parameters to the returned example values, but does not meaningfully extend the parameter documentation.

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, 'Show,' with a specific resource: a catalog template's versions, prerequisites, whether it creates its own GVC, and the example values.yaml. It also positions itself relative to install_template, making its read-only detail role 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?

It gives explicit when-to-use guidance: read this before install_template, and copy/edit the returned values to configure deployment. It does not explicitly contrast with browse_templates or state when not to use it, which leaves a small gap in routing to 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?

Annotations already declare readOnly/idempotent/non-destructive, and the description adds significant behavioral context: truncation of very large traces to the first spans in tree order, with error spans always listed. It also describes the output structure (span tree, per-span durations/services, error-span list), which goes well beyond annotation coverage.

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 serving a distinct purpose: stating the function, giving usage guidance, and disclosing a limitation. It is front-loaded with the core purpose and contains no 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?

The description covers what the tool does, how to use it, and a critical limitation (truncation). Since an output schema exists, the description doesn't need to detail the return format further. This is complete for a complex trace-summarization tool.

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 already fully documents both org and traceId with patterns and constraints, so the description doesn't need to add much. It reinforces that traceId comes from query_traces results, but this is also in the schema. No new parameter semantics are provided 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 clearly states the tool fetches a trace by ID and summarizes it with a span tree and error-span list, explicitly sourcing from query_traces. This distinguishes it from sibling tools like get_resource or get_template, and the verb 'Fetch' plus resource 'distributed trace' is specific and 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?

The description provides clear usage context: 'Use it to pinpoint WHERE latency or failures sit inside a request path.' It also implies a workflow by referencing query_traces as the source, but it doesn't explicitly state when not to use it (e.g., alternative tools for listing or other analysis).

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, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds context about the tool's diagnostic purpose and suggests a workflow, which supplements the annotations without 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?

Three sentences, each purposeful: purpose, usage scenario, and recommended prerequisite. Front-loaded with the core action and outcome, no fluff or repetition.

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 an output schema, the description fully covers when to use, why, and complementary actions. Combined with rich schema descriptions and annotations, it is complete for effective use.

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 each parameter (org, gvc, name) having detailed guidance (e.g., never guess org, discover gvc). The description itself doesn't add parameter-level details, but the schema already does the heavy lifting, warranting the baseline score.

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 ('Fetch'), resource ('event log for a workload'), and the diagnostic purpose ('readiness/liveness probe issues and errors'). It clearly distinguishes from sibling tools like get_workload_logs by specifying event log vs. logs.

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 states when to use ('Use after a deploy fails') and pairs it with specific alternatives/complements ('list_deployments and get_workload_logs'). Also recommends a runbook (get_cpln_skill) for first-time users, providing valuable context.

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 readOnly, idempotent, and non-destructive. The description adds significant behavioral detail: raw query replaces structured params entirely and must embed all labels, filter is a literal substring match (|=) not regex, and replica/stream are only accessible via raw query. It also discloses return shape (structured JSON with timestamps, messages, labels). This exceeds what annotations provide without 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?

The description is information-dense with no filler. Once the purpose is stated, it covers structured vs raw query, label availability, filter semantics, the cron special case, return type, and a recommended runbook—each sentence adds distinct value. The length is justified by the tool's complexity; it is not bloated.

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 12 parameters, a raw query mode, and intricate edge cases, the description covers nearly all necessary context: dual modes, special labels, regex handling, cron workflow, return format, and prerequisite reading. Combined with full schema coverage and an output schema, it is complete enough for an agent to invoke 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% for all 12 parameters, so baseline is 3. The description adds meaningful semantic context beyond the schema by explaining the relationship between `query` and structured params (replacement semantics), the exact meaning of `filter` (literal substring vs regex), and which labels are only available via raw query. This is valuable but not a full per-parameter breakdown, so a 4 is merited.

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 'Query workload logs from a GVC', giving a specific verb and resource. It clearly distinguishes this tool from siblings like query_metrics or query_traces by focusing on workload logs, and further clarifies the tool's two modes (structured params vs raw LogQL).

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 gives explicit guidance on when to use structured params versus a raw query, noting that replica and stream labels are only reachable via raw query and that regex requires a raw query. It also provides a specific alternative workflow for cron workloads using list_deployments, and recommends a prerequisite skill. This is thorough and actionable.

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 annotations (readOnlyHint=false, idempotentHint=true), the description adds valuable disclosures: never returns secret values, does NOT modify workload env/volumes, and creates/updates policy binding. It also explains the resume behavior of paused deployments. 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?

The description is front-loaded with the core purpose, then proceeds through prerequisites, safety, non-behaviors, and resource pointers. Every sentence earns its place—no filler. The length is appropriate for a tool with 6 parameters and important caveats.

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 complexity (mutation, prerequisites, security considerations) and presence of output schema and annotations, the description is complete. It covers identity creation, policy binding, secret existence, non-modification of env/volumes, and references the skill runbook. No critical gaps remain.

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 parameter-specific meaning beyond the schema; it mentions 'pass the name only' indirectly through schema descriptions but not in the tool description itself. Schema already handles parameter semantics thoroughly.

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+resource+scope: "Grant an EXISTING workload access to a secret" and explains the mechanism (ensures identity, creates/updates policy binding with reveal permission). It clearly distinguishes this from sibling tools like create_identity or create_policy by framing it as a composite grant operation, not just identity or policy creation.

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 states prerequisites and alternatives: workload must already exist (call create_workload first for new workloads), secret must exist (use setup-secret skill if missing), and points to get_cpln_skill("setup-secret") as recommended reading. It also mentions the behavioral consequence of deployment pausing until access is granted, giving clear when-to-use 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 only declare readOnlyHint=false and destructiveHint=false; the description carries the behavioral burden and does so well. It discloses creation semantics, asynchronous deployment requiring follow-up verification, the preview/dry-run path, version defaulting, and the gvc condition — traits an agent cannot infer from annotations alone.

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 front-loaded with the core action and then covers parameter essentials, validation, verification, and prerequisite reading in five purposeful sentences. No filler or repetition of schema details beyond a useful one-line summary.

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 6-parameter, 4-required create operation with no nested objects and an output schema, the description is complete: it explains input sources, when gvc is optional, how to validate first, how to confirm the result, and where to learn more. The only minor concern is referencing preview_template, which is not in the sibling list, but 'where available' mitigates the risk.

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 restates key parameter behaviors already present in the schema (version defaults to latest, values come from get_template, gvc matters unless the template creates its own) but adds no new parameter-level information beyond what the schema documents.

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 object: 'Install a catalog template as a new release.' The phrase 'new release' and the explicit parameter list (name, template, version, values, gvc) distinguish it from sibling tools like upgrade_template and uninstall_template.

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?

Provides clear context: validate first with preview_template when available, deployment is asynchronous and must be verified with get_installed_template, and get_cpln_skill('template-catalog') should be read first. It does not explicitly state when to prefer upgrade_template/uninstall_template for existing releases, so it stops short of full when-not coverage.

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 destructiveHint=false, so the safety profile is covered. The description adds useful behavioral context by explaining lifecycleStage transitions (pending → running → completed/failed) and the kinds of operations (cron runs, replica stops, volume operations), which goes beyond the annotations without contradicting them.

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: first explains what is listed and shown; second explains required/optional parameters and points to get_command. It packs substantial detail without redundancy or 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?

The tool has a rich output schema and annotations, so the description doesn't need to explain return structure. It fully covers scope, required inputs, and alternative tools. The only minor gap is not specifying a default for limit (schema says 'default: all'), but that is present in the schema.

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 detailed descriptions for all six parameters (e.g., 'kind' explains workload vs. volumeset; 'gvc' includes discovery guidance). The tool description adds minimal parameter-level semantics 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 clearly states the tool lists asynchronous operation commands against a workload or volumeset, enumerates specific command types, and distinguishes from the sibling tool get_command by noting 'Use get_command for one command’s full status.' This is a specific verb-plus-resource with clear sibling differentiation.

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 specifies required parameters (kind, gvc, name) and an optional filter (lifecycleStage), and explicitly directs users to get_command for single-command details. While it doesn't list exclusions (e.g., when not to use), the guidance is clear and actionable, earning above-average but not perfect.

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 substantial behavioral context beyond the readOnly/idempotent annotations: it explains the difference between omitting vs. specifying 'location', the presence of version chain and per-container readiness/restarts/messages in the full detail, and the status.jobExecutions location for cron workloads. It also warns against constructing URLs manually, which is not inferable from 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?

The description is dense yet well-organized: purpose → usage pattern → parameter behavior → cron edge case → related tools. Every sentence contributes unique value with no redundancy or 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?

The description fully contextualizes the tool within the workload lifecycle: it explains readiness polling, when to use with/without location, special cron handling, and how to combine with events/logs for diagnostics. The presence of an output schema means return-value details do not need to be exhaustively described.

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 covers all parameter descriptions at 100%, but the description adds key semantic nuance for the 'location' parameter (omit for all locations + canonical URL, pass a location for single deployment detail) and clarifies the use of org/gvc/workload. This exceeds the baseline for a fully-documented 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 clearly defines the tool as listing a workload's per-location rollout status, and explicitly distinguishes it from diagnostic tools like get_workload_events and get_workload_logs. It also positions it as the primary readiness check after create_workload/update_workload, making its purpose unmistakable.

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: poll after create/update until ready, use without 'location' for all-location readiness, and pair with get_workload_events/get_workload_logs for failure diagnosis. It also tells the agent to report the canonical endpoint as the public URL and never hand-construct it.

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 disclose readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds the scope 'in an org' and the output fields, but does not provide additional behavioral context such as pagination, authorization requirements, or rate limits. It does not contradict annotations.

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

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

The description is two concise sentences with no filler. The first sentence states the action and the output fields; the second points to a more specific sibling tool for deep detail. Every sentence serves a purpose.

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 listing tool with a detailed output schema and strong annotations, the description is complete. It communicates the scope (org), the output fields, and directs users to get_installed_template for per-release details. No significant gaps remain.

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 covers 100% of parameters with detailed descriptions (org pattern, limit min/max), so the description's reference to 'org' adds little beyond the schema. The mention of returned fields is about output, not parameter semantics. Baseline 3 is appropriate when the schema already provides thorough parameter documentation.

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 'List the template releases installed in an org' and enumerates the returned fields (name, template, version, GVC, revision). It uses a specific verb ('List') with a resource ('template releases') and explicitly distinguishes itself from get_installed_template, making the purpose unambiguous.

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

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

The description provides an explicit alternative: 'Use get_installed_template for the resources and status of a specific release.' This tells the agent when not to use this tool and when to choose a sibling instead, satisfying the criteria for when/when-not/alternatives 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=true, idempotentHint=true, and destructiveHint=false, so the bar is lower. The description adds substantive behavioral context: it returns both documented defaults and live org metrics, and the `metric` parameter fetches real label dimensions and values from live data. 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?

The description is longer than typical but every sentence adds value: purpose, return content, parameter nuances, and usage triggers. It is front-loaded with the key 'discover' message and structured logically. Minor verbosity is justified by the tool's broad scope.

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 existence of an output schema and annotations covering safety, the description is complete enough: it states what is returned, how to filter, how to ground metrics, and when to use it. Minor omissions like pagination details are not critical 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?

Input schema covers all parameters with descriptions (100% schema_description_coverage), so baseline is 3. The description enhances meaning by clarifying `filter` is a case-insensitive substring that narrows 'catalog and live metric names' and that `metric` exposes live label dimensions (workload, gvc, location) and works for custom metrics, 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 opens with a specific verb and resource: 'Discover what metrics you can query before calling query_metrics'. It enumerates exactly what is returned (documented default metrics with types and PromQL templates, plus live metrics including custom and kube_/node_ families), clearly distinguishing it from sibling tools like query_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?

Explicit usage guidance is given: 'Reach for this whenever a metrics query returns nothing or you are unsure of names/labels' and the exclusion 'optional, not required when you already know the metric you want.' It positions the tool as a precursor to query_metrics, making the use case unmistakable.

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, idempotentHint=true, and destructiveHint=false, and the description confirms 'Read-only'. It adds useful context about the response format ('Each entry includes current usage, max, unit, and any dimensions') and the ≥80% nearLimit threshold, which goes beyond annotation coverage.

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 sentences front-load the primary purpose, then provide a concrete filter use case and an escalation path. There is no filler or redundancy; every sentence contributes to agent understanding.

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?

This is a simple tool with full annotations, a complete schema, and an output schema. The description covers the key use case (pre-provisioning check), response contents, and the alternative action for quota increases, leaving no significant gaps.

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 schema itself robustly documents all three parameters, including org's 'NEVER guess' guidance. The tool description adds no new parameter meaning beyond the schema, 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 opens with 'List quotas for an organization (per-org Control Plane resource limits)', providing a specific verb, resource, and scope. This clearly differentiates it from sibling tools like list_resources or list_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?

The description explicitly frames the nearLimit=true filter as a 'what is about to break?' check to run before provisioning. It also provides a clear when-not: 'Read-only — to raise a quota, request an increase by pinging Control Plane on Slack or emailing support@controlplane.com'.

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?

While annotations already declare readOnlyHint, idempotentHint, and destructiveHint, the description adds valuable behavioral context: it returns a summary table (not full JSON), and it clarifies that workload deployments are excluded. This goes beyond the annotations, though it stops short of describing pagination or default limits, which are partially covered by the 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?

The description is three sentences, front-loaded with the core purpose. Each sentence earns its place: function, usage pattern, and alternative tools. 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?

The tool has a rich schema, annotations, output schema, and many siblings. The description covers the tool's role, required inputs, GVC-scoping nuance, and key alternatives. With the output schema handling return-value details, nothing essential 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%, so the baseline is 3. The description mentions the key parameters (kind, org, gvc) and provides examples, but this largely mirrors what the schema already documents. It does not add new semantic details about format or behavior beyond the schema, so it stays at the baseline.

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 lists Control Plane resources of one kind as a summary table, using the specific verb 'list' and identifying the resource type. It distinguishes itself from get_resource (full JSON) and list_deployments (deployments are not a kind), making its 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?

The description explicitly positions this as 'the single read-list tool for every resource kind' and provides concrete usage instructions (pass kind, org, and gvc for GVC-scoped kinds). It also names alternatives: get_resource for a single item's full JSON and list_deployments for workload deployments, offering clear when-to-use and when-not-to-use 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=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds a bit of context by clarifying it deals with 'running replicas' and being an 'operational inventory', but it does not disclose additional behavioral details such as pagination, authentication requirements, or rate limits. With strong annotations, a score of 3 is appropriate.

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 long, front-loading the purpose in the first sentence and adding useful context (operational inventory, runbook recommendation) afterward. It is concise and well-structured, though the runbook sentence is somewhat ancillary to the tool's immediate purpose.

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 has an output schema, so return values do not need explanation. The description covers the purpose, scope, and a recommended prerequisite (the runbook). With 5 params fully documented in the schema, this is reasonably complete for a read-only list tool, though it could perhaps mention the default location behavior explicitly.

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 rich descriptions for each parameter (e.g., 'NEVER guess' for org, guidance on gvc). The tool description itself does not elaborate on parameters, relying on the schema to carry that weight. Given the high coverage, this meets the baseline of 3.

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 identifies the action ('List the names of the running replicas (pods) of a workload in a location') with a specific verb and resource. It distinguishes itself from siblings like list_deployments or get_workload_logs by focusing on the inventory of running pods, which is a distinct operational concern.

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 states a clear use case ('Read-only operational inventory for confirming which replicas are currently serving'), providing context for when to use the tool. It also recommends a runbook before first use. However, it does not explicitly name alternatives or state when not to use this tool, so it stops short of a 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?

Beyond the annotations (idempotentHint=true), the description reveals critical behaviors: mounting only into the FIRST container, the create-only nature of size/fileSystemType/performanceClass, workload-type constraints, and the immutable workload-type consequence that requires delete/recreate downtime. This is substantial added transparency.

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 compact given the tool's complexity, with approximately five sentences each carrying essential information. It front-loads the primary action, then covers create-only semantics, workload-type rules, immutability warning, and a reference to the skill runbook—no filler or 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 tool with 11 parameters, conditional create semantics, and workload-type restrictions, the description covers all key behavioral caveats and even references a runbook for deeper context. Since an output schema exists, return values need not be explained. The description is sufficiently complete for correct tool selection and 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 input schema already provides 100% parameter descriptions, including the create-only semantics for size/fileSystemType/performanceClass and workload-type rules for fileSystemType. The tool description reinforces these in a concise summary, adding a holistic view that ties parameters to the overall flow, but does not introduce entirely new 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 opens with a specific verb+resource: 'Attach a volumeset to a workload — mounts into the FIRST container only.' This unambiguously identifies the tool's action and scope, and distinguishes it from siblings like create_volumeset, expand_volumeset, and create_workload.

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 states when to use this tool (attach volumeset, optionally creating it) and when not (e.g., size is ignored if the volumeset already exists, implying expand_volumeset for growth). It also explains workload-type requirements and points to get_cpln_skill('stateful-storage') for first-use guidance, giving explicit context and 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is clear. The description adds useful behavioral context beyond annotations: events are "merged and sorted newest-first" when multiple names are supplied, and platform events live in the built-in `cpln` context. This exceeds the baseline but stops short of describing pagination or edge cases.

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: purpose, usage variants, filtering/context note. No redundancy or fluff. It is front-loaded with the core purpose 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?

The description covers the key high-level behaviors: audit trail, mutations, same-kind scope, all/single/multiple mode, filtering capabilities, and the default cpln context. With a rich schema and an output schema present, it does not need to explain parameter syntax. Minor gap: it does not mention when custom contexts are relevant for workload-written events, which is left to the schema.

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 reference `name` and `names` and their omit/supply behavior, but this information is already present in the schema descriptions. No additional parameter meaning is added, so the score remains at the baseline.

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: "Query the Control Plane audit trail for mutations on one or more resources of the same kind." This clearly distinguishes the tool from sibling tools like query_metrics, query_traces, and get_resource, which target different data. The scope (mutations, same kind) is explicit.

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 actionable guidance: "Omit `name` and `names` to fetch every event... Supply `names` to audit multiple resources in one call." It also mentions filtering by subject, context, and time range. However, it does not explicitly name alternative tools or state when not to use this tool, so it falls short of a 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?

Beyond the annotations (readOnly, idempotent, non-destructive), it discloses key behaviors: default range query over last hour at 60s step, result slicing to first 50 series in prose, full Prometheus response as JSON, and the rule never to wrap pre-rated metrics in rate(). 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?

The description is long but information-dense; every sentence serves a purpose, from defaults to output format to metric-type rules to fallback guidance. It is front-loaded with the primary action and default behavior, followed by examples and alternatives.

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 defaults, time-window handling, resolution modes, output truncation, metric-type guidance, and explicit fallback to list_metrics. With an output schema present, return-value documentation is unnecessary, leaving no significant gap.

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?

Although the schema has 100% coverage, the description adds crucial parameter semantics: what 'instant' vs 'range' means, how since/from/to interact, and metric-type-specific query patterns (gauges bare, counters with rate(), histograms with histogram_quantile). This goes far beyond the schema's field 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 opens with a specific verb and resource: 'Run a PromQL query against Control Plane metrics (Prometheus-compatible).' It clearly distinguishes from siblings by naming list_metrics as the lookup tool and focusing on Prometheus metrics versus audit events or traces.

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 when to use the tool directly ('If you already know the metric, just query it') and when to call list_metrics first ('Only when you are unsure... or a query returns no series'). It also gives a concrete use case: 'Use this to verify autoscaling signals before changing scaling settings.'

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 readOnly/idempotent annotations, the description discloses that a raw `traceql` query REPLACES structured params, that traces are only present when tracing is enabled and sampled, and that results are a table of trace IDs with root span, start time, and duration. This adds real behavioral context without contradicting 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?

The two-sentence description is information-dense but efficient; it front-loads the core purpose, then packs interaction rules, prerequisites, and output format without 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?

Given the complexity of 11 parameters, an output schema, and annotations, the description covers the essential selection guidance, the replace semantics of traceql, the tracing-enabled prerequisite, sampling caveat, and result shape, making it a complete usage summary.

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?

While the schema fully documents each parameter, the description adds critical interaction semantics: raw `traceql` replaces all structured filters, and `minDuration` is framed as the slow-request finder. It also lists available span attributes for query authoring, exceeding 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 opens with a specific action ('Search distributed traces (Tempo/TraceQL)') and states the purpose ('find slow or failing requests'), explicitly distinguishing itself from the sibling get_trace for drilling into a single trace.

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 specifies the use case (find slow or failing requests), names the follow-up alternative (get_trace), and notes a key prerequisite (tracing must be enabled on the GVC). It doesn't enumerate all exclusion cases but gives sufficient context for 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?

Given annotations already indicate destructive and idempotent behavior, the description adds valuable context about the immediate impact on live traffic and workforce reachability. This goes beyond the structured hints and helps the agent anticipate consequences.

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, front-loaded with the action, and every word adds value. There is no filler or repetition of structured data.

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 destructive removal tool, the description is sufficient: it states the action and immediate consequences. With complete schema, annotations, and an output schema, it does not need to explain return values. Minor omissions like prerequisites are not critical given the schema covers 'existing listener port number.'

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 already provides descriptions for all three parameters (100% coverage), so the description does not add parameter-level meaning. The baseline of 3 is appropriate because the schema handles the details and the description's mention of 'port' aligns with portNumber.

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 ('Remove a port listener from a domain') with a specific verb and resource, distinguishing it from sibling tools like remove_domain_route. The scope is 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?

The description implies when to use this tool by focusing on port listeners, but it does not explicitly mention alternatives or when not to use it. The consequence of live traffic stopping provides contextual cues, but no exclusion or alternative guidance is given.

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 mark this as destructive and idempotent, and the description adds the specific consequence of 404 responses until a new route is configured. This is useful behavioral context beyond the structured hints, though it omits details like permission requirements or failure modes.

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 just two sentences: the first states the action, the second explains the consequence. No filler, no redundancy, and the most important information 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?

With full schema coverage, an output schema, and annotations covering destructive/idempotent behavior, the description adds the key implication (404 until a new route). It does not mention prerequisites like the route needing to exist, but that is likely covered by the output schema or implied by the operation.

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 detailed parameter descriptions including the routeIdentifier identity semantics. The tool description itself adds no additional parameter meaning beyond what the schema provides, so a 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 uses a specific verb 'Delete' and clearly identifies the resource as 'a single route entry from a port listener.' This distinguishes it from sibling tools like remove_domain_port and add_domain_route, and the phrase 'single route entry' narrows the scope appropriately.

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 clear context by stating the immediate effect ('Traffic that matched this route returns 404 on the affected listener until a new matching route is configured'), which helps the agent understand when this destructive tool is appropriate. However, it does not explicitly mention alternatives or when not to use it, so it falls short of a 5.

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