Control Plane

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

The description contradicts the annotations: it says 'Errors if a listener for that port number already exists', which implies non-idempotent behavior, but the annotation has idempotentHint=true. No other behavioral details are disclosed beyond what annotations already provide, and the contradiction undermines trust.

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

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

The description is concise with three sentences, front-loading the purpose and adding necessary usage guidance. No wasted words, though the contradiction slightly detracts from overall utility.

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 nested objects and optional fields, the description covers the minimal requirement, error condition, and points to additional reading. The output schema exists, so return values are not needed. However, the contradiction with annotations leaves a gap in behavioral understanding.

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 descriptions for all parameters. The description adds minimal value beyond summarizing the minimal port definition and noting optional fields. Baseline 3 is appropriate as the schema does the heavy lifting.

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

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

The description clearly states the verb (Add) and resource (new port listener to a domain). It distinguishes from sibling tools like add_domain_route and remove_domain_port by specifying the exact action and resource.

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

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

The description explicitly tells when to use this tool (to add a new port listener) and when not (if listener already exists, use other tools). It also recommends reading a runbook, providing context for first-time users.

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

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

Annotations indicate idempotent, non-destructive, and open world. The description adds the critical behavioral rule that the new route must not collide with an existing one, which explains potential failure modes. It does not detail exact error behavior but adds value beyond 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, each earning its place: purpose and action, minimal route and matching options, and alternative tool plus learning resource. No unnecessary words.

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

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

Given the complexity of nested parameters and many sibling tools, the description covers the essential points: what the tool does, how to construct the route, collision constraint, and reference to further documentation. The output schema exists, so return values are not needed. Slightly missing mentions of preconditions (listener existence) but overall sufficient.

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

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

With 100% schema coverage, the description still adds value by summarizing the minimal valid route structure and the default matching behavior (omit prefix/regex to match '/'). This helps the agent quickly understand the most common usage without reading the full 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 action ('Append a route entry to an existing port listener'), specifies the minimal route structure, and distinguishes from the sibling tool 'update_domain_route' by mentioning replacement. The purpose 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 explicitly says when to use (appending), when not to (must not collide), and provides an alternative ('Use update_domain_route to replace an existing entry'). It also recommends the runbook for first-time use, giving clear 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 readOnlyHint, idempotentHint, destructiveHint, and the description clarifies it's a listing operation that returns specific fields (name, category, version, GVC info), fully consistent 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 concise and well-structured, starting with the action 'List', providing examples, usage guidance, and next steps in a single focused paragraph with 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?

Complete for a read-only browse tool with one parameter and an existing output schema; it covers what the tool returns, when to use it, and how to proceed (call get_template), leaving no 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 schema already fully describes the filter parameter (case-insensitive substring), and the description only repeats 'Pass `filter` to narrow' without adding new semantic meaning, warranting the baseline score for high coverage.

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

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

The description states the tool lists the Control Plane Template Catalog with specific examples, and distinguishes itself from sibling tools like get_template by positioning itself as the first step for browsing common services.

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 users to 'Reach for this first' when they want a database, cache, queue, etc., and advises passing a filter and then calling get_template for details, providing clear workflow 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?

The description adds useful behavioral context beyond annotations: it states the listener reverts to defaults and specifies that on port 443 with http/http2, TLS cannot be disabled only reset. This aligns with destructiveHint=true and idempotentHint=true, and provides nuance.

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

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

The description is extremely concise: two sentences with no wasted words. The main action is front-loaded, and the caveat about port 443 is provided immediately.

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

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

Given the simple nature of the tool and presence of output schema, the description is comprehensive enough. It explains the core behavior and a key edge case. Could mention that only TLS is affected, but overall sufficient.

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 descriptive parameter descriptions for org, domain, and portNumber. The description does not add additional parameter semantics beyond the schema, so 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 removes TLS configuration from a port listener and reverts it to platform defaults, with a specific note about port 443 behavior. This distinguishes it clearly from sibling tools like set_domain_tls.

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

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

The description implies usage for clearing TLS on ports other than 443, but does not explicitly state when to use this tool versus alternatives like set_domain_tls or remove_domain_port. The note about port 443 provides some guidance but overall lacks explicit when/when-not 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?

The description reveals that the manifest is dry-run validated before conversion (no resource created), returning errors instead of HCL for invalid manifests. This adds context beyond the readOnlyHint and idempotentHint annotations, detailing the exact behavior and error handling.

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

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

The description is concise at four sentences, each serving a distinct purpose: stating the main function, explaining validation, indicating gvc usage, describing generateImports, and providing the sibling alternative. No redundant or unnecessary information.

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

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

For a tool with 4 parameters, existing output schema, and full annotations, the description covers the core purpose, validation behavior, parameter conditions, import command workflow, and alternative tool. It provides sufficient context for correct 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?

Schema coverage is 100%, so baseline is 3. The description adds extra guidance for 'generateImports' (when to run the import commands) and reiterates the gvc condition. While most parameter details are already in the schema, the additional context for generateImports slightly increases value.

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

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

The description uses a specific verb 'convert' and clearly identifies the resource (Control Plane manifest YAML/JSON to Terraform HCL). It distinguishes the tool from the sibling 'export_terraform', which is for existing resources, by explicitly stating the alternative.

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

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

Explicitly states when to use this tool (for manifest conversion) and when not (for existing resources, use export_terraform). Also provides a condition for the 'gvc' parameter (required for GVC-scoped kinds) and explains the purpose of 'generateImports'.

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

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

