deed.page

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

Annotations already declare non-readOnly, destructive, idempotent, and openWorld, so the description adds value on top: it discloses the post-call state ('Status starts at pending_dns until DNS and the certificate are ready'), the exact artifacts returned, and quota limits. It does not explain why destructiveHint is set for an add operation (e.g. whether an existing hostname is overwritten), which is a minor gap.

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

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

Front-loaded with the action and its return value, then inputs, then state, quotas, and the rejection rule. Every sentence carries information, though the run-on DNS-record clause and the quoted input list make it slightly denser than necessary.

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

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

For a mutating tool with no output schema, the description covers the important return values (CNAME/A/ALIAS/TXT records), the resulting state (pending_dns), quota enforcement, and input rejection. Only the reason behind destructiveHint=true remains undisclosed.

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 (slug, token, domain) are already documented with format guidance and token semantics in the schema itself. The description only restates the input list, adding no format or edge-case 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?

States a specific verb and resource ('Attaches a hostname to a slug') and immediately clarifies the output (DNS records to create, split by subdomain vs apex). The reader can distinguish this from siblings like remove_domain, list_domains, and domain_status 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 concrete usage constraints: token sourcing, plan quotas (Free 1, Hobby 3, Pro 20), and an exclusion ('deed.page names are rejected'). It does not, however, explicitly route the agent to alternatives such as domain_status or remove_domain when the domain already 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=true, idempotentHint=false, openWorldHint=true), the description discloses genuinely valuable behavior: the HMAC secret is returned only once, deliveries are best-effort with up to 3 attempts, and private/internal/localhost targets are rejected. These are non-obvious operational facts an agent could not infer from the structured fields.

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

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

The purpose is front-loaded and the body is dense with specific facts (limits, security rejects, retry count) rather than filler. The "Inputs: url, optional events, and token" clause is mild redundancy against a 100%-documented schema, keeping it just under 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 steps in and states what comes back (webhook id and one-time HMAC secret), and it covers quotas, target restrictions, and delivery guarantees. An agent has everything needed to call this correctly and to set expectations about the response.

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 documents url constraints, the token fallback via Authorization header, and the event enum more precisely than the description does. The description's "Inputs: url, optional events, and token" largely restates the schema, so the baseline 3 is appropriate.

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

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

The description opens with a precise verb+resource ("Registers an http or https URL") and enumerates the exact event types the webhook subscribes to, so the agent knows exactly what this tool creates. It does not explicitly name or contrast with the sibling webhooks tools (list_webhooks, delete_webhook), so it falls one notch 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?

It gives real selection context: tier quotas (Free 1, Hobby 5, Pro 20), the rejection of private/internal/localhost targets, and delivery semantics, all of which inform whether the call is appropriate. It stops short of naming alternatives such as list_webhooks or delete_webhook for managing webhooks afterwards, so usage guidance is clear but not bounded by explicit 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 destructiveHint=true and idempotentHint=true, so the bar is lower. The description goes beyond them by disclosing the concrete consequence: custom hostnames are detached and the slug becomes available again for reuse.

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 primary action and consequence in two tight sentences. The trailing 'Inputs: slug and token' duplicates the fully-covered schema and is the one sentence that doesn't earn 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 destructive tool with no output schema, the description covers the key consequence (irreversibility and hostname detachment), and annotations carry the safety profile. Minor gaps remain around error/return behavior, but nothing critical is missing.

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

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

Schema description coverage is 100%, so both slug and token are already documented in the schema (including the deed_tok_ prefix and Authorization fallback). The description's 'Inputs: slug and token' merely restates them without adding 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 (permanently removes) and resource (a slug owned by the token), and even names the side effect (detaching custom hostnames). An agent can immediately distinguish this from get_site, update_site, or restore_version.

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 permanence is implied by 'Permanently removes,' which signals when this is appropriate versus the reversible restore_version. However, no explicit when-to-use guidance or named alternative is given, leaving the agent to infer that deletion should precede restore_version.

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=true, and readOnlyHint=false, so the safety profile is fully covered by structured data. The description adds nothing beyond restating the operation—it does not say whether deletion is permanent, what happens to queued deliveries, or what errors occur for an invalid id.

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 the operation front-loaded and no filler. The trailing 'Inputs:' clause is somewhat redundant with a 100%-documented schema, but it is brief and does not obscure the main 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 single-object delete with complete schema coverage and rich safety annotations, the description is minimally sufficient. It omits any mention of irreversibility, error behavior for a malformed or missing id, and post-deletion state, which would be useful 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%, so both parameters (id and token) are already fully documented in the schema, including the whk_ prefix and the optional Authorization fallback. The description merely echoes the id format, adding no meaning beyond the schema; baseline 3 applies.

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

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

