Ployz

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

'Staged' and 'This call asks no human' add real context beyond the annotations: the removal is queued rather than immediately applied, and no approval gate exists, which also explains why destructiveHint is false despite a delete-shaped tool. What is not disclosed is the effect on workloads currently mounted to the Config, which matters for a full-Config removal.

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

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

Three short sentences, front-loaded with the two removal scopes, then the staging and approval facts. No sentence is 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 five-parameter removal tool with no output schema, the definition covers the modes, staging semantics, and the lack of human approval. It leaves open how a staged removal is committed and what happens to running mounts on full-Config removal, which is a meaningful gap for a destructive operation.

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

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

Schema coverage is 80%, so the schema already documents file, project, environment, and expect_revision. The description corroborates the file-omission behavior but adds no format, constraint, or revision-conflict detail beyond the schema, which is the expected baseline here.

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

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

The description names a specific verb (Remove) and both scopes it operates on: a single file inside a Config, or the entire Config plus its mounts. That is enough to separate it from config_write and config_rename without opening a schema. It stops short of a 5 because no sibling is named explicitly.

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

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

The dual mode is stated (file vs. whole Config), and the schema reinforces that omitting 'file' removes everything. However, there is no guidance on when to prefer this over alternatives such as discard, config_write, or a subsequent deploy to apply the staged change, so usage 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?

Adds real context beyond the annotations: associated files and mounts are preserved, the change is staged rather than immediately applied, and no human approval gate is involved. These are meaningful behavioral traits (side-effect scope, timing, approvals) that the readOnly/destructive hints alone don't convey.

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

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

Four short fragments, front-loaded with the action, with no wasted words. The telegraphic style ('Staged. This call asks no human.') is slightly cryptic but efficient and each sentence earns its place.

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

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

Covers the core rename plus the two most important behaviors (preservation and staging), but with five parameters and no output schema, an agent still lacks guidance on what 'staged' implies next (deploy step?) and how expect_revision conflicts surface. Adequate but with clear gaps.

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

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

Schema description coverage is 80%, so the schema already documents 'to', 'project', 'environment', and 'expect_revision'. The description adds nothing about the 'config' parameter or the revision-conflict semantics, so it neither compensates nor detracts.

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 ('Rename a Config'), which cleanly separates it from config_remove and config_write. It doesn't explicitly name which sibling to use instead when the intent is something other than renaming, but the action is unambiguous.

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

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

There is no explicit when-to-use or when-not-to-use guidance, and no named alternatives among the many config/service/project rename siblings. Only 'Staged' hints at a workflow context, leaving the agent to infer that this is the right tool.

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

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

Annotations only declare readOnlyHint=false and destructiveHint=false; the description adds real behavioral context beyond that — the write is 'Staged' (not applied immediately) and 'asks no human' (no approval gate), plus the ${{ SERVICE.KEY }} interpolation rule for file contents. It stops short of saying what 'staged' means downstream (when it reaches the running workload) or whether existing files are overwritten or merged.

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 compact sentences front-loading the main effect before the optional mount and the interpolation note. The clipped fragments ('Staged. This call asks no human.') are terse but each carries information; minor cost in readability rather than waste.

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

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

For a 10-parameter mutation with a nested files object and no output schema, the description covers the critical unknown behaviors (staging, no approval, variable interpolation, mount target). The remaining gap is write semantics on re-write — replace vs merge of file contents — which matters for repeated calls.

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 80%, so most parameters (config, service, path, mode, expect_revision) are already documented. The description contributes the one genuinely new piece — that file contents may interpolate ${{ SERVICE.KEY }} — but says nothing about uid/gid/mode application or the concurrency semantics of expect_revision. Baseline 3 fits given the schema carries most of the load.

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

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

Specific verb+resource: 'Write files into a Config, creating it if needed, and optionally mount it into a Service at a directory' tells an agent exactly what happens and the two effect targets (Config and Service mount). It is naturally distinct from siblings like config_remove/config_rename, though it never names them.

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?

Implies usage through 'creating it if needed' and the optional mount pairing with service/path, and 'This call asks no human' hints at the approval-free path. But there is no explicit when-to-use/when-not vs other tooling (e.g. deploy for applying staged config), leaving routing to inference.

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

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

Goes well beynd the annotations: it discloses that pruning removes Services unless no_prune, that Volumes may be destroyed (accept_volume_loss), that the call is asynchronous and returns before completion, and that every deploy requires human approval.

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

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

Front-loaded with the core action followed by scoping caveats and async/approval behavior. Each sentence carries weight, though the final sentence slightly repeats the earlier approval point.

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 10-parameter destructive mutation with no output schema, the description covers the destructive, async, and approval traits thoroughly. It omits return shape and idempotency, which are left to the schema.

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

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

With 100% schema coverage the baseline is 3; the description adds cross-parameter meaning by tying no_prune to pruning, skip_deploy to a save, and approval to the approval_required retry flow.

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 ('Deploys everything staged') and explains the staging model, but it never names a sibling alternative (e.g., discard or deployment_start) to differentiate itself.

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 specifies when to use skip_deploy (save instead of deploy) and no_prune (keep running Services), and explains the approval flow. It stops short of explicit when-not guidance or naming alternatives.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false. The description adds useful behavioral context by noting that changes already applied to servers remain and that no human approval is requested, though it does not explain immediacy, status effects, or reversibility.

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

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

The description is three short sentences with the core action front-loaded and no wasted text. Each sentence contributes distinct information about the operation, its persistence effect, and approval behavior.

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 cancellation tool with fully described parameters and no output schema, the description covers the essential action, partial-effect behavior, and approval model. It could say more about resulting deployment status, but the core calling information is present.

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

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

Schema description coverage is 100%, and the schema itself documents project, deployment, and environment. The description adds no parameter-specific meaning beyond what is already in the schema, so the baseline of 3 is appropriate.

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

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

The description states a specific verb and resource: cancel a Deployment, scoped to one that is queued or running. It is clear, but it does not explicitly differentiate this tool from nearby siblings such as deployment_retry, deployment_start, or discard.

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

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

The phrase 'queued or running Deployment' implies the applicable state for use, but the description does not state when not to use it, nor does it name alternatives or prerequisites. Usage is reasonably inferable but not explicitly guided.

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 cover the safety profile (readOnlyHint true, destructiveHint false), and the description adds real context beyond them: results are ordered newest first, entries include status, and the call is non-interactive ('asks no human'). It omits pagination behavior, which matters given cursor/limit, keeping it 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?