Annotations indicate a write operation (readOnlyHint=false) and not destructive (destructiveHint=false). The description adds context about provisioning, DNS validation, and organizational ownership, but 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 one paragraph of about 4-5 sentences, front-loading the main purpose. It is reasonably concise without fluff, but could be slightly shorter.

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 (11 parameters, 4 required) and the existence of an output schema, the description covers the main purpose and minimal requirements. It lacks details on error states or special port behavior, but is adequate.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds minimal parameter context (minimal port and route items) but does not significantly enhance understanding 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 provisions a Control Plane domain, maps routes to workloads, and captures DNS records. It specifies minimal requirements for ports and routes, distinguishing it from sibling tools like add_domain_port or 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 instructs to run the tool in the owning organization and recommends reading a runbook first. However, it does not explicitly state when to avoid this tool or compare it to alternatives like update_domain or add_domain_route.

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

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

Annotations already provide readOnlyHint=false and destructiveHint=false. The description adds no additional behavioral context beyond that. It does not mention side effects, permissions, or rate limits, but also 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 sentences, front-loaded with the purpose, and efficient. Every sentence adds value 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 (15 parameters, nested objects, output schema exists), the description covers critical usage points (locations, alternative tool) and avoids unnecessary detail. The output schema handles return values, so completeness is high.

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 does not add new semantic information for parameters beyond what the schema already provides; it focuses on usage advice rather than parameter details.

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 'Create a new GVC (Global Virtual Cloud)' with a specific verb and resource. It distinguishes the tool from sibling tools like create_domain, create_identity, etc., by focusing on the GVC resource.

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: requires locations, advises to ask user first (not guess), warns against creating empty GVC, and directs to create_domain for custom domains. This fully addresses when and how to use the 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 provide no hints (readOnlyHint=false, etc.), so the description must carry the burden. It states 'Create a new identity' indicating mutation, but fails to disclose side effects, permissions required, or any behavioral traits beyond creation. The return values are handled by output schema, but the creation process itself (e.g., synchronous, idempotent) is not mentioned.

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-loading the core purpose and a usage recommendation. Every word earns its place, with no redundancy or fluff. It is appropriately concise for a tool with a rich input 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 tool's complexity (13 parameters, nested objects), the description is too brief. It does not explain the structure of identity creation, how to choose between network resource types, or the relationship between identity and workload. The runbook recommendation helps, but the description itself is incomplete for a first-time user.

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 mentions optional seeding of networkResources and nativeNetworkResources, but this is already clear from the schema. No additional parameter-specific meaning is added that goes beyond what the schema provides. Hence, the description adds minimal value here.

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

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

The description clearly states the tool creates a new identity in a GVC, with optional network resource seeding. It uses a specific verb and resource, and the mention of assignment via spec.identityLink adds clarity. Although it doesn't explicitly differentiate from siblings like update_identity, the action 'create' is distinct enough.

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 recommends reading a runbook before first use, which provides context. However, it does not explicitly state when to use this tool versus alternatives (e.g., update_identity), nor does it provide any exclusions or specific usage scenarios. The guidance is minimal.

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

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

Annotations indicate non-read-only and non-destructive. The description adds important behavioral context: name immutability (renaming = delete+recreate), error conditions (missing principal list), and the need for naming conventions. No contradictions.

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

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

Two well-structured sentences with critical information front-loaded. Every part is meaningful with no waste.

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 (13 params, nested objects, output schema exists), the description covers the essential constraints and setup. The output schema handles return values, so no need to describe them. Slightly incomplete regarding the full scope of targetQuery structure, but adequate.

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

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

All 13 parameters have schema descriptions (100% coverage), so baseline is 3. The description adds value by explaining the relationship between parameters (exactly one target scope, principal bindings), which goes beyond individual parameter descriptions.

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

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

The description clearly states the tool creates a new policy, specifies the required components (target kind, target scope, principal bindings), and is distinct from sibling tools like update_policy or delete_resource.

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 and provides critical constraints (exactly one target scope, principal bindings with addPermissions plus at least one principal list). Recommends reading the runbook, but doesn't explicitly differentiate when not to use.

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?

Description only restates 'create' and notes server assembly, adding minimal context beyond annotations. Annotations already indicate it's not read-only and not destructive, so description provides little new behavioral insight.

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, 18 words, front-loaded with purpose. Every word earns its place; no fluff 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?

Despite output schema existing (from context signals), the description omits success/error states, uniqueness constraints (e.g., name immutability mentioned in schema but not reinforced), and behavior on duplicate entries. Adequate but with notable gaps for a creation tool with nested parameters.

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 descriptions for each parameter. Description adds only generic 'provide the typed fields below', which does not enhance understanding beyond the schema. 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 verb 'create' and the resource 'dictionary secret', and explains it is a map of arbitrary key→value string pairs. This distinguishes it from sibling secret types like docker, ecr, opaque, tls.

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

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

No guidance on when to use this tool vs alternatives (e.g., when to use dictionary vs opaque secret). No exclusions or context for selection among the many sibling secret creation tools.

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

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

Annotations already indicate readOnlyHint=false and destructiveHint=false. The description adds the behavioral note that 'the server assembles the secret data', providing some additional context beyond 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 concise sentences that immediately convey purpose and process. No unnecessary words.

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

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

The description covers the core purpose and input method. With an output schema present, it does not need to detail return values. Slight omission: no mention of required vs optional parameters, but the schema covers that.

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 a general instruction about typed fields but does not enhance parameter meaning.

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 'Create', the resource 'docker secret' / 'Docker registry pull secret', and distinguishes from sibling secret types by specifying the Docker registry scope.

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

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