The description states a specific verb (Deletes) and resource (one webhook), which is unambiguous against siblings like delete_site or revoke_token. It does not, however, explicitly differentiate itself from alternatives such as revoke_token or explain its relationship to list_webhooks.

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 delete a webhook versus revoking a token or other cleanup operations, and no note about needing to find the id via list_webhooks first. The user is left to infer usage entirely from the verb.

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 safety is covered; the description adds real value by enumerating the returned status values and noting an error carries a reason. Caveat: 'refreshes verification, DNS config, and certificate state' suggests a server-side side effect that sits in mild tension with readOnlyHint=true, though idempotentHint makes a re-poll interpretation plausible.

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 primary purpose, then return values, then error behavior. The 'Inputs:' sentence is redundant with a fully documented schema, but the rest of the text is dense and 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?

No output schema exists, so the description rightly covers return values (status enum, dns_records, error reason) and inputs. It is missing any routing guidance against sibling domain tools and does not clarify the refresh side effect, but for a 3-parameter status check 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%, so the schema already documents slug, token, and domain. The description only restates the same three names ('Inputs: slug, domain, and token') with no added format, defaults, or interaction detail, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Returns the verification status of a custom domain') and adds the refresh scope, which separates it cleanly from add_domain/list_domains/remove_domain. An agent can distinguish this status-check tool from its domain siblings without opening a schema.

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

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

Usage is only implied: you call this to poll verification progress after attaching a domain. No alternative is named and there is no explicit when-not guidance (e.g., use list_domains to enumerate, add_domain to attach). Adequate but inferential.

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=true, and readOnlyHint=false, so the safety profile is covered. The description adds real value beyond that: hash verification, content screening, slug locking, and the crucial 'writes nothing' guarantee on version_conflict, which tells the agent a failed call is safe to retry.

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 inputs, then failure modes in a tight three-sentence block with no filler. The 'Inputs:' enumeration partially restates the schema, which is the only minor 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 four-parameter mutation with no output schema, the description covers prerequisites (session id), concurrency handling (expected_version), and three named error outcomes. It omits what a successful commit returns (e.g., version identifier), which is the only meaningful 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 75%, and the one undocumented parameter, expected_version, is exactly what the description explains — a stale value yields version_conflict and no write. It also confirms the session format (upl_...). via and token semantics are already fully carried by the schema.

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

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

States a specific verb and resource chain: verifies hashes, screens bytes, and commits one version under the slug lock. This clearly separates it from plan_upload (which only plans) and publish_site, and the 'finalize' framing signals the terminal step of an upload session.

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 error cases imply this is the step taken after bytes are uploaded, but the description never explicitly says to call it after plan_upload or when to prefer publish_site instead. Usage is inferable from context rather than stated, which is the definition of implied 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 readOnly/idempotent/non-destructive, so the safety profile is covered; the description then adds real behavioral context beyond them: signature is null when no signing key exists, the public key discovery URL, and that no token is required. It doesn't address rate limits or failure modes, but adds solid value over structured fields.

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

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

Front-loads the return payload, then the inputs, then the auth/key-discovery detail in one compact, waste-free block. Every sentence (payload fields, nullable signature, key URL, no token) carries information the caller 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?

With no output schema, the description carries the full burden of describing the return value, and it does so thoroughly (field list plus signature nullability). Combined with the auth note and key-discovery URL, an agent has everything needed to call and interpret the result.

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

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

