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

The annotations already declare a non-read-only, idempotent, open-world mutation; the description adds substantive context beyond them by disclosing the automatic side effects (Cloudflare creates the DNS record and certificate) and the account-scoped zone restriction. Return shape and propagation timing are not described, which keeps it off a 5.

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

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

Two sentences, front-loaded with the action, then the prerequisite and side effects. Every clause carries information and nothing is redundant.

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

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

For a mutation tool with full schema coverage and annotations covering safety and idempotency, the description supplies the important missing context: prerequisites and automatic DNS/certificate creation. It omits what the call returns (the domain object) and failure modes for inactive zones, but the definition is largely sufficient.

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

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

Schema description coverage is 100%, so hostname, service, zone_id, zone_name, and environment are already documented inline. The description's only parameter-adjacent contribution (the zone must be active in this account) duplicates the zone_id description, 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?

The description opens with a specific verb and resource ('Attach a custom domain to a Worker') that clearly separates it from delete_worker_domain and list_worker_domains. It doesn't name those siblings explicitly, but the operation 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 gives the key precondition for use: the domain's zone must be active in this account, and external zones are not supported. It doesn't say when to prefer it over list_worker_domains for verification or what to do on conflict, so it stops short of explicit alternative routing.

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

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

Annotations already declare destructiveHint=true, openWorldHint=true, and idempotentHint=false, so the risk profile is covered structurally. The description adds the shape constraint on traffic splitting but says nothing about what happens to the prior deployment, whether the change is reversible, or what the force flag means in practice — details an agent would want before a destructive 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?

Two tight sentences with the primary action front-loaded, followed by the configuration shapes and the summation constraint. Nothing redundant and nothing padded.

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, non-idempotent mutation with no output schema, the description conveys the operation's shape and constraints adequately, and annotations carry the safety signal. The main missing piece is the effect on the existing live deployment and the relationship to rollback_worker, which would matter for recovery.

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

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

With 100% schema description coverage, the baseline is 3: the schema already documents force ('deploy even if normally blocked'), message, script_name, and the version/percentage pair. The description restates the versions shape and the sum-to-100 rule, which duplicates rather than extends the schema, and never touches force or message.

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 ('point live traffic at Worker versions') and enumerates the two supported shapes: single version at 100% or a two-way split. It does not, however, distinguish itself from the sibling deploy_worker, which likely performs a very similar action, leaving the boundary between the two 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?

Usage is implied rather than stated: the mention of a 'gradual rollout' signals when this tool is appropriate, but no alternatives are named and no exclusions given. An agent cannot tell from this text whether to prefer this over deploy_worker, deploy_preview, or rollback_worker.

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

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

Beyond the annotations (readOnly=false, destructive=false, idempotent=false) it discloses two non-obvious behaviors: live traffic is untouched, and existing secrets carry over unless a binding with the same name is passed. The secret-inheritance rule is real operational value that no annotation or schema conveys. It does not mention that repeated calls create distinct versions (consistent with idempotentHint=false) or any permission requirements.

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

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

Two sentences, front-loaded with the single most important fact (this does not deploy), followed by the operational caveat about secret inheritance. Nothing is padded or redundant.

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

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

For a 9-parameter tool with nested modules and six binding variants and no output schema, the description covers the crucial lifecycle relationship and the secret-override gotcha. It leaves out what the call returns (a version identifier for later use with create_deployment) and any permission requirements, which are mild gaps given the fully documented 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 coverage is 100%, so the baseline is 3, but the description adds semantics the schema cannot express: bindings with a matching name override inherited secrets, which changes how an agent should populate the bindings array. That is meaningful behavioral meaning layered onto the parameter, not a restatement.

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 ("Upload a new Worker version") and immediately delimits it against the deployment siblings: it does NOT change live traffic until create_deployment references it. An agent can distinguish it from deploy_worker and create_deployment without opening any schema.

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

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

Gives an explicit use case ("staged rollouts") and names create_deployment as the follow-up step that activates the version, which effectively routes the agent to the right sibling for going live. It stops short of an explicit when-not-to-use rule versus deploy_worker, but the staged-vs-live distinction is clear.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the description's real contribution is blast radius: it discloses that deployments are deleted along with the preview and that production is untouched. It does not say whether the deletion is reversible or what happens on a repeat call, which leaves minor gaps against the idempotentHint=false signal.

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 resource and cascade effect front-loaded and the safety reassurance second. No filler, no restatement of the title.

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

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

For a two-parameter destructive tool with full schema coverage and annotations carrying the safety profile, the description covers the two things the agent most needs beyond structured data: what else gets destroyed and what does not. Reversibility is the only notable omission.

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

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

