Control Plane

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

Annotations already declare idempotentHint=true and destructiveHint=true; the description earns credit by explaining *how* — same args reuse existing resources, and allowWorkloads re-applies the template, potentially redeploying and resetting out-of-band changes like volume snapshot settings. It also discloses the 40-second readiness wait and that credentials are generated server-side. That said, the destructive caveat is a single dense clause rather than a clearly separated warning, leaving some ambiguity about exactly which changes get reset.

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

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

Purpose and defaults are front-loaded, and every sentence carries information (credentials, readiness, idempotency, destructive caveat, alternative). The middle section is very dense — several distinct behaviors packed into one long sentence — which slightly hurts scanability.

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

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

Covers what annotations and schema cannot: the GVC fallback chain, the readiness wait, the returned host/port and cpln://secret env references, and the destructive re-apply behavior. For a 9-parameter creation tool with a destructive hint, this is 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 baseline is 3. The description reinforces the gvc default behavior and the allowWorkloads admission rules, but these are largely already spelled out in the property descriptions, so it adds little 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?

Names a specific action (install a database) plus the exact engine set and source (Template Catalog), and distinguishes itself from install_template/browse_templates by routing non-listed templates or unsupported settings there. An agent can tell it apart from install_template without opening either schema.

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

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

Explicitly states the fallback when gvc is omitted, what happens on re-invocation, and the exact alternative path ('browse_templates with the template name, then install_template') for other templates or settings like backups. It also flags the risky case (existing database + allowWorkloads) in advance.

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 safe read-only, idempotent, non-open-world lookup, so the description does not need to restate safety. It adds substantive behavior beyond them: results are ranked, each carries a confidence and install prerequisites, alternatives are suggested for other needs, and detail mode returns README notes and an example values.yaml to copy.

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 purpose and category coverage, then the query/name/category modes, then routing to plan_app, install_template, and add_database, so every part has a role. It runs long across several sentences, but the length comes from useful routing detail 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?

With an output schema present and annotations covering safety, the description still covers the modes (search, list, detail), the decision between goal and capability, and the handoffs to plan_app, install_template, and add_database. Nothing an agent needs in order to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: `query` should hold a capability or product rather than a raw goal, `name` switches from search to detail mode, and `category` scopes a listing when no query is given. That clarifies how the optional parameters interact, which the schema alone does not.

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

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

States a specific verb and resource ('Find templates in the Control Plane Template Catalog') and enumerates the catalog's coverage. It explicitly distinguishes itself from siblings plan_app, install_template, and add_database, so an agent can tell which tool applies without opening another 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 gives explicit when-to-use rules: name the capability in `query` if the user names one, derive the capability first if they describe a goal, omit `query` to list the catalog or one `category`, and use `name` for detail instead of searching. It also names the alternatives and the conditions that select them: build requests go to plan_app, and Postgres/MySQL/MariaDB/MongoDB/Redis go to add_database unless a setting such as backups is needed.

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?

Despite annotations already covering readOnly=false, destructive=true, and openWorld=true, the description adds substantial context: the build continues asynchronously after the call, building an existing NAME:TAG replaces that image and may trigger redeploys, no Docker daemon is involved, the output is always linux/amd64, and private repos require a one-time browser auth link returned by the tool. This goes well beyond what annotations provide.

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

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

The description is front-loaded with the core action and then systematically covers source options, async behavior, auth, and CLI fallback. Every sentence contributes, though the single dense paragraph could be slightly tighter; it remains efficient and well-organized.

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

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

Given the tool's complexity (7 params, build + push operation) and the existence of an output schema, the description covers all critical aspects: source options, async return, replacement semantics, authentication, and the CLI alternative for local folders. Nothing needed for correct invocation is missing.

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

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

Schema description coverage is 100%, so the schema already documents all seven parameters in detail. The description reinforces the repoUrl omission and the name/tag replacement semantics, but adds little parameter-level meaning beyond what is already in the structured descriptions. A baseline of 3 is appropriate.

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

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

The description states a specific verb and resource: 'Build a container image on Control Plane and push it to the org's private registry.' It clearly distinguishes from siblings like get_image_build (which reads builds) and write_app_files (which stores app files) by explaining the two source paths and the resulting buildId.

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

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

It explicitly says when to use repoUrl versus omitting it for app files, and provides a clear alternative for local folders ('A folder on the user's machine still goes through the CLI'). It also flags the private repo authorization requirement and the need to use connectNonce on retry, leaving no ambiguity about selection or prerequisites.

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

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

Annotations cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=false), so the bar is lower. The description still adds real behavioral context beyond them: 'No login, one hour, up to 100 MB per file', the instruction to 'Show the link exactly as returned', and the fact that the user drops everything at once while the page sorts it.

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

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

It is front-loaded with the purpose, and most sentences carry information. But it is a dense run-on block with no structural separation between purpose, usage, parameter rules, and constraints, and contains mild redundancy ('never ask for attachments and never inline them'). Readable but not efficiently structured.

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

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

An output schema exists, so return values need no explanation, and the description still covers everything an agent needs: the workflow, the files/folders distinction, the follow-up call to get_app_files, and the access/size/time constraints. Nothing material for correct invocation is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description meaningfully elaborates beyond the schema: files are 'each file the code uses in one specific place' (logo, hero image) whereas folders are 'a set the code does not tell apart', any number, any order, with caption added when each one must be named. This clarifies the semantic intent of the two structures rather than merely restating field names.

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

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