Schema coverage is 50%: the 'version' parameter is already documented in the schema as 'Omit for the live version', which the description largely repeats, while 'slug' remains undefined in both places. At this coverage level the description only marginally compensates, so a baseline 3 is appropriate.

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

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

States a specific verb (returns) and resource (canonical manifest for a site version) and enumerates the payload contents (paths, sha256, sizes, version, slug, created_at, Ed25519 signature). This is clearly distinguishable from siblings like get_site and list_versions 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?

Explains the conditional behavior of the optional version input ('When version is omitted, the result is the live site') and states that no token is required, giving the agent enough context to invoke it. It stops short of naming alternative tools (e.g., list_versions) or when-not-to-use guidance, so no explicit 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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds non-obvious context the annotations do not: that no authentication token is required, which is a real behavioral fact affecting invocation. It stops short of describing response format or error behavior for a missing slug.

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, front-loaded sentences with no filler: the return payload first, then the input and auth note. Every clause 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?

With only one required parameter at full schema coverage and no output schema, the description compensates by enumerating the returned fields (URL, version, size, timestamps) and flagging the auth requirement. A reader could call it correctly; only error/not-found behavior is unaddressed.

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 'slug' parameter, so the schema already documents it fully. The description only restates 'Input: slug' without adding format, casing, or lookup semantics, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Returns whether a slug is live, plus its URL, version, size, and timestamps'), enumerating the returned fields so the agent knows exactly what it gets. It is clearly distinct from listing siblings (list_sites, list_versions) and analytics tools, though it never names those siblings to differentiate 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?

'Input: slug' plus 'No token is required' gives a minimal usage cue, including a useful auth precondition. However, there is no guidance on when to prefer this tool over list_sites, get_manifest, or site_analytics, so the usage context is implied rather than stated.

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

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

Annotations declare readOnlyHint=true and openWorldHint=true, so the safety profile is already covered; the description adds the genuinely important nuance that 'the call does not charge' and payment occurs out-of-band on Stripe's page. That resolves the obvious confusion of a read-only tool producing a payment link. Link expiry or token-invalid behavior is not covered.

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

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

Three tight sentences, front-loaded with the return value and pricing before inputs and the no-charge caveat. The input enumeration is slightly redundant with the schema but is short enough to be harmless.

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 says the return value is a URL and explains that the charge happens elsewhere. For a two-parameter tool this is nearly complete; only error and link-lifetime behavior 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?

Schema coverage is 100% and both parameters already document their meaning and the Authorization-header fallback for token. The description's 'Inputs: plan (hobby or pro) and token' largely restates the schema, adding only the per-plan pricing, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Returns a Stripe Checkout URL'), names both plan options with prices, and scopes the result to the token. No sibling tool does anything billing-related, so an agent can immediately tell this is the upgrade path.

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 makes the use case clear (buying the Hobby or Pro plan) and clarifies the follow-up step: payment happens on the returned Checkout page. It doesn't state exclusions or prerequisites (e.g., whether an existing paid plan blocks the call), 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, idempotentHint, and destructiveHint=false, so the safety profile is fully covered. The description does add one genuinely useful behavioral note — that status reflects the last-checked value, i.e. it may be stale — but otherwise adds no extra behavioral context beyond the structured fields.

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

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

Three short sentences, scope behavior front-loaded, no filler. The 'Inputs: token, and optional slug' sentence is largely redundant with the schema, a minor 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?

No output schema exists, and the description names what is returned (custom hostnames) plus the meaning of the status field, which is adequate for a simple list tool. It could mention ordering or result size, but nothing essential to correct invocation is missing.

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

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