Two tight, front-loaded sentences with no padding. The second sentence is slightly cryptic in phrasing but still adds information an agent can act on.

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 list tool with no output schema, the description conveys ordering and per-item content, but leaves pagination (limit/cursor) and the full record shape unexplained, which an agent needs to call it reliably.

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 only 50% – project and environment are documented, but limit and cursor carry no description anywhere. The description does not compensate, saying nothing about page size caps or cursor continuation despite 'newest first' implying a paged order.

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 the resource (an Environment's Deployments) and the ordering (newest first) plus what each entry carries (status), which distinguishes it from deployment_show by implication. However, it never states an explicit verb like 'list' and never names deployment_show as the single-record alternative.

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

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

'This call asks no human' is a hint that it will not block on approval, but there is no explicit when-to-use or when-not, and no routing vs deployment_show or the mutating siblings (deploy, deployment_start, deployment_cancel).

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 readOnlyHint=false, so safety is partly covered. The description adds real behavioral context beyond that: every redeploy is human-approved and the call may pause to return an approval_required-style response, matching the approval parameter. It omits, however, any mention of the volume-loss risk implied by accept_volume_loss.

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, front-loaded sentences with no wasted framing. The approval message is stated twice in slightly different words ('A human approves every redeploy' / 'May stop to ask a human to approve'), which is minor redundancy rather than bloat.

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 destructive tool with no output schema, the approval flow is well explained, but the definition leaves out what a successful retry returns, what stays versus changes on the target environment, and the volume-loss caveat. It is adequate but not complete enough for an agent to act without reading the schema closely.

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 57%, leaving version, request_key, and accept_volume_loss undocumented in the schema. The description clarifies the semantics of the deployment parameter (older versus newer, rollback effect) but says nothing about accept_volume_loss, which is the most consequential parameter for a destructive retry.

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 verb phrase 'Ship an ended Deployment's commit and settings again' names both the action (redeploy) and the resource, with the 'ended' constraint that separates it from deploy/deployment_start. It does not explicitly name the sibling it supersedes, but an agent can still tell it apart from a fresh deploy without reading 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?

'An older one rolls back newer ones' gives a concrete rule for which deployment to choose, which is genuinely useful selection guidance. However, it never states when to prefer deployment_start or deploy instead, nor does it spell out prerequisites (e.g., project/environment must exist).

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

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

Beyond the readOnly and non-destructive annotations, the description discloses meaningful behavior: it can wait for completion, reports service outcomes, omitted or config-breaking variables, warnings, failed step/server, and returns redacted log excerpts. 'This call asks no human' also signals that no approval workflow is involved.

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 definition is front-loaded with the core purpose and scope, then follows with the response details and wait behavior. It is dense but every sentence adds relevant information without repetition.

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

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

With no output schema, the description compensates by describing the returned status, service outcomes, warnings, failure details, and redacted logs. Combined with full parameter schema coverage and read-only annotations, it gives an agent enough to call the tool correctly.

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

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

Schema coverage is 100%, so the parameter meanings are already documented. The description still adds useful semantics by clarifying that the deployment number is optional and defaults to the latest, and that wait_seconds makes the call wait for the deployment outcome.

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 identifies a specific resource ('One Deployment') and a precise scope ('the latest unless you name its number'), then enumerates what the response covers. This clearly distinguishes it from the sibling deployment_list, which handles collections rather than a single deployment.

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

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

It states a clear usage context: inspect a single deployment, defaulting to the latest, and optionally wait for completion. It does not explicitly name deployment_list as the alternative for listing deployments, so the when-to-use guidance is strong but not fully explicit about alternatives.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=true, so the write/destructive nature is covered. The one genuinely additive piece of context is 'This call asks no human' — it discloses that approval gates are bypassed, which matters for a destructive action. It does not say what happens to a running or already-started deployment, or whether the action is reversible.

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 very short sentences, zero filler, and the action plus its key property (no human gate) are front-loaded. Nothing could be removed without losing information.

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

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

For a destructive, immediate mutation with no output schema, the description is thin: it does not describe the resulting state, what happens on a non-queued deployment, or any failure behavior. The approval-bypass note is valuable, but an agent still has to infer the post-call outcome.

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

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

Schema coverage is 100%; each of the three optional parameters documents its own 'Omit for the latest / the one you are in' default, so the schema carries the burden. The description adds no parameter-level meaning beyond what is structured, which is the baseline expectation.

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: handing a *queued* Deployment to a runner, which distinguishes it from siblings like deployment_cancel, deployment_retry, and deployment_show. The 'queued' qualifier is what makes the action unambiguous, though the description never names an alternative tool outright.

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?

'Hand a queued Deployment' implies a precondition (the deployment must already be queued) and the word 'now' implies immediacy, so usage is inferable. However, it never says when to prefer this over deployment_retry or the generic deploy, nor what to do if the deployment is not queued.

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

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

The description adds useful behavioral context by saying 'This call asks no human,' which tells the agent no approval step is required. With destructiveHint=true already indicating danger, it does not go further to explain irreversibility or what exactly is lost when staged changes are returned.

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 short and front-loads the core action. The second sentence is somewhat cryptic, but the overall structure is efficient and has little wasted language.

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

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

For a destructive mutation with no output schema, the description covers the basic revert semantics and the absence of human approval. It still leaves a gap around consequences, especially whether discarded staged changes are permanently lost and how conflicts with expect_revision are handled.

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 parameter descriptions already explain config, volume, project, service, environment, and expect_revision. The description adds some selection nuance with 'one Service, Volume or Config' and 'A named one differing only from saved returns to saved,' but it does not clarify project, environment, or revision behavior beyond the schema.

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

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

The description states a specific action and object: returning staged changes, or one Service, Volume or Config, back to deployed/saved state. It is clear enough to identify the operation, but it does not explicitly distinguish itself from siblings such as deploy or deployment_cancel.

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 staged-versus-deployed framing implies when to use it, and the schema note about omitting service/volume/config clarifies scope. However, there is no explicit guidance on when to choose discard over alternatives or when not to use it.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is known. The description adds that the call 'asks no human', which is useful behavioral context, but it does not describe search result format, pagination, or what a page read returns. With annotations covering safety, this is adequate but not rich.

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

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

The action is front-loaded in the first sentence, and the long page list is justified by providing concrete retrievable paths. The only slightly odd sentence is 'This call asks no human', but it is short and does not distract. Overall it is appropriately sized for a documentation retrieval tool with enumerated pages.

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 documentation tool with one parameter and no output schema, the description gives enough context to call it correctly: search mode, read-by-path mode, and the full set of known page paths. It does not explain return shape or search ranking, but no output schema exists and those details are less critical for invocation.

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

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

Schema coverage is 100% and the parameter description already says 'A question, or a page path ending in .md.' The tool description adds value by listing the valid page paths, effectively serving as an enum of supported documents, which goes beyond the schema's generic string field.

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

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

The description uses specific verbs ('Search' and 'read') and a clear resource ('the Ployz docs'), and explicitly distinguishes the two modes by query type. It also enumerates page paths, so an agent can immediately tell whether it can retrieve a known page or search generically.

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

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

It states the two usage modes: pass a question to search, or pass a page path ending in .md to read a specific page. The extensive page list further clarifies when the read-by-path mode is applicable. No explicit exclusion or sibling-based routing is needed because no equivalent sibling exists.

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

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description discloses three non-obvious traits: the change is staged rather than immediately live, a custom hostname returns DNS records the member must act on, and "This call asks no human" – useful given the presence of approval-related siblings. It stops short of covering conflict/error behavior or reversibility via domain_remove.

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 short sentences, front-loaded with the core action and mode split, followed by staging behavior, the DNS return, and the no-approval note. No sentence is filler and the most important constraint leads.

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

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

There is no output schema, and the description compensates by saying a custom hostname returns DNS records to create. For a 7-parameter mutation with annotations present, the main remaining gap is what happens on failure or when a domain already exists on the service.

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 86% schema description coverage, the schema already documents port, prefix, hostname, project, environment and expect_revision well, including the prefix/hostname mutual exclusion. The description only restates the hostname-vs-generated distinction and adds no syntax, format, or default details beyond it, 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?

The description gives a specific verb+resource ("Give a Service a public domain") and immediately distinguishes the two modes it supports: a member-owned hostname or a Ployz Cloud generated one under the cluster domain. Against siblings like domain_update, domain_remove and domain_check, the additive nature is unambiguous.

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

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

It supplies operational context ("Staged until the next Deploy") and notes the DNS-record consequence for custom hostnames, which implies when the call is appropriate. However, it never names an alternative or states a when-not – nothing tells the agent to prefer domain_update for an existing domain or domain_check to verify one. Usage is implied, not guided.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds real context beyond them: 'This call asks no human' tells the agent there is no confirmation gate, and it previews the response payload (status, reason, remaining DNS records), which matters since no output schema exists.

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 compact clauses with the action front-loaded and the non-interactive guarantee placed last where it is most actionable. The phrase 'and why' is slightly cryptic about what question is being answered, a minor cost to an otherwise efficient 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?

Adequate for a read-only 3-param tool with no output schema: it tells the agent what comes back and that no human approval is needed. It leaves the project/environment scoping and any domain-not-found or auth failure behavior unaddressed, which is a noticeable gap given two undocumented parameters.

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

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

Schema description coverage is only 33%: 'domain' is documented in the schema, but 'project' and 'environment' have no description anywhere, only a regex pattern. The description says nothing about how those two scoping parameters interact with the hostname, so it fails to compensate for the coverage gap.

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 ('Check') and resource ('domain') and enumerates what the check returns: status, reason, and pending DNS records. That is enough to separate it from the mutating siblings domain_add/domain_update/domain_remove, though no sibling is named explicitly.

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

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

'Check a domain now' implies an on-demand verification, most plausibly after adding or updating a domain, but the description never states when to reach for it versus domain_add or domain_update, nor any prerequisite (e.g. the domain must already exist). Usage 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?

With annotations only saying readOnly=false and destructive=false, the description adds real behavioral context: a serving domain normally requires human approval, while this call executes without a human. That materially changes how an agent should treat the call. It does not explain reversibility or what happens to the detached domain, keeping it below 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 short sentences, front-loaded with the action, followed by the one nuance that matters. No filler or repetition.

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

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

For a 4-param removal tool with a full schema and no output schema, the description covers the key behavioral wrinkle (staged approval vs immediate action). It omits what happens after removal or failure modes, but nothing critical to invoking 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 domain/project/environment/expect_revision are already documented in the schema. The description adds no parameter-level detail beyond that, so baseline 3 is appropriate.

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

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

"Take a public domain off its Service" gives a concrete verb (remove/detach) and resource (public domain), clearly distinct from the add/update/check domain siblings. It stops short of naming an alternative explicitly, so it lands at clear-but-not-differentiating.

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 staging note implies when the call applies (removal of a serving domain is gated to human approval at next deploy; this call is the immediate path), but it never states when to use this versus domain_update, domain_add, or the approval flow. Usage is inferable rather than spelled out.

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

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

Annotations only declare readOnlyHint=false and destructiveHint=false; the description adds two genuinely useful traits beyond them — that the change is staged rather than applied immediately, and that no human approval gate is involved. It leaves open what 'staged' concretely means (whether it takes effect on apply, on next deploy, or can be discarded).

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, front-loaded sentences with no filler; the mutable surface comes first and the behavioral caveats follow. 'Staged.' is the only sentence that is terse to the point of being cryptic rather than economical.

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

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

For a 6-parameter mutation tool with no output schema, the description covers what changes and the no-approval/no-destructiveness profile, but says nothing about what a staged change produces, how it is later applied or abandoned, or what expect_revision failure looks like. Complete enough to call, not complete enough to predict the outcome.

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

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

Schema coverage is 100%, so every parameter is already documented in the schema, and the description correctly signals the two interesting ones (prefix, port). It adds no format or interaction detail — notably nothing about how expect_revision or the project/environment pair should be supplied — so it stays at the baseline.

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

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

It names a specific verb (Change) and the exact mutable aspects (a generated domain's prefix, or the port any domain reaches), which cleanly separates it from the add/remove siblings in the domain_* family. It stops short of naming those siblings explicitly, but the resource and scope are unambiguous.

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

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

The phrasing implies this is the tool for modifying an existing domain rather than creating or deleting one, but there is no explicit when-to-use versus domain_add / domain_remove, and no stated prerequisites. The only guidance given is the behavioral note that the call is staged and needs no human approval.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, and the description usefully adds that the operation executes with no human approval. What it omits is consequential: whether turning it off tears down existing per-PR Environments, and what the response contains. For a toggle that may shave PR environments, that gap matters.

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 short sentences, front-loaded with the action and scope, with no filler. The no-approval note is the only extra and it earns its place.

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

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

The schema is rich and there is no output schema to explain, so the structural side is covered. Still, the description leaves the effect of disabling undefined and says nothing about return values or the expect_revision conflict behavior, which an agent needs before flipping this switch.

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

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

Schema description coverage is 100%, so all five parameters are already self-documenting, including the boolean semantics of 'enabled' and the meaning of expect_revision. The description adds no parameter-level detail beyond 'built from this Environment', 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 pair (turn on/off) and a specific resource (an Environment per GitHub pull request) that is clearly different from environment_setup, environment_protect, and environment_remove. It is not fully crisp: 'Environment per GitHub pull request, built from this Environment' requires knowledge of the product's Environment concept, and the tool's core effect is described only in toggle terms.

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?

'built from this Environment' implies the prerequisite that an existing Environment must exist, and 'This call asks no human' signals the toggle is unapproved/automatic. However, no sibling is named and no when-not/alternative is given (e.g. environment_protect vs this), so the agent must infer selection on its own.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the mutation/safety profile is partly covered. The description adds genuinely new behavioral context the annotations lack: the tool 'May stop to ask a human to approve,' signalling a mid-call approval gate that pairs with the approval parameter. It doesn't spell out permission requirements or reversibility beyond the protect/unprotect framing.

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, front-loaded sentences with no filler: the action, the scope exclusion, and the approval caveat. 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 reversible settings toggle with no output schema and full schema description coverage, the description supplies the essentials: scope, exclusions, and the human-approval behavior. Minor gaps remain around permissions/idempotency, but nothing critical to invoking 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 schema already documents project, environment, approval, and protected (including the true/false semantics). The description only paraphrases protect-vs-unprotect and adds no format or constraint detail beyond the schema, so baseline 3 applies.

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

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

States a specific verb and resource ('protect a Project's own Environment ... or unprotect it') and immediately bounds scope by excluding Branches and PR Environments, which distinguishes it from siblings like environment_pr and environment_remove. An agent can tell what it does 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 a clear when-not ('Branches and PR Environments cannot be Protected') and hints at the approval flow, so the agent knows this applies only to a project's own Environment. It stops short of naming an alternative sibling to use for branches/PR envs, so no explicit routing.

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

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

Beyond the annotations, the description discloses that volumes and their data are destroyed (scope of data loss), the precondition/blocking semantics, the ambiguous async outcome ('removed' or 'removing'), and that the call may interrupt for human approval. That approval interrupt behavior is not captured anywhere in the schema or annotations and is exactly what an agent needs to handle the approval parameter.

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 short, front-loaded sentences with almost no filler; the destructive scope leads. Slight terseness ('holds its part') costs a little clarity, 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 destructive, 7-parameter tool with no output schema and only 14% schema coverage, the description covers destruction scope, async results, and the approval flow well, but leaves the non-trivial multi-value parameters (every_copy, accept_volume_loss, wait_seconds) undocumented anywhere.

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

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

Schema description coverage is only 14%, with just 'approval' documented. Six parameters (project, version, every_copy, environment, wait_seconds, accept_volume_loss) are unexplained, and while the cascade-delete wording loosely contextualizes accept_volume_loss, the description never explains every_copy, wait_seconds, or how to resume after approval.

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 (delete an Environment) and immediately scopes the operation to its cascade (its Volumes and their data). This is distinguishable from siblings like environment_show, environment_protect, or volume_remove 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?

The precondition 'once no server runs it' gives real when-to-use guidance and the unresponsive-server clause explains a blocking case. However, no alternative is named (e.g., server_remove or volume_remove first), so the agent must infer the deletion workflow.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The phrase 'This call asks no human' adds genuinely useful context that the call is non-interactive and needs no approval, but nothing is said about what the response contains or how omissions of optional params are handled.

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 short sentences with no wasted text, and the prerequisite list is front-loaded. 'This call asks no human' is slightly cryptic but is doing real work in one clause.

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-param read-only check with no output schema, the description should hint at the shape of the answer (a list of missing items?) and what happens with no arguments. It names the categories of prerequisites but leaves the return structure and default scoping unstated.

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

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

Schema coverage is 100% and both parameters are documented there, so baseline 3 applies. The description adds nothing about project/environment semantics, and notably does not clarify behavior when both are omitted (required=0), which would have been valuable.

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 conveys the intent indirectly: it reports outstanding prerequisites (servers, GitHub connection, cluster domain) before a deploy. But there is no clear verb+resource construction such as 'list' or 'check,' and 'environment_setup' could be misread as a mutation tool. An agent must infer the operation from the enumerated items.

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

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

No guidance on when to call this versus siblings like environment_show, deploy, domain_check, github_ls, or server_show, which all touch the same prerequisite surface. The deploy context is implied but no exclusions or sequencing advice are given.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description does add one genuine behavioral fact beyond annotations — "This call asks no human," i.e. no approval prompt — and enumerates the returned content, but says nothing about pagination, size, or cost of the call.

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

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

Two short sentences with no padding; the returned-content list is front-loaded and the approval note is appended. The list is dense but each item conveys 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?

With no output schema, the description usefully enumerates what comes back, which is its main contribution. But it omits how optional project/environment parameters affect scope and what happens when they are omitted, which is the decision an agent most needs to make before calling.

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

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

Schema coverage is 100% and both parameters are documented there with patterns, so the baseline is 3. The description never mentions project or environment at all, leaving the schema to carry semantics entirely.

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 verb is only implied by the fragment "Where you are"; the noun list (Projects, Environments, Services, Volumes, Configs, Staged count, broken references, latest Deployment) makes clear it is an overview/status read of the current context. However, nothing distinguishes it from siblings like service_inspect, environment_pr, or deployment_show, so an agent must infer its role as the top-level snapshot.

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

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

No statement of when to call this versus alternatives, no prerequisites, and no guidance on whether the optional project/environment parameters must be supplied or what the default scope is. The only usage-adjacent note is "This call asks no human," which speaks to approval flow rather than invocation choice.

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

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

Annotations already establish readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The sentence 'This call asks no human' adds genuinely new behavioral information: it signals no interactive OAuth/consent prompt will block execution, which matters when an agent is chaining calls. It also enumerates the informational payload, partially compensating for the missing output schema.

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

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

Two short sentences, front-loaded with the payload, so it is efficient. However, phrasing like 'the page that connects more' is cryptic and reads as a fragment, costing clarity for the space it saves.

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

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

With no output schema, the description carries the burden of describing results, and it does name the three things returned (connected status, readable repos, connection page). It stops short of stating the return shape or what an unconnected state looks like, which is a modest gap for a simple zero-parameter probe.

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 is nothing for the description to disambiguate; baseline 4 applies. No misleading parameter talk is present.

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 enumerates what the call reports (connection state, readable repositories, a link to connect more), so the subject matter is clear, but it never uses a verb and never says explicitly that this is a read-only status probe. It also does not distinguish itself from the sibling `github_ls`, which plausibly also surfaces repositories, leaving ambiguity about which one to call for repo data.

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

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

No when-to-use statement, no preconditions, and no mention of `github_ls` or any other sibling as an alternative. The agent must infer that this is the connectivity check before listing repos.

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

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

Annotations already establish that this is a read-only, non-destructive operation, and the description adds useful context beyond that: a 64 KB cap on file reads and 'This call asks no human', which matters given the sibling approval tools. It doesn't say whether directory listings are truncated or paginated, which is the remaining 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?

Two short sentences, front-loaded with the primary capability and its size constraint. Nothing is padded or repeated from the name.

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

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

There is no output schema, so the description ideally should say what a directory listing returns (file paths only, or names plus metadata). That omission is minor against annotations that already convey the safety profile and a schema that documents every parameter.

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 (ref, path, match, repository) are already documented in the schema, including the glob syntax and default branch behavior. The description reinforces the path semantics but adds no syntax or format detail beyond what the schema provides, so baseline 3 applies.

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

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

States a specific verb and resource ('List a connected GitHub repository's files') and covers both modes of operation (list a directory, read a single file). No sibling tool overlaps with this capability, so the agent can select it unambiguously.

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?

Explains the list-vs-read distinction through the path parameter ('List ... at a path, or read one file') and notes 'Omit for the top', which gives clear usage context. It stops short of explicit when-not guidance, but there is no competing sibling that would need routing away from.

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

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

The description adds substantial behavioral context beyond annotations: it clarifies that changes are staged (not applied immediately), that the next deploy requires human approval if removals occur, that sealed values and volume data are not restored, and that this call itself asks no human. This is exactly the kind of nuance an agent needs for a non-read-only, non-destructive staging operation.

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

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

Four sentences, each earning its place: what it does, staging and human-approval behavior, what is not restored, and that no human is asked during the call. Front-loaded and waste-free.

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 six-parameter staging tool with no output schema, the description covers the critical behavioral traits (staging, human interaction, non-restored items) well. It could be slightly more complete by explicitly routing against sibling tools like 'discard' or 'review', but no essential calling information is missing.

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

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

Schema description coverage is 100%, so all six parameters are well documented in the schema. The description mentions 'undo' but adds no syntax or meaning beyond what the schema already provides. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

The description states a specific action: staging a Saved revision's whole configuration, with an undo variant. It clearly conveys the verb and resource, though it doesn't explicitly distinguish from sibling tools like 'review' or 'discard'.

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 explains the two modes (whole configuration vs. undo only) but gives no explicit guidance on when to choose this tool over alternatives, and no sibling tools are named for comparison.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds only the "pending" scope qualifier and says nothing about result ordering, pagination, or volume for a list operation, so it adds modest value beyond structured data.

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

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

A single short sentence with the resource scope front-loaded and zero filler. Nothing could be trimmed without losing meaning.

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

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

For a no-parameter, read-only list tool the description is essentially sufficient. With no output schema, a brief note on what the listing returns (or whether it is paginated) would have closed the remaining gap.

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

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

The tool takes zero parameters and the schema is an empty object, so there is nothing for the description to disambiguate. Baseline 4 applies; no parameter semantics are missing.

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 a precise resource scope ("the Organization's pending approvals"), which is clearer than a generic list. It does not, however, distinguish itself from the sibling org_approval_show, leaving the agent to infer the ls/show split from naming convention 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?

The description gives no when-to-use context, no prerequisites, and no mention of the alternative org_approval_show for inspecting a single approval. The "pending" qualifier hints at scope but is not framed as usage guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds useful content context by saying the response shows 'what the plan destroys and how it was answered', but it does not cover auth/permission requirements or whether the answer data can be incomplete or pending.

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 short sentence, front-loaded with the verb and resource, with the return-content detail appended. Every clause earns its place and there is no filler.

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

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

With one required parameter, read-only annotations, and no output schema, the description's hint about return content ('what the plan destroys and how it was answered') covers the main unknown. It is nearly complete for a simple lookup, missing only permission/error context.

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

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

There is a single 'id' parameter with 100% schema description coverage, so the schema already carries the semantics; per the baseline rule this is a 3. The description adds no format, source, or retrieval hint (e.g., where the id comes from) beyond the schema.

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

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

The description gives a specific verb ('Show') and resource ('one approval'), and the phrase 'one approval' implicitly separates it from the sibling org_approval_ls. It does not explicitly name the list sibling, but an agent can still tell the singular-fetch role from the surrounding tool names.

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?

Usage is only implied: fetching a single approval by id versus listing approvals. There is no explicit when-to-use/when-not statement, no prerequisites, and no named alternative, so the agent must infer the routing from the 'one' qualifier.

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 this a safe read (readOnlyHint=true, destructiveHint=false), so the description is not burdened with the safety profile. What it usefully adds is the 'pending' scope, implying accepted/revoked invites are excluded. It says nothing about pagination, ordering, or return fields, so it adds only modest context beyond the annotations.

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

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

A single front-loaded sentence with no filler; the resource and the 'pending' qualifier both carry information. There is nothing redundant given the empty schema and the annotations.

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

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

For a zero-argument read-only list tool this is nearly adequate, but there is no output schema, and the description never hints at what a returned invite contains (invitee, role, date, status). It also omits ordering/pagination behavior. Those gaps are minor but real.

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 per the baseline there is no parameter surface for the description to clarify. The 100% schema coverage with an empty properties object is consistent with the description. Nothing about arguments needs explaining.

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 gives a specific verb (List), resource (Organization's invites), and a scoping qualifier (pending). That distinguishes it in practice from org_invite_revoke and org_member_ls, which operate on other aspects of invites/membership. It stops short of explicitly naming any sibling, so it is clear but not maximally differentiated.

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?

There is no when-to-use or when-not-to-use guidance, and no alternative is named. An agent can infer that it is for checking outstanding invitations, but nothing tells it whether to prefer this over org_member_ls or how it relates to org_invite_revoke after acceptance.

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 readOnlyHint=false, so the safety profile is covered. The description usefully specifies the concrete effect (the invite link stops working), but says nothing about permissions, idempotency, or what happens if the invite was already accepted.

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

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

A single tight sentence with the verb and the consequence 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?

For a two-parameter, annotation-covered mutation with no output schema, the description covers the core action and effect. It omits the approval retry flow (covered in the schema) and edge cases like already-accepted invites, but nothing essential to calling it 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% — both 'invite' (id or email) and 'approval' (approval ID after approval_required) are fully documented in the schema. The description adds no parameter detail, so the baseline 3 applies.

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

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

States a specific verb (revoke) and resource (pending invite) and even the observable effect (the link stops working). The word 'pending' scopes it away from member-removal siblings like org_member_rm, though it doesn't explicitly name an alternative.

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

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

The qualifier 'pending invite' implies the condition under which this tool applies (not accepted invites, not existing members), which is implicit usage guidance. However, no explicit when-to-use note or alternative (e.g. org_member_rm for accepted members, org_invite_ls to find the invite) is offered.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description usefully indicates the returned content (members plus their roles) in the absence of an output schema, but omits pagination behavior and whether the listing is filtered or complete.

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

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

A single front-loaded sentence naming verb and resource with no filler. Every word earns its place.

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

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

For a parameterless read-only list tool with annotations covering safety, the description supplies what is returned, which is the key missing piece since there is no output schema. It could still note pagination or scope limits, but nothing critical 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?

The tool takes zero parameters, so the schema has no semantics to describe and the baseline is 4. The description correctly implies an unfiltered, parameter-free listing.

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 (the Organization's members and their roles), which an agent can distinguish from siblings like org_member_rm (removes a member) and org_member_role (changes a role). It does not explicitly name those siblings, so it stops short of full differentiation.

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

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

The description says nothing about when to use this tool versus org_member_role, org_invite_ls, or org_approval_ls, nor about prerequisites such as org context or permissions. Only the verb 'List' implies its usage.

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

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

Annotations already flag destructiveHint=true and readOnlyHint=false, but the description adds concrete impact that annotations cannot convey: organization tokens stop working and devices lose server access. It does not state whether the removal is reversible, whether it requires confirmation beyond the approval token, or how long revocation takes to propagate.

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 short clauses with zero filler; the core action plus its consequence are front-loaded and the second sentence exists only to convey impact. Nothing redundant with the schema or annotations.

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

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

With no output schema, the description covers the action and its side effects, and the schema covers both parameters including the approval-retry protocol. Missing only permission requirements and reversibility, which an agent would likely need for a destructive operation.

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

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

Schema description coverage is 100%, with both 'member' and the retry-only 'approval' parameter fully documented in the schema itself. The description adds no syntax, format, or disambiguation detail beyond that, 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 ('Remove a member') that an agent can immediately distinguish from org_member_ls and org_member_role via the name's org_member_ prefix. The consequence sentence reinforces what the operation is, though it never explicitly says the member belongs to the organization.

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

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

No guidance on when to choose this over siblings such as org_member_ls or org_invite_revoke, and no prerequisites (e.g. required admin role, whether the member must be invited first). The only usage-adjacent information is the approval flow, which lives in the schema's parameter description rather than the tool description.

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

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

Annotations declare readOnlyHint=false and destructiveHint=false, so the safety profile is already covered. The description adds an authorization constraint beyond that, which is genuine value, but it says nothing about the effect on the member's prior role, reversibility, or notifications for a mutation tool.

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

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

Two short sentences, zero filler, with the action and the permitted values front-loaded and the permission caveat second. Nothing could be cut without losing 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 simple three-parameter mutation with no output schema, the description covers what the tool does and the key authorization rule, while the schema documents the approval retry path. It is nearly complete; only the success/return behavior and failure handling are unstated.

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 all three parameters (including the approval retry flow) are documented in the schema itself. The description merely repeats the role enum already present in the schema, adding no new parameter 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 ('Change a member's role') plus the exact target values (owner, admin, member), so an agent can tell this apart from org_member_rm and org_member_ls by inference. However, it never names or contrasts a sibling explicitly, which is what the top score requires.

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?

'Only an owner can make or remove an owner' gives a real precondition that determines whether the call will succeed. It stops short of stating when to prefer this over alternatives or what to do on failure, so it is clear context without exclusions.

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

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

Annotations already mark it as non-read-only and non-destructive. The description adds useful behavioral detail beyond annotations: it creates a default Environment named "production," starts with no Services, and "asks no human," indicating no approval prompt.

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

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

Three short sentences, front-loaded with the core action and followed by key side effects. There is no wasted wording.

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

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

For a simple create tool with fully documented parameters, the description covers the important creation side effects and approval behavior. It does not describe the return value, but no output schema exists and the core invocation needs are met.

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema. The description does not add parameter-specific meaning beyond what the schema provides.

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

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

The description gives a specific verb and resource: "Create a Project." It also states the created scope (default Environment "production" and no Services), which distinguishes it from siblings like project_rename, project_remove, environment_setup, and service_add.

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 does not explicitly say when to use this tool versus alternatives or when not to use it. The context implies initial project setup, but there is no direct routing guidance beyond the creation side effects.

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

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

Annotations already mark it destructive/non-read-only, but the description adds substantial context the annotations do not: cascade deletion of environments and volumes with data, ordered deletion ('Default last'), async return semantics ('removed or removing'), partial-failure behavior for unresponsive servers, and the possibility of a human approval gate. This is rich beyond the structured hints.

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

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

Four short sentences, with the primary action front-loaded. The distributed-server sentence is dense and slightly cryptic, but no sentence is 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, high-consequence operation with no output schema and very low parameter documentation, the description covers the blast radius and async/approval flow well but leaves half the parameters opaque. Adequate but with clear gaps given the tool's complexity.

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

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

Schema coverage is only 17% (just the approval param) across 6 parameters, so the description must carry the burden and largely does not. It gestures at approval ('may stop to ask a human') and at data loss implicitly, but version, every_copy, wait_seconds, and accept_volume_loss are left unexplained in both schema and description.

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

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

States a specific verb+resource ('Delete a Project') and precisely defines the cascade scope (every Environment, Volume, and their data), which distinguishes it from the narrower environment_remove/volume_remove siblings. It stops short of explicitly naming those siblings, so an agent must infer the distinction from scope 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?

The description never states when to choose this tool over project_rename, environment_remove, or volume_remove, nor any prerequisites or exclusions. The cascade and approval notes are behavioral, not usage-routing guidance.

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

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

Beyond the annotations, it discloses that the rename takes effect immediately, that Environments keep running, and that no human approval is involved. These are meaningful behavioral details for a mutation tool, though it does not discuss permissions or collision/error behavior.

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

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

Three short sentences, front-loaded with the action and containing no wasted text. Each sentence adds a useful behavioral fact.

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

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

For a two-parameter mutation tool with annotations covering safety and no output schema, the description supplies the key operational context: immediate effect, environments unaffected, and no approval step. It is mostly complete, with minor gaps around permissions and error handling.

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

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

The schema documents the new name ("to") and its uniqueness constraint, but the "project" parameter has no schema description. The description establishes that "project" is the target and "to" is the new name, but it adds little beyond that implicit mapping.

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: "Rename a Project." That is clear enough to distinguish it from project_create/project_remove and the other rename tools, though it does not explicitly name alternatives.

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 implies the operation is immediate and requires no human approval, which gives useful usage context. However, it does not explicitly say when to choose this over siblings such as service_rename or config_rename, nor does it state prerequisites or exclusions.

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 the read-only, non-destructive profile. The description adds useful behavioral context by stating that the call asks no human and by listing what the plain-line output covers: version, required approvals, and broken references.

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 short sentences, front-loaded with the key output description and followed by the important non-interactive behavior. There is no filler, and each sentence contributes new information.

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

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

With no output schema, the description appropriately explains what the call reports: version, approvals, and broken references. It could be slightly more complete by clarifying that the review is scoped to the given project and environment, but the schema covers those inputs.

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 project and environment are already documented. The description does not add parameter-specific meaning, so the baseline score of 3 is appropriate.

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

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

The description clearly conveys that this is a preview of what the next deploy would apply, including version, required approvals, and broken references. It is specific about the resource and output, but it does not explicitly name a verb like 'preview' or directly distinguish itself from the sibling deploy tools.

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

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

The phrase 'What the next deploy applies' implies this should be used before a deploy, and 'This call asks no human' hints that it is non-interactive. However, it does not explicitly say when to use this instead of deploy, deployment_start, or other siblings, nor does it state exclusions.

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 readOnlyHint=false, but the description adds real substance: the blast radius spans containers on every server and volumes including their data, and it warns of an interactive approval gate. That is meaningful context beyond the safety flags, though it omits reversibility and whether approval can be bypassed.

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

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

Two tight sentences with the destructive verb and scope front-loaded, then the approval caveat. No filler, though the phrasing 'a leftover no Environment owns' reads awkwardly and costs a little clarity.

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

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

For a destructive multi-server teardown with no output schema, the description covers the what and the approval flow but leaves gaps: the accept_volume_loss parameter needed to authorize data loss is unexplained, and the approval round-trip is only hinted at rather than described end-to-end.

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 only 40%: only 'leftover' and 'approval' are described in the schema, while 'version', 'request_key', and 'accept_volume_loss' are bare. The description mentions data loss on volumes but never ties it to accept_volume_loss or explains request_key's idempotency role, so it fails to compensate for the coverage gap.

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 (a leftover no Environment owns), then enumerates the scope: containers on every server plus volumes with their data. That precision lets an agent distinguish it from sibling teardown tools like environment_remove or volume_remove, though it never names them explicitly.

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

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

Usage is only implied by 'a leftover no Environment owns' and by the approval hint. There is no explicit when-to-use, when-not-to-use, or routing to alternatives such as discard or environment_remove, so the agent must infer the trigger condition.

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 readOnlyHint=false, so the risk profile is covered. The description adds genuinely new behavior: a drain may be incomplete ('what stayed because its data is there') and the call may pause for human approval, which explains the approval and wait_seconds parameters. It does not say whether the operation is resumable, idempotent, or what state the server is left in on failure.

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 short sentences with no filler, and the core effect is front-loaded before the caveats. The phrasing is slightly telegraphic ('place none there'), 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 no output schema, the description does briefly disclose the result shape (services that stayed and why), which is helpful. However, for a destructive, possibly-async, possibly-approval-gated tool with three undocumented parameters, it omits resume semantics and the meaning of request_key/wait_seconds.

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

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

Schema description coverage is only 25%: only 'approval' is documented in the schema, while 'request_key' and 'wait_seconds' have no description anywhere. The description alludes to the approval flow but adds no meaning for request_key (idempotency?) or wait_seconds (poll timeout?), so it fails to compensate for the coverage gap.

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

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

States a specific verb+resource: 'Move Services off a server and place none there', which is clearly a drain/cordon operation and distinct from siblings like server_clean, server_forget, and server_remove. It does not name or contrast those siblings explicitly, but the action is unambiguous 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?

There is no statement of when to drain versus cleaning, forgetting, or removing a server, and no prerequisites (e.g., that the server must be schedulable, empty of volumes, or that drain precedes removal). Usage is only implied by the operation itself.

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, but the description adds the concrete blast radius ('its volumes are lost'), a refusal condition, and the fact that the call may pause for human approval — context the annotations alone do not convey. It does not address irreversibility or retry semantics beyond the approval hint.

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

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

Three short sentences, zero filler, with the core action front-loaded and the caveats following. Every clause carries distinct information (scope, refusal, approval).

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 3-parameter tool with no output schema, the description covers destruction scope and the approval interruption well, but leaves request_key (likely idempotency) and the server identifier format unaddressed. Adequate, with clear gaps.

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

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

Schema description coverage is only 33%: the 'approval' parameter is documented in the schema, but 'server' and 'request_key' have no descriptions anywhere. The description text adds nothing about parameter formats, the naming pattern constraint, or what request_key is for, so the coverage gap is not compensated.

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 ('forget') and resource ('a server'), and immediately clarifies the scope with 'without a reset', which separates it from the destructive-then-reset semantics of siblings like server_remove or server_clean. It does not name a sibling tool directly, so it stops 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?

Gives a real precondition — refusal while the server 'answers and holds a volume copy' — which tells the agent when this call will not succeed. However, it never says when to prefer this over server_remove, server_clean, or server_drain, leaving the routing decision to inference.

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

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

Annotations already establish readOnly and non-destructive, and the description adds useful behavior: output caps (200 lines/16 KB/500 B per line), redaction of secret-shaped values, and no human approval requirement. It does not discuss pagination or auth, but it is substantially more informative than the annotations alone.

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

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

The definition is compact and front-loads the resource, sources, limits, and redaction before the no-human note. Every sentence carries operational information without repetition.

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

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

For a four-optional-parameter read tool with no output schema, the description covers the important behavior: process sources, result caps, redaction, and no human approval. The remaining gap is the unexplained since_minutes window and default line count, but the tool is otherwise callable.

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 50%; the description adds the process default (ployz) and the line cap, while server omission and enum choices are already in the schema. It says nothing about since_minutes semantics or the lines default of 100, leaving partial compensation.

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 the resource (a server's own recent logs) and the selectable daemon/process sources, and 'server's own' implicitly separates it from service_logs. It does not explicitly name the sibling alternative, so it is clear but not maximally differentiated.

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 no when-to-use/when-not-to-use guidance and never mentions service_logs or server_metrics as alternatives. An agent must infer that this is the server-scoped log tool from the purpose alone.

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

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

Annotations already declare readOnlyHint=true, so the description earns credit for adding behavior beyond them: 'This call asks no human' tells the agent the call is non-interactive and requires no approval, and 'Default: the last hour' discloses the default time scoping. It does not say anything about cost, sampling granularity, or what happens for containers that no longer exist.

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, front-loaded sentences with no filler: resource content first, then default window, then approval behavior. It is perhaps too sparse rather than padded, but every sentence carries signal.

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 two undocumented parameters, no output schema, and no explanation of return shape (per-container breakdown vs aggregate), the description leaves real gaps an agent must guess at. The behavioral/metadata side is reasonably covered; the input and output side is not.

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 0%, so the description must carry parameter meaning and largely fails. 'Default: the last hour' hints that a time-window parameter exists, but since_minutes is never named, its units/bounds (1..10080) are unexplained, and the server identifier's expected format (DNS-style lowercase name) is not mentioned at all.

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 resource (a server's CPU, memory, network, disk, plus container OOM kills, exits and restarts), which is clearly distinct from server_show (state) and server_logs (log text). It does not explicitly contrast with service_metrics though, leaving the server-vs-service scope boundary implicit.

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 implied use case (fetch server-level metrics) is clear from the content, and 'Default: the last hour' gives the time window. But there is no explicit when-to-use vs server_show/server_logs/service_metrics guidance and no conditions given for when not to call it.

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

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

Annotations already declare destructiveHint=true, so the description's real added value is the detail of what gets destroyed (containers, volumes, and their data), the redeploy behavior of surviving services, the volume-pinned exception, and the approval interruption path. The exception clause is phrased vaguely enough ('except those whose Volume was there') to leave the reader guessing at the exact outcome, which keeps it out of 5 territory.

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 destructive action, no filler. Minor awkwardness in 'Services still there stop' and 'except those whose Volume was there' costs it a point but the density-to-length ratio is good.

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, no-output-schema tool with five parameters, the description covers the consequences and the approval loop reasonably well but leaves the volume-loss authorization path and idempotency key unexplained. An agent could call it correctly in the happy path but would be under-informed on the risky branch.

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

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

Schema description coverage is only 20% (just the 'approval' parameter), so the description bears nearly the full burden — and it fails. The critical 'accept_volume_loss' parameter, which governs whether volume data loss is authorized, is never mentioned, nor are 'version' or 'request_key'. The description only obliquely hints at the approval mechanism.

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 ('Remove a server') plus the scope of collateral destruction ('delete its containers and volumes with their data'). It does not, however, distinguish itself from the closely-named siblings server_forget, server_clean, and server_drain, which an agent could easily confuse with this one.

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 conveys the operational consequence (services stop and redeploy elsewhere) and flags that human approval may be required, which implicitly tells the agent this is a heavyweight irreversible action. But it never says when to choose this over server_forget/server_clean/server_drain, and gives no prerequisites or when-not-to-use guidance.

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

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

Annotations only declare readOnlyHint=false and destructiveHint=false; the description goes further by disclosing that disabling web traffic on the last server serving a domain requires human approval and that the call may pause for approval. This is meaningful behavioral context the agent cannot get from annotations alone, though the approval re-invocation contract is left to the schema.

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

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

Three short sentences, front-loaded with the core action. The final sentence ('May stop to ask a human to approve') partially restates the preceding approval sentence, costing a little efficiency but not much.

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 tool with 29% schema coverage and no output schema, the description leaves too much unexplained: build_concurrency format, request_key purpose, and how this tool relates to server_drain/server_clean. The approval behavior is covered, but the rest is not.

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

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

Schema description coverage is only 29%, so the description must compensate, yet it only loosely maps three booleans (builds, services, web traffic) to accepts_builds/accepts_services/accepts_ingress. build_concurrency, request_key, the server name pattern, and the approval ID semantics receive no explanation from the description.

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 (set) and resource (server) plus the configurable dimensions (builds, services, web traffic), which map to the boolean parameters. However, it does not distinguish itself from siblings like server_drain, which also manipulates traffic, so sibling differentiation is absent.

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?

There is no explicit when-to-use or when-not-to-use guidance, and no routing to alternatives such as server_drain or server_clean. The approval-flow sentence describes a behavior rather than a usage condition, leaving the agent to infer when this tool is the right choice.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered structurally. The description adds a useful behavioral note that 'This call asks no human' (no approval prompt) and hints at response content through the field list, but says nothing about pagination, freshness, or return format.

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 one dense sentence that front-loads scope ('Your servers now') and packs the returned fields without filler. The trailing clause about a hidden failed/lost/interrupted drain is hard to parse and slightly muddies the structure.

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

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

With no output schema, the description usefully enumerates what data comes back (state, release, upgrade, drain, disk, workloads, orphans, latest operation), filling the main gap. It does not explain return format or auth needs, but for a one-parameter read-only show tool it is largely complete.

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

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

Schema description coverage is 100% and the single 'server' parameter is fully documented there ('Omit for every server'). The description adds no syntax or semantic detail beyond implying plural 'your servers' as the default, so the baseline 3 is appropriate.

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

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

The description enumerates the returned data (state, release, upgrade, drain, disk, workloads, unowned leftovers, latest operation), so an agent can infer this is the current-state view of servers. But it never uses a verb like show/list and never names a sibling to contrast with, so the purpose depends on inference rather than an explicit verb+resource statement.

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?

Usage is only implied by 'now' as a current snapshot read; there is no explicit when-to-use, when-not, or routing away from server_metrics, server_logs, or deployment_show. The only scoping guidance is in the schema ('Omit for every server').

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false; the description adds genuinely new context by disclosing that apps keep running during the upgrade (non-disruptive) and that no human approval gate exists. What is not covered: reversibility, whether the server restarts, and any timeout or rate constraints.

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

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

Three short sentences, front-loaded with the core action and scope. The trailing 'This call asks no human' is slightly cryptic phrasing but still earns its place as a confirmation-free signal.

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?

It covers the behavioral essentials for a non-destructive mutation and needs no output-schema explanation since none exists. But with zero parameter documentation and no mention of failure handling (e.g., what happens if the server is draining or the channel has no newer release), an agent lacks enough to invoke it confidently in edge cases.

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 0% for three parameters, and the description adds nothing: it does not explain that 'server' is a hostname matching the given pattern, nor what 'request_key' (apparent idempotency key) or 'wait_seconds' (bounded wait for completion) do. Only the single required parameter's intent is derivable from the name.

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 ('Upgrade Ployz on a server to its channel's latest release'), which an agent can distinguish from server_show or server_upgrade_policy_set. It stops short of naming the policy sibling that controls which release the channel resolves to, so differentiation is inferred rather than stated.

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

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

'This call asks no human' and 'Apps keep running' imply this is a safe, unattended operation, which gives some context for when to invoke it. However, it never says when to prefer it over server_upgrade_policy_set, server_drain, or deployment_start, and no preconditions (server must be healthy, not draining) are given.

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

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

Annotations already declare this as a non-read-only, non-destructive mutation, and the description usefully adds that the change is Organization-wide rather than per-server. However, with both parameters optional it never explains partial-update behavior (does omitting a parameter preserve or reset it?) or whether the change is reversible, which is the key behavioral gap for a 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?

A single front-loaded sentence with the resource named first and the two affected aspects listed after the colon. No filler, though the trailing clause is a slightly loose paraphrase of the schema.

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

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

For a two-optional-parameter mutation with no output schema, the description covers the what and the org-wide scope but omits partial-update semantics, permission requirements, and any indication of what a successful call returns or changes. Adequate but with clear gaps.

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

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

Schema description coverage is 100% and both parameters already carry their own descriptions and an enum, so the schema does the heavy lifting. The description's phrasing of 'the Release Channel every upgrade follows' essentially restates the channel schema text rather than adding format, default, or interaction semantics.

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

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

States a specific verb (Change) and resource (the Organization's upgrade policy) and enumerates the two mutable aspects, so an agent can distinguish it from server_upgrade_policy_show or server_upgrade. It stops short of explicitly naming the read sibling it complements, which keeps it out of the top band.

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?

There is no when-to-use or when-not-to-use guidance, no mention of prerequisites or permissions, and no reference to the closely related server_upgrade_policy_show or server_upgrade tools. The agent must infer the routing entirely from the name.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful content beyond that by disclosing what the operation returns (release channel plus auto-upgrade status), which matters because there is no output schema.

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

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

A single front-loaded sentence with no filler; the resource and the returned fields come first and 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 no parameters, no output schema and read-only annotations, the description is nearly self-sufficient; it fills the output-schema gap by naming the two returned values. Only a pointer to the related setter tool 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?

The tool takes zero parameters, so the baseline is 4. There is nothing parameter-wise for the description to clarify or compensate for.

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 (Show) and resource (the Organization's upgrade policy), and enumerates the two fields returned (Release Channel, automatic upgrades). The read counterpart to server_upgrade_policy_set is obvious from the name, though the description never names that sibling explicitly.

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

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

No explicit when-to-use or when-not-to-use guidance is given; the read-only 'show' naming implies it is the inspection counterpart to server_upgrade_policy_set. Adequate but the agent must infer that this is the correct tool for checking current policy before calling the setter.

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 this is a write operation that is not read-only and not destructive. The description adds meaningful context beyond that: creation is staged and will run after the next Deploy, and the call requires no human approval. It does not discuss permissions or return behavior, so a 4 is appropriate.

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

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

The description is short and front-loaded with the primary action. Each sentence adds useful information, though the phrasing "Give image to run a container image" is slightly awkward and could be tightened.

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

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

Given 7 parameters with full schema descriptions, annotations covering the mutation profile, and no output schema, the description is largely complete. It covers the key behavioral traits but does not explain result handling or optional parameter defaults, which are adequately covered in the schema.

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

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

Schema description coverage is 100%, so parameter semantics are already well documented by the schema. The description reinforces the image-versus-repository choice but does not add syntax or defaulting details beyond what the schema provides, making the baseline 3 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?

The description uses a specific verb and resource: "Create a Service." It also clarifies the two creation modes, container image versus GitHub repository build, which distinguishes the tool from sibling operations like service_update or service_remove.

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 tells the caller to supply either image or repository depending on the desired source, which is useful usage guidance. It does not name when-not-to-use conditions or point to alternative sibling tools, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds a genuinely new behavioral fact — no human confirmation is required — plus an enumeration of the data surfaced, which tells the agent what it gets back in the absence of an output schema. It stops short of describing return shape or size.

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

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

One front-loaded sentence opens with the core purpose, then lists returned data, then closes with the key behavioral caveat. No filler. The trailing 'This call asks no human' is terse to the point of being cryptic, but it 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 read-only inspection tool with three simple flat parameters and no output schema, the enumeration of returned data does useful work in place of a return spec. Still missing is scope clarification: which environment is inspected, whether results default to a single environment, and how it differs from service_status.

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 67%, and the required 'service' parameter has no description at all. The description never mentions any parameter, so it does nothing to compensate — notably it never clarifies whether project/environment are needed to disambiguate which Service (and which environment's staged state) is inspected.

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 resource ('one Service') and enumerates exactly what it returns: settings with values and defaults, variables, mounts, Configs, domains with status, and staged state. That is far more concrete than a name restatement. It does not, however, distinguish itself from the neighboring service_status or service_logs, so an agent must infer the boundary.

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

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

'This call asks no human' implies it is safe to invoke autonomously without confirmation, which is implied usage guidance. But there is no explicit when-to-use statement, no mention of when service_status or service_logs would be preferable, and no note on prerequisites such as project/environment context.

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

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

Annotations already establish readOnlyHint=true and destructiveHint=false. The description adds useful behavioral context beyond that: output is capped at 200 lines, 16 KB, and 500 B per line; secrets are shown by name; deployment logs fall back to the build log on failure; and the call asks no human.

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 short and front-loads the main resource and limits. The deployment sentence is tightly compressed to the point of slight ambiguity, but overall every sentence carries relevant information.

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

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

For a read-only log retrieval tool with annotations covering safety and no output schema, the description covers output caps, secret handling, and deployment fallback. It remains incomplete for a 7-parameter tool because several filtering and time-window parameters are not explained.

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

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

Schema description coverage is only 29%, so the description needs to carry more parameter meaning. It explains the line cap and deployment behavior, but leaves project, environment, server filtering, and since_minutes largely undocumented beyond their parameter 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 description clearly identifies the resource as 'A Service's recent logs' and extends that to a specific Deployment's containers or build log when deployment is provided. This distinguishes it from the sibling server_logs by resource scope, though it does not use an explicit retrieval verb.

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

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

It gives a conditional usage cue: with a deployment, it returns that Deployment's containers or failed build log. However, it does not say when to choose this over service_status, service_inspect, deployment_show, server_logs, or other diagnostic siblings, nor does it state exclusions.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so 'This call asks no human' is largely redundant, though it does clarify no confirmation step is involved. The description adds real value by disclosing what is computed (now/avg/peak) and which failure signals are included, which matters since there is no output schema. It says nothing about retention limits or response size.

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

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

Two tight sentences, with the metric inventory front-loaded and the default window immediately after. 'This call asks no human' is slightly cryptic phrasing but costs only a few words.

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

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

The description does the job of an output schema by enumerating returned metrics and aggregates, which is valuable. But for a 5-parameter tool with 20% schema coverage and no output schema, leaving project/environment scoping and the since_minutes bounds unexplained is a real gap.

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

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

Schema coverage is only 20% — just 'deployment' is documented — and the description never explains project, environment, service or since_minutes. 'Default: the last hour' implicitly signals the since_minutes default, but with four undocumented parameters the description should compensate more than it does.

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 resource (a service) and enumerates the metrics returned: CPU, memory, network, disk with now/avg/peak aggregates, plus OOM kills, exits and restarts. That is far more specific than the name alone. It does not distinguish itself from siblings like server_metrics, service_status or service_inspect, which is the main missing piece.

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?

'Default: the last hour' gives a usable default time window and implies this is the per-service metrics lookup, but it never says when to pick this over server_metrics, service_status or service_logs. Usage is inferred from the name rather than stated.

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

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

The description explains why destructiveHint=false despite a delete-shaped name: the removal is only staged until a human-approved deploy, and the call itself prompts nobody. That reconciles the naming with the annotations and is real value-add. The fragment "`broken`: references deploys skip" is too cryptic to count as disclosure.

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

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

Short and front-loaded, which is good, but the middle sentence ("`broken`: references deploys skip") is a compressed fragment that costs space without conveying a parseable rule. Two of three sentences earn their 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 four-parameter mutation with no output schema, the description covers the two things an agent most needs: the effect is deferred and no confirmation is raised here. It still leaves open whether the service keeps running until the deploy and how a staged removal is undone (the `discard` sibling is never mentioned).

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 75%, so most parameters (project, environment, expect_revision) are already documented at the schema level. The description adds nothing about parameters, and the required `service` argument has no description in either the schema or the description; the opaque `broken` reference may relate to inputs but is not resolvable.

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 ("Remove a Service") plus the key nuance that the removal is staged rather than immediate. It does not differentiate against near siblings such as service_stop or environment_remove, so an agent must infer which removal tool applies.

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

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

"This call asks no human" signals that the call is safe to invoke without an interactive confirmation, which is genuinely usage-relevant. Beyond that, there is no explicit when-to-use/when-not guidance and no pointer to alternatives like service_stop or `discard` for reversing a staged removal.

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

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

Annotations only say readOnly=false/destructive=false; the description adds real substance — that DNS names and references are updated as a side effect, that the change is staged rather than immediate, and that no approval is required. It doesn't say whether the rename is reversible or how revision checks interact, which keeps it 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 terse sentences, action first, then consequences, then staging, then approval. Nothing is wasted, though the telegraphic 'Staged.' and 'This call asks no human.' could carry slightly more precision.

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

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

For a 5-param mutation with no output schema, the description covers consequences and staging but leaves gaps: what 'staged' operationally means (does a deploy follow?), whether scoping to project/environment is required, and what the response reports.

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 80%, so the schema already documents four of five parameters (including expect_revision). The description adds no parameter-level meaning and says nothing about the undocumented 'service' param or the required project/environment scoping.

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?

A clear verb+resource ('Rename a Service') with named knock-on effects (private DNS names and references follow). It is distinguishable from siblings like config_rename and project_rename by the resource noun, though it never states that distinction explicitly.

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

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

'Staged' and 'This call asks no human' imply usage context (changes take effect later and require no approval), but the description never states when to rename vs. remove/recreate or what prerequisite state the service must be in.

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

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

Annotations declare readOnlyHint=false and destructiveHint=false, so the agent knows this is a non-read, non-destructive mutation. The description adds one genuinely useful trait beyond that: the call may pause and require human approval, which is a behavioral characteristic not visible in the annotations. It omits downtime impact, restart semantics (rolling vs full), and rate/queueing behavior.

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

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

Two short sentences, front-loaded with the action. Nothing is wasted, though the phrasing "May stop to ask a human to approve" is slightly awkward and could be tightened.

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

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

For a 7-parameter mutation tool with 29% schema coverage and no output schema, the description is thin. It covers the action and the approval gate but leaves scoping, idempotency, and timing parameters undocumented anywhere.

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 only 29% across 7 parameters, so the description must compensate and does not. It never mentions environment/project/server scoping, request_key idempotency, or wait_seconds, and only alludes indirectly to the approval parameter via the approval-request flow.

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: "Restart a Service's containers." This is unambiguous and distinguishable in principle from service_start/service_stop, but the description never actually contrasts itself with those siblings, so it stops 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?

No guidance on when to restart versus service_stop + service_start, no prerequisites, no exclusions. The only contextual remark is about human approval, which describes mechanics rather than selection criteria.

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

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

Annotations already declare the tool is non-read-only and non-destructive. The description adds useful context that the call 'asks no human,' implying no approval step is required, but it does not explain permissions, idempotency, or side effects for a mutation tool.

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

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

The description is two short sentences with the core action front-loaded. There is no redundant or wasted text.

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

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

For a mutation tool with six parameters, low schema description coverage, and no output schema, the description is too sparse. It leaves key parameters and behavioral details unexplained, so an agent would need to infer much of the call semantics.

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

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

Schema description coverage is only 17%, with just the 'server' parameter documented. The description mentions 'Service' but adds no meaningful semantics for the other parameters such as project, environment, request_key, or wait_seconds.

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 ('Start a Service's stopped containers'), making the operation clear. It does not explicitly distinguish itself from the sibling service_restart, so it falls short of full sibling differentiation.

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

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

The phrase 'stopped containers' implies the tool should be used when a service is not running. However, it gives no explicit guidance on when to choose service_start over service_restart or deploy, and no exclusions or prerequisites are stated.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered structurally. The description adds a useful operational note that no human approval is required and lists the state fields surfaced, but says nothing about scoping behavior when service is omitted or any limits on the container list.

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 compact, but the first sentence is a dense comma-list fragment that requires re-reading, and the trailing 'This call asks no human' is sentence-fragmented. Front-loading is acceptable but clarity suffers for the size.

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

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

With no output schema, the field enumeration is valuable, but two of three parameters remain undocumented and there is no guidance on the all-Services case or output shape per server. For a 3-parameter status tool it is roughly the minimum viable description.

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 only 33%: only 'service' carries a description ('Omit for every Service here'). The description adds no meaning for 'project' or 'environment' and does not explain that omitting 'service' broadens the query to all Services in scope.

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 indicates a read of a Service's state and its containers per server, and enumerates the returned fields (health, restarts, image, Deployment, latest restart, start/stop). However, the phrasing 'as the canvas shows it' is vague and it never distinguishes itself from close siblings like service_inspect, service_metrics, or server_show.

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?

There is no explicit statement of when to use this versus service_inspect or deployment_show. The only usage-adjacent signal is 'This call asks no human', which tells the agent nothing about selecting this tool over its 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 only declare readOnlyHint=false and destructiveHint=false; the description adds real value beyond them by clarifying 'Deletes nothing' (reassuring against service_remove confusion) and disclosing that an approval gate may interrupt the call. It stops short of explaining the approval/retry flow or wait behavior, which would be needed for 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 short, front-loaded sentences with no filler. The core action and its non-destructive guarantee come first, and the approval caveat follows.

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 purpose, non-destructiveness, and the possibility of an approval gate for a mutation tool with no output schema. However, with 7 parameters at low schema coverage, the request_key idempotency key, wait_seconds, and the approval-resume flow are undocumented, leaving real 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?

With only 29% schema description coverage across 7 parameters, the description must compensate and does not. It never mentions server, project, environment, request_key, or wait_seconds, and the 'approve' hint does not explain the approval parameter's retry semantics.

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

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

States a specific verb and resource ('Stop a Service's containers') and adds the reversibility scope ('until started again'), which separates it from service_remove and service_start. It does not name any sibling explicitly, so it falls just 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?

No guidance on when to choose this over service_restart, service_remove, or service_start. The 'May stop to ask a human to approve' line is behavioral context, not a when-to-use rule, so usage is left almost entirely to inference.

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

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

Goes well beyond the annotations: it distinguishes Staged changes (undoable until the next deploy) from immediate ones (template, autoDeploy, waitForCi, watchPaths, preferredBuilder) that cannot be undone that way, and says the result lists them under immediate. It also discloses that secret values never pass through this call and that no human approval is requested. This is exactly the kind of behavior an agent needs before a 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-loaded with the core action, then the patch semantics, then the staging caveat, then the secret rule, with no filler sentences. It is dense as a single unbroken paragraph covering several distinct concerns, which makes scanning harder than it needs to be, but every sentence carries 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 9-parameter mutation tool with nested objects and no output schema, the description covers the highest-risk aspects: reversibility, immediate effects, and secret handling. Gaps remain around optimistic concurrency (expect_revision) and the rename/reference-update interplay, both of which the schema documents but the description never surfaces.

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 89%, so the baseline is 3, but the description adds real meaning: set is a patch that keeps unnamed Settings, env inside set sets only the variables it names, and five named parameters have immediate, non-undoable effect. It does not explain expect_revision concurrency or the rename_env/update_references interaction, leaving those 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: change one Service's Settings and variables in one step. It also draws the boundary against domain_update and config tools by saying domains are not Settings and are not changed here. An agent can tell exactly what this mutates 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?

Clear context on when this applies, plus exclusions ('Domains are not Settings and are not changed here') that implicitly route the agent elsewhere. It also notes secrets must go through generate_secret rather than being passed here. It does not name sibling tools such as service_rename explicitly, so routing is inferred rather than stated.

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