The description implies usage for Docker registry authentication via 'Docker registry pull secret', but does not explicitly compare with alternatives like create_secret_opaque or create_secret_tls. Context is clear enough.

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 readOnlyHint=false and destructiveHint=false, so the description's statement 'the server assembles the secret data' adds a minor behavioral note about data assembly. However, it does not disclose error behavior, idempotency, or side effects beyond creation. The description adds limited value over 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 extremely concise with two short sentences, no redundant information, and front-loads the main action. Every word serves a purpose, making it efficient for an agent to parse.

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

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

Given the tool has 9 parameters (5 required) and an output schema exists, the description is minimal. It does not explain what the server returns, any prerequisites (e.g., existing ECR repository), or post-creation effects. While output schema reduces the need for return value details, the creation process itself is underspecified.

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 states 'Provide the typed fields below; the server assembles the secret data', which does not add meaningful semantic detail beyond what each parameter's description already provides. No additional context is given for parameters like constraints or relationships.

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 'Create a ecr secret' with specific resource type 'ECR pull secret (AWS creds scoped to one or more ECR repos)'. This distinguishes it from sibling tools like create_secret_docker or create_secret_opaque, as it is purpose-built for ECR pull credentials.

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

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

The description does not explicitly guide when to use this tool versus alternatives. While the name and context imply it is for ECR pull secrets, there is no mention of prerequisites, when not to use it, or comparisons with other secret types. Sibling tools cover different secret formats, but no guidance is provided.

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

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description adds no behavioral traits. It states that the server assembles the data, but does not disclose potential failures, idempotency, or whether existing secrets are overwritten. For a create operation, more transparency about side effects would be helpful.

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-loads the key information, and contains no unnecessary words. 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?

Given the presence of an output schema and comprehensive schema descriptions, the description is largely complete. It could briefly mention the output (e.g., secret metadata) but the output schema likely covers that. For a create tool, this is sufficient.

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 individual parameter descriptions. The tool description adds minimal value beyond the schema—it only generically mentions 'typed fields' and 'server assembles the secret data.' Baseline score of 3 is appropriate.

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

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

The description clearly states the action ('Create') and the resource ('opaque secret'), and distinguishes it from sibling secret tools by noting it is the most common type for a single freeform value. It also directs the user to provide typed fields, 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 implies this is for single freeform values (the most common type), but does not explicitly state when to use this tool versus alternatives like create_secret_dictionary or create_secret_tls. No 'when not to use' or exclusion criteria are provided; the name alone does the differentiation.

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 non-readOnly and non-destructive behavior. The description adds minimal behavioral context beyond stating creation and that the server assembles the data. No contradictions, but no significant additional disclosure beyond 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 short sentences, front-loading the core purpose. Every sentence is necessary and free of fluff, achieving maximum conciseness.

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

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

Given the tool has an output schema and 100% parameter documentation, the description is nearly complete. It briefly explains the assembly process, but lacks mention of immutability or output structure, though these are covered in the schema. Slight gap in summarizing key constraints.

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%, providing thorough parameter details. The description's mention of 'typed fields' and 'server assembles' adds little new meaning; the schema already adequately documents each parameter.

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 'Create a tls secret' and specifies the components (certificate, private key, chain). It clearly distinguishes from other secret types like create_secret_opaque or create_secret_docker, 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?

The description does not provide guidance on when to use this tool over alternatives such as create_secret_opaque or update_secret_tls. It lacks explicit context for when a TLS secret is appropriate, leaving the agent to infer from the name alone.

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 indicate this is not read-only or destructive, the description elaborates on immutable fields (performance class, filesystem type, name), snapshot default injection, and renaming consequences. 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 average but every sentence adds critical information. It is front-loaded with the main purpose and well-structured. Could be slightly more concise, but the detail is justified given complexity.

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 12 parameters, required fields, nested objects, and existing output schema, the description covers all essential behavioral aspects: creation steps, immutability, snapshot defaults, limitations, and related tools. No gaps identified.

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%, but the description adds significant value beyond the schema: explains how initialCapacity minimums depend on performanceClass, that mountOptions only apply to shared filesystem, and the distinction between fileSystemType options (xfs/ext4 support snapshots, shared does not).

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 creates a volumeset with explicit parameters, distinguishing it from siblings like expand_volumeset, mount_volumeset_to_workload, and update_volumeset. It provides a specific verb-resource combination and 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 states when to use this tool (create a volumeset) and when not to use it (customEncryption cannot be set here, use cpln apply instead). It also directs to use get_resource_schema first and mentions mounting via mount_volumeset_to_workload.

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 important behavioral traits beyond annotations: type and name immutability (delete+recreate), cron-specific parameter rejections, public omitted meaning deny-by-default, secret reference reveal permission, and platform defaults for probes and scaling. No contradiction with annotations (readOnlyHint=false, openWorldHint=true, destructiveHint=false).

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 well-structured with line breaks and bold for emphasis. It front-loads the main purpose and provides detailed guidance. Given the tool's complexity (21 parameters), the length is justified, though a more streamlined version could be slightly more concise.

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 tool with nested schemas and 4 required parameters, the description is thorough: covers immutable fields, cron specifics, firewall decisions, secret handling, KEDA prerequisites, and references to related tools. Output schema exists, so return values need not be detailed.

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 summarizing key parameter constraints (e.g., containers is the only way to define containers, autoscaling metric defaults per type, cron parameter exclusions) but some repetition of schema details exists.

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

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