Schema description coverage is 100%, so both token and slug are already documented, including the fallback to the Authorization header. The description's restatement of the inputs and the omit-slug behavior adds nothing beyond what the schema already says; 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 ('Returns custom hostnames') and clarifies the two scope modes (one slug vs. every site on the token). It does not differentiate itself from the sibling domain_status, which an agent may reasonably confuse with a per-domain lookup.

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 scope rules: omit slug to list everything, supply slug to narrow. There is no explicit when-to-use guidance relative to domain_status, add_domain, or remove_domain, so the agent must infer routing from names 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, destructiveHint=false and openWorldHint=false, so the safety profile is covered externally. The description adds useful scope ('live sites owned by the token') and auth requirements (token or Authorization bearer header), but says nothing about pagination or result limits even though it lists potentially many sites.

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 result set front-loaded. The trailing 'Input: token, or an Authorization bearer header' duplicates the schema's parameter description almost verbatim, which is a minor waste of space.

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, unauthenticated-by-default listing tool with readOnly annotations and no output schema, the description covers scope and return content ('URLs and versions') adequately. It would be fully complete if it noted result volume or pagination behavior.

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 token parameter is fully documented in the schema, including the deed_tok_ prefix and the optional bearer-header alternative. The description merely restates that same token/bearer choice, adding no new 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 ('Returns every live site owned by the token') and adds return content ('with URLs and versions'), which distinguishes it from singular get_site. It does not explicitly name siblings like get_site or list_versions, 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 gives no when-to-use guidance and does not contrast this with alternatives such as get_site (one site) or list_versions (versions). Only authentication mechanics are mentioned, which is parameter-level rather than selection 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 readOnly, idempotent, and non-destructive, so safety is covered. The description adds genuinely new behavioral context: entries are ordered newest first, the shape of each entry, and the retention caps per plan (10/50/unlimited), which is critical for interpreting 'every retained version'.

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 operation and ordering, then the inputs, then the return fields, then retention limits. Every clause carries information, though 'Inputs: slug and token' is mild redundancy given the 100%-covered schema and could be cut.

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

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

No output schema exists, and the description compensates by enumerating the returned fields (version, created_at, file_count, bytes, kind, restored_from, permalink). Combined with the retention quotas and the newest-first ordering, an agent has everything needed to call and interpret this tool.

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

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

With 100% schema description coverage, the schema already documents both slug and token in more depth than the description ('Bearer token returned by your first publish'). 'Inputs: slug and token' restates the schema without adding syntax, format, or constraint detail, so the baseline of 3 applies.

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

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

States a specific verb and resource ('returns every retained version of a slug'), plus scope (owned by token) and ordering (newest first). This clearly separates it from the mutation sibling restore_version and from get_manifest, which returns a different artifact.

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: an agent can infer this is a read-only inventory call to run before restore_version, and the phrase 'owned by the token' hints at the auth scope. But there is no explicit when-to-use, when-not-to-use, or named alternative.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds one genuine behavioral detail beyond that — that secrets are excluded from the output — which is useful, but return format and pagination are not addressed.

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 padding; the scoping details come first. The trailing 'Input: token' is redundant given the schema, which keeps it just below a 5.

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

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

For a simple read-only list tool with no output schema, the description covers what is returned (URLs, no secrets) and the token input sufficiently. Nothing an agent needs to call it correctly is missing, though return ordering/pagination is unmentioned.

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 token parameter (format, optionality via Authorization header) is already fully documented in the schema. The description's 'Input: token' merely restates it and adds no syntax or format 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 ('Returns'/list) and resource ('webhook URLs registered for the token'), and clearly differentiates from siblings like create_webhook and delete_webhook. An agent can tell exactly what this tool 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?

Usage is only implied by the pairing with create_webhook/delete_webhook siblings; there is no explicit when-to-use statement, no prerequisites, and no named alternative for listing a different scope. Adequate but leaves the agent to infer 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 declare readOnlyHint=false, idempotentHint=false, destructiveHint=false, openWorldHint=true. The description adds real context beyond that: it is a preparatory step that 'does not publish by itself', it returns a session id for a later finalize, and it discloses the token/bearer auth path. It does not cover TTL/expiry semantics or rate limits.

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

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

Front-loads the most decision-relevant fact (what it returns) before the input list and applicability rules. Dense but every clause carries information; the input enumeration is somewhat list-heavy but earns its place given 8 parameters.

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 correctly supplies the return shape (stored hashes, upload URLs, session id), plus the trigger condition and the 'does not publish' caveat, which is the key mental model for a two-step upload. Remaining gaps are minor: what to do with the session id / which sibling finalizes, and TTL behavior.

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% and the strong per-parameter docs (via, slug, merge, token, expected_version, files item shape) already live in the schema. The description only re-lists parameter names and the manifest entry fields, adding little semantic meaning beyond the structured data. Baseline 3 applies.

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

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