Schema coverage is 100% and the schema already documents that 'preview' accepts a name, slug, or id sourced from list_previews. The description repeats that same fact without adding format, resolution-order, or edge-case detail, 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 ('Delete a Worker preview and its deployments'), and the mention of 'preview' plus 'Production is unaffected' implicitly separates it from delete_worker and delete_preview-adjacent tools. It stops short of naming a sibling it could be confused with, which keeps it from a 5.

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

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

The clause 'Production is unaffected' gives useful context about when this is safe to run, but there is no explicit guidance on when to pick this over delete_worker, rollback_worker, or list_previews, and no stated prerequisites or confirmation requirements. Usage is implied rather than directed.

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

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

Annotations already declare destructiveHint=true and idempotentHint=false, and the description still adds real value: deletion triggers a new version deployment and causes runtime code reading the secret to see undefined. That side-effect disclosure is exactly the kind of context annotations cannot convey. It stops short of noting reversibility (a prior version could be restored via rollback_worker) or failure behavior for a nonexistent secret.

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 action front-loaded and the consequence immediately after. Nothing is padded or repeated from 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-parameter destructive mutation with full schema coverage and complete annotation hints, the description covers the essential unknown: that a new version is deployed as a side effect. Only minor gaps remain, such as behavior when the binding does not exist and whether rollback is the recovery path.

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 (script_name, name) are already documented in the schema. The description adds no format, casing, or resolution detail beyond that, so the baseline of 3 applies.

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

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

The description states a specific verb and resource ('Delete one secret binding from a Worker') with scope limited to a single binding, which cleanly separates it from delete_worker, list_secrets, and set_secrets. It never names a sibling explicitly, but the resource-level specificity makes selection 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 guidance on when to use this versus set_secrets (e.g., overwriting with an empty value) or whether the Worker must exist first. Usage is only implied by the verb, and no prerequisites or exclusions 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 destructiveHint=true and idempotentHint=false, so the safety profile is covered. The description adds genuinely non-redundant behavior: deletion cascades to versions, deployments, and static assets, and dependent resources block deletion unless force is set. It does not mention auth requirements or whether the cascade is recoverable, 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?

Two short sentences, front-loaded with the destructive scope and followed by the one non-obvious parameter behavior. No filler, though the second sentence could have been folded into the first for tighter 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?

For a two-parameter, fully documented tool with an output schema absent and annotations covering the safety profile, the description supplies exactly what structured data cannot: what else gets destroyed and how dependencies interact with the force flag.

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

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

Schema description coverage is 100%, and the description's note that force overrides dependency protection largely restates the schema text for that parameter. It adds no syntax, format, or default details beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('Permanently delete a Worker script') and enumerates the cascade scope (versions, deployments, static assets). It does not explicitly name a sibling to contrast with, but the resource name makes confusion with delete_worker_domain or delete_preview unlikely.

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 second sentence gives actionable guidance on when to set force ('to delete even when other resources depend on it'), which implies force should otherwise be omitted. However, there is no explicit statement of when to prefer this tool over siblings like delete_preview or rollback_worker, nor any prerequisite or confirmation 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 destructiveHint=true, idempotentHint=false, and openWorldHint=true, so the safety profile is covered structurally. The description still adds real value beyond them by naming the concrete consequence: the hostname stops routing to the Worker and its previews, which an agent could not infer from the hints alone. It stops short of saying whether the DNS record or the domain attachment itself is destroyed and whether the change 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 short sentences with zero filler, and the most important fact (what detaching does to routing) is front-loaded immediately after the action statement.

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

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

For a one-parameter destructive operation with no output schema, the description covers the action and its routing consequence adequately. The only missing pieces are whether the underlying DNS/attachment record is removed and what is returned on success, but these are minor for a tool of this complexity.

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

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

Schema coverage is 100% and there is a single required parameter, so the schema already fully documents domain_id including its source (list_worker_domains). The description adds no further meaning about the identifier's format or behavior, so the baseline of 3 applies.

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

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

The description uses a specific verb ("Detach") plus resource ("a custom domain from its Worker"), which is unambiguous and clearly distinct from add_worker_domain and list_worker_domains. It does not name those siblings explicitly, but the operation is easy to distinguish from them by intent 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?