The description clearly states the tool creates serverless/standard/stateful workloads or cron jobs. It differentiates from siblings by explicitly mentioning that for databases/caches/etc. the Template Catalog should be proposed first, and it references other tools like get_cpln_rules and get_cpln_skill.

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?

Extensive guidance is provided: when to use cron vs other types, when to set public, how to define containers in the typed array, autoscaling restrictions per type, and explicit instructions to decide firewall exposure at create time. It also advises against guessing org/gvc and recommends reading the runbook.

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

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

Annotations indicate destructiveHint=true, and the description adds crucial context: 'Deletes on the call (your client confirms the write first),' 'Deletion is permanent,' and the prerequisite to read the resource first. This builds trust beyond what annotations alone 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?

Every sentence is purposeful: purpose, confirmation behavior, precondition, permanence, and naming guidelines. No wasted words despite being a single paragraph; it is front-loaded with the core action.

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

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

The description covers the tool's purpose, preconditions, side effects (permanent), and parameter usage guidance. With an output schema present, not detailing return values is acceptable. The description is complete for safe and 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?

With 100% schema description coverage, the description still adds significant value: for 'org' it warns 'NEVER guess' and how to handle errors; for 'gvc' clarifies it's required only for certain kinds; for 'name' gives examples for domain and image; for 'kind' lists all values. The schema descriptions alone would not capture this behavioral nuance.

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 'Delete one Control Plane resource by kind + name' and positions itself as 'the single delete tool for every deletable kind,' providing a specific verb and resource while distinguishing it from sibling tools that are not deletion-oriented.

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 clear guidance: 'Before calling, read the resource and tell the user what the deletion removes and which dependents break, and proceed only on their explicit approval.' Also advises 'Never invent a name.' Though it does not explicitly mention alternative tools, there are no other delete tools among siblings, so the guidance is 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 (readOnlyHint=false, idempotentHint=true, destructiveHint=false) are minimal. The description adds critical behavioral details: live operation, no data loss, throttling behavior, filesystem compatibility, and the recommendation to read a runbook. This goes well 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 concise (3 sentences), front-loaded with the primary action, and includes essential behavioral notes without fluff. 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?

Given the tool has 7 parameters (6 required), an output schema, and annotations, the description covers all essential aspects: what the tool does, safety profile (no downtime/data loss), throttling constraints, filesystem compatibility, and a recommended runbook. No critical information 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%, and each parameter already has detailed descriptions in the schema (e.g., GVC slug usage rules, immutability of names). The tool description adds no additional parameter-specific meaning, 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 explicitly states 'Increase the storage capacity of a volume in a volumeset,' providing a specific verb and resource. This clearly distinguishes it from sibling tools like create_volumeset, update_volumeset, and 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?

The description provides clear usage context: it is a live operation with no downtime, details throttling limits (4 per volume per 24 hours) and HTTP 429 handling, and recommends reading a runbook. However, it does not explicitly contrast with alternatives or state when not to use this tool, missing a minor opportunity for exclusion guidance.

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

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

Annotations already indicate readOnly, idempotent, non-destructive. Description adds important behavioral details: secrets embed revealed plaintext, refs targeting secrets directly are refused without includeSecretValues, unsupported kinds return supported list. No contradiction.

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

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

Description is comprehensive yet concise, covering all key aspects in a dense paragraph. Some restructuring could improve readability, but every sentence adds value and is front-loaded with 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 complexity (4 params, bulk export, secrets handling, output schema exists), description covers input, flags, behavioral nuances, error handling, and references sibling tools. Users have sufficient info to use 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%, but description adds significant value beyond schema: explains self link path depth, usage of generateImports after terraform init, includeDependencies for self-containment, and security implications of includeSecretValues. Provides actionable context.

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

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

The description clearly states it generates Terraform HCL for existing resources from a self link, differentiating single vs. bulk export. It explicitly distinguishes from sibling tool 'convert_to_terraform' which handles 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?

Provides explicit guidance on when to use this tool (export existing resources) vs. convert_to_terraform. Details when to set generateImports, includeDependencies, and includeSecretValues with clear context. Recommends reading get_cpln_skill for further 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, destructiveHint=false, so the safety profile is covered. The description adds behavioral context about content scope and usage pattern, but 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?

Two sentences with no wasted words. Front-loaded with the purpose and then usage advice. Every sentence adds value.

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 zero parameters and an output schema present, the description fully explains what the tool returns and provides usage context. No 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?

No parameters exist, so the description correctly omits parameter details. Baseline score of 4 is appropriate as no additional parameter information 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?

Description clearly states it returns the Control Plane operating guide and lists the specific topics covered (resource model, secrets/images/workloads/domains, defaults, verification, failure handling). The verb 'Returns' and resource 'operating guide' are specific, and it distinguishes from sibling tools which are all about specific actions (create, update, delete, etc.)

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 advises reading it once per session before the first create/update/delete, and anytime a multi-resource task is unfamiliar. This provides clear when-to-use guidance and implies when not to use (skip if familiar).

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 readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds value by detailing the contents of the runbook (constraints, wrong tool indications, result usage), going beyond the annotations to inform the agent of behavioral traits.

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, each serving a distinct purpose: first explains what the runbook contains, second explains when to use the tool. No redundant information, front-loaded with key concepts.

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

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

Given the tool has one parameter, full annotation coverage, and an output schema (not shown), the description covers purpose, usage, behavioral traits, and result handling. It is complete for the tool's simplicity.

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 a complete enum listing. The description adds 'Skill to read — tools name their skill as "recommended reading".' which provides context but does not significantly extend the schema's own description. 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?