States a specific verb+resource (plan a large upload) and, unusually, enumerates the return payload (already-stored hashes, per-hash upload URLs, session id). The phrase 'Does not publish by itself' implicitly separates it from finalize_upload/publish_site, so an agent can place it in the upload flow without opening the sibling 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 an explicit applicability condition ('files larger than about 4 MB, or when each sha256 is already known'), which tells the agent when this tool is the right entry point rather than a single-shot publish. It stops short of naming the alternative path for small/unknown-hash uploads, so the routing is implied rather than stated.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false and openWorldHint=true, and the description still adds substantial value: token is returned only on the first anonymous publish, a lost token is unrecoverable without a recovery email, version_conflict writes nothing, racing publishes conflict even without expected_version, and content_rejected/.bin/octet-stream screening rules. This is exactly the mutation-risk context annotations cannot express.

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

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

The purpose is front-loaded and each subsequent sentence carries distinct information about errors, tokens, and encoding. Mild waste in enumerating every input parameter, which duplicates the schema, but the overall density is high.

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

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

There is no output schema, and the description compensates by naming the return fields (url, path_url, slug, version, token) and the exact failure modes (version_conflict, content_rejected, slug_invalid/slug_reserved are schema-side). For an 8-parameter destructive publish tool with nested objects, an agent has what it needs to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, and the description mostly restates the parameter list already documented in the schema. It adds a little (paths stored exactly, slug semantics, first-publish token) but no syntax or format detail the schema lacks.

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 first sentence gives a specific verb and resource ('Publishes files to a live permanent URL at a slug'), which is far more concrete than the title alone. It never explicitly contrasts itself with close siblings like update_site, delete_site, or restore_version, leaving the agent to 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?

The description is rich in behavior but offers no when-to-use/when-not-to-use guidance or named alternatives; nothing tells the agent whether to publish_site vs update_site vs plan_upload/finalize_upload. Practical warnings (token recovery, version_conflict) inform risk but not 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 destructiveHint=true, idempotentHint=true, and openWorldHint=true, so safety/behavioral profile is covered. The description adds the concrete effect of removal, which is useful, but the slug precondition merely restates the schema rather than adding new behavioral context (permissions, irreversibility, re-adding).

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 tightly written sentences with the effect front-loaded. The 'Inputs: domain, optional slug, and token' clause partially repeats the schema, which is minor waste but not harmful.

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 conveys the effect but omits permission/auth requirements beyond the token, whether removal is reversible, and what happens on failure. Annotations carry the safety profile, so the gap is moderate rather than severe.

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 domain, slug, and token. The description's slug conditionality duplicates the schema text and adds no new syntax or format detail, making baseline 3 appropriate.

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

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

States a specific verb (removes) and resource (hostname/domain) and even describes the effect: 'requests to that host no longer serve the site.' This distinguishes it from add_domain, but it never names or contrasts with a 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 and no mention of alternatives (add_domain, domain_status, list_domains). The slug precondition is stated, but that is a requirement, not 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 cover the safety profile (destructiveHint=true, idempotentHint=false), and the description adds real behavioral context beyond them: the version_conflict guard on expected_version that results in nothing being written, and the retention behavior of the previous permalink. It does not explain auth/permission requirements or rate limits, but the added conflict and retention semantics are valuable.

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

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

Four tight sentences that front-load the core behavior before the input list and edge cases. No filler, though the trailing retention sentence is tangential to invoking the tool.

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

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

For a mutation tool with no output schema, the description covers the write effect, the concurrency guard, and the failure mode. It omits what the resulting version is named/returned and any permission requirements, but the essentials for correct invocation are present.

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

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