The opening sentence names a specific verb+resource (get an upload link for user files that become part of the app's code) and scopes it precisely ('stay as they are until the next build'). It also explicitly distinguishes itself from write_app_files and get_app_files by stating what content does and does not belong here, so an agent can tell it apart from siblings 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 gives explicit when-to-use rules (files vs folders), explicit exclusions ('Content the owner adds or changes after launch... never goes here, not even as a first batch'), and the explicit next step ('call get_app_files and put the stored paths in the code'). It even routes the agent to plan_app for the post-launch owner content 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-destructive and open-world, so the safety profile is covered. The description adds real context beyond that: the result lists DNS records the user must add, waitSeconds makes the call block until ready, and calling against an existing domain adds the route rather than failing.

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 common path and only then the escape hatch to custom configuration; every clause carries information. It is dense — the second sentence packs dnsMode, ports, port item shape and route matching into one line — 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 15-parameter creation tool with an output schema and exhaustive field documentation, the description covers the two dominant call patterns and the readiness semantics. Specialty paths (tags like cpln/wildcard, TLS and CORS on ports) are left to the schema, which documents them fully.

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 derivation logic the schema cannot express — that workload+gvc derives the 443 listener, its route and cname mode, and that a route without prefix matches /. This meaningfully shifts which parameters an agent needs to supply.

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 ('Put a domain in front of a workload') and immediately names the three parameters that drive the simple path. It also clarifies the upsert-like behavior on an existing domain, which an agent could not infer from the name alone.

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 splits the simple case (domain + workload + gvc) from the custom case (dnsMode and ports for ns delegation, gvcLink, multiple routes), which is exactly the branching decision an agent faces. It does not reference the update_domain sibling, so the choice between creating and updating an existing domain is only implied.

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

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

Beyond the annotations (readOnly=false, destructive=false, openWorld=true), the description discloses a consequential behavior: a GVC without placement cannot run workloads. It also preempts the most likely misuse by clarifying that locationOptions is DNS geo-routing tuning, not placement.

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 identity and purpose, then the placement decision rule, then the domain exclusion — a sensible priority order. Slightly redundant, since the ask-first instruction is restated both in the description body and the locations schema field.

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 15-parameter create tool with nested objects and an output schema, the description correctly focuses on the one decision an agent can get wrong (placement) and defers field-level detail to the schema. It omits any mention of org scoping or auth prerequisites, which is a minor gap given the tool is open-world.

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 earns extra by disambiguating the three placement-related parameters (locations, locationQuery, locationOptions) and stating they are alternatives rather than complements. It stops short of adding anything the schema does not already imply about the remaining twelve optional fields, but those do not need help.

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 plus a one-clause explanation of what a GVC is ('the deployment scope workloads live in'), which is far more than a restatement of the title. It also distinguishes this create call from the domain and location resources an agent might otherwise conflate with it.

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 procedural guidance: ask the user for placement if unspecified, use list_resources kind="location" to show options, pick one fitting location and state it when delegated. It also names the alternative path for custom domains (create_domain) and states a hard exclusion ('Never create an empty GVC').

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 openWorldHint=true, so the description's job is to add consequence detail beyond the flag — and it does: 'deleting a secret breaks the workloads that read it ... and any GVC pull secret or domain TLS that uses it,' plus 'Deletes on the call' (immediate write, no dry-run) and 'Deletion is permanent' (irreversibility). It does not cover permissions needed or whether deletion is rate-limited/eventually-consistent, so it stops short of 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?

Four sentences, each earning its place: identity, blast radius, timing, and required pre-call procedure, with the most consequential facts (blast radius, irreversibility) front-loaded after the one-line purpose. No restated schema content or filler.

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

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

For a destructive, open-world mutation with four parameters, an output schema that documents return values, and rich schema descriptions, the description supplies exactly what the structured fields cannot: dependent-risk examples, immediacy of the write, and the approval workflow an agent must follow. Nothing an agent needs to call this 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% — the schema already documents gvc scoping, org, the 15-value kind enum, and the per-kind name-format exceptions (domain = full hostname, image = NAME:TAG). The description adds the 'kind + name' identity framing but no syntax beyond the schema, so the baseline 3 is correct.

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 (delete) and resource (Control Plane resource identified by kind + name) and explicitly claims scope as 'the single delete tool for every deletable kind.' This distinguishes it from the many create_/update_/remove_ siblings without the agent needing to open another schema.

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

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

Gives an explicit pre-call workflow: read the resource, tell the user what will be removed and which dependents break, and proceed only on explicit approval. The 'for every deletable kind' phrasing also routes the agent here rather than to a kind-specific alternative, which is the only alternative available.

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 openWorldHint=true, so the write/outside-world profile is known. The description adds real substance beyond that: it creates a standard workload or updates one it created, applies production defaults (HTTP readiness/liveness checks, 2 replicas, exposure set now), grants secret access, waits up to 40 seconds, and returns status, public URL, and the exact next call. It stops short of describing what happens to a same-name workload it did not create (that lives in the schema's replace field), so a 4 rather than 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?

Purpose and build-source routing are front-loaded in the first two sentences, and every clause carries distinct information (build source, GVC handling, workload defaults, secret access, wait time, return payload, handoff). The middle is one long run-on sentence that could be broken up, costing it the top mark.

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 20-parameter, nested-object, open-world mutation with an output schema, the description covers the decisions an agent must make: which build source, GVC handling, storage vs add_database, and when to use the sibling instead. Return values are covered by the output schema and briefly signaled, so nothing critical is missing.

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

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

Schema coverage is 100%, so the baseline is 3 and most parameter meaning is already documented. The description still adds cross-parameter workflow semantics the schema treats only field-by-field: resume via buildId, and the branch/healthPath/minScale defaults that flow from build vs image vs storage choices.

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: 'Build and deploy an HTTP app in one resumable call.' It further distinguishes itself from the sibling create_workload by naming the exact cases it does not cover (serverless, several containers, cron, other protocols). An agent can select it 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?

Routes the agent explicitly: build sources are write_app_files (default), repoUrl, or image; storage routes to the storage field and databases to add_database; the closing sentence hands off non-HTTP/single-container cases to create_workload. GVC omission behavior (job-created GVC, prompt, or create-once-location-picked) is spelled out rather than 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?

Adds substantial context beyond annotations: it discloses the data sources read (per-location deployments, recent events, last 30 minutes of error logs), the failure catalogue it matches against, and the shape of the response (likely cause + evidence + fix). The 'Read only' sentence duplicates readOnlyHint=true but does not contradict it. Missing only things like latency/cost of the scan.

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 that state purpose first, then mechanics, then safety. The failure-category list is long but each item is informative; nothing is redundant except the trailing 'Read only' which annotations already cover.

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

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

For a read-only diagnostic tool with a full schema, an output schema, and safety annotations, nothing an agent needs is missing: it knows what is inspected, how long of a log window, what failure classes are detected, and what the response contains.

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 four parameters are already documented, and the description adds no per-parameter meaning. Baseline 3 is appropriate since the schema does the work.

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 ('diagnose a workload') plus the exact problem domain (unhealthy, not starting, failing). It is clearly distinguishable from siblings like get_workload_logs or query_metrics because it names the multi-source correlation it performs.

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?

'in one call' signals this replaces manually chaining logs, events, and deployment reads, which is implicit routing guidance against the sibling list tools. It stops short of explicitly naming those alternatives or stating when not to use it (e.g. healthy workloads, single known log lookup).

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

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

Annotations already declare readOnly/idempotent/non-destructive, yet the description adds substantive context beyond them: manifest conversion is dry-run validated against the API first (nothing is created), validation failures return the error instead of HCL, secrets are never exported or converted and a closure containing one is refused, and unsupported kinds are rejected with the supported list. These are exactly the failure-mode and side-effect details an agent needs.

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

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

Front-loaded with the core verb and resource, and every sentence carries real information (modes, dry-run, secrets exclusion, unsupported kinds). It is a single dense paragraph with nested parentheticals and example paths, which makes it slightly harder to scan than a short bulleted layout would 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?

An output schema exists, so return values need no explanation, and the 100% schema coverage covers the inputs. For a read-only export tool the description supplies the remaining essentials: mode selection, dry-run/validation behavior, secret refusal, and rejection of unsupported kinds.

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 the one thing the schema does not declare: that `resource` and `manifest` are mutually exclusive alternatives (no required params are marked), and that `gvc` only matters for GVC-scoped manifest kinds while `org` is required when several orgs are granted. That clarifies overall parameter interplay rather than merely restating field docs.

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

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

The description names a specific verb and artifact ("Generate Terraform (HCL)") and the exact resource scope (EXISTING Control Plane resources), then enumerates the two distinct input modes: a self link or a manifest. No sibling tool in the list generates Terraform/HCL, and the description makes that unique purpose unmistakable.

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

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

It clearly explains which parameter selects which behavior: `resource` for existing resources (with bulk semantics by path depth, e.g. `/org/acme` exports the whole org), or `manifest` plus `org`/`gvc` for conversion. It also states when to set `generateImports` (after `terraform init`, before first `apply`) and `includeDependencies`. It doesn't name an alternative sibling tool to use instead, but no sibling competes for this job.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds real behavioral context beyond that: the operation is asynchronous and returns lifecycleStage and messages, signalling a poll-until-terminal pattern.

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

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

One dense sentence with the action, the lookup key, and the return payload front-loaded; no filler or redundancy.

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

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

Output schema exists, so return values needn't be detailed, and the annotations carry the safety profile; the description supplies enough about async lifecycle and the id source for the agent to call it correctly. It could note the GVC/parent scoping required by the schema, but that is minor.

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 a mapping hint by tying the kind values to command types (cron run/replica stop vs volume set command) and restates that commandId comes from the initiating call, which reinforces the schema rather than merely repeating it.

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

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

Uses a specific verb (Fetch one) plus a specific resource (asynchronous command) and enumerates concrete command types (cron run, replica stop, volume set command), which separates it from siblings like run_volumeset_command and get_image_build.

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?

Ties usage to the id returned by the call that started the command, which tells the agent this is the follow-up/polling tool for async operations. It doesn't explicitly state when not to use it or name a sibling alternative, so it falls short of a full 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so safety is covered; the description adds the non-obvious behavioral detail that a full read begins with a list of section headings, which tells the agent how to discover sections before drilling in. It does not mention size/length or cost of a full read, which is the one behavioral trait an agent would still want.

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, each carrying distinct information, with the core verb-and-resource statement front-loaded. The parenthetical '(deploy_app, add_database, and the rest)' is slightly loose but reinforces the routing quickly; 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 a two-parameter read tool with an output schema, full annotations, and a 100%-described schema, the description covers what it returns, when to prefer it, when to prefer the operating-guide instead, and how to navigate sections. Nothing an agent needs 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 enum is self-documenting, so the baseline is 3. The description earns above that by explaining what 'skill' means semantically (one Control Plane task family) and how section interacts with a full read ('Pass section to read one part'; a full read starts with headings), which is workflow guidance the schema does not give.

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 the runbook for one Control Plane task family') and enumerates the content: correct usage, easy-to-miss platform constraints, and when the feature is the wrong tool. It explicitly separates itself from the job tools (deploy_app, add_database) and from the operating-guide skill, so an agent can place it against siblings 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 both a use case ('optional deep reference for work the job tools do not cover') and an explicit routing rule away from this tool ('Rules that apply to every task ... are in the operating-guide skill'). The word 'optional' also sets the priority relative to the action tools, which is exactly the disambiguation 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 (readOnly, idempotent, non-destructive), and the description goes further by disclosing non-obvious behavior: the log auto-returns only on failure, that waiting happens server-side up to a limit, and that the log is large. These are behavioral traits an agent could not infer from annotations or schema 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?

Three dense sentences with the core purpose front-loaded and no filler. Every clause conveys either returned content, status semantics, or a parameter's intended use.

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

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

An output schema exists, so return shape need not be restated, and the description still covers status vocabulary, log-return conditions, and the polling-vs-wait decision. 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. The description nonetheless adds semantic intent for the load-bearing parameters, explaining WHY to pass includeLog and waitSeconds rather than just what they are. It does not discuss logOffset or maxLogLines, but the schema carries those.

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 (read) and resource (a build started by build_image), and enumerates what is returned: status, progress events, and log. It clearly complements rather than duplicates the sibling build_image, and enumerates the status values, so an agent knows exactly what it is selecting.

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 usage: the log comes back automatically on failure, includeLog is only for reading it while building or after success, and waitSeconds is prescribed 'instead of calling again and again.' This gives concrete when/when-not guidance tied to alternatives.

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

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

Goes well past the readOnly/idempotent annotations: it discloses that install values and manifests are never returned, that reads require `reveal` permission on the helm bookkeeping secret, and that waitSeconds blocks server-side until workloads are ready or the timeout expires. These are exactly the auth and scope facts an agent needs before calling.

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 primary action and response fields, then handles the list mode, the wait behavior, and the permission caveat in order. It is dense as a single paragraph, but every sentence carries distinct information with no restatement of the title.

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 a modest three-parameter schema, the description covers both invocation modes, expected response fields, the permission prerequisite, and the exclusion of sensitive payloads. With an output schema present, 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 baseline is 3, but the description adds a constraint the schema does not: waitSeconds is only meaningful when passed with `name`, and `name`'s absence switches the whole response shape to a list. That mode-switching semantics adds real value beyond the field docs.

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 ('Show an installed release's current status, revision, and the Control Plane resources it created') and explicitly covers the second mode (list releases in the org). The two-mode framing separates it cleanly from siblings like install_template, upgrade_template, browse_templates, and uninstall_template.

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

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

Gives concrete usage conditions: omit `name` to list, supply `name` plus waitSeconds to block until deployed and workloads are ready, and 'use this instead of calling again and again' to steer away from polling. It stops short of naming a specific sibling (e.g., browse_templates for discovering installable templates), so it is clear but not fully disambiguating.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is free. The description adds genuine behavioral context: secrets return metadata only because the API never includes their data, and a volume set also lists its snapshots. It stops short of describing payload size or truncation behavior, but the output schema covers the return shape.

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

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

Densely front-loaded: the core operation comes first, then return shape, then routing guidance, then the schema mode. It is somewhat run-on (multiple clauses chained with semicolons), but nearly every sentence carries distinct information.

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

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

For a read tool with full annotations, a complete 7-parameter schema, and an output schema, this description covers everything an agent needs: naming rules, org exception, GVC scoping implications, secret data restrictions, and the schema-lookup path. 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%, so the baseline is 3; the description earns an extra point by explaining cross-parameter interaction — omit `name` for kind='org', omit it again when `schema: true` — and by clarifying that the call returns a schema plus REST endpoints rather than a resource. That is semantics the schema states piecemeal but the description makes operationally clear.

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

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

States a specific verb and resource ('Fetch one Control Plane resource by `kind` + `name`') and immediately scopes it as 'The single read-one tool for every resource kind', which separates it from list_resources, search_control_plane, and the query_* siblings. The org exception and the schema mode are called out up front.

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 the target here before update_* or delete_resource, and that job tools (rollback_workload, diagnose_workload) read it themselves — a real when-not-use signal. It also gives a distinct use case for `schema: true` (before writing a cpln apply manifest or API body) with the warning 'never guess field names'.

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 flag destructive/not-idempotent; the description goes much further by disclosing that granting creates an identity and policy binding, that redeployment is triggered when the workload waits on the secret, that revocation preserves the identity, and that deployment pauses then resumes on new workloads. 'Never returns values' also sets a security expectation about the response.

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 leads, then alternatives, then constraints, with no filler sentences. The telegraphic semicolon-heavy packing of four distinct instructions into the middle makes it slightly dense 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?

Given an output schema, full annotation set, and 100% parameter coverage, the description fills the remaining gaps an agent needs: prerequisites (existing workload, existing secret), ordering with create_workload/create_secret, side effects, and the env/volume boundary.

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 defaults such as the {gvc}-{workloadName}-secrets-policy name and the name-only convention are already documented in the schema. The description only restates remove-true semantics, which the schema parameter description already covers; the one genuine addition is the cpln://secret/NAME.KEY reference format, which is tangential to the tool's own 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?

States a precise verb+resource pair ('grant an EXISTING workload access to a secret') and enumerates the concrete side effects (identity creation, policy binding with reveal, conditional redeploy). It also disambiguates the reverse operation ('remove true revokes it, keeping the identity') so the tool cannot be confused with allow_workload_access or grant_cloud_access.

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 routing instructions for every adjacent case: 'Use it rather than building the identity and policy by hand', 'For a NEW workload, create_workload first', 'A missing secret: create_secret first'. It also states a negative boundary ('Does not edit env or volumes') with the alternative mechanism (cpln://secret/NAME.KEY).

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: the install refuses and creates nothing when a required secret is missing, values containing passwords/keys/tokens are rejected, dryRun applies nothing, and deployment is asynchronous. These are non-obvious failure and lifecycle behaviors an agent could not infer from readOnlyHint/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?

Dense but front-loaded: the required inputs come first, then the add_database branching, then the secret rule, then dryRun and async waiting. No filler sentences, though the run-on middle paragraph could be split for easier 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?

For a 7-parameter mutation with an output schema, the description covers inputs, conditional requirements, rejection behavior, dry-run mode, and the async completion path. 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%, and the description still adds value: version defaults to latest, gvc is conditional on the template creating its own, values must be an YAML mapping with secret references rather than literal credentials. It stops short of explaining org or the exact values syntax, which keeps it below a 5.

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 ('Install a catalog template as a new release') and immediately enumerates the key inputs, so the operation is unmistakable. It also routes the agent away from the sibling add_database for the common database templates.

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

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

Explicitly states when to prefer add_database over install_template and names the exception (settings add_database doesn't take, such as backups). It also prescribes prerequisites (create_secret for required secrets), the dryRun path, and the follow-up (get_installed_template with waitSeconds).

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 read-only/idempotent, and the description adds behavior beyond them: waitSeconds polls server-side and returns latest state on timeout, the canonical endpoint must be reported as the public URL (never hand-built), and cron workloads expose per-execution history in status.jobExecutions. These are operational details an agent cannot infer from annotations.

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

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

Every sentence carries actionable information: purpose, readiness framing, wait behavior, aggregate vs single-location, replica usage, cron history, and error routing. The most important guidance (primary readiness check, use waitSeconds) is front-loaded with no filler.

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

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

With an output schema present, the description needn't explain return shapes, and it still supplies the interpretive guidance (canonical URL, replica values, jobExecutions location) an agent needs. Annotations fully cover the safety profile, so nothing material is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema: it explains what omitting location yields (all locations + canonical URL), ties replica counts to the --replica flag for exec/connect/cp/port-forward, and clarifies the wait-or-timeout behavior of waitSeconds.

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 ('A workload's deployments: its per-location rollout status') and immediately frames it as the readiness check, distinguishing it from siblings like get_resource and diagnose_workload. An agent knows exactly what this returns 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 when to call it ('PRIMARY readiness check after create_workload/update_workload'), the alternative for failures ('A location that reports an error: diagnose_workload'), and how the optional location parameter selects between aggregate and single-deployment modes.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, openWorldHint=false, so the safety profile is fully covered by structured data. The description adds value by disclosing the scoping rule (only user-granted orgs) and that GVCs/locations are included in the response. With an output schema present and annotations covering behavior, a 3 is appropriate.

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

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

Two sentences: the first states what is returned and its scope, the second states when to call it. Fully front-loaded with zero filler; 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 zero-parameter, read-only list tool with a full output schema and rich annotations, the description covers purpose, scope, return contents, and call triggers. Nothing an agent needs in order 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?

Zero parameters, so per the rubric the baseline is 4. There is nothing for the description to document, and it correctly does not invent parameter semantics. No higher because there is no parameter content to add value 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 (List) and resource (organizations), and crucially scopes the result set to 'this connection ... the ones the user granted when connecting'. It also discloses the nested return shape (GVCs + locations), which no sibling tool does. Clearly distinguishable from list_resources, list_deployments, list_quotas.

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

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

Gives an explicit trigger: 'Call it when the user has not named an org, or to see whether an org has a GVC yet.' That is genuine when-to-use guidance. It stops short of naming alternatives (e.g. search_control_plane, list_resources) or stating when not to use it, so it is a solid 4 rather than a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds what the annotations cannot: the response is a summary table, not full objects, and gvc is scoped/ignored depending on kind. It stops short of stating rate limits or truncation behavior, so it is 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?

Three tight sentences with no filler. Core capability and the routing constraints (get_resource, list_deployments) are front-loaded before any supporting detail.

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

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

With an output schema present, return values need not be explained, and annotations carry the safety profile. The description covers scope, required inputs per kind, and the sibling hand-offs, leaving nothing an agent needs missing in order 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% and already documents kind, org, gvc requirements, and the limit range. The description mostly restates the gvc/org combination and offers example kind values, adding only marginal meaning over the schema. 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?

States a specific verb (List), resource (Control Plane resources), scope (of one `kind`) and output form (summary table). It explicitly names the sibling it is not — get_resource for single-item JSON and list_deployments for deployments — so an agent can route 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 when-to-use (the single read-list tool for every kind), the discriminating inputs to pass (kind, org, gvc for GVC-scoped kinds), and two negative cases with named alternatives (get_resource for one item's full JSON; list_deployments because deployments are not a kind here).

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

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

Annotations already declare readOnly, idempotent, non-destructive, and non-open-world, so the safety profile is covered. The description adds real value beyond that by clarifying this is an advisory planning step to run before writing code and by summarizing what it returns (how to settle with the user, how Control Plane keeps files/records/secrets/replicas, with the relevant tools).

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 condition (plan before writing when the app keeps state), which is the most important information. However it carries two lengthy example lists that could be trimmed without losing meaning, adding modest verbosity.

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

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

For a no-input advisory tool with an output schema present, the description gives enough: when to invoke it, what class of app it targets, and the nature of the guidance returned. Return-value detail is appropriately left to the output 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?

The tool takes zero parameters, so there are no parameter semantics to document; the baseline for a parameterless tool is 4. The description correctly introduces no input arguments, consistent with the empty 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 (plan) and resource (an app) and precisely scopes it to apps that keep state (content, records, files, sign-ins). It cleanly separates this tool from the direct-build path for stateless apps, so an agent can route 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 conditions (app persists anything: added/changed content, records, files, sign-ins) and explicit when-not conditions (stateless apps like a game, calculator, or landing page, which should be built directly). Both sides of the decision are named.

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

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

Annotations already declare readOnlyHint/idempotentHint/non-destructive, so safety is covered; the description adds real behavior: multi-name results are merged and sorted newest-first, platform events live in the `cpln` context, and default lookback is 7d. It does not mention pagination or result caps beyond the limit param, leaving a small gap.

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 the name/names decision before the filters, and every sentence carries signal. It is dense — the context and diagnose_workload points 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?

With an output schema available, the description need not explain return values, and it already covers scoping, defaults, context switching, and the sibling boundary for an 11-parameter tool. Nothing an agent needs 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; the description goes further by explaining cross-parameter semantics (to is only valid with from; since is exclusive with from/to; gvc is required only for GVC-scoped kinds with name/names) and the merged-sorted behavior of `names`. These add meaning beyond the individual schema entries.

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 (Query) plus a precisely scoped resource (Control Plane audit trail for mutations on resources of one kind), with an explicit note that runtime events belong to diagnose_workload. An agent can separate this from diagnose_workload and search_control_plane 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?

States the omit-name/names default, when to use `names` for multi-resource audits, and names the alternative (diagnose_workload) for runtime events with the exact condition that selects it. Both when-to-use and when-not-to-use 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 already declare a safe, idempotent read, but the description adds substantial context: newest-first ordering, span attribute names usable in TraceQL, the sampling/tracing-enablement caveat, and truncation behavior for very large traces (first spans in tree order, error spans always listed). That is exactly the kind of behavior an agent needs before invoking.

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 filter modes, then preconditions, then return shape. Most sentences carry unique information, though the long span-attribute enumeration and return-value recap are heavy given an output schema already exists.

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

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

Covers the two call modes, filter interplay, enabling/sampling prerequisites, and truncation semantics, so an agent can call it correctly even though the output schema handles return shape. No significant gaps remain.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it maps filters to concrete span attributes (resource.gvc, span.http.status_code as a string, span."guid:x-request-id") and clarifies that `traceql` replaces and must subsume the structured params. This helps agents author correct queries beyond what the schema 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 ("Search distributed traces (Tempo TraceQL)") and immediately distinguishes the two modes: search vs. single-trace detail via `traceId`. It is clearly separable from siblings like query_metrics and query_audit_events.

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

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

Gives clear use cases (slow, failing, or specific requests) and a critical precondition: traces only exist where `spec.tracing` is enabled and only for requests sampled after that. It also states the `traceql`-vs-structured-params rule. It doesn't explicitly name sibling alternatives for non-trace questions, keeping it just shy of a 5.

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

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

Annotations only declare non-readOnly, non-idempotent, non-destructive; the description goes well beyond that with 'every call files a new request, so never resubmit a pending one', which is the practical consequence of idempotentHint=false. It also enumerates the three outcomes with their side effects: approved means retry the action now, pending means Control Plane review plus an email and Console notification, denied comes with a reason. That is real behavioral disclosure an agent cannot get from the annotations.

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

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

The action and trigger are front-loaded, and nearly every clause carries distinct information (error mapping, gvc requirement, no-resubmit, outcome semantics, out-of-scope routes). It is on the long side for a four-parameter tool and the outcome enumeration could be tightened, but there is no filler sentence.

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

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

An output schema exists, yet the description still summarizes the return (request id plus status) and explains what each status means for the caller's next step, which is the part an agent actually needs. Combined with the trigger conditions, missing-input rule, per-GVC requirement, and the pointer to Control Plane support, nothing needed to invoke this correctly 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 baseline is 3, and the description adds genuine meaning on top: quota values are derived from the error message, cpu-per-workload is in millicores and memory-per-workload in MiB, and gvc is required only for the three per-GVC quota families it names. It stops short of explaining the org parameter or the 0-1,000,000 bound, leaving a little on the table.

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 states a specific verb and resource: 'Ask Control Plane to raise an org quota.' It then distinguishes this tool from the adjacent support route by naming exactly what is out of scope (lowering a max, orgs-per-billing-account). An agent can tell this apart from every sibling in the list 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 trigger condition is explicit and operational: use it after a create or update fails on a quota, with the mapping from error text to quota name ('a workload's total CPU or memory error means cpu-per-workload or memory-per-workload'). It also states the when-not ('file it only when the user wants the increase') and the exclusion (lowering a max and orgs-per-billing-account go through Control Plane support), plus a missing-input rule for requestedMax.

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 real substance: replicas are replaced, secrets and env are re-read, and there is a bounded wait for readiness. Minor ambiguity: it says 'waits up to 40 seconds' while the schema allows waitSeconds up to 45, and it does not say what state is returned if readiness never happens (the schema hints at 'latest state').

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, zero filler, and the ordering is deliberate: what happens first, then what is excluded, then the safety gate. The approval warning is placed last so it lands.

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

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

With an output schema present, return values need no explanation, and the description covers effect, exclusions, approval, and wait behavior. The remaining gap is failure semantics — what the caller should do if the workload is not ready after the wait window.

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 four parameters (gvc, org, name, waitSeconds) are already documented, including the 'use this instead of polling repeatedly' guidance for waitSeconds. The description adds only the implicit default wait duration, which is not enough to exceed the baseline for fully documented schemas.

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 (restart) and resource (workload) and immediately defines the semantics: every replica replaced by a fresh one on the same spec, a rolling restart that re-reads secrets and env. This distinguishes it from update_workload and rollback_workload, which would otherwise be plausible confusions.

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 excludes two cases (cron workloads, pointing to start_workload_cron as the alternative; and suspended workloads) and adds a precondition: get approval first. Nothing about when to choose this tool 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?

Adds real behavioral content beyond the annotations: the ~40s readiness wait, the fact that env and other settings are untouched, the 30-day history boundary, and that the running version is replaced requiring approval. Annotations already carry destructive/openWorld/non-idempotent, so this is meaningful added context.

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

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

Front-loaded with the action and mechanism, then constraints, then the approval warning. Dense but nearly every clause carries information; the run-on middle sentence is the only mild cost.

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

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

With an output schema present, rich annotations, and full schema coverage, the description supplies everything an agent still needs: what is preserved, how long the wait is, and the approval prerequisite.

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, including the default behavior of image. The description restates the image default and its first-container targeting but adds no new syntax or edge-case meaning, 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 plus the exact mechanism: restores the previous image of every container whose image changed, or sets the image on the first container. The scope detail ('only images change') makes it distinguishable from restart_workload and update_workload even though they aren't named.

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 context: the 30-day change-history window, the image-override option, and an explicit 'get approval first' warning that flags the operation as a replacement of the running version. It stops short of naming alternatives (restart_workload, update_workload) or stating when-not to use it.

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

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

Annotations declare destructiveHint=true and non-idempotent, but the description goes well beyond them: anything outside Control Plane holding old values breaks, workloads only re-read secrets on restart, generated values are never visible to anyone, and database credentials from add_database retain their own password. These are exactly the consequences an agent needs before invoking a destructive rotation.

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 blast radius are front-loaded, and every sentence carries workflow information rather than filler. It is dense and slightly convoluted in places ('get new random ones now, which nobody sees'), and the preview note is tacked on at the end rather than grouped with the rotation modes.

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, multi-step, two-call workflow, the description covers the full path: dry run, auto-generated rotation, user-supplied rotation, workload restart, and database special-casing. An output schema exists, so return formatting need not be repeated, and nothing material to correct invocation is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantics: preview is a no-op report, userSaved is only valid after a Console save, and 'No input accepts a value' clarifies that no parameter carries secret material. That last point is a meaningful constraint the schema alone does not convey.

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+resource pair ('Replace a secret's values') plus its key side effect ('restart the workloads that use it'), which cleanly separates it from create_secret and the update_* family. An agent can tell what this tool does and what it is not (a plain settings update) 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?

It gives explicit conditions for the two operating paths: generated values rotate immediately, user-supplied values require a Console link and a follow-up call with userSaved: true; preview: true is defined as a no-op dry run. It never names a sibling alternative, so it falls short of a 5, but the when-to-use guidance is concrete.

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 annotations: asynchronous execution and following the command id with get_command, expand rate limit of 4 per volume per 24 hours, shrink constraints and replica restart, snapshot/recovery behavior, and irreversible data loss. These details align with destructiveHint=true and are crucial for safe invocation.

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 action, then organizes command-specific behavior in compact semicolon-separated clauses. Despite its density, every sentence carries safety, rate-limit, or command-selection information with no filler.

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

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

Given 15 parameters, destructive operations, and an output schema, the description covers execution mode, approval requirements, command effects, rate limits, and follow-up via get_command. No essential agent-facing context 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 93%, so the baseline is 3, but the description adds meaningful command-specific semantics for newStorageCapacity, snapshotName, targetLocation, targetVolumeSet, and the destructive copy acknowledgement. Some parameters such as org, zone, snapshotTags, and timeout are left largely 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: run one command on one volume selected by location and volumeIndex. It enumerates the seven command types and distinguishes itself from update_volumeset for other settings.

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 per-command usage guidance, including when to create a snapshot before destructive commands, when to restore or copy, and when to use update_volumeset instead. It also specifies approval requirements before removal or replacement.

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 read-only, idempotent, non-destructive, and closed-world. The description adds a result cap (at most 5 hits), the shape of each hit (excerpt, path, link), and an iterative-search behavior, which are useful beyond annotations. It does not cover rate limits or auth, but those are likely unnecessary for this read-only search.

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 the purpose front-loaded, followed by return details and a practical tip; 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 simple one-parameter search with full schema coverage, output schema, and rich annotations, the description covers purpose, return cardinality/shape, and how to get more detail. Nothing critical is missing.

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

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

Schema coverage is 100% and the only parameter is documented as 'Search query'. The description adds no query syntax, format, or examples beyond the schema, so the baseline 3 is appropriate.

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

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

States a specific verb 'Search' and resource 'Control Plane docs', making the tool's function unmistakable. However, it does not explicitly differentiate from sibling tools that also retrieve information (e.g., get_cpln_skill), so it falls short of a 5.

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

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

Provides a clear iterative usage tip ('For more of a page, search again with terms from it') but does not state when to choose this tool over alternatives or any prerequisites/exclusions. The context is implied by 'Control Plane docs', but there is no explicit guidance on use vs siblings.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, but the description adds genuinely new operational context: each invocation spawns an additional run with real side effects, and user confirmation is expected first. That is the key non-obvious behavior for a repeat-callable mutation. It does not describe failure modes or what the returned run looks like, 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 action and followed by the caution. Every clause carries distinct information with no restatement of the name or title.

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?

Output schema exists so return values need no explanation, and the schema fully documents the 5 parameters. The description covers the trigger semantics and the confirmation requirement. A minor gap is the absence of any guidance versus restart_workload or what to do if the run fails.

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 carries full parameter meaning, including the location/list_deployments cross-reference and containerOverrides shape. The description adds nothing about parameters. Baseline 3 applies when the schema does the work.

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: 'Trigger an immediate run of a cron workload'. An agent can immediately tell this is an out-of-band execution trigger rather than a schedule edit. It does not explicitly contrast with close siblings such as restart_workload or deploy_app, which keeps it from a 5.

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 use conditions: 'when the schedule is suspended or you need an out-of-band execution'. It also adds a prerequisite ('confirm with the user'). No explicit exclusion or named alternative tool, so it stops short of a 5.

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

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

While annotations confirm the tool is destructive, the description provides critical behavioral detail by specifying that it removes 'the resources it created, including volume data.' This clarifies the scope of mutation beyond a simple API 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?

The description is highly efficient. It uses two focused sentences, front-loading the core function and the necessary constraints/distinctions immediately.

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

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

Given the complexity of managing interconnected resources (volumes, databases, etc.), the definition is complete. It covers what the tool does, what it deletes, and when to choose it over alternatives, leaving no critical operational gaps.

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

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

Although schema coverage is 100%, the description adds vital semantic context by identifying the required parameter 'name' as the 'release name'—the unique, immutable identifier of the released instance.

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

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

The description clearly defines the purpose as uninstall a release, specifying the removal of all associated resources and volume data. It achieves a perfect distinction by explicitly stating it should be used instead of delete_resource for install_template creations.

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

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

It provides explicit usage guidance by contrasting itself with the sibling tool delete_resource. The directive 'Use it, not delete_resource, for anything install_template created' is a highly actionable rule for the agent.

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 destructive/openWorld/idempotent, and the description adds real behavior beyond them: the remove-before-add ordering within one write, the identity rule that governs route replacement, and the non-obvious side effect that gvcLink/workloadLink bindings create DNS records the user must provision. The DNS-records warning is exactly the kind of post-condition an agent cannot infer from annotations.

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

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

Three sentences, front-loaded with the mutation surface, then ordering/identity semantics, then the DNS post-condition. Every clause carries information an agent needs; no restatement of the title or schema.

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

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

For a destructive 18-parameter mutation with an output schema and full schema coverage, this description supplies the remaining gaps: ordering guarantees, route-replacement identity, and the DNS-provisioning consequence of binding. 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 coverage is 100%, so the schema already documents each of the 18 parameters including nested TLS/CORS/canary shapes. The description adds cross-parameter semantics the schema cannot express: that addRoutes replaces the route with matching port/prefix-or-regex/host identity, and that ordering of removes vs adds determines the outcome. Marginal value over a 3 baseline, hence 4.

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 ('Update a domain') and immediately enumerates the mutable surface: description, tags, acceptAllHosts/acceptAllSubdomains, certChallengeType, bindings, listeners and routes. That enumeration makes it unmistakably the mutation counterpart to create_domain and distinct from update_gvc/update_workload.

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

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

Gives concrete operational guidance: removals apply before additions in a single write, and 'removeRoutes plus addRoutes changes a route's path or host' tells the agent exactly how to achieve a rename. It also tells the agent to re-read status.dnsConfig after binding. It stops short of naming when to prefer create_domain or how to scope with org, but usage context is otherwise 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 flag destructiveHint=true, but the description goes well beyond them: it distinguishes MERGE families (scalars, tags, env, pullSecretLinks, addLocations) from REPLACE families (loadBalancer, keda, tracing, sidecarEnvoy, locationOptions, locationQuery), warns that partial nested objects silently drop sub-fields, and states that placement/endpoint changes can redeploy workloads or affect public availability. That is exactly the context an agent needs before a destructive 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?

Front-loads purpose, then the merge/replace contract, then the side-effect warning; for 25 parameters the length is justified and no sentence is filler. Sentences are long and clause-dense, which slightly hurts 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 25-parameter destructive mutation with nested objects, the description covers mutation semantics, deletion paths, side effects, and the domain-tool boundary; an output schema exists so return values need no explanation. Minor gaps remain around required gvcName/org scoping and whether a call with no partial fields is a no-op.

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

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

With 100% schema coverage the baseline is 3, but the description synthesizes a rule the schema states only piecemeal: which parameter groups merge, which replace wholesale, and which remove* flags delete an optional block entirely. It also correctly notes aliasWorkloadLink is inert while the target workload is suspended - a detail beyond a typical schema blurb.

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?

Declares a specific verb (update) and resource (GVC), then defines what a GVC is - 'the deployment scope that sets which locations its workloads run in' - so an agent unfamiliar with the domain can place it. It never explicitly contrasts itself with create_gvc or update_workload, so sibling discrimination is left partly to inference.

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 one class of change elsewhere: 'Custom domains are configured with the Domain resource (create_domain), not on the GVC.' That is a real exclusion with a named alternative. It gives no general when-to-use framing (mutate an existing GVC vs. create_gvc for a new one), so it falls shorted of a 5.

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