Ankra

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

Annotations only declare readOnlyHint=false, idempotentHint=false and destructiveHint=false; the description goes well beyond that by disclosing non-obvious side effects ('Auto-creates the namespace manifest and wires dependency parents') and the secret-handling contract (never pass a real secret, use ANKRA_SECRET_PARAMETER, use ${variable_name} for customisable values). These are exactly the behaviors an agent could not infer from the structured fields.

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

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

Purpose is front-loaded in the first sentence, followed by the non-deploy nature, side effects, and parameter conventions. Every sentence carries distinct information and nothing is repeated from the schema or annotations.

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 non-idempotent mutation into a draft with no output schema, the description covers purpose, side effects, and the tricky value/secret semantics well. It stops short of describing what the call returns (e.g. an addon id for follow-up calls) or any auth/permission prerequisite, which would make it fully self-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%, so the baseline is 3 and the schema already documents all seven parameters. The description adds genuine meaning on top of it: it defines the secret-value convention for values_yaml and the ${variable_name} convention, and clarifies that 'parents' is a deploy-order wiring concept.

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

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

States a specific verb ('Add') and resource ('a Helm chart addon to a stack profile builder draft'), which is enough to separate it from add_manifest_to_stack_profile_draft by resource type. It does not explicitly name a sibling or alternative, so it stops short of the 5 bar, but the scope is unambiguous.

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

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

'This composes the reusable template - nothing deploys and no cluster is needed' gives clear context that this is a draft-authoring step rather than a deploy action. However, it never states when to prefer it over add_manifest_to_stack_profile_draft or update_addon_in_stack_profile_draft, so no explicit exclusions or alternatives are given.

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

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

With annotations only stating it is a non-read-only, non-idempotent, non-destructive write, the description carries rich extra context: Ankra validates the token reaches the zone with DNS edit before storing anything, the zone's external-dns runs upsert-only and never modifies or deletes records it doesn't own, and the operation is refused when the generated zone already covers it. This is exactly the behavioral disclosure that annotations cannot 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 purpose is front-loaded in the first clause, followed by prerequisites, validation behavior, and refusal condition. The single long sentence-chain is dense but every clause contributes; it could be broken into sentences for readability but nothing is wasted.

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

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

For a mutation tool with no output schema and sparse annotations, the description covers prerequisites, validation, side effects, and failure conditions well. The only minor gap is that it says nothing about what the tool returns or confirms on success.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema by explaining the credential_name/provider coupling (provider 'cloudflare' requires an organisation Cloudflare credential) and the organisation-scoped nature of the credential. It does not, however, clarify the cluster_id vs cluster_name optionality.

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

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