Schema coverage is 100% and the schema already documents each parameter, including that a mismatch returns version_conflict. The description largely restates the same semantic for expected_version and lists the inputs, so it meets the baseline without materially extending 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+resource ('creates a new version whose files equal a retained version') and a distinguishing mechanism ('without uploading those files again'). This clearly separates it from siblings like list_versions, get_manifest, and publish_site.

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 the scenario (copying a retained version forward) but never states when to choose this over alternatives such as re-publishing or uploading fresh files, nor prerequisites like needing a version discovered via list_versions. Usage is inferable but not 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 declare destructiveHint=true and idempotentHint=true, but the description goes well beyond them by disclosing the post-revocation error contract (401 token_revoked, distinct from 403 suspended), the fact that sites stay online, and the consequence that a revoked token cannot update sites without a recovery email. That is exactly the kind of downstream effect an agent needs before committing to a destructive call.

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

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

The description is dense, front-loaded with the core action, and nearly every clause carries information (scopes, error codes, side effects). The only slack is the "Inputs: token, and optional scope" clause, which restates what the schema already lists.

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 cover the return contract, and it does disclose the key failure mode (401 token_revoked vs 403 suspended) plus the effect on live sites. It stops short of describing the successful response shape, leaving a small gap for a mutation tool with 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 100%, so the baseline is 3, but the description adds real meaning the schema lacks: scope="all" also covers "any overlap window" of tokens, and it clarifies the distinction between the default current scope and the principal-wide behavior. It goes slightly beyond restating the enum.

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 ("Revokes owner tokens") and immediately defines what each scope value does, so the agent knows exactly what operation is performed. It does not, however, differentiate itself from the lifecycle sibling rotate_token, which is the closest alternative in the toolset — 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?

Usage is only implied: the scope semantics tell the agent which variant of the revocation to pick, but nothing states when an agent should revoke versus rotate a token, nor are prerequisites or alternatives named. There is no explicit "use this when…" or "use rotate_token instead when…" 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 cover the safety profile (destructiveHint=true, idempotentHint=false), and the description goes well beyond them: the previous token dies immediately when overlap is 0, both work during a non-zero window, the old token then returns 401 token_revoked, and the new secret is shown only once. That is exactly the destruction/one-time-secret context an agent needs.

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

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

Front-loaded with the core action and outcome, then the parameters, then the failure semantics in four short declarative sentences. The only mildly redundant clause is the restated 0-300 range, which does not meaningfully dilute the entry.

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

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

No output schema exists, and the description compensates by stating the return value ('the new token is returned once'). Combined with the annotations, parameter docs, and error semantics, an agent has everything needed to call this destructive, non-idempotent operation 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 both parameters are already documented, including the 0-300 range and the Authorization-header alternative. The description restates the range and optionality without adding syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb+resource: issues a new token for the same principal, with the scope qualifier that every site carries over. An agent can distinguish it from revoke_token (which invalidates) and from publish_site without another lookup.

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 context is implied rather than stated: the overlap_seconds rationale ('so an in-flight deploy can finish') tells the agent when a non-zero window matters, but nothing says when to rotate versus revoke, or whether rotation is safe to call repeatedly. No alternative is 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 and idempotent=true, and the description adds genuinely new behavior: the write is a scrypt hash stored on the site record, no outside system is contacted, and plan gating produces a specific plan_required error. It also explains that clearing removes the hash (making the site public), which is the destructive action the annotation only flags abstractly.

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

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

Every sentence carries load: what changes, what the inputs are, the password constraint, the storage mechanism, and the plan gating. The core action and inputs are front-loaded, and there is no filler or 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 three-parameter mutation with no output schema, the description covers the action, the value constraints, the side effect (hash written or removed), the absence of external calls, and the plan-dependent error. 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 baseline is 3, and the description goes beyond the schema by adding the 8-to-200-character length constraint on password and restating the null-clears semantics in behavioral terms. The token parameter's optional-if-header behavior is only in the schema, so it is not fully redundant, but the description does not elaborate on it.

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

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

States a specific verb and resource: it changes the stored access setting (password) for a slug on deed.page, and clarifies the mechanism by saying it writes or removes a scrypt hash on the site record. That is far more precise than the sibling update_site, but the description never names or contrasts with update_site, so an agent must infer the boundary 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?