Usage is only implied: an agent can infer this is the removal counterpart to adding a domain, and the schema's "from list_worker_domains" hints at the discovery step. There is no explicit statement of when to use this versus alternatives or any prerequisite caution before detaching.

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 a non-destructive, non-read-only, open-world write; the description adds real value beyond that by disclosing the beta API, the stable per-preview URL format, the per-deployment URL, and the update-on-redeploy semantics. It stops short of noting permission/auth requirements or that preview URLs may need enable_preview_urls to be routable (that implication lives only in 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?

Four short sentences, no repetition, front-loaded with the action and the mode choice, then return values, then re-deploy behavior. Every sentence adds information the agent needs.

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

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

For an 11-parameter deploy tool with no output schema, the description covers the action, mode selection, return shape, and re-deploy semantics, which is most of what an agent needs. Missing are prerequisites like required API scope and the dependency on enabling preview URLs, which affect whether the call succeeds.

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

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

Schema coverage is 100%, so the baseline is 3. The description does add one genuinely useful clarification the schema lacks — that 'directory' and 'modules' are the two mutually exclusive input modes — but the remaining 9 parameters get no treatment beyond their own descriptions.

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

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

States a specific verb and resource ('Deploy a preview of an existing Worker') plus the two supported modes (static-site directory/assets vs Worker code/modules), which immediately separates it from deploy_worker and deploy_static_site. The 'without touching production' clause pins the scope further.

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 when-to-use context: preview-only, existing Worker, re-deploy with the same preview_name to update. The prerequisite that the Worker must already exist is carried in the schema ('deploy production first') rather than the description, and no explicit alternative (deploy_worker, deploy_static_site, list_previews) is named as a fallback.

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 openWorldHint=true, but the description adds the substance the agent needs: only missing files are uploaded, _headers/_redirects are applied as config rather than uploaded, .assetsignore excludes files, and most importantly that deploying over a coded Worker replaces it with assets only and strips its bindings and secrets. That last clause is exactly the consequence an agent must know before invoking a destructive 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 core action is front-loaded in the first clause, and each subsequent sentence covers a distinct concern (hosting, SPA/prefix options, config files, destructive replacement). It is dense but every sentence earns its place; minor cost is that configuration-file rules and parameter hints share one long paragraph rather than being visually separated.

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, seven-parameter deploy tool with no output schema, the description covers the risk profile, incremental upload behavior, config-file handling, and ignore semantics. The one gap is that it never says what the call returns (e.g., the deployed URL or version id), which matters since there is no output schema to lean on.

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

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

Schema description coverage is 100%, so all seven parameters are already documented, including enum values and the base_path prefix caveat. The description restates SPA mode and the base_path purpose without adding syntax, defaults, or constraints beyond what the schema carries, so it sits at the expected 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?

"Deploy a local directory as a static site on Workers (assets-only Worker)" names a specific verb and resource and immediately scopes it as assets-only, which is what separates it from the sibling deploy_worker that handles code. It also enumerates the mechanics (manifest build, incremental upload, deploy) so the agent knows the operation's shape.

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 actionable when-to-use guidance for two optional parameters (SPA mode via not_found_handling, prefix serving via base_path) and makes the assets-only vs code distinction clear. It stops short of explicitly naming deploy_worker or redeploy_assets as the alternative, so the routing decision requires the agent to infer from 'assets-only Worker'.

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 by disclosing the destructive mechanics: the code and the entire binding set are replaced on redeploy, while existing secrets survive unless a same-named binding is passed. It also explains the side-channel benefit of the path form (source never enters the conversation, binary .wasm works) and the default workers.dev serving 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?

Front-loaded with the action, then the replace-secrets rule, then the path-vs-content advice, then keep_assets. Every sentence carries weight, though the closing workers.dev sentence partly restates the enable_workers_dev schema description.

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

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

For a 9-parameter destructive mutation with no output schema, the description covers what is destroyed, what is preserved, and how to supply code safely. It stops short of saying what the call returns (version/deployment identifiers) or whether a deployment record is created, which matters given the create_version/create_deployment siblings.

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

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

Schema coverage is 100%, so the baseline is 3; the description still adds real semantics on top, notably the secret-retention rule for bindings and the keep_assets behavior, which are cross-parameter effects not expressed in the schema. The path-vs-content and content_type guidance largely duplicates the existing schema descriptions.

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

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

Opens with a specific verb+resource pair ('Upload and deploy a Worker script') and scopes the payload (ES modules plus optional bindings). It does not explicitly name the sibling it is not (deploy_static_site, redeploy_assets, create_version/create_deployment), so the boundary with those is left to inference.

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

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

Usage guidance is present but is parameter-level rather than tool-level: 'prefer path for bundled or large code', 'Set keep_assets to retain a site's static assets'. There is no statement of when to choose this over deploy_static_site, redeploy_assets, or create_version/create_deployment, so an agent must infer the routing.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds only the gloss that cron triggers are scheduled events; it says nothing about what authentication, account/namespace scoping, or eventual-consistency behavior applies to the read.

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 front-loaded and no filler. It is efficient, though the terseness leaves gaps that other dimensions penalize.

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

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

For a simple one-parameter read tool with full annotation and schema coverage, the description is serviceable. However, with no output schema, it never indicates what the return looks like (cron expressions/strings versus objects), which an agent may need in order to consume the result.

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

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

Schema description coverage is 100% with a single documented parameter (script_name, "The name of the Worker script"), so the schema does the full job. The description adds no meaning about the parameter, 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 gives a specific verb+resource ("Get a Worker's cron triggers") plus a clarifying gloss ("scheduled events"), which distinguishes it from set_cron_triggers by polarity of operation. It stops short of any explicit sibling comparison, but the meaning 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 guidance on when to call this versus set_cron_triggers, no mention of prerequisites such as the Worker needing to exist or be deployed, and no exclusions. The agent must infer usage 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, idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is fully covered elsewhere. The description's one genuine addition is the phrase 'immutable snapshot', which tells the agent the returned configuration cannot change retroactively — useful, but the rest largely restates that it returns detail. No output schema exists, so it could have said more about the response shape than a field 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?

A single front-loaded sentence with the verb, resource, and scope in the first few words, followed by a compact field enumeration. No filler, no repetition of the title, nothing to trim.

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

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

For a two-parameter read tool with full schema coverage and strong annotations, the description supplies the one thing structured fields cannot: what the response actually contains. The remaining gaps — explicit sibling routing and error behavior when a version_id is unknown — are minor given the annotation coverage.

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

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

Schema description coverage is 100%, and the schema already explains that version_id comes from list_versions and that script_name is the Worker script name. The description adds no meaning beyond those two fields, so the baseline of 3 applies.

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

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

The description names a specific verb and resource ('Get a Worker version's detail') and enumerates the fields returned (main module, bindings, compatibility date/flags, asset config, placement, limits), which clearly separates it from get_worker and list_versions. It stops short of explicitly naming those siblings by name, so the differentiation is inferable 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?

Usage is only implied: needing a single version's full detail implies calling this after list_versions (the schema's version_id description hints at that lineage). There is no explicit 'use this instead of X when Y' guidance and no stated preconditions, such as that the script and version must already 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?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered. The description adds real value by disclosing the breadth of the returned payload (settings plus cron triggers plus subdomain status), which an agent could not infer from the one-parameter schema. It stops short of noting permission requirements or what happens for a nonexistent script.

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 sentence, front-loaded with the core action, with the parenthetical field list earning its place because no output schema exists. No redundant or filler 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?

With no output schema, the description appropriately compensates by enumerating what comes back. It is nearly complete for a simple read tool; only error behavior for missing Workers and any permission/account scoping are 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?

There is a single parameter, script_name, fully documented in the schema at 100% coverage. The description only implies it identifies the Worker whose live-version settings are returned, adding nothing about naming format or scoping. Baseline 3 applies since the schema does the work.

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

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

States a specific verb and resource (get a Worker's settings) and enumerates the returned facets: bindings, compatibility date and flags, placement, observability, logpush, cron triggers, workers.dev subdomain status. The phrase 'for its live version' implicitly separates it from get_version/get_worker_code, though no sibling is named 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?

Usage is only implied: an agent can infer this is the inspection tool for a Worker's configuration. There is no statement of when to prefer it over list_workers, get_version, or update_worker_settings, and no prerequisites or failure conditions mentioned.

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

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

Annotations already declare read-only, idempotent, non-destructive behavior. The description adds useful output-shape behavior: one entry per module, single script for service-worker syntax, and no code for assets-only Workers.

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 followed by the key return-shape caveat. There is no filler or repetition.

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

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

For a simple one-parameter read tool, the description covers purpose and major output variations. It does not detail response structure beyond module entries, but no output schema exists, so a minor gap remains.

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 only parameter, script_name, is fully documented in the schema as 'The name of the Worker script.' The description does not add syntax or format details beyond that, so schema coverage carries the parameter semantics.

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

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

Uses a specific verb and resource: 'Download the source code of a Worker's live version.' It also clarifies the live-version scope and module-entry output, which distinguishes it from general Worker metadata tools.

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

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

The description implies when to use it by saying it downloads live Worker code, but it does not explicitly compare against siblings such as get_worker, get_version, or list_versions. No when-not guidance is provided.

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

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

The annotations already declare readOnlyHint=true and idempotentHint=true, establishing that this is a safe, read-only operation. The description adds value by specifying exactly what is verified (API token validity and connectivity), which goes beyond the annotations. No behavioral contradictions are present.

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

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

The description is extremely concise, consisting of two short, purposeful sentences. It front-loads the core action and immediately provides a practical use case. There is no redundant or extraneous information.

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

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

Given the tool's simplicity (no parameters, no output schema), the description fully covers all necessary context. It clearly states what the tool does and when to use it, making it complete for an agent to select and invoke correctly. No gaps are apparent.

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

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

The tool has zero parameters, so there is nothing to document in the description. The baseline for zero-parameter tools is 4, as the description need not compensate for missing schema coverage. The description's focus on the tool's purpose is appropriate.

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

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

The description uses a specific verb ('Verify') and clearly identifies the resource (API token and Cloudflare connection). This distinguishes it from all sibling tools, which focus on worker management, deployment, and domain operations. The statement is unambiguous and directly conveys the tool's function.

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

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

The description provides clear context for when to use the tool ('troubleshooting authentication issues'), which effectively signals the intended scenario. It does not explicitly name alternatives or when-not-to-use, but the unique purpose and sibling context make the usage clear without needing 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 readOnly, idempotent, and non-destructive, so the safety profile is covered. The description goes beyond that by disclosing result ordering (newest first) and the domain semantics — each deployment maps traffic percentages to versions and the newest is live — which materially helps an agent interpret output. It omits any mention of pagination or result bounds despite openWorldHint=true.

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 action front-loaded and zero redundant wording. Every clause (ordering, traffic mapping, live-ness) carries information an agent would otherwise have to guess.

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

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

For a single-parameter read tool with no output schema, the description covers what is returned conceptually and how to interpret it. The main remaining gap is volume/pagination behavior, minor given the tool's simplicity and read-only annotations.

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

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

Only one parameter (script_name) at 100% schema coverage, so the schema fully documents it. The description adds no extra meaning such as name formatting or whether a worker ID is accepted, which is the expected baseline for fully-covered schemas.

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

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

States a specific verb (list) and resource (a Worker's deployments) plus the ordering guarantee 'newest first'. It does not distinguish itself from adjacent siblings such as list_versions or list_previews, so an agent must infer which listing it needs.

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 the verb 'list' — there is no explicit statement of when to prefer this over list_versions or list_previews, nor of prerequisites (e.g., that the Worker must exist). The note that the newest deployment is the live one gives some context for interpreting results but not for tool selection.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds two pieces of context beyond that: the API is in beta (implying possible instability) and the returned URLs are stable. It does not describe pagination or result volume, which matters for an open-world list 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?

One short sentence that front-loads the action and resource, then adds the payoff (stable URLs) and the beta caveat in a parenthetical. No filler.

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

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

For a one-parameter read-only list tool with a fully documented schema and no output schema, this is nearly sufficient. The only meaningful gap is how results are returned or paged, which the description omits.

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

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

Schema coverage is 100% and the single script_name parameter is already documented by the schema. The description's 'a Worker's' reinforces that the parameter scopes to one script, but adds no format, naming, or ID-versus-name guidance 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?

States a specific verb and resource ('List a Worker's previews') and adds the useful detail that results carry stable URLs. It does not explicitly contrast itself with siblings like list_deployments or list_versions, so the agent must infer the distinction from the word 'previews'.

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 guidance and no mention of alternatives or prerequisites. The agent can infer it is the read counterpart to deploy_preview/delete_preview, but the description never says so or explains when a preview list is the right call versus deployments.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds genuinely new and important behavior: the response is limited to names and types because Cloudflare never returns secret values, which prevents an agent from expecting to read secret contents.

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 sentence, front-loaded with the action and resource, with the critical constraint placed in a parenthetical immediately after. 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?

There is no output schema, so the description must hint at the return shape, which it does by disclosing that only names and types are returned. For a one-parameter read tool with full annotation coverage, little else is needed, though a note on empty results or permissions would have made it fully 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 there is only one parameter (script_name) with its own description, so the schema carries the semantics. The description only implies that the resource is a Worker and adds no format or naming detail beyond that, which is the baseline for a fully documented single parameter.

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

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

States a specific verb and resource ('List the secret bindings on a Worker') plus the exact scope ('names and types only'). This is clearly distinguishable from set_secrets and delete_secret, though it does not name them explicitly, so it falls just short of the top tier.

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: an agent can infer this is the read-side counterpart to set_secrets/delete_secret and is the way to audit which secrets exist. There is no explicit when-to-use statement, no prerequisites, and no mention of 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, idempotentHint, and destructiveHint=false, so safety is covered. The description adds genuinely new behavioral facts: results are capped at the 100 most recent, returned newest-first, and versions are immutable snapshots — the last point being important context that explains why there is no update_version sibling to reach for.

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

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

Two sentences, both dense with non-redundant information: the first front-loads scope, ordering, cap, and returned fields; the second supplies the immutability caveat and the sibling hand-off. Nothing is padded or repeated from the title.

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

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

With no output schema, the description usefully enumerates the returned fields, and for a single-parameter read tool that is close to sufficient. The remaining minor gap is behavior when script_name does not resolve (empty list vs. error), which an agent might want to know.

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% for the single script_name parameter, so the schema already carries the semantics and the baseline applies. The description's phrase "a Worker's" reinforces the scoping but adds no format, naming, or lookup detail 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?

States a specific verb and resource ("List a Worker's ... versions") plus the exact scope: 100 most recent, newest first. The returned fields (version ID, number, author, source, deploy message/tag) further pin down what the tool yields, so an agent can distinguish it from get_version and create_version without opening any schema.

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

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

Explicitly routes the agent to list_deployments "to see which are live", a clear when-to-use-this-instead signal for the most likely confusion in this sibling cluster. It stops short of covering the other near neighbor, get_version, for retrieving a single version by ID, but the usage context is otherwise clear.

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

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

The annotations already declare this as read-only, idempotent, non-destructive, and open-world. The description adds account scoping and optional filtering, but it does not disclose return shape, pagination, auth requirements, or rate limits beyond what the annotations cover.

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

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

The description is two sentences with the primary purpose front-loaded and no wasted wording. The second sentence efficiently signals optional filtering without bloating the definition.

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

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

For a simple list tool with rich annotations and full schema coverage, the description is complete enough to understand what it returns in broad terms. It could mention pagination or return format, but those are minor gaps for this tool type and there is no output schema to defer to.

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

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

Schema description coverage is 100%, so the schema already documents all five filter parameters. The description names Worker name, hostname, and zone as filter dimensions, but it omits environment and adds no syntax or format detail 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 verb and resource: 'List custom domains attached to Workers in this account.' It is clearly distinct from mutation siblings like add_worker_domain and delete_worker_domain, but it does not explicitly route against list_workers or other list tools.

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

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

The description notes that filters are optional, which gives some usage context. However, it does not say when to choose this tool over list_workers or other domain-related siblings, and it provides no exclusions or prerequisites.

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

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

The annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is fully covered and the description rightly spends no words on it. It adds useful behavioral content by naming exactly what comes back, which matters because there is no output schema, but says nothing about pagination, ordering, or whether the listing spans all workspaces.

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 that packs the verb, scope, and the full field inventory with zero filler. Nothing redundant or padded.

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

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

For a zero-parameter read tool with no output schema, the description covers what an agent needs to decide to call it and what to expect back. The only real omission is pagination/result-size behavior for an account that may hold many workers.

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 and the baseline of 4 applies. The schema is an empty object and the description correctly does not invent parameter guidance.

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

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

The description uses a specific verb and resource ('List all Workers in your account') and enumerates the fields returned (name, timestamps, workers.dev/observability flags). The plural 'all' implicitly contrasts with the singular get_worker sibling, but 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?

Usage is only implied: an agent can infer this is the discovery/browse entry point before calling get_worker or get_worker_code. There is no explicit when-to-use statement, no mention of when to prefer get_worker for detail, and no note about result size or pagination.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so safety is covered. The description adds value beyond that by disclosing the observability prerequisite and the shape of returned events, though it omits retention limits and pagination behavior (both only in 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 front-loaded sentences with no filler: purpose, return shape, prerequisite in that order. Minor redundancy in the parenthetical '(Workers Logs / observability)' keeps it from a 5.

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

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

With no output schema, the description usefully enumerates returned fields, and it flags the enabling prerequisite. The only real gap is no guidance on the relationship to tail_worker for live tailing versus historical queries.

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 every parameter is documented in-schema with defaults and bounds. The description adds no parameter-level meaning such as filter interaction or cursor/filter-matching rules, 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 (query a Worker's logs) and names the underlying feature area (Workers Logs / observability), plus what the response contains (message, outcome, request, timing). It does not distinguish itself from the closely related sibling tail_worker, so it falls short of a 5.

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

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

The description gives a real prerequisite — observability must be enabled via deploy_worker's enable_observability or update_worker_settings — which is actionable context. However, it never says when to use this instead of tail_worker or get_worker, so the choice among log-related siblings is left to inference.

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

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

Adds real behavior beyond the annotations: the refusal conditions (staged version or gradual rollout pending) and the dedupe guarantee that unchanged files are not re-uploaded. It does not spell out the consequence of destructiveHint=true, i.e. that live traffic moves to the new version and what happens to the prior one, so a small gap remains.

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

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

Three dense sentences: capability first, then the exclusion with the sibling redirect, then the precondition. No filler, and the most decision-relevant information (what it is, what it can't do) is front-loaded.

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

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

For a two-parameter mutation with no output schema, the description covers scope, exclusions, and blocking preconditions well. It omits what the call returns (e.g. version or deployment identifier) and how the caller would verify or roll back the result, which would be useful since no output schema exists.

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

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

Schema coverage is 100%, so both parameters are already documented, including the YYYY-MM-DD format and default. The description only adds a rationale for compatibility_date via the 'bump compatibility_date' example; it adds no new syntax or constraint 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 chain and resource: create and deploy a new version of an assets-only Worker, reusing the live version's files and asset config. The qualifier 'assets-only' plus the explicit sibling reference to deploy_static_site lets an agent distinguish it from deploy_worker and deploy_static_site without opening schemas.

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

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

Gives a concrete use case ('e.g. to bump compatibility_date'), an explicit exclusion with a redirect ('cannot change html_handling/not_found_handling/base_path; use deploy_static_site for that'), and a precondition ('refuses while a staged version or a gradual rollout is pending'). When-to-use, when-not-to-use, and the alternative are all named.

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

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

Annotations already declare destructive=true, idempotent=false, openWorld=true, but the description adds material context beyond them: bound resources (KV, R2, D1 data) are NOT reverted, which is critical for an agent assessing blast radius. The force parameter's bypass behavior is documented in the schema rather than the description, so it isn't double-counted here.

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: the action and mechanism first, then the eligibility limit and the non-reverted resources. No filler, and the most consequential caveat is front-loaded where an agent will read it.

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, non-idempotent mutation with no output schema, the definition covers the essential risk surface (what is and isn't reverted, eligibility window). It would be stronger with a pointer to list_versions for discovering version_id or a note about required permissions.

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 every parameter carries a description, including the version_id recency constraint and force bypass rationale. The description only restates the recency limit, adding no syntax or format meaning 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 (roll back) and resource (Worker) plus the mechanism (deploying an older version at 100% traffic), which separates it from deploy_worker and redeploy_assets. It does not explicitly name those siblings, so sibling differentiation is implied 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?

Gives a concrete eligibility constraint (only the 100 most recent versions) that tells the agent when this call will succeed versus fail. It lacks explicit when-to-use-vs-alternative routing such as 'use deploy_worker to go forward' or 'use list_versions to find version_id'.

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 and idempotentHint, so the bar is lower; the description still adds material context by making clear this overwrites the entire set rather than appending, and that it fails if no scheduled handler exists. It stops short of stating permission requirements or what the response contains.

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, the replacement scope is front-loaded, and the empty-list case comes second — no filler.

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

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

For a two-parameter mutation with fully documented schema, the description covers the destructive replace semantics and the runtime prerequisite; the main residual gap is error behavior on Workers lacking a scheduled handler, which is only implied.

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 crons parameter description already says 'REPLACES ... pass [] to remove all triggers', so the description largely restates structured data. Only the scheduled-handler prerequisite adds meaning about how crons will be evaluated.

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 ('Replace a Worker's full cron trigger set') and makes the replacement scope explicit, which separates it cleanly from the sibling get_cron_triggers.

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 concrete usage rule ('Pass an empty list to remove all triggers') and a prerequisite ('the Worker must export a scheduled handler'), but never names the read counterpart or says when to use this instead of deploy_worker.

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

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

Annotations only flag destructive/openWorld/idempotent; the description adds what those hints do not: all changes collapse into ONE new version that is deployed immediately, unlisted secrets are untouched, values are never echoed back, and secret values transit the conversation (a real security caveat with a named escape hatch). This is exactly the behavioral context an agent needs before invoking a destructive, immediately-deploying write.

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 what the tool does and its blast radius, then the string/null mechanic, then the security caveat. Every sentence carries distinct information with no repetition of 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 two-parameter mutation with no output schema, the definition covers the blast radius (new version, immediate deploy), non-targeted bindings, deletion semantics, and the return-value behavior ('values are never echoed back'). Nothing needed to call it safely is missing.

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

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

The schema already documents both parameters at 100% coverage, including the string-sets/null-deletes semantics and the 'names not listed are left unchanged' rule. The description restates the string/null convention and adds little parameter-level meaning 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?

The description opens with a specific verb set (create/update/delete) and a precise resource (secrets on a Worker), and scopes it with 'without touching its code or other bindings'. That scope statement separates it from siblings like deploy_worker, update_worker_settings, delete_secret and list_secrets without the agent needing to open another schema.

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

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

It gives a clear usage context (bulk secret management in a single version) and an explicit alternative for a specific case: use `wrangler secret put` for highly sensitive values. It stops short of naming sibling tools such as delete_secret or list_secrets, so an agent still has to infer when the single-secret sibling is preferable to this batch operation.

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

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

Annotations already declare non-read-only, idempotent, non-destructive, open-world behavior, so the safety profile is covered. The description adds only the optional previews behavior, not whether disabling immediately takes the URL offline, whether auth or account-level permissions are needed, or how long propagation takes. Useful but shallow 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 that covers the enable/disable action, the target subdomain pattern, and the optional previews clause with no redundant wording. 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 simple three-parameter toggle with full schema coverage and annotations covering safety and idempotency, the description is nearly sufficient. The only meaningful omissions are the effect of disabling (traffic impact) and whether a response/state is returned, which are minor for this complexity level.

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 three parameters (script_name, enabled, previews_enabled) are already documented in the schema. The description echoes the same meaning without adding format details, defaults, or interaction rules (e.g., whether previews_enabled is meaningful when enabled is false). 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 states a specific verb pair (enable/disable) and a precise resource: serving a Worker on its <script_name>.<account>.workers.dev subdomain, plus optional preview URL serving. This clearly separates it from domain tools like add_worker_domain and from deployment tools. It stops short of explicitly naming the sibling it differs from, so it lands at 4 rather than 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?

Usage is implied by the wording: use this to toggle workers.dev serving. There is no explicit statement of when to prefer this over add_worker_domain (custom domains) or deploy_worker, and no prerequisites or exclusions such as 'only after deploying a script'. An agent can infer the use case but is not guided to alternatives.

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

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

Annotations already cover the safety profile (readOnly, non-destructive, openWorld), and the description adds real context beyond them: that observability need not be enabled, that capture is limited to the listening window, and that the live operation is inherently ephemeral. It stops short of covering output shape or what happens if the tail cannot connect, but it is well above the annotation baseline.

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 core behavior front-loaded, then the caveat about window-only capture, then the sibling disambiguation. Every sentence carries distinct information and nothing is repeated from 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 six-parameter tool with no output schema, the description still conveys what a caller receives (requests, logs, exceptions, outcomes) and the key operational constraint that only in-window traffic is seen. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so search, max_events, errors_only, script_name and duration_seconds are all documented in structured fields. The description only reinforces trigger_url (send a request once connected), adding no new semantics for the remaining parameters, so the baseline of 3 applies.

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

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

Names a specific verb and resource ("Live-tail a Worker") and immediately enumerates what is captured: requests, console logs, exceptions and outcomes. The closing sentence explicitly distinguishes it from the sibling query_worker_logs by contrasting live vs. historical logs.

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

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

States both when to use it (live, short-window capture during debugging) and the alternative for the other case ("For historical logs use query_worker_logs"). It also advises passing trigger_url because only window traffic is captured, which is actionable guidance for getting useful results.

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

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

Annotations declare destructive/idempotent but the description carries the real behavioral burden: bindings REPLACE the entire binding set (sharpening what 'destructive' actually destroys), existing secrets survive unless listed, and binding/compatibility edits deploy a new version. These are non-obvious side effects an agent cannot derive from annotations or schema.

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

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

Three sentences, front-loaded with purpose, then the most dangerous semantic (replacement), then preconditions. Every clause conveys a distinct constraint; nothing is redundant with the title.

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

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

For a six-parameter mutation with nested binding objects and no output schema, the description supplies the critical destructive semantics and the refusal preconditions. It stops short of saying what is returned (e.g., a new version id) or confirming that omitted settings are left untouched, which matters given no output schema.

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

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

Schema coverage is 83%, so the baseline would be 3, but the description adds replace-vs-merge semantics for `bindings` and the secret-preservation exception that the schema text alone does not convey. It leaves the partial-update behavior of omitted optional fields (logpush, observability) unstated.

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 (update a Worker's settings) and enumerates the exact settings surfaces covered: bindings, compatibility date/flags, logpush, observability. The clause 'without re-uploading its code' cleanly separates it from deploy_worker and create_version in the sibling list.

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

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

Gives a clear when-not condition ('refuses while a staged version or a gradual rollout is pending') and implicitly routes code changes to a deploy tool via 'without re-uploading its code'. It never names a sibling tool explicitly, so the alternative 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.