Description explicitly states: 'Returns the runbook for one Control Plane task family — how to use the feature correctly, the platform constraints that are easy to miss, when it is the WRONG tool, and what to do with the result.' This clearly identifies the verb (returns) and resource (runbook), and distinguishes it from sibling tools which are concrete actions.

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: 'Tools that belong to a family name their skill as recommended reading; read it once per session before the first such operation.' It also states the runbook itself will indicate when the tool is the WRONG choice, offering clear context for when to use this tool versus 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 indicate readOnlyHint=true and idempotentHint=true. The description adds that the tool requires secret reveal permission because release state is stored in a helm-release secret, which is valuable behavioral context beyond the annotations.

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

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

Description is a single clear sentence plus a short permission note, with no wasted words. Front-loaded with the primary action and return values.

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 presence of an output schema, the description covers all necessary aspects: what is returned (status, revision, resources), a permission constraint, and the tool's read-only nature. No gaps identified.

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 has 100% description coverage with detailed explanations for org and name. The tool description does not add additional parameter semantics beyond what the schema provides, so a baseline score of 3 is appropriate.

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

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

Description clearly states the tool shows an installed release's status, revision, and created resources, with a specific verb and resource. It distinguishes from sibling tools like get_template, list_installed_templates, and install/uninstall.

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?

Description mentions a permission requirement (secret reveal), which is a usage condition, but it does not provide explicit guidance on when to use this tool versus alternatives like get_template or list_installed_templates. Usage is implied but not contrasted with 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 provide readOnlyHint, idempotentHint, and non-destructive nature. Description adds the endpoint path but no further behavioral traits like rate limits or authorization needs. With good annotation coverage, a 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?

Two sentences: first states purpose, second gives a usage recommendation. No filler, front-loaded with core 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?

With an output schema present, the description need not detail return values. It covers purpose and a recommended reading. The tool is simple with 2 parameters and clear schema, so description is largely sufficient.

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. The tool description does not add extra meaning beyond the schema, 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?

Description clearly states the tool fetches available permissions for a resource kind, with a specific endpoint path. Differentiates from sibling tools like get_resource or get_resource_schema, which serve other purposes.

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

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

Recommends reading get_cpln_skill('access-control') as a runbook before first use, which is explicit guidance. However, does not specify when to use this tool versus alternatives like get_resource or get_resource_schema.

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 declare readOnlyHint, idempotentHint, and destructiveHint, the description adds that it returns a summary plus full JSON, and that secret values are masked. This provides behavioral context beyond the annotations.

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

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

Three sentences, each earning its place: purpose, special behavior (secret masking), and usage advice. Front-loaded with core purpose and constraints; no wasted words.

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

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

Given the complexity of resource kinds and many sibling tools, the description covers org special case, secret masking, and pre-update/delete recommendation. Output schema exists, so return value details are not needed. Completes the tool's role effectively.

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 baseline is 3. The description adds meaning: no name for org kind, naming conventions for domain (full hostname) and image (NAME:TAG), and that gvc is required only for GVC-scoped kinds. This enhances parameter understanding.

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 fetches one Control Plane resource by kind and name, with a specific exception for org (no name required). This distinguishes it from list_resources and other read 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?

Explicitly states it is the single read-one tool for all kinds, advises using reveal_secret for masked secret values, and recommends calling it before update/delete to capture current state. Provides 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?

Discloses that large schemas return stubs and explains how to expand them via `path`. Mentions that server-managed fields are removed and `name`/`kind` are required at create. All consistent with annotations (readOnlyHint, idempotentHint, destructiveHint). No contradiction.

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

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

The description is informative but could be slightly more concise. Each sentence adds value, and the critical instructions are front-loaded. Minor verbosity in the middle.

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 covers the tool's purpose, usage context, parameter behavior, and limitations (e.g., stub expansion). With high schema coverage, annotations, and output schema present, 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?