Gives concrete call conditions: setting a password requires Hobby or Pro and Free returns plan_required, while clearing is allowed on every plan. This is real when-to-use context with a documented failure mode, though it offers no explicit guidance on when to prefer this tool over update_site or delete_site.

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, idempotentHint true), and the description still adds meaningful context: cookieless design, owner-only authorization, the 90-day retention window, and the privacy guarantee that no raw IP or full user agent is stored. The note that the accuracy field describes under-counting is real behavioral disclosure an agent needs when interpreting results.

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

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

Three tight sentences, front-loaded with what is returned before inputs are mentioned. Every clause carries information: no restating of the title, 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 no output schema, the description carries the burden of describing the response and does so (per-day views, top paths, top referrers, crawler families) plus the accuracy caveat. Combined with full schema coverage and safety annotations, an agent has everything needed to invoke and interpret the call.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds the 'maximum 90' range constraint that the schema omits and restates the from/to defaults in terms of the last 7 days, which clarifies how the two date params interact. The token parameter's fallback to Authorization: Bearer is covered in the schema rather than 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 (Returns) and resource (cookieless analytics counts for a slug) and enumerates the returned dimensions: views per UTC day, top paths, top referrer hosts, and AI crawler counts by user-agent family. No sibling tool returns analytics, so the agent can disambiguate this from list_sites/get_site purely from the description.

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

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

Gives clear operating context: 'owner-only' establishes the prerequisite, defaults are spelled out (last 7 days), and a hard cap (maximum 90 days) is stated. It doesn't name any when-not condition or alternative tool, but no sibling provides comparable analytics, so there is little to exclude.

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 (destructiveHint, idempotentHint) by disclosing optimistic-concurrency behavior: a mismatched expected_version yields version_conflict and nothing is written, and two racing updates also return version_conflict rather than silently dropping files. That atomicity/conflict contract is exactly the kind of behavior an agent cannot infer from structured fields.

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

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

Front-loaded with the core replace/merge distinction, then conflict semantics; no filler. The 'Inputs: slug, files, and optional ...' enumeration is mildly redundant given the schema but is short and scannable.

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 names the return payload (url, path_url, slug, new version) and the primary failure mode, which is what an agent needs. It is silent on other failure modes (invalid slug, reserved slug) and on overwrite/destroy scope beyond the merge wording, so it is strong but not exhaustive for a 7-param destructive tool.

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

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

Schema description coverage is 100%, so every parameter (spa, via, slug, files, merge, token, expected_version) is already documented in the schema. The description's input list and merge/conflict notes largely restate 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: replaces the files of a slug owned by the token, and spells out the two write modes (full replace vs merge). An agent can tell what it does without opening the schema, though it never names a sibling (e.g. publish_site) to disambiguate the write path.

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 through the merge flag semantics; there is no explicit when-to-use-this-vs-publish_site/restore_version guidance and no stated preconditions beyond token ownership. Adequate but leaves tool selection 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 declare readOnlyHint=true, openWorldHint=false, destructiveHint=false, so the safety profile is fully covered by structured data. The description adds the returned field set, which is genuine value, but says nothing about auth failure behavior, rate limits, or what happens with an invalid token.

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 useful payload (what is returned) and ending with the input requirement. Compact with minimal waste, though 'Input: token' is a slightly awkward tail that mostly repeats 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?

With a single optional parameter, full schema coverage, and annotations covering the read-only, non-destructive profile, the description supplies exactly the missing piece: the shape of the response. No output schema exists, so enumerating plan, limits, site count, and hostname count is the right call.

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 explains the token format (deed_tok_...), the publish-time origin, and the optional fallback to the Authorization header. The description's lone 'Input: token' adds no new information beyond that, but with full schema coverage the baseline is 3 and there is no gap to 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?

Specific verb (returns) plus enumerated resource details (plan, limits, site count, custom hostname count). It reads clearly as the account/token introspection tool and is distinguishable from siblings like list_sites or get_site, which operate on sites rather than the token's own plan/quota.

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 name whoami and the content of the response imply this is a diagnostic/token-info call, so usage is reasonably inferable. But there is no explicit guidance on when to reach for this versus revoke_token, rotate_token, or list_sites for inspecting account state.

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