The description states a specific action on a specific resource: declaring that a cluster serves a DNS zone via an organisation credential, so Ingress hosts in that zone are published. It is clearly distinct from remove_cluster_custom_dns_zone and list_cluster_custom_dns_zones, though it doesn't name those siblings explicitly.

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 supplies real preconditions (requires credentials.write; the Cloudflare credential must be an organisation credential connected via `ankra org cloudflare connect`) and a clear exclusion (refused for a zone the cluster's generated zone already covers). It stops short of naming the alternative tool an agent should use for the covered-zone case.

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

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

Annotations already declare non-read-only, non-idempotent, non-destructive, and the description adds real behavioral context beyond them: the registry is indexed after the call and charts become usable for stack design. However, it says nothing about authentication needs for private/OCI registries, duplicate-name behavior, or how long indexing takes — gaps that matter for a mutation tool.

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

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

Three sentences, each doing distinct work: purpose, post-call consequence, usage trigger. It is front-loaded with the action and free of filler, though the long inline example quote is slightly heavier than needed.

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 3-parameter mutation tool with no output schema and adequate annotations, the description covers what it does, why it matters, and when to invoke it. It could be more complete about credential requirements and indexing side effects, but nothing essential to calling it correctly is missing.

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

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

Schema coverage is 100%, so all three parameters (including the http/oci enum and default) are already documented in the schema. The description's URL example duplicates the schema's own example and adds no new semantics, so the baseline 3 is appropriate.

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

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

Specific verb+resource: 'Add a Helm chart registry to the organisation's catalog,' which is unambiguous and distinct from siblings like list_helm_registries or sync_helm_registry. It stops short of naming a sibling explicitly, but the 'isn't in the catalog yet' framing implicitly separates it from listing/lookup 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?

Gives an explicit when-to-use trigger ('when the user needs charts from a registry that isn't in the catalog yet') with a concrete example utterance. It does not state when not to use it (e.g., registry already present, or an OCI registry that needs credentials first), so it falls short of full alternative routing.

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 a non-readonly, non-idempotent, non-destructive mutation. The description adds genuinely useful context beyond that: provisioning happens asynchronously at the cloud provider and the cluster must be fully provisioned first.

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?

Four dense but well-ordered sentences that front-load the action, then prerequisites, then optional blocks. No filler, though the count/autoscaling restatement slightly overlaps the schema.

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

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

Given 9 parameters with nested objects and no output schema, the description covers the critical gaps: prerequisites, where the size comes from, and that node provisioning is asynchronous. It could mention how to check pool status afterward, but the essentials are present.

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 every parameter is already documented in the schema, including count defaulting to 1 and the autoscaling constraints. The description largely restates those defaults, adding little new syntax or format detail.

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

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

States a specific verb+resource (add a node pool to a managed Kubernetes cluster) and enumerates the supported providers, which lets an agent distinguish it from sibling mutations like update_managed_node_pool or add_node_group.

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 the required inputs, where the size slug comes from (list_managed_k8s_options with the cluster target), and the precondition that the cluster must have finished provisioning. It stops short of naming when to prefer add_node_group or update_managed_node_pool instead.

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 cover safety profile (readOnly=false, idempotent=false, destructive=false), and the description adds a non-obvious behavioral constraint: real Secret values are rejected and every data/stringData value must be ANKRA_SECRET_PARAMETER. That's exactly the kind of context annotations can't convey. It stops short of describing the return or whether this mutates the draft in place.

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 tight sentences with zero waste; the core action is front-loaded and the Secret constraint that would otherwise cause a failed call is stated immediately after.

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 4-param mutation tool with no output schema, the description covers the essential action and the key failure mode (Secret rejection). Missing only draft lifecycle context (does this persist, can it be removed via remove_manifest_from_stack_profile_draft).

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 all four parameters are already documented in the schema. The description reinforces manifest content expectations but adds no syntax or format detail beyond the schema baseline.

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

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

Specific verb (Add) + resource (raw Kubernetes manifest) + target (stack profile builder draft), with concrete examples (Namespace, ConfigMap, Secret scaffold). Clearly distinguishes from siblings like apply_manifest, validate_cluster_manifest, and add_addon_to_stack_profile_draft.

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 Secret-handling rule implies when this tool is appropriate, but it never states when to use this versus alternatives such as apply_manifest or validate_cluster_manifest, nor any prerequisites like draft existence.

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

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

Goes well beyond the annotations, which only say it is a non-idempotent mutation: it discloses that workers provision in the background, that out-of-stock types are refused before the card is raised (implying a cost gate), that names must be unique and lowercase, that disk_tier/disk_gibibytes and user_data apply to replacements and scale-ups too, and that scale-to-zero is conditionally refused naming the instance type.

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

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

Front-loads the verb, resource, and target scope, followed by parameter behavior and constraints — no filler sentences. It is dense and long with heavy parenthetical nesting, but every clause carries information an agent needs.

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

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

For a 13-parameter mutation tool with nested objects and no output schema, the description covers provisioning behavior, provider-specific caveats, naming rules, and refusal conditions well. What is missing is any description of what the call returns (e.g. creation status/job handle) and explicit cost/approval flow.

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

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

Schema coverage is 100%, so the baseline is 3; the description still adds value by giving provider-specific instance_type examples ('cx23' on Hetzner, 'px-medium' on Proxmox VE, numeric service-plan id as a string on Morpheus) and reiterating the default count of 1. Most other parameter nuance is left to 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 a specific verb and resource ("Add a new worker node group") and scopes it to Ankra-provisioned self-managed clusters, naming the seven supported providers. An agent can immediately distinguish this from add_managed_node_pool or cluster-creation 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?

Gives clear preconditions (group name must not already exist, instance type must be in stock, works on running or stopped clusters) and routes to list_instance_types / list_proxmox_options / list_morpheus_options for picking a type. It never explicitly contrasts with add_managed_node_pool or states when to use update_node_group instead, so sibling-level exclusion is missing.

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?

With annotations (readOnlyHint=false, idempotentHint=false, destructiveHint=false), the safety profile is already covered, yet the description adds real value: it explains that existing stacks are loaded as drafts then updated and applied, and that a new target_stack name creates a single-addon stack. That dual execution path is genuinely useful behavioral context not present in 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 front-loaded sentences with no filler. The core purpose leads, and the behavioral clarification follows immediately; every clause earns its place.

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

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

For a non-idempotent mutation tool with no output schema, the description plus annotations and full schema coverage give the agent enough to invoke it correctly. It could be slightly stronger by noting the list_available_charts prerequisite and the post-apply result, but it is largely 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 coverage is 100%, so the schema already documents every parameter in detail. The description adds the existing-vs-new-name semantics for target_stack, but otherwise just restates required parameters and notably omits cluster_id (also required) and values_override. Baseline 3 is appropriate when the schema carries the detail.

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

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

States a specific verb ('Install'), resource ('addon from the org chart catalog'), and destination ('into a target stack'), which cleanly distinguishes it from draft-oriented siblings like add_addon_to_stack_profile_draft. The agent knows exactly what operation it performs without opening the schema.

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

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

The word 'known' implies the addon must already exist in the catalog, and the schema hints at verify-with-list_available_charts, but the description never names that prerequisite or any alternative path. It gives implied usage context but no explicit when-to-use or when-not-to-use guidance versus rollback_addon, sync_addon, or profile-draft 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 flag destructiveHint=true and idempotentHint=false, but the description goes well beyond them: it explains that the apply seals values into every deployment and rolls the workloads, that deleting the last key causes removal of the sealed Secret, and that a reconcile would otherwise reinstate deleted values. It also distinguishes a refusal from an error and notes that an empty catalogue is not a refusal.

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

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

Front-loaded with the core action, then the consequences of applying and not applying. It is information-dense but somewhat long, and the heavy use of all-caps emphasis (CLEARED, REMOVES, NOT) is a little noisy, though every sentence carries substance.

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

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

For a one-parameter, no-output-schema mutation tool with annotations covering the safety profile, the description supplies everything an agent needs: the effect on running workloads, the deletion behavior, and the refusal conditions. Success-response detail is not required since no output schema exists.

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

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

Schema coverage is 100% for the single application_id parameter, so the baseline is 3. The description adds meaningful semantics by stating 'Takes no values - the ones applied are the ones already stored', which clarifies that no secret payload is supplied here, giving a small lift above the schema baseline.

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

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

States a specific verb+resource: 'Seal an Application's stored environment secrets into every deployment of it and roll the workloads that read them.' It explicitly separates itself from the sibling 'set' operation by explaining that setting a value does not touch what is running until it is applied, so an agent can tell it apart from set_application_env_secret/delete_application_env_secret without opening a schema.

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

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

Gives explicit when-to-use (the step that makes a stored value reach a running Application), covers the inverse case (a CLEARED last key also applies, removing the sealed Secret), and enumerates the precise conditions under which it refuses (not deployed yet, tearing down, unsealable deployment, no Kubernetes Secret Ankra can derive). Nothing is left to inference.

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

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

Annotations only say destructive=true; the description goes much further by describing replace semantics, the untouched-stack guarantee, the fact that refusals write nothing, that refusals name the affected members, and the PVC-pruning second acknowledgement. This is precisely the context an agent needs to avoid a data-destroying call.

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

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

Front-loaded with the effect and free of filler, but it is one dense paragraph with long semicolon-chained clauses, especially the member-removal sentence, which is harder to parse than it needs to be. Content earns its place; structure could be split for scannability.

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

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

For a destructive mutation with no output schema and full annotation coverage, it covers preconditions, refusals, and confirmation flows thoroughly. The remaining gap is the outcome side: it does not say what a successful apply returns or whether it is synchronous, so an agent cannot predict the result shape.

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 already 100%, so baseline is 3, but the description adds real decision logic: prune means 'the manifest is the complete current definition' while confirmed_member_removals is the targeted alternative sent only after a refusal, and allow_repoint_destroying_data is framed as the second-level ack. It does not add format detail for manifest_yaml_base64, but the schema covers that.

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

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

States a specific verb and resource ('Apply an ImportCluster YAML declaratively') and immediately enumerates the concrete effects: cluster created if absent, named stacks created or replaced, unnamed stacks untouched. It also differentiates itself from siblings by citing create_stack / update_stack for single-stack work.

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

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

Explicitly says to read state with export_cluster_iac first, validate with validate_cluster_manifest, and use create_stack / update_stack when touching one stack at a time. It also gives the exact condition selecting prune vs confirmed_member_removals and the two acknowledgements needed for a GitOps repoint.

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=false, but the description adds a non-obvious guardrail the annotations cannot express: ArgoCD-managed resources are rejected by default. It doesn't disclose apply semantics (create vs. server-side apply/patch), so it stops short of 5.

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

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

Three sentences, zero filler, and the core action is front-loaded before the routing and safety caveats. Every sentence carries distinct information.

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

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

For a destructive write tool with no output schema, the description covers purpose, scope, routing and the key safety gate; what's left out is the return/outcome shape and whether a rejected call surfaces an error or a pending confirmation. Minor gap for an otherwise complete definition.

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

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

Schema description coverage is 100%, so all five parameters (including allow_bypass and its warning) are already documented in the schema. The description only restates the manifest type and the bypass condition, adding no syntax or format detail beyond it — 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?

States a specific verb and resource ('Apply a Kubernetes manifest (YAML) to create or update resources') and scopes it ('Supports any Kubernetes resource type'), which separates it from validate_cluster_manifest, apply_cluster_manifest, patch_resource and the draft tools without opening any schema.

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

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

Explicitly names the preferred path for stack-managed resources (add_manifest_to_draft + apply_stack_changes) and states the hard exclusion: direct apply against ArgoCD-managed resources is rejected unless allow_bypass=true. Both the alternative and the condition selecting it are given.

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

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

Goes well past the annotations by naming the two files written, explaining that nothing restarts because apt/needrestart only read them at next run (safe on production), disclaiming arbitrary command execution, capping a run at 100 nodes, visiting hosts one at a time, and defining report semantics (verified true only when apt-config shows the policy in force; unreachable/apt-less hosts report false with a reason). This is consistent with readOnlyHint=false and 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?

Information-dense and front-loaded with the purpose, but delivered as one long run-on paragraph with heavy nested parentheticals, mixing mechanism, prerequisites, reporting and exclusions. Almost every sentence earns its place, yet the lack of segmentation makes it harder to scan than it needs to be.

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 7-parameter, no-output-schema, SSH-driven mutation tool, the description covers everything needed: prerequisites (policy enabled), exclusions (imported/managed-K8s, Scaleway), target combinations, safety behaviour, and the shape and semantics of the returned per-host report. An agent could call this correctly without opening any other artifact.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema: node_id is preferred over node_name, all_nodes is capped at 100 per run, include_bastion can be combined with either a single node or all_nodes, and cluster_id/cluster_name are optional once a cluster is selected. It does not add format/syntax detail beyond that.

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

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

States a specific verb pair (write/remove) and specific resource (Ankra's node OS update policy, naming both files) on a specific target scope (existing nodes and bastion of an Ankra-provisioned cluster, over SSH via the bastion). It explicitly distinguishes itself from neighbours like set_os_patch_policy and run_os_patches, and rules out imported/managed-Kubernetes and Scaleway clusters.

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

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

Gives explicit applicability and refusal conditions: apply is refused unless the cluster's OS patch policy is enabled via set_os_patch_policy, while revert is always allowed. It also explains the concrete failure mode avoided (Ubuntu's daily unattended upgrade restarting systemd-networkd on all nodes) and the target-selection matrix (include_bastion, node_id/node_name, all_nodes).

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=false, but the description goes beyond them by explaining the actual destructive semantics: the default is non-destructive preservation, deletion of absent items happens only under an explicit opt-in, and removal tracking is done via draft removal tools. That is exactly the operational context an agent needs before firing a destructive ship action.

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?

Four sentences, front-loaded with the core action before the conditional semantics. Each sentence carries informational weight, though the middle two restate the preservation/removal rule from slightly different angles and could be tightened.

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

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

For a destructive mutation with no output schema, the description covers the critical gaps: default behavior, the destructive escape hatch and its guardrail, and how the target draft is resolved. Return format is not required since no output schema exists, and annotations carry the safety profile.

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, and the description adds real value on top by framing replace_missing as a destructive mode with a user-confirmation precondition and explaining why draft resolution matters. It does not add meaning for members, draft_id, cluster_id, or expected_digest beyond what the schema already says.

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

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

States a specific verb and resource: 'Apply the current stack draft to the cluster', then adds scope ('handles both brand-new database drafts and already-deployed stacks by computing the lifecycle and bill of materials internally'). This separates it from plain manifest/applies in spirit, but no sibling tool (e.g. redeploy_stack, apply_manifest, resolve_gitops_conflict) is named, so the distinction is inferred rather than explicit.

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

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

Gives clear operating conditions: absent items are preserved by default, and replace_missing=true is reserved for a full replacement 'only after confirming the exact deletions with the user'. The destructive opt-in condition is spelled out, though no alternative tools are named for the non-draft path and no prerequisites (permissions, cluster lock) are mentioned.

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 establish readOnlyHint=true, and the description adds real protocol beyond that: a hard cap of 2 calls per turn and the requirement to end the turn and wait for the user's next message. Those two facts materially change how an agent must sequence its calls and are not derivable from the schema or annotations.

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

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

Front-loaded with purpose, then usage conditions, then the negative case, then operational constraints. Every sentence changes agent behavior; there is no filler or repetition.

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

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

Single-parameter tool with no output schema, and the description covers the one thing that would otherwise be ambiguous: that the answer arrives as a user reply in the next message rather than as a tool result. Nothing needed to invoke it correctly is missing.

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

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

Top-level schema description coverage is 0% and the 'questions' array itself carries no description, though nested fields (id, prompt, options, label) do and the schema enforces minItems/maxItems/defaults. The description conveys only the 'multiple-choice' shape implicitly and says nothing about the batch limit of 3 questions, 12 options, or the 480-char prompt cap, so it neither compensates nor is required to.

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

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

States a specific verb and resource ('Ask the user a structured multiple-choice question') plus the goal ('resolve a genuine ambiguity'). Nothing in the large sibling set does the same thing, and the wording makes that distinction immediately obvious.

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

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

Gives explicit when-to-use criteria ('missing information you cannot infer... would save more than two tool calls of guessing'), examples (clusters, namespaces, charts), and explicit when-NOT-to-use guidance naming alternatives ('Do NOT use for questions you can answer from cluster_query, the page context, or a single sensible default'). This is a complete routing rule.

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

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

Annotations only declare the safety profile (readOnly=false, idempotent=false, destructive=false). The description goes well beyond by stating the effect on consumers ('the service's connection details are delivered for them'), the deployment prerequisite, the create-vs-update semantics, and the required permission scopes ('applications.deploy and clusters.operate'), which the agent cannot get from structured fields.

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

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

Four sentences, front-loaded with the core action, each carrying distinct information (purpose, setup semantics, prerequisite, revision behavior, permissions). The CLI-twin parenthetical is the only element that does little work for an MCP agent.

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

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

For a 6-parameter mutation with no output schema, the description covers prerequisites, side effects, create-vs-update behavior, and auth requirements. Remaining gaps are minor: no return-value guidance and no statement about what happens to an existing binding when expected_revision conflicts.

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

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

Schema coverage is 100%, so the baseline is 3. The description still adds workflow-level meaning to two parameters – allow_planned relaxes the deployment prerequisite, and expected_revision selects update-over-create – rather than just restating the schema's field descriptions.

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

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

States a specific verb and resource with scope: 'Bind an application namespace on a cluster as a consumer of managed services.' An agent can distinguish it from list_service_consumers or unbind_service_consumer by the verb alone, though the description differentiates itself via a CLI twin ('ankra services consumers bind') rather than by naming the relevant sibling 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?

Gives clear preconditions ('The application must be deployed to that namespace unless allow_planned is true') and create-vs-update routing ('Pass expected_revision to change an existing binding; omit it to create one'). It does not explicitly point to unbind_service_consumer as the way to remove a binding, so the alternatives story is incomplete.

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

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

Adds rich context beyond the destructiveHint=true annotation: the run and session flip to 'cancelled', the runner interrupts the in-flight turn within seconds, the agent itself is not paused, and already-finished runs respond with their final status rather than erroring. This discloses effect, timing, and edge behavior that the annotations alone do not.

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

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

Front-loaded with the verb and resource, then effects, then constraints, then usage. Every sentence carries information, though the description is on the denser side; no filler.

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

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

For a single-parameter mutation tool with no output schema, the description covers effect, timing, auth requirement, parameter provenance, and finished-run behavior, leaving no material gap for correct invocation.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds provenance by telling the agent to source run_id from list_agent_runs. It adds useful meaning without detailing format (the schema already states UUID).

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

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

States a specific verb+resource (cancel one live AI agent run) with clear scope, and the phrase 'AI agent run' distinguishes it from sibling cancellers like cancel_execution, cancel_data_run, and cancel_execution_step. An agent can identify the target without opening the schema.

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

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

Gives explicit when-to-use triggers ('an agent run is working on something it should not') and routes the agent to list_agent_runs to obtain run_id, plus notes admin-only restriction and the already-finished-run behavior. It stops short of naming sibling cancellation tools as explicit alternatives, so a 4 rather than 5.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, but the description adds real context beyond them: the terminal-state rule ('work already finished stays finished'), the concrete consequence ('no complete restore point'), and required scopes (runs.operate, backups.operate). It doesn't address retry/idempotency behaviour on repeated calls, which the non-idempotent annotation leaves open.

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

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

Three short sentences, zero filler, with the purpose stated first and the operational caveats following. Every sentence carries distinct information.

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

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

For a single-parameter destructive mutation, the agent gets the verb, the affected resources, the terminal-state semantics, the downstream effect on restore points, and the required permissions — with no output schema needed to explain returns.

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 with 100% schema description coverage, and the schema already points to list_data_runs as the source of the UUID. The description adds no format or constraint detail beyond that, 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?

Specific verb (cancel) plus the exact resource set it acts on (running backup, restore or clone), which cleanly separates it from retry_data_run, get_data_run and list_data_runs. The parenthetical mapping to `ankra runs cancel` adds an unambiguous anchor.

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?

Restricts scope to a *running* run and clarifies that finished work cannot be un-finished, which tells an agent when this is and isn't applicable. It never names the sibling alternatives (retry_data_run for re-running, list_data_runs for discovery) explicitly, so routing is implied rather than spelled out.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false. The description adds critical context beyond that: the terminal consequence 'a mid-flight cancellation can leave the affected resource between versions until the next reconcile' is a genuinely useful behavioral disclosure not captured by annotations. It also clarifies idempotency-adjacent behavior: 'Not running executions answer their settled state unchanged.'

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 tightly-packed sentences: purpose with resource definition, usage caution with rationale, and non-running behavior. No filler; the caution is front-loaded appropriately for a destructive tool.

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

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

For a destructive single-parameter tool with annotations covering safety flags, the description supplies the missing pieces: consequence of mid-flight cancellation, preference ordering vs alternative, and no-op behavior. Nothing an agent needs to decide to call this is absent.

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

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

Schema coverage is 100%, so the single parameter is fully documented. The description adds value by referencing list_recent_executions as the source for execution_id, reinforcing correct lookup flow beyond the schema's own description of the field.

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

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

States a specific verb+resource ('Cancel a running platform execution') and defines the resource by enumerating what an execution is ('a deploy, sync, or other operation from list_recent_executions'). This distinguishes it from siblings like cancel_agent_run, cancel_data_run, and cancel_execution_step which cancel different resources.

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 discourages use: 'prefer letting a deploy finish and rolling back unless it is actively harmful.' It names an alternative behavior (wait + rollback) and gives the condition under which cancellation is warranted, plus notes behavior for non-running executions.

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 flag destructiveHint=true and idempotentHint=false, but the description adds genuine behavioral context beyond them: the state eligibility gate and the half-applied consequence ('can leave its resource between versions until the next reconcile'). That consequence is not derivable from the schema or annotations and directly informs the cancel-vs-not decision.

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 tight sentences with the action, the constraint, and the alternative front-loaded in that order; no filler. The parenthetical CLI-twin reference is the one arguably optional fragment, keeping it below a 5.

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

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

For a two-parameter mutation with full schema coverage and no output schema, the description supplies everything an agent needs: eligibility rules, id source, alternative tool, and downstream risk. Nothing material is left to inference.

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 both UUID fields are already documented there, including that step_id comes from get_execution_details. The description's 'Get the step ids from get_execution_details' largely repeats the schema, so the baseline of 3 applies.

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

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

States a specific verb and resource with scope: 'Cancel one step of a running platform execution ... while the rest of the execution continues.' It is immediately distinguishable from the sibling cancel_execution by being step-scoped rather than operation-scoped.

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

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

Gives explicit eligibility ('only running, pending or blocked steps can be cancelled'), names the discovery tool (get_execution_details), and routes to the alternative ('prefer cancel_execution when the whole operation is wrong'). Both when-to-use and when-not are covered.

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

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

The annotations declare readOnlyHint=true, but the description describes an unambiguous mutation ('Edit an existing json canvas artifact', 'replaces an existing element', 'deletes an element', 're-parents an element') with server-side validation and refusals. This directly contradicts the read-only annotation and would mislead an agent about whether state is modified. Per the contradiction rule, this scores 1 despite the otherwise rich behavioral detail.

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

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

The purpose and the routing to canvas_present are front-loaded, and the sentence on operations is dense but information-bearing. The block is long and unstructured (one paragraph with embedded JSON), which slightly hurts scanability, but nearly every clause earns its place given the tool's 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?

With no output schema, the description covers return/refusal behavior thoroughly: the returned revision_id, refusals carrying 'the exact problems' with nothing changing, and the current_revision_id/content on a stale base_revision_id. Constraints (128 elements, 12 levels, ids start with a letter, no cycles) and the v1→v2 time migration are all present, so an agent has what it needs to call correctly.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds substantial meaning beyond the per-field text: it explains the semantics of each op (set replaces and keeps children when omitted, insert appends when index is omitted, remove prunes unused subtree, move re-parents), the id-stability rules, and that time/filters replace the dashboard control and force schema_version 2.

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

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

States a specific verb+resource+scope: 'Edit an existing json (JSON Render) canvas artifact element by element instead of resending the whole spec.' It explicitly distinguishes itself from the sibling canvas_present by contrast (patch operations vs. resending the whole spec). An agent can tell exactly what it does and how it differs from the alternative without opening the schema.

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

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

Gives explicit when-to-use ('Use it for every change to a json dashboard already on the canvas') and explicit when-not with the named alternative ('Only json artifacts can be patched: for html, svg or markdown send the complete content with canvas_present'). It also names prerequisites (artifact_id from canvas_present) and the base_revision_id condition for library-saved artifacts.

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 describes a state-mutating operation: it creates a new artifact, returns an assigned artifact_id, and updates artifacts in place with live refresh in an open canvas. The annotations declare readOnlyHint=true, which asserts the tool does not modify its environment. Despite an enormous amount of genuine behavioral disclosure (sandboxing, no external network, self-contained content, theme handling), the core read/write nature directly conflicts with the annotation.

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

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

It is front-loaded correctly (purpose, then when-to-use, then constraints, then spec), but it runs to several thousand words and embeds an entire component catalog, Grid layout rules, colour tokens and binding schema inline. Reference material of that volume belongs in docs; here it buries the operative instructions an agent needs at call time.

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 create/update tool with no output schema, the description still tells the agent that the tool result returns the assigned artifact_id, that the canvas refreshes live on update, and how content is validated per language. Nothing needed to invoke it correctly appears to be missing.

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

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

Schema coverage is already 100%, so the baseline is 3, but the description adds real semantics beyond the schema: omit artifact_id to create versus pass it to update in place, always send complete content rather than a diff, and content is described as a JSON-encoded string with a full JSON Render element grammar. Only title/language receive no added nuance 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 opening sentence gives a specific verb and resource ('Create or update an artifact on the chat canvas') and immediately defines what the canvas is, so an agent can distinguish it from canvas_patch and from chat-only replies. It goes further by enumerating the artifact classes it accepts, leaving no ambiguity about 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?

It states an explicit trigger ('whenever the user asks for a diagram, architecture map, flowchart...'), explicit exclusions ('do not return inline Mermaid/chart blocks, ASCII diagrams, source dumps, or file attachments'), and names the alternative tool for the update case ('to change a json dashboard already on the canvas use canvas_patch instead of resending it'). This is the strongest form of routing 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 declare destructive=true and non-idempotent, but the description adds the operational consequences the agent actually needs: growing happens live with no downtime, reducing is offline, instance_type rolls one controller at a time, and the single-controller resize takes the Kubernetes API down for 3-8 minutes and is refused without accept_api_downtime=true. This is exactly the context annotations cannot convey.

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

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

Front-loaded with the core action and the one-of constraint before the branching behavioral detail; the long Hetzner paragraph is dense but earns its place. Minor redundancy between the description and the fully documented schema keeps it from a 5.

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

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

For a destructive, mode-dependent mutation with no output schema, the description covers prerequisites (list_node_groups), both change paths, downtime risk and consent gating, and notes that the answer carries the follow-up operation. Nothing an agent needs to call it safely is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds real value beyond the schema: it explains why count must be 1/3/5 (etcd quorum needs an odd number), that the two aspects are mutually exclusive per call, and which mode each triggers, though it largely restates the accept_api_downtime gating already in 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 a specific verb and resource ('Change the control plane of an Ankra-provisioned self-managed cluster') and immediately enumerates the two mutually exclusive aspects (count, instance_type). This is clearly distinguished from scaling worker node groups or updating node groups in the sibling list.

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

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

Explicitly says to call list_node_groups first for current state and feasibility, gives the 'exactly ONE of' constraint, and names alternatives: grow to 3 controllers (no downtime) or apply offline on a stopped cluster. When-not conditions (running single-controller Hetzner) and the required explicit user acceptance are spelled out.

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

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

Annotations only declare readOnlyHint=true; the description goes well beyond that by defining the eligible/ready/ineligible semantics and explaining per-check remediability, including which cloud/distribution/CNI attributes cannot be changed on a running cluster. This is exactly the behavioral context an agent needs and cannot get from the annotation or schema.

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

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

Front-loaded with the purpose, then the eligible/ready distinction and remediation routing. Dense and largely waste-free, though the remediable/cloud/CNI clause is long enough to be slightly heavy for a single paragraph.

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?

There is no output schema, so the description must carry return-value meaning, and it does by defining eligible, ready, and remediable. Combined with the read-only annotation and the prerequisite relationship to create_cluster_mesh, an agent has everything needed to call it correctly.

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

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

Schema coverage is 100% and the single parameter is already documented as 'Cluster UUIDs to judge as one candidate mesh', so the baseline is limited upside. The description still adds value by clarifying 'Takes CLUSTER ids, not a mesh id', which prevents a plausible misuse.

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

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

States a specific verb+resource: judging whether given clusters could form one mesh, with failing checks reported per cluster. It explicitly distinguishes itself from create_cluster_mesh and make_cluster_mesh_ready, so an agent can route correctly without opening a schema.

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

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

Gives explicit when-to-use and alternatives: 'Always run this before create_cluster_mesh', and route to make_cluster_mesh_ready when a failing check is remediable. It also names the alternative outcome (rebuild for ineligible clusters), leaving nothing to inference.

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

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

Goes well beyond the readOnlyHint annotation: it declares the tool only PROPOSES text and writes nothing, describes the returned artifacts (pipeline_yaml, notes, validation verdict), warns that unmappable third-party steps become failing stages rather than being dropped, and states the 20-file/256KB bounds. Rich, decision-relevant behavioral detail.

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

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

Front-loads the core purpose and remains information-dense with little waste. It is a single long paragraph though, and the edge-case behavior could be more scannable, keeping it short of a 5.

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 conversion tool with no output schema, the description covers inputs, required prerequisites, return shape, failure modes, limits, and the follow-up step for landing the change. An agent has everything needed to call it correctly.

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

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

Schema description coverage is 100%, so the schema already documents format inference, application_id resolution, and workflow_files semantics. The description adds the procedural note to read files first and pass their contents, but does not exceed the schema's parameter documentation, so baseline 3 applies.

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

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

States a specific verb+resource (convert existing CI definitions into an Ankra pipeline) and enumerates the exact source formats it accepts. The scope is unmistakable and clearly distinguishable from the validate/propose siblings.

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

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

Gives strong operational context: read files first with github_read_file/workspace_read_file, pass contents here, then land the result via scm_create_pull_request or github_create_pull_request. It doesn't explicitly contrast with cicd_propose_application_pipeline or the cicd_validate_* siblings, so the exclusion boundary is left implicit.

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

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

Annotations declare readOnlyHint=true, which the description confirms ('Read-only - no commits happen here'), so there is no contradiction. It adds substantial behavioral context beyond annotations: server-side rendering, the returned violation list and severity, and the required retry behavior. It does not, however, describe pagination or limits, though those are largely irrelevant for a render operation.

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

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

The opening paragraph is well front-loaded (purpose, read-only nature, next-step loop) and the shape/target paragraphs are logically ordered. It is long and repeats some detail already carried in the schema descriptions, which keeps it just short of a 5.

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 having no output schema, the description fully explains what is returned (rendered files plus validator violations and a severity) and what to do with each severity outcome. For a complex two-shape, multi-file rendering tool, the agent has everything needed to call it correctly and act on the result.

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

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

Schema coverage is 100%, so the baseline is 3 and the schema already documents each field in depth. The description still adds cross-parameter meaning the individual field docs do not: that the apps array overrides the top-level app_name/tailoring/dockerfile, and how target interacts with shape (one grouped .ankra/pipeline.yaml vs one workflow per app).

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

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

States a specific verb (render) and a precisely enumerated resource (Kubernetes manifests + application descriptor + CI definition + optional Dockerfile) for a target repo. It clearly differentiates from the cicd_validate_* siblings by noting it does not write files itself and that output is rendered server-side from a fixed 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?

Gives explicit when-to-use rules for both shapes (single-app vs monorepo, including the repo signals like nx.json/turbo.json/multiple Dockerfiles that select the apps shape) and for the two target values. It also names the escalation path via github_create_pull_request and the revise-and-retry loop on warn/fatal severity.

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

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

Annotations only declare readOnlyHint=true; the description adds real substance beyond that by enumerating the specific security checks performed and stating the return shape (severity plus per-violation keys). It still omits anything about rule-set versioning, false positives, or how severity is assigned, so not a 5.

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

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

Two sentences, front-loaded with the exact validation scope and followed by the usage trigger and return shape. Every clause carries information; nothing is padded or repeated.

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

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

For a single-parameter, read-only validator with no output schema, the description supplies the missing return contract ('severity and per-violation keys') and the intended workflow position, which is everything an agent needs to call it correctly.

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

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

Schema coverage is 100% and the single parameter already documents 'Full values.yaml content (typically read via github_read_file).' The description only restates that the input is a values.yaml string, so it adds essentially nothing beyond the schema; baseline 3 applies.

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

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

Names a specific verb (validate) and resource (Helm chart values.yaml string) plus the exact rule set enforced (KSV-0014, readOnlyRootFilesystem, runAsNonRoot, capabilities.drop, healthCheck.path). This clearly separates it from sibling validators like cicd_validate_pipeline_yaml, cicd_validate_workflow_yaml, and deploy_inspect_chart_values, which do different things.

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 the intended moment of use: 'on a customer's pre-existing chart values before suggesting changes,' which gives the agent a clear trigger. It stops short of naming alternatives or when-not-to-use, so it is context-rich but not fully routing.

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

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

readOnlyHint=true already covers the safety profile, so the description earns credit for adding beyond it: it discloses the severity model, that a 'fatal' pipeline cannot be planned, and the notable error behavior that unreadable YAML returns a fatal violation rather than a tool error. No auth/rate-limit context, but a material failure-mode detail is provided.

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

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

Front-loads purpose, then return shape, then failure semantics, closing with a read-only note. Four short sentences with no filler, and each earns its place given there is no output schema to carry the return description.

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

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

With no output schema, the description takes on the return-value burden and does so fully (severity values, violations with classifier key and message, declared name, stages in order, trigger events) while also covering when to use and the fatal failure mode. Nothing needed to call it correctly is missing.

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

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

Schema coverage is 100% and the single parameter is fully documented as the full contents of the .ankra/pipeline.yaml document. The description adds no syntax or format detail beyond the schema, so the baseline of 3 applies.

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

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

States a specific verb (Validate) and resource (Ankra pipeline definition, .ankra/pipeline.yaml) and explicitly contrasts itself with the sibling cicd_validate_workflow_yaml ('the twin ... for the definition that replaces the GitHub Actions workflow'). An agent can tell the two apart without opening either schema.

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

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

Gives clear context ('before proposing or committing it') and names the alternative (cicd_validate_workflow_yaml) plus the condition that selects between them (pipeline.yaml vs GitHub Actions workflow). It does not enumerate when not to use it, but the sibling routing is explicit enough to guide selection.

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

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

readOnlyHint=true already tells the agent this is a safe non-mutating operation, so the bar is lower. The description still adds real context: the specific platform invariants enforced and the return shape (severity plus per-violation keys), which annotations cannot convey.

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

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

Two sentences, front-loaded with the validated invariants and followed by usage and return info. The parenthetical invariant list is long but each item earns its place by telling the agent what will be flagged.

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?

No output schema exists, yet the description discloses the return shape (severity, per-violation keys), and the read-only annotation covers the safety profile. For a single-parameter validation tool this is nearly complete, with only the exact violation vocabulary left unspecified.

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 single content parameter is already documented as the full workflow YAML. The description adds no syntax or format guidance beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb (Validate) and resource (a GitHub Actions workflow YAML string), then enumerates the exact invariants checked (single build-and-push job, step sequence, --password-stdin, lowercased GHCR owner, etc.). This clearly distinguishes it from siblings like cicd_validate_pipeline_yaml and validate_cluster_manifest, which target different artifacts.

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

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

"Use this to inspect a customer's pre-existing workflow before splicing security steps" gives a concrete usage context and implies the workflow stage it belongs to. It does not, however, explicitly name alternatives such as cicd_convert_workflow_to_pipeline or state when NOT to use it, so routing rests partly on inference.

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

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

Annotations only declare the safety profile (readOnly=false, idempotent=false, destructive=false). The description goes far beyond: draft-not-deployed default, encrypted values stripped with warnings, name conflicts auto-resolved with suffixes, config-only vs data semantics, and explicit refusal conditions. This is exactly the behavioral disclosure the annotations can't carry.

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

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

The purpose and default (draft) are front-loaded, then permissions, then data handling, then the follow-up apply step. Dense but warranted for a 10-parameter mutation; a few clauses could be tightened but nothing is wasted.

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

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

For a complex cross-cluster mutation with a nested object and no output schema, the description covers permissions, side effects, data modes, refusal conditions, and the required post-step ('review and apply the draft'). An agent has everything needed to invoke it correctly.

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

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

Schema description coverage is 100%, so the schema already documents all 10 parameters thoroughly; the description largely restates that content (include_data, deploy_after_clone, data_clone_mode). It adds integration context but little syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb+resource+scope: 'Clone a stack from the current cluster to another cluster in the organisation as a stack DRAFT.' This distinguishes it from siblings like create_stack, redeploy_stack and rename_stack without opening any schema.

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

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

Gives rich contextual conditions: clone yields a draft unless deploy_after_clone is set, include_data requires backups.operate and is refused on name conflict, and the user must hold ai.execute and stacks.write on the target. It doesn't explicitly name alternative sibling tools, but the when-to-use and when-refused conditions are 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 only mark this destructive/non-idempotent; the description goes further, disclosing the exact side effects (ticket marked closed plus a 'closed by the customer' thread note) and an operational limitation (the support team's own board is not moved). This is behavior an agent could not infer from the structured fields.

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

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

Front-loaded with purpose, then usage rules, then identification, then the caveat. Every sentence carries distinct information, though the final 'known gap' sentence is dense enough that it could be split for readability.

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 mutation tool with no output schema and no annotation detail, it covers side effects, authorization scope, and the limitation clearly. It does not say whether a close can be undone or what happens on a repeat call, which matters given idempotentHint=false.

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 both parameters are already documented, so the schema does the heavy lifting. The sentence 'Identify the ticket by ticket_number or ticket_id' adds only the either/or relationship, which the schema descriptions already imply. 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?

Specific verb+resource ('Close a support ticket from the customer's side') with the mechanical consequence stated (marked closed, note added) and an equivalent CLI reference. It is clearly separable from comment_support_ticket, the sibling it explicitly contrasts itself with.

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

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

Gives an explicit when ('only when the user says the matter is resolved or no longer needed'), an explicit when-not ('do not close on support's behalf'), and routes the alternative case to comment_support_ticket when support is still expected to act.

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

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

Adds substantial behavior beyond readOnlyHint=true: it is a Postgres read, never contacts the agent, never escalates on its own, and discloses staleness semantics including heartbeat refresh defaults and stale_fallback_required thresholds. These are important operational traits an agent could not infer from the annotation alone.

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

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

The description is front-loaded with the key cache-vs-live distinction and avoids repetition. It is dense rather than lean, especially the heartbeat/default-staleness parenthetical, but those details help interpret the returned staleness fields.

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

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

Because there is no output schema, the description usefully explains the payload fields last_seen_at, staleness_seconds, and stale_fallback_required. The main remaining gap is that required and optional parameters are not explained beyond the partial schema coverage.

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 only 40%, and the description does not explain the semantics of kind, name, namespace, or how they select the named resource. The low schema coverage requires the description to compensate, but it provides no parameter-specific guidance.

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

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

States a specific verb and resource: returns one named resource from the synced k8s_resources cache, explicitly shaped like describe_resource. It clearly distinguishes itself from describe_resource by describing itself as a Postgres cache read rather than a live cluster read.

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 defines when to use this tool: the fresh-cache case that avoids a describe_resource agent round-trip. It also names when not to use it and the alternative: when verifying a recent change or confirming state a write depends on, escalate to describe_resource.

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?

With readOnlyHint already covering safety, the description still adds substantial behavioural context: it never contacts the agent, is sub-50ms, reads a single cluster and refuses to span the organisation, and it defines the staleness model (last_seen_at, staleness_seconds, heartbeat refresh default 480, stale_fallback_required at 300s) so the agent can interpret results correctly. This is far beyond what the annotation conveys.

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

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

Front-loaded with the crucial cache-vs-live distinction, but delivered as one dense run-on block that interleaves usage guidance, parameter semantics and return shape. It also repeats the schema's own namespace/all_namespaces explanation ('a list that names no namespace reads every namespace ... and says so in a note'), which costs space without adding 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?

There is no output schema, yet the description still covers the return contract in detail: one summary row per match with kind-specific status fields (phase/ready/restarts/node/reason for Pods, ready/desired plus first unmet condition for workloads, type/reason/object/message for Events), failed-first ordering, the total/returned/truncated envelope, and where to go for full detail. Nothing needed to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds usable meaning on top: it explains that omitting namespace reads every namespace and flags it in a note, how to narrow scope, and what the payload carries (total, returned, truncated, scope, citation marker). It does not add much for field_selector beyond the already detailed schema text, so it stays just above baseline.

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

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

States a precise verb+resource+mechanism: a 'Structured SQL-backed lookup against the agent's synced resource index (the k8s_resources cache)'. It immediately differentiates itself from the get_pods/get_deployments/get_services/get_configmaps wrappers and from describe_resource, so an agent can route correctly without opening any schema.

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

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

Gives explicit when-to-use ('exact lookups, label selectors, and JSONB-path filters', inventory and filtering questions) and when-not ('when you need the live object - verifying a change you just made, or confirming state a write depends on'), naming the alternative tools for each case. Nothing is left to inference.

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

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

With readOnlyHint already covering the safety profile, the description still adds substantial context beyond annotations: it never contacts the agent, never escalates, runs entirely in Postgres with no external API, and reads exactly one cluster. It also discloses staleness semantics (last_seen_at/staleness_seconds, heartbeat refresh at K8S_LAST_SEEN_REFRESH_SECONDS default 480) and the advisory stale_fallback_required flag tied to K8S_CACHE_MAX_STALENESS_SECONDS.

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

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

Front-loaded with the core purpose and the crucial live-vs-cache distinction before the operational details. It is dense and long, with the staleness constants packed into the middle, but nearly every sentence carries decision-relevant information rather than filler.

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

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

Although there is no output schema, the description explains the return shape (top-K ranked hits with citations), the per-hit staleness fields, and the advisory stale_fallback_required. Combined with the single-cluster scoping rule and live-read alternatives, an agent has everything needed to call and interpret it correctly.

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

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

Schema coverage is 100%, so the baseline is 3 and the schema already documents query syntax, limit, and filters. The description nonetheless adds meaning to cluster_id/cluster_name by explaining the single-cluster targeting rule and the multi-cluster refusal behavior, and clarifies that hits are pointers to be resolved via cluster_describe/describe_resource.

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

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

States a specific verb and resource: Postgres full-text search over the synced resource index (the k8s_resources cache). It immediately distinguishes itself from live-read siblings by asserting it is 'a Postgres read, NOT a live cluster read'. An agent can tell it apart from cluster_describe/cluster_query without opening either schema.

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

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

Gives explicit when-to-use guidance with concrete examples ('find anything mentioning prometheus', 'workloads using the nginx image', 'recent warning events about scheduling'), which are fuzzy keyword lookups. It names the alternatives for live reads (cluster_describe, describe_resource) and states the single-cluster scope rule plus the refusal behavior with multiple readable clusters.

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

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

Beyond the readOnlyHint annotation, it discloses that it is read-only, that secrets in log lines are redacted, that results stay under 8 KB, and that unresolved parts mean a read did not happen rather than a finding. It also explains fallback resolution across Ankra Pipelines, the Ankra application, and OCI revision labels, which is rich behavioral context an agent needs.

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

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

The description is long but front-loads its purpose in the first sentence and structures the five returned components as a numbered list, so it remains navigable. It is dense and could be trimmed if an output schema existed, but for a tool with no output schema the detail is largely earning 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?

With no output schema, the description carries the full burden of explaining return values and does so thoroughly: it enumerates the five result components, the resolution fallback chain, the grouping behavior, and the size and redaction constraints. An agent has enough information to call it correctly and interpret the result.

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 six parameters including their defaults and enum. The description does not add per-parameter meaning beyond what the schema provides, so the baseline of 3 is appropriate for a tool whose parameter semantics are fully carried by the schema.

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

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

The description states a specific verb and resource — a single compact read that returns runtime context (image-to-commit mapping, revision timing, error log lines, stack frames, restart details) for a Kubernetes workload. It is unmistakably distinct from siblings like get_pod_logs or get_deployments because it aggregates commit provenance, logs, and stack frames together, and it frames itself as the first call for debugging code.

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

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

It gives explicit when-to-use guidance: call it FIRST when fixing, debugging, or explaining a crashing service, when asked which commit a workload runs, or before handing a production error to a coding agent. It does not name alternative tools or state when not to use it, so it falls short of the top score, but the triggering conditions are clear 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?

Annotations already declare readOnlyHint=false and destructiveHint=true, so the safety profile is covered. The description adds real behavioral context beyond that: the reply reaches the support team, and a ticket waiting on the customer moves back to 'in progress' — a concrete state side effect not derivable from the annotations. It stops short of stating irreversibility or any auth/permission requirements.

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

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

Front-loads the verb and resource, then the concrete use cases, then the identifier hint, then the sibling routing. Four sentences each carrying distinct information, with no filler, though it is slightly longer than strictly necessary for the primary purpose statement.

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?

No output schema exists, so the description carries some return-behavior burden; it partly covers this by describing the resulting ticket status transition. Combined with annotation coverage of the safety profile and full schema coverage of parameters, the definition is largely complete, missing only auth/permission prerequisites and irreversibility disclosure.

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 body, ticket_id, and ticket_number. The description reinforces the ticket-identifier choice ('Identify the ticket by ticket_number or ticket_id'), which slightly clarifies the either/or relationship implied by the schema, but adds no format or constraint detail beyond it. Baseline 3 applies.

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

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

States a specific verb ('reply on') and resource ('existing support ticket') and enumerates concrete sub-purposes: answer a question, add evidence, or report a changed problem. It also explicitly distinguishes itself from the close_support_ticket sibling, so an agent can tell it apart from related tools without reading a schema.

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

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

Gives clear when-to-use conditions and names a specific alternative ('To close a ticket the user considers resolved, use close_support_ticket instead'), which is exactly the routing guidance an agent needs. It does not, however, address the potentially overlapping sibling ticket_comment, leaving some ambiguity about which commenting tool to pick.

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 flag destructiveHint=true and non-idempotent, so the bar is the added context — and the description delivers it: irreversibility ('This cannot be undone'), the digest staleness/expiry refusal rule, the required permissions (applications.deploy and stacks.delete), and the follow-up polling pattern. This is well beyond the safety 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?

Front-loaded with the destructive action and scope, then prerequisites, irreversibility, follow-up, and permissions — every sentence earns its place. Slightly dense with parenthetical asides, but nothing is redundant.

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

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

For an irreversible mutation with no output schema, the description covers the prerequisite tool, the follow-up verification tool, the failure modes (changed/expired digest), irreversibility, and required permissions. Nothing an agent needs to invoke it safely is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real semantic value for `digest`: it must be the exact value returned by prepare_service_retirement and is invalidated if the plan changed or expired. It is less specific about retirement_id/instance_id beyond naming their source, so it lands just above baseline.

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

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

States specific verbs and resource: 'Confirm a prepared retirement and DELETE the managed service and its data'. Explicitly positions itself as step two of `ankra services delete` and names the sibling tools prepare_service_retirement and get_service_retirement, so an agent can distinguish it from them without opening schemas.

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

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

Gives explicit sequencing: it must follow prepare_service_retirement (whose digest it consumes) and be followed by get_service_retirement until it settles. It also states the precondition that the digest must be unchanged and unexpired, which is exactly the when-to-use condition an agent needs.

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 cover the safety profile (not read-only, not idempotent, not destructive). The description adds substantial context beyond that: the auth requirement (applications.deploy), the digest-matching precondition, the refusal behavior for changed/expired plans, and the caveat that starting deployment is not proof of readiness. Rich behavioral disclosure.

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

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

Front-loaded with the core action and workflow position, then layers preconditions and follow-up. Every clause earns its place; 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?

No output schema exists, but the description tells the agent what to do next (follow with get_service_instance) and covers permissions, preconditions, and failure modes. Nothing needed to call it correctly is missing.

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

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

Schema documents both parameters at 100% coverage (baseline would be 3), but the description adds real meaning: the digest must be exactly the one returned by prepare_service_setup, and a changed/expired plan is refused. That clarifies the value constraints and provenance beyond the schema's terse 'from prepare_service_setup'.

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

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

States a specific verb+resource: 'Confirm a prepared managed-service review and start its deployment.' It also positions the tool within the workflow ('step two of `ankra services setup`'), distinguishing it from prepare_service_setup and the get_service_instance sibling.

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

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

Explicit context and sequencing: use it after prepare_service_setup, and follow it with get_service_instance. It also names the failure condition (a changed or expired plan is refused). An agent knows exactly when to invoke this vs. its 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 only say destructive=true and idempotent=false; the description goes well beyond them by enumerating the side effects on confirm (resource-graph write, best-effort webhook provisioning, initial commit of cluster state, sync nudge) and the refusal/prune behavior on repointing. It even clarifies the safe re-connect case, which is exactly the nuance an agent needs given the destructive hint.

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?

Long but dense: purpose, input sourcing, side effects, and refusal behavior are front-loaded and each sentence adds distinct operational information. Slightly heavier than necessary, but nothing is padding.

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 no output schema, the description carries the return/effect burden and does so: it describes what is written, what is provisioned, what is pushed, and when the call is refused. An agent has everything needed to call it correctly and predict the outcome.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantics: credential_id is preferred over credential_name, credential_name is refused when ambiguous, and repository must appear in the credential's synced repository list. This is meaningfully more than the schema fields carry.

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

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

Opens with a specific verb+resource+scope: 'Connect a GitOps repository to a cluster that has none', and pins the scope further with 'bind an existing GitHub credential plus a repository and branch'. It also names the related lookup siblings (list_gitops_credentials, list_gitops_repositories), so an agent can place it precisely in the GitOps flow.

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 where inputs come from ('Pick the credential from list_gitops_credentials ... and the repository from list_gitops_repositories'), the precondition that the repo must be in the credential's synced list, and a clear when-not: refused when the cluster is already connected to a different GitOps source, which must go through the cluster settings flow instead.

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

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

Annotations only declare write/non-idempotent/non-destructive; the description goes far beyond, disclosing that server-side re-derivation refuses on any mismatch, that an organisation admin must confirm, that a read-only probe runs first and writes nothing on failure, that the source is then registered in the resource graph with GitOps/audit/drift/IaC inheritance, and that no secret material may transit the tool.

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

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

The purpose and the exact-copy requirement are front-loaded, and nearly every sentence carries a distinct constraint (mismatch refusal, probe, credential path, secret handling). It is nonetheless a dense, uninterrupted block that could be structured into clearer segments; length is justified by the operational complexity but the density is high.

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?

No output schema exists, and the description compensates fully: it covers precondition (a prior refusal), confirmation flow, probe behavior, credential sourcing including the 401/403 case, failure modes, and the off-cluster/derived-mismatch path. Nothing material for correct invocation appears missing.

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

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

Schema coverage is 100%, so the baseline is 3, and the schema descriptions already document most param constraints. The description still adds workflow meaning beyond the schema: how provider/endpoint must be sourced (verbatim from the refusal, re-derived server-side), and the conditional linkage between endpoint_is_operator_supplied and credential_from_cluster_id.

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

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

The description states a specific verb and resource ('Propose connecting the log source Ankra derived from this cluster's installed addons'), and it is readily distinguishable from siblings like query_logs, connect_metrics_source, and set_cluster_hosted_log_shipping. It also names the originating trigger (a query_logs refusal), anchoring the action to a concrete workflow.

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

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

Explicit when-to-use (a query_logs refusal named a derived candidate), explicit when-not-to-use ('Do not use this to repair a misconfigured existing source'), and named alternatives for the external-store and mismatch cases via endpoint_is_operator_supplied=true. It also routes the credential path to credential_from_cluster_id rather than user input.

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

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

Annotations only convey the mutate/non-idempotent/non-destructive profile; the description adds substantial context: org-admin confirmation is required, a read-only probe runs first and writes nothing on failure, and the registration produces a prometheus_metrics source inheriting GitOps, audit, drift detection and IaC export. It also states no credential is needed for an in-cluster endpoint. Strong behavioral disclosure, though it could clarify reversibility of the registration itself.

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

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

Dense but front-loaded: the core action and the verbatim-copy constraint come first, then behavior, then the exception case. Every sentence carries operational information, though the length is at the upper bound and could be tightened.

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 mutation tool with no output schema and a multi-step flow, the description covers the confirmation gate, probe, side effects, credential guidance and edge cases (external store, render mismatch). Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: provider and endpoint must be copied verbatim from the refusal, are re-derived server-side, and any mismatch causes refusal. It also frames when endpoint_is_operator_supplied should be true. This is meaningful beyond what the schema alone states.

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

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

States a specific verb (propose connecting) and resource (Prometheus-compatible metrics source) and grounds it in an exact trigger ('the one a query_prometheus refusal named'). An agent can immediately distinguish this from connect_log_source or query_prometheus without opening the schema.

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

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

Explicitly names the triggering condition (a query_prometheus refusal naming a derived candidate), an explicit exclusion ('Do not use this to repair a misconfigured existing source'), and the alternative path (re-propose with endpoint_is_operator_supplied=true for external stores or render mismatches). Covers when, when-not, 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 only give the safety triad (readOnly=false, idempotent=false, destructive=false); the description carries the real behavioral burden. It discloses that running pods are NOT evicted, that PodDisruptionBudgets are NOT consulted by delete_pod, that unknown nodes are refused with no side effects, and that the operation is fully reversible via uncordon_node.

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 action and its effect are front-loaded in the first sentence, and the operational guidance is logically ordered (effect, reversibility, workflow context, caveats, error behavior). It is on the long side and a sentence or two of the consolidation narrative could be trimmed without losing correctness.

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 mutating tool with no annotations backing and no output schema, the description covers everything an agent needs: effect, non-eviction of pods, reversibility, prerequisite lookup via get_nodes, error handling for unknown nodes, and the PDB caveat for the follow-on delete_pod step.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond it: node_name must match the Kubernetes node name exactly, get_nodes should be called to list them, and unknown nodes are refused without changes. It adds nothing extra for cluster_id or dry_run, which the schema already documents.

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

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

States the exact verb and resource ('Cordon one Kubernetes node') and immediately defines the mechanism ('set spec.unschedulable=true so no new pods schedule onto it'), which is specific enough to distinguish it from sibling mutations.

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 frames the tool as 'the standard first step of node consolidation' and names the surrounding workflow (remove pods, let autoscaler reap the node). It also routes the agent to alternatives and exclusions: uncordon_node for reversal, delete_pod for pod removal, and it notes patch_resource refuses the Node kind.

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

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

Annotations only establish that this is a non-read-only, non-destructive, non-idempotent write. The description adds substantial behavioral context beyond that: minute-level evaluation, unique names per organisation, refusal of invalid condition types/values/operators and unknown integration names, default enabled state, notification routing, and reversibility.

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?

It is front-loaded with purpose, usage guidance and prerequisites before the detailed condition catalog, and most sentences carry useful operational detail. However, it is a single very dense paragraph with an unusually long condition vocabulary, which makes it less scannable than ideal.

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 nested create tool with no output schema, the description supplies prerequisites, validation behavior, defaults, scoping rules, lifecycle alternatives and notification semantics. It is complete enough for an agent to construct a correct call without additional discovery.

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 already 100%, but the description adds cross-parameter semantics that the schema does not fully capture: condition vocabulary by resource_type, metric keys and their meanings, allowed operators, logical combination, scoping interactions between cluster_ids/environments/all_clusters, and special defaults such as min_failure_duration_minutes.

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

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

States a specific verb and resource: 'Create an alert definition', then defines it as a named alert with rules the platform evaluates every minute. It explicitly distinguishes this from create_alertmanager_silence, so an agent can route between the two without opening either schema.

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

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

Gives explicit when-to-use guidance, prerequisite calls, and alternatives: use when asked to create/add/set up an alert, use create_alertmanager_silence instead for a silence, and call list_alerts, list_clusters and list_alert_destinations beforehand where relevant. It also names delete_alert and set_alert_enabled for follow-up management.

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 non-read-only, non-idempotent, non-destructive, so the safety profile is covered. The description adds meaningful behavioral context beyond that: a new destination silently receives nothing until a notification route points at it, and webhook destinations carry credentials that this tool deliberately cannot handle. It does not cover error/duplicate-name behavior, but the added context is substantial.

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?

Four sentences, zero filler: scope, channel provenance, excluded webhook case, and downstream routing dependency, in that order. The most decision-relevant constraint (which destinations belong here) is front-loaded.

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

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

For a mutation tool with no output schema, the description supplies everything an agent needs to call it correctly: required channel provenance, excluded use cases, and the follow-up route requirement. Annotations plus schema cover the remaining structural details.

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

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

Schema description coverage is 100%, so name, enabled, template, channel_id, description and the integration_type enum are already documented. The description's note that channel_id must originate from list_alert_destination_channels duplicates the schema's own wording rather than adding new semantics, so the baseline 3 applies.

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

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

States a specific verb (Create) and a precisely scoped resource (channel-based alert destination), and immediately narrows it to Slack channels the Ankra app posts to or Teams channels the Ankra bot is installed in. It also distinguishes itself from the webhook-destination variant, so an agent can tell it apart from siblings like create_notification_route without opening a schema.

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

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

Explicitly routes the agent: channels must come from list_alert_destination_channels, webhook destinations (Discord, PagerDuty, custom, Slack incoming webhooks) must be created in the portal or CLI and 'never here', and a route is required via create_notification_route before delivery. Both when-to-use and when-not-to-use are covered with named 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 only declare it is a non-read-only, non-idempotent, non-destructive operation; the description adds substantial context beyond that: the silence starts immediately and is backdated one minute so it never sits pending, the duration ceiling is 30d, and the response carries the silence id that must be relayed. It also explains Alertmanager auto-discovery and when to override with namespace/service/port.

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 but front-loaded: purpose first, then matcher rules, duration bounds, comment requirement, timing behavior, and service discovery. Every sentence carries operational information, though the paragraph is long and could be broken up for faster scanning.

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?

There is no output schema, so the description carries the return-value burden and does so by noting the response contains the silence id. Combined with matcher constraints, duration limits, and auto-discovery behavior, an agent has everything needed to invoke this 7-parameter mutation correctly.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds matcher strategy (anchor on exact alertname, add cluster/namespace) and clarifies the comment is the operator-visible reason, giving the agent decision guidance beyond the field docs. It does not add syntax detail for duration beyond what the schema already lists.

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

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

States a specific verb and resource (create a silence in the cluster's Prometheus Alertmanager) plus the observable effect (matching alerts stop notifying via Slack/email until the silence ends). It also names the sibling used for the inverse operation (expire_alertmanager_silence), so an agent can separate it from list_alertmanager_silences and expire_alertmanager_silence without opening a schema.

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

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

Gives explicit selection rules (anchor on an exact alertname matcher, add narrowing labels like cluster/namespace, at least one exact non-regex matcher required) and a clear when-not boundary ('longer suppressions need a human in Alertmanager/Grafana'). It also routes follow-up work to expire_alertmanager_silence, leaving little to inference.

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

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

Annotations only say it is a non-idempotent, destructive write. The description adds what is actually built (private network or adopted one, NAT router, firewall admitting only the private network, bastion holding the one public IPv4, CCM always installed) and a full preflight contract: every failing item is reported and 'nothing is written on refusal'. It also discloses that an adopted network is never deleted with the cluster, which materially tempers the destructiveHint.

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

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

Purpose is front-loaded in the first clause and the sibling disambiguation is placed after the scope details, which is sensible ordering. It is a dense ~200-word block with no paragraph breaks, and the enumerated preflight checklist is the one stretch that could be shortened without losing decision-relevant 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 32-parameter, destructive, no-output-schema creation tool, the description covers prerequisites, provisioning side effects, defaults for credentials, and refusal semantics. The only gap is that it says nothing about what the call returns or whether it is synchronous versus long-running, which an agent needs in order to decide whether to wait or poll.

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 still adds relational meaning beyond the schema by explaining that list_managed_k8s_options locations map to zones and node sizes map to plans, and that preflight validates credential, billing, zone compute, plan/template existence, adopted-network zone and quota. It does not, however, add syntax or defaults for most of the 32 parameters.

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

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

Opens with a specific verb and resource ('Create and provision a new self-managed Kubernetes cluster on Ankra Cloud'), then narrows scope: k3s or kubeadm, self-managed, one zone, bastion-fronted. It is unmistakable against siblings such as create_managed_cluster or create_aws_cluster.

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 routes the agent away from this tool ('A managed Ankra Cloud Kubernetes cluster ... is create_managed_cluster with provider=ankracloud_k8s, not this tool') and states the enabling prerequisite ('Only available to organisations with Ankra Cloud enabled'). It also names the two prerequisite lookup tools (list_managed_k8s_options, list_provider_credentials) and what to read from them.

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

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

Annotations already disclose readOnlyHint=false and idempotentHint=false, but the description adds value: it says the platform links the repo/branch and provisions a CI/CD pipeline, revealing side effects beyond a plain record insert. The security warning that the credential must be referenced by name is concrete behavioral guidance.

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 tight sentences, front-loaded with the action and mechanism, then closing with the critical security constraint. No filler and nothing that could be dropped without losing meaning.

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 5-required-param creation tool with no output schema, the definition covers the action, the side effects, and the key parameter constraint. It does not mention post-creation behavior such as first build timing or idempotency, but nothing essential for calling it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning for repo_credential_name by stressing it is referenced BY NAME and that secret values must never be passed. This clarifies an ambiguity the schema alone does not resolve.

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

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

States a specific verb (Create) and resource (Application) plus the source (connected git repository) and the side effect (provisions the CI/CD pipeline). It is hard to confuse with delete_application or list_applications, though it does not explicitly name or contrast any sibling.

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 phrase 'from a connected git repository' implies the prerequisite that the repo must already be connected, and the tool name makes its role obvious, but there is no explicit when-to-use/when-not-to-use statement or named alternative (e.g. create_stack, cicd_propose_application_pipeline). Usage is implied rather than stated.

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 a non-readonly, non-idempotent, destructive mutation, and the description adds substantial behavior beyond them: the VPC 'all torn down with the cluster', 'Ankra never modifies an adopted VPC's network', the preflight that 'refuses with every failing item' and writes nothing on refusal, and SSH-exposure reporting. These are the operational facts an agent needs before proposing the call.

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?

It is long, but the length is justified by a 32-parameter topology tool; the core purpose and the create-vs-adopt fork are front-loaded, followed by requirements, preflight, and sibling routing. Subsequent sentences each carry distinct constraints, though the density is close to the limit.

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 no output schema and a highly complex tool, the description covers prerequisites, the adoption flow, preflight failure semantics, and sibling alternatives well. It does not describe the success-side outcome or that provisioning is likely long-running, which is the one notable gap for a mutation of this scale.

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 32 parameters and the baseline is 3. The description still adds a higher-level model that spans parameters — the created-network CIDR/zones plan, the created-vs-adopted branch rules, and EC2 instance-type naming — which meaningfully frames how the parameters interact.

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

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

The description opens with a specific verb and resource ('Create and provision a new self-managed Kubernetes cluster on AWS EC2: k3s or kubeadm on Ubuntu instances reached through a bastion host'), plus the stack it installs. It explicitly distinguishes itself from the sibling create_managed_cluster ('Managed EKS creation is create_managed_cluster, not this tool'), so an agent can route correctly without opening a schema.

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

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

It states when to use this tool and its exclusions ('Only available to organisations with AWS self-managed provisioning enabled'), names the help tools to call first (list_provider_credentials with provider='aws'/'ssh-key'), and lays out the adoption-vs-created-network decision with the exact conditions and required fields for each branch.

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 it discloses that a published profile version is immutable, that the request requires `profiles.write`, that a refused request returns the failing field, and that Ankra never sees or stores generated Secret values, which are created once per service namespace and untouched on upgrade. That is exactly the operational context an agent needs for a destructive, non-idempotent mutation.

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

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

Purpose is front-loaded in the first clause, and every sentence carries non-redundant information. It is a single dense paragraph with some run-on parentheticals (the CLI twin, the key-length range) that could be split for easier scanning, but 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?

With 7 parameters, a nested `generated_secret` object, and no output schema, the description still covers creation, publication, immutability, permission requirements, error shape, and the follow-up pin check. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is already 100%, so the baseline would be 3, but the description adds genuine meaning: `registry_name` may be the organisation's own registry or the shared catalogue's, `values_yaml` is the chart's values, and `generated_secret` keys may be random (16-64 chars, default 32) or fixed values such as a user or database name. It also states the cross-field relationship between the generated Secret and the chart's existing-secret values, which the schema cannot express.

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

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

The description opens with a specific verb and resource: make one Helm chart into a stack profile that a managed-service package is published over, and publish its first version. The parenthetical twin (`ankra services packages init --addon`) and the later distinction from `publish_service_package` make the scope unambiguous, so an agent can separate it from `create_stack_profile` or `add_manifest_to_stack_profile_draft`.

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 a clear downstream path: call `get_service_profile_pin` on the returned profile and version before `publish_service_package`. It also explains when to supply `generated_secret` and how to wire that Secret into `values_yaml` via `connection.secret_name`. It stops short of naming the sibling profile-creation tools or stating when to prefer this over them, so no 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 only state readOnly=false, idempotent=false, destructive=false. The description adds substantial context well beyond them: the record is written into the customer's own Cloudflare account and affects real traffic, duplicates are refused (consistent with idempotentHint=false), and created records are stamped 'Managed by Ankra'. It also repeats 'Managed by Ankra' with a user-confirmation requirement, which is meaningful operational guidance.

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?

Four tight sentences, front-loaded with the action and the confirmation requirement, then the naming rules and duplicate check. Some content duplicates the schema (name forms, comment default), which costs a little, but there is no filler.

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

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

For a 9-parameter mutation with no output schema and a low-bar annotation set, the description covers side effects, prerequisites, naming rules, and failure modes well. It stops short of stating what a successful call returns or the credential/permission requirements, though credential_name is documented in the schema.

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

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

Schema description coverage is 100%, so the schema already documents all nine parameters including the name forms and the comment default. The description largely restates the name-qualification rules ('bare label', 'fully-qualified', '@' apex) and the 'Managed by Ankra' default rather than adding new semantic detail, so the baseline 3 applies.

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

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

States a specific verb and resource – 'Create a DNS record in one of the organisation's Cloudflare domains' – and scopes it clearly against the sibling DNS tools (list/update/delete). An agent immediately knows this is the creation path and which resource family it touches.

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

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

Explicit conditions: confirm the domain and content with the user first, and call list_cloudflare_dns_records beforehand to check the name is not already taken because Cloudflare refuses an exact duplicate. It also names a when-not case (a name outside the domain is refused), leaving nothing to inference.

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

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

Annotations declare readOnlyHint=false, destructiveHint=false, idempotentHint=false; the description adds meaningful context beyond that by explaining that no cluster state changes until join_cluster_to_mesh. It does not address whether duplicate mesh names are allowed or what identifier the created mesh returns.

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

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

Three short sentences with no filler: the creation action first, the state-change caveat second, the prerequisite third. Each sentence carries distinct information.

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

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

For a single-parameter, non-destructive create with no output schema and annotations covering the safety profile, the description covers purpose, side effects, and ordering. Minor gap: it does not hint at what the call returns (e.g. a mesh identifier) that later join/readiness calls would need.

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 single 'name' parameter already documents the expected human-readable format with an example. The description adds no syntax or constraint detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource ('Create a new, empty cluster mesh') and sets it apart from neighboring mesh tools by clarifying that it only records the mesh object. An agent can distinguish it from join_cluster_to_mesh and check_cluster_mesh_readiness without opening schemas.

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

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

Explicitly routes the agent: run check_cluster_mesh_readiness first, then use join_cluster_to_mesh to actually attach clusters. It states the precondition, the follow-up action, and the fact that nothing changes until the join step.

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

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

Annotations declare non-readonly, non-idempotent, destructive, and the description adds meaningful context beyond them: provisioning starts immediately after creation, and the required credential types. It omits cost implications and failure/rollback behavior, but with annotations covering the safety profile this is solid additional value.

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 front-loaded sentences, each earning its place: the action, the prerequisites, the immediate-provisioning warning, and the credential/size lookup guidance. No filler.

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

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

For a 12-parameter destructive creation tool with no output schema, it covers prerequisites, timing, credential discovery, and sizing conventions well. It does not describe what the tool returns on success (no output schema exists), leaving a minor gap for a create operation whose result the agent may need to act on.

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, but the description adds real meaning: worker/bastion/control-plane sizes are DigitalOcean droplet slugs like 's-2vcpu-4gb', and it warns that list_instance_types does not cover DigitalOcean, steering the agent away from a plausible wrong lookup.

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

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

States a specific verb and resource ('Create and provision a new Kubernetes cluster') scoped to DigitalOcean, which cleanly distinguishes it from the many sibling create_*_cluster tools (aws, hetzner, ovh, scaleway, upcloud). An agent can identify the provider and operation without opening the schema.

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

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

Gives concrete prerequisites (DO API credential, SSH key credential, region) and routes the agent to list_provider_credentials for credential IDs, plus an explicit exclusion ('list_instance_types does not cover DigitalOcean'). It stops short of contrasting with sibling cluster-creation tools or stating when not to use it, but the provider scoping makes the context clear.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false and destructiveHint=true, so the write/non-idempotent profile is covered structurally. The description adds genuinely new behavioral context beyond that: "The cluster will begin provisioning immediately after creation," i.e. no dry-run or confirmation step and side effects start at once. It stops short of covering cost implications or how the resource is later torn down, so it is not quite a 5.

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

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

Five dense sentences with no filler, ordered from what the tool does to prerequisites to optional behavior to immediate side effects to prerequisite-lookup tools. For a 21-parameter tool this is an appropriately sized, front-loaded introduction.

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 no output schema, the description carries the return-value burden and does not describe the create result (though the schema notes the result names auto-picked server types). It otherwise covers prerequisites, optional modes, and immediate provisioning for a large, complex creation tool. The main remaining gap is the absence of any lifecycle/cost framing (e.g. cleanup via delete_cluster, billing impact).

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 and the schema already documents defaults, enums and UUID sources. The description still adds cross-parameter meaning the schema only implies per-field: node_groups replacing worker_count/worker_server_type, GitOps defaulting to GitHub unless gitops_provider is 'bitbucket_cloud', and the guidance to omit server types so the platform selects location-provisionable ones. That is a modest but real increment over the schema.

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

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

The description opens with a specific verb+resource+provider ("Create and provision a new Kubernetes cluster on Hetzner Cloud"), which cleanly separates it from the many sibling cluster-creation tools (create_aws_cluster, create_digitalocean_cluster, create_proxmox_cluster, create_managed_cluster). It also enumerates the distinguishing capabilities (GitOps, heterogeneous node groups) that an agent needs to match the request to this tool.

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

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

It states the prerequisites explicitly (Hetzner API credential, at least one SSH key credential, a datacenter location) and then routes the agent to the exact prerequisite-lookup siblings: list_provider_credentials, list_instance_types, list_gitops_credentials and list_gitops_repositories, each with the reason to call it. It even flags a caveat about list_instance_types not showing per-location stock, which is real when-to-use guidance.

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