With 100% schema coverage, the description adds significant value by explaining when each parameter is needed (e.g., `gvc` for GVC-scoped kinds, `path` for expansion, `maxDepth` for depth control). Provides actionable advice like 'never guess the org slug'.

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 exact object schema and REST API endpoints for a Control Plane resource kind, enabling accurate manifest authoring or direct API calls. It distinguishes from siblings by being the only tool that provides schema information.

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 to call this tool FIRST when writing manifests or building API requests, including a strong directive not to guess field names. Provides conditions for using specific parameters like `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 indicate read-only, idempotent, non-destructive behavior. Description adds further details about the specific information returned (versions, prerequisites, GVC creation, example values) and that it can target a specific version or the latest, which goes beyond 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 that front-load key outputs and purpose, with no wasted words. The structure efficiently conveys all necessary 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 tool's simplicity (read-only retrieval of template details), the description covers all major outputs. The presence of an output schema (not shown) further reduces the need to describe return values. Slightly lower due to lack of mention of pagination or error handling, but not critical for this 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?

Schema coverage is 100% with already clear descriptions for both 'template' and 'version' parameters. The description does not add new semantic meaning for the parameters themselves, just recommends copying the example values, which is a usage hint rather than parameter explanation.

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

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

Description clearly states the tool shows catalog template details including versions, prerequisites, GVC creation info, and example values. It specifically distinguishes from sibling tools like browse_templates and install_template, making its role 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 says 'Read this before install_template' and advises to copy and edit example values for deployment configuration. This provides clear context, though it does not explicitly state when not to use 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds context about the kind of events returned (probe issues, errors), which helps the agent understand the diagnostic value. No contradictions.

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

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

Three sentences, each earning its place: purpose, usage guidance, and a recommendation to read a skill. Front-loaded with the core purpose, no wasted words.

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

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

With an output schema present, return values are covered. The description provides sufficient context for a simple read-only tool with three well-documented parameters, including usage scenarios and companion tools.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add any parameter-level information beyond the schema; it only implicitly references the workload identity.

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 verb 'Fetch' and resource 'event log for a workload', with a specific diagnostic purpose 'to diagnose readiness/liveness probe issues and errors'. It distinguishes from sibling tools like get_workload_logs and list_deployments by explicitly mentioning them as companions for triangulation.

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 ('Use after a deploy fails'), recommends companion tools for triangulation, and suggests reading a skill runbook before first use. This is comprehensive 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=true, idempotentHint=true, destructiveHint=false), the description adds critical behavioral details: raw query replaces structured params, filter is literal substring not regex, raw query is unsanitized, and return format is structured JSON with timestamps, messages, and labels. 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?

The description is a single paragraph that is front-loaded with the main action. Every sentence adds value, covering modes, labels, cron handling, and recommendations. It is moderately long but efficient; slight improvement could be achieved with bullet points for clarity.

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 two query modes, multiple labels, cron edge case, and reference to a runbook, the description is thoroughly complete. It includes output format, unsanitized warning, and specific label availability, making it fully actionable for an AI agent.

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 significant system-level context: explains the structured vs. raw query dichotomy, which labels are accessible only via raw query, and the difference between filter (|=) and regex (|~). It also details the cron workflow, adding value beyond individual parameter descriptions.

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

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

The description clearly states 'Query workload logs from a GVC.' as the purpose, using a specific verb and resource. It distinguishes from siblings like list_deployments for cron workloads and recommends get_cpln_skill as a runbook for this tool family.

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 structured params vs. raw query, including specific scenarios like accessing replica/stream labels or using regex. It also gives step-by-step instructions for cron workloads involving list_deployments and raw queries, and recommends reading the runbook before first use.

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

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

Annotations indicate readOnlyHint=false and destructiveHint=false. The description adds value by disclosing asynchronous deployment and the need to verify with get_installed_template. It also mentions validation step, which helps the agent understand non-obvious behavior.

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, each concise and meaningful. It front-loads the purpose, then flows logically through validation, async note, and recommended reading. No unnecessary words.

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

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

Given the tool's complexity (6 params, async behavior, validation workflow), the description covers all essential aspects: purpose, usage flow, parameter hints, error prevention (validation), and post-deployment verification. Output schema exists, so return values need not be detailed here.

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%, but the description adds a helpful summary of which parameters to provide and their roles (e.g., 'version defaults to latest', 'gvc unless the template creates its own'). This aids understanding beyond 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 clearly states 'Install a catalog template as a new release,' using a specific verb and resource. It distinguishes from siblings like browse_templates, get_template, upgrade_template, and uninstall_template by focusing on the initial installation action.

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: recommends validating with preview_template first, mentions async deployment with verification via get_installed_template, and suggests reading get_cpln_skill for context. It lacks explicit when-not-to-use but gives clear 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 indicate readOnly, idempotent, non-destructive. Description adds behavioral details: polling semantics, distinction between location modes, and specific fields returned (version chain, per-container readiness, restarts, messages). No contradiction.

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

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

Description is informative but slightly verbose. It front-loads the core purpose and provides critical usage guidance. Each sentence adds value, though some could be tightened without losing clarity.

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 (4 params, output schema exists) and annotations, the description covers all necessary context: purpose, usage modes, behavior, and linkage to other diagnostic tools. 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 coverage is 100% with detailed parameter descriptions. The tool description further explains the impact of the location parameter, distinguishing between listing all locations vs. full detail for a single location, adding value 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's purpose: listing per-location deployment status for a workload. It distinguishes itself as the primary readiness check after create/update operations and differentiates from siblings like get_workload_events by specifying its role.

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 guides when to use: poll without location until ready, then report canonical endpoint. It specifies never to construct URLs manually and pairs with get_workload_events and get_workload_logs for diagnosis, providing clear 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 the return fields (name, template, version, GVC, revision), which is helpful but not essential beyond the annotations.

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

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

Two efficient sentences: first states purpose and output, second provides alternative. No wasted words.

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

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

For a listing tool with 2 parameters, strong annotations, and an output schema, the description is complete. It covers purpose, scope, and differentiation.

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 description does not elaborate on parameter syntax or meaning beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description clearly states the verb 'List' and the resource 'template releases installed in an org', specifies fields returned (name, template, version, GVC, revision), and explicitly differentiates from the sibling tool 'get_installed_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?

The description explicitly guides when to use this tool (to list all installed templates) vs. an alternative (get_installed_template for specific release). It does not explicitly state when not to use, but the context is clear.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds value by explaining it returns both documented default metrics (with type and PromQL template) and live/custom metrics, and that passing `metric` yields real label dimensions. This goes beyond annotations, though annotations already cover safety and idempotency.

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 front-loaded with the core purpose. Every sentence adds value (discovery, behavior, parameter use, usage guidelines). Some redundancy exists (e.g., 'live data' mentioned twice), but overall it is well-structured and informative without fluff. Score 4 due to slight verbosity.

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 covers the tool's functionality: what it returns (defaults with templates, live custom metrics), how to filter (`filter`), how to get label dimensions (`metric`), and when to use. Given the complexity (discovery tool with multiple return types) and that an output schema exists, this description is complete and leaves no 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 coverage is 100% with descriptions for all 4 parameters. The description adds context beyond schema: for `filter` it explains substring narrowing, for `metric` it explains grounding with real labels, for `org` it warns against guessing, and for `limit` it states default 'all' (not in schema). This extra guidance earns above baseline 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 explicitly states it is for discovering metrics before calling `query_metrics`, and distinguishes itself as a discovery tool vs. its sibling `query_metrics`. It specifies the verb 'discover' and the resource 'metrics', with clear 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 provides explicit when-to-use guidance: 'Reach for this whenever a metrics query returns nothing or you are unsure of names/labels' and also clarifies when not needed ('optional, not required when you already know the metric you want'). It also names the alternative sibling tool `query_metrics`.

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 that the output is a summary table, implying a non-exhaustive view, and clarifies scope (e.g., workload deployments excluded). This adds some context beyond annotations but not extensive behavioral details.

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

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

The description is two sentences: first summarizes purpose and scope, second provides parameter guidance and alternatives. Every word is necessary, no redundancy, and the key 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?

Considering the 4 parameters (all schema-described), annotations, and presence of an output schema, the description covers the core behavior, parameter usage, and distinguishes from key sibling tools. It doesn't mention the limit parameter or pagination, but those are in the schema. Overall, complete for a list 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?

Schema description coverage is 100%, so the baseline is 3. The description adds usage examples for kind and clarifies that gvc is required only for GVC-scoped kinds, which is already in the schema but reinforced. It does not add significant new meaning 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 lists Control Plane resources of one kind as a summary table, using the verb 'list' and specific resource identifier. It distinguishes from siblings by pointing to get_resource for full JSON and list_deployments for workload deployments, which are not covered 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?

The description explicitly tells when to use this tool (for listing any resource kind) and when not to (for single item JSON use get_resource, for deployments use list_deployments). It also specifies required parameters and context. However, it could be more explicit about other sibling list tools like list_metrics, but those are different domains.

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. Description adds the context that listing is read-only and that exec uses the first replica by default, which is helpful beyond annotations. No contradictions.

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

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

Three concise sentences: purpose, usage guidance, and recommendation. No wasted words, front-loaded with key 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 output schema exists, description doesn't need to detail return values. It adequately explains what the tool does and how to use it, and includes a reference to a runbook for deeper context.

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

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

Schema coverage is 100%, so baseline is 3. The description does not add any parameter-specific details beyond what the schema already provides, such as format or constraints.

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

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

The description clearly states it lists the names of running replicas (pods) of a workload in a location. It distinguishes itself from sibling tools by explaining its use before workload_exec to target a specific replica, differentiating it from other list 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?

Explicitly states when to use this tool ('Use this before workload_exec to target a specific replica with its replica argument') and what happens without it. Also recommends reading a skill runbook, providing context for first-time use.

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

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

Annotations indicate idempotentHint=true, destructiveHint=false. The description adds critical behavioral details: it creates volumesets if missing, ignores create-only parameters on existing volumesets, mounts only to the first container, and enforces file system type rules. This fully discloses the tool's side effects and constraints beyond what annotations convey.

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

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

The description is moderately long but every sentence serves a purpose. It is front-loaded with the core action and uses formatting (bold) for emphasis. The inclusion of a skill recommendation adds context without being overly verbose, maintaining good conciseness.

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 11 parameters, 3 required, and presence of an output schema (not shown), the description covers all key behavioral aspects: idempotency, create vs. mount, workload-type rules, and parameter role differentiation. It references a runbook for deeper context, making it complete for an AI agent to understand proper 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%, but the description adds significant value by explaining which parameters are create-only (size, fileSystemType, performanceClass) and their specific constraints (e.g., high-throughput-ssd requires size ≥ 200). It clarifies that workloadName must reference an existing workload and that volumesetName defaults to '{workloadName}-vol'. This enriches the schema's already detailed descriptions.

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

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

The description clearly states the action ('attach a volumeset to a workload'), specifies scope ('mounts into the FIRST container only'), and distinguishes from sibling tools by explaining create-on-missing behavior and workload-type rules. It leaves no ambiguity about what the tool does and how it differs from alternatives like 'create_volumeset' or 'expand_volumeset'.

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 context: when to use (mount volumeset to workload), when parameters are ignored (create-only for existing volumesets), workload-type constraints (ext4/xfs require stateful/vm, shared mounts on any), and recommends reading a skill before first use. It also warns about immutability of workload types, guiding appropriate usage.

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 readOnlyHint=true and idempotentHint=true. The description adds important behavioral traits: events are merged and sorted newest-first, supports filtering by subject and time range, and mentions platform events in the cpln context. No contradictions.

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

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

The description is a single paragraph that efficiently conveys the main purpose and key details. It is front-loaded with the primary function. Could benefit from slight restructuring but is still concise.

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 output schema exists (not shown but indicated true), the description covers the key behaviors: merging, sorting, filtering, and context handling. It is complete enough for a query tool with 11 parameters.

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 baseline is 3. The description adds significant meaning beyond the schema: explains the relationship between name/names, from/to vs since, kind usage for custom contexts, and subject patterns. This adds value.

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

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

The description clearly states it queries the Control Plane audit trail for mutations on resources of the same kind. It specifies the verb 'Query' and the resource 'Audit Events', distinguishing it from sibling tools like query_metrics or get_workload_events.

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

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

The description explains when to use the tool, including how to omit name/names for all events, use names for multiple resources, and the GVC requirement for GVC-scoped kinds. It does not explicitly state when not to use, but the context is clear enough.

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 slicing to first 50 series, full JSON response, automatic org scoping, and parameter interactions. All annotations are consistent and description adds significant context beyond read-only/idempotent 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?

Dense and front-loaded with key information; every sentence adds value, though slightly long. Could be more concise but 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?

Fully covers complexity: defaults, metric types, edge cases, and sibling guidance. Output schema exists, so return value explanation is 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?

Schema has 100% coverage, but description adds concrete examples for query, explains resolution differences, and clarifies parameter overrides, enriching 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?

States the tool runs a PromQL query against Control Plane metrics, clearly distinguishing from sibling list_metrics by explicitly noting when to use the sibling instead.

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 extensive guidance: default behavior, parameter adjustments, metric type examples, and explicit instructions to call list_metrics when unsure of metric names or no results.

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 annotations by stating that live traffic stops immediately and workloads become unreachable. This reinforces the destructiveHint and openWorldHint. No contradiction.

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

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

Two sentences with no fluff. First sentence states action, second describes consequences. Efficient 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 tool's complexity (3 required params, annotations, output schema), the description covers purpose and consequences well. Minor gaps: does not mention idempotency or error cases like non-existent port.

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

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

Schema coverage is 100% and the schema already describes all three parameters well. The description does not add further meaning to the parameters, so 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 ('Remove') and resource ('port listener from a domain'), clearly stating the action and immediate consequence. It distinguishes this tool from siblings like 'remove_domain_route' and 'add_domain_port'.

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

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

The description implies usage (to stop traffic on a port) but does not explicitly state when to use this tool vs. alternatives or when not to use it. No mention of prerequisites or conditions.

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 destructiveHint=true, but the description adds value by explaining the concrete behavioral outcome: traffic returning 404 until a new route is configured.

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 wasted words. The first states the action, the second explains the consequence. Efficient and 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?

Given the existence of an output schema and full schema coverage, the description covers the core purpose and effect. It could benefit from noting when to use this over remove_domain_port, but is otherwise 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 description does not need to add parameter details. It adds no extra meaning 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 action ('Delete') and the resource ('a single route entry from a port listener'), effectively distinguishing it from sibling tools like add_domain_route or remove_domain_port.

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

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

The description implies usage by mentioning the 404 effect, but does not explicitly state when to use this tool over alternatives or provide when-not 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 that the result prints plaintext into conversation context and warns against persistence. Adds context about auditing and permission requirements beyond 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, no wasted words, front-loaded with purpose, then usage and behavioral notes. 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 the presence of an output schema, the description covers purpose, usage, behavioral impact, and permission—leaving no 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 coverage is 100% and the description adds crucial guidance for userRequestedPlaintext, emphasizing it must be true only on explicit user request.

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 reveals actual secret data with break-glass access, distinguishing it from siblings like workload_reveal_secret. It specifies the verb 'Reveal' and resource 'secret data'.

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 to call ONLY when the user explicitly asks for plaintext, and contrasts with using cpln://secret/NAME references. Provides clear usage boundaries.

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, destructiveHint=false. The description adds that it returns contextual content with titles and links, but no new behavioral traits beyond 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: first states purpose, second gives usage and next steps. Every word is valuable, 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?

Tool is simple (one param, read-only). Description covers purpose, usage, output format, and how to get full content. Output schema exists to document return structure.

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?

Only one parameter 'query' with a basic description. Schema coverage is 100%, so the schema carries the burden. Description doesn't add query syntax or format details, meeting the baseline 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 states it searches the Control Plane knowledge base for relevant info, code examples, API refs, and guides. It distinguishes from the sibling query_docs_filesystem by explaining when to use each.

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

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

Explicitly says when to use (answer questions, find docs, understand features) and provides a specific alternative (query_docs_filesystem) with instructions on appending .mdx.

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 destructiveHint=true and idempotentHint=true. The description adds the key behavioral detail that existing settings are overwritten, which aligns with destructiveHint and provides practical guidance. 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 with no filler. Each sentence adds distinct value: purpose, behavioral warning, and preparatory recommendation. Well 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?

Given the presence of a sibling tool for clearing TLS (clear_domain_tls) and the annotations, the description covers the essential contextual need: it's a write operation that overwrites. It does not detail the output schema but that is provided separately. Minor gap: no mention of error handling or prerequisites beyond reading the runbook.

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 parameters are well-documented structurally. The description adds crucial usage insight: 'Provide the complete TLS shape' implying a full replacement, not incremental update. This compensates for any ambiguity in schema about partial updates.

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 ('Set or replace the TLS block'), specifies the resource ('port listener'), and lists the components affected ('cipher suites, minimum protocol version'). It distinguishes from sibling clear_domain_tls by emphasizing replacement.

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 warns that existing TLS settings are overwritten and recommends reading the runbook for the tool family before first use. It does not explicitly mention when not to use (e.g., to remove TLS), but the context is clear enough.

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 destructiveHint=true. The description adds that resources are removed, confirming the destructive nature. It also includes a recommended reading link, which adds helpful context beyond 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 extremely concise: two sentences, no fluff. The first sentence states the action and result. The second sentence provides a usage hint. Every word earns its place.

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

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

Given the tool's simplicity (2 parameters, all required, with 100% schema coverage, destructiveHint annotation, and an output schema), the description fully covers what an AI agent needs to know to select and invoke the tool correctly.

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