deed.page

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

Annotations only declare the safety profile (destructive, idempotent, openWorld); the description goes well beyond by disclosing the return payload (CNAME for subdomain, A or ALIAS for apex but not both, all TXT records), the pending_dns status lifecycle, and the badge_note/upgrade_pitch fields with instructions to pass them to the human exactly once. These are non-obvious behaviors an agent cannot infer 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?

The core action and returned DNS records are front-loaded in the first sentence, with constraints following. The later sentences on badge_note and upgrade_pitch are dense and edge-case heavy, but each carries an instruction the agent must act on, so the length is largely justified.

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

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

With no output schema, the description carries the full burden of explaining returns, and it does so thoroughly, including conditional extras and error behavior. The one gap is that it says status stays pending_dns until DNS and the certificate are ready but never points the agent to domain_status for verification, leaving the follow-up step implicit.

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 by noting that the domain value may be a subdomain or an apex and that this choice determines which DNS record type is returned. The mention of slug/domain/token as inputs is redundant, but the apex-versus-subdomain distinction is genuine added value.

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 distinguishes the operation from siblings like list_domains, domain_status, and remove_domain by describing the attach action and its DNS side effects. An agent can identify this as the create path for custom domains without opening the schema.

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

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

Gives clear preconditions and exclusions: deed.page names are rejected, Free allows 1 hostname, Hobby 3, Pro 20, and a Free token denied a 2nd hostname gets a specific error. It doesn't explicitly route the agent to siblings such as domain_status for polling or remove_domain for detaching, so the when-to-use guidance is contextual rather than exhaustive.

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 flag destructiveHint=true and readOnlyHint=false, and the description adds the material specifics: revoked seats don't touch the others, the new seat token is returned only once and cannot be re-fetched, seats share the owner's sites, and seat tokens are blocked from rotation, global revoke, seat management, recovery-email changes and billing. It also documents the plan_required error path for Free/Hobby callers and the upgrade link to surface to a human.

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

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

The Pro-only gating and the one-time token return are front-loaded, and nearly every clause carries new operational information. It reads as one long run-on paragraph, though, so a small structural tightening (bulleted actions) would improve scanability without losing content.

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 still tells the agent what comes back (a list of seats; a one-time seat token on create) and what happens on failure (plan_required plus an upgrade link). For a 4-parameter, plan-gated management tool this covers everything needed to call it correctly.

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

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

Schema coverage is 100% and the schema already labels label/seat_id as create-only/revoke-only, so the baseline is 3. The description adds genuine meaning beyond the schema by tying token type to authorization scope ('the owner token revokes any seat, a seat token only itself') and noting the seat token is returned exactly once, which affects how the agent handles the response.

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 resource (named agent seats on a Pro account) with concrete scope (up to 5, each with its own token sharing the owner's sites) and the three operations it performs. An agent can distinguish this from the sibling revoke_token/rotate_token tools because the description explains seats are separately revocable and that seat tokens cannot rotate or revoke all tokens.

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

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

It gives explicit per-action prerequisites: 'list' works with any token, 'create' needs the owner token plus a label, 'revoke' needs seat_id and the owner token to revoke any seat or a seat token for itself. What's missing is an explicit 'when not to use this' pointer to siblings (e.g. use revoke_token for a single token), so it stops short of a 5.

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

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

Goes well past the annotations: it discloses the concrete side effects (limits rise by 25 sites and to 50 MB per site, badge turned off for 30 days), the day-3 re-check that can revoke the badge, and the automatic restoration after 30 days. The 'each one-time' grants are consistent with idempotentHint=false and destructiveHint=false, so no contradiction.

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

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

Purpose and the 'Free plan only' constraint are front-loaded, and most sentences carry real policy weight (eligibility, revocation, posting consent rules). It is dense and run-on in places, and the final 'Inputs: url and token' clause is redundant with 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 no output schema, the description still covers what matters: return handling ('Show the returned user_message, which includes the Hobby link'), side effects, revocation timing, and the human-approval requirement before posting. An agent has everything needed to invoke it responsibly.

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

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

Schema coverage is 100% and both parameters are already documented, including the X-vs-Reddit distinction and the bearer-token fallback. The description's only addition is the trailing 'Inputs: url and token', which restates the schema rather than adding format or validation detail. Baseline 3 is correct here.

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

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

States a specific verb+resource ('claim the share credit' and 'badge-free month') scoped to 'Free plan only', and the opening sentence tells an agent exactly what input it needs (a public X/Reddit post URL). It is unmistakably distinct from siblings like set_badge or get_upgrade_link.

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

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

Explicit eligibility gates are given: free plan only, post must be public, mention/link deed.page, be within 30 days, and be unclaimed; it also explains the repeat-claim case for a token that already has the credit. It routes to the Hobby plan as the paid alternative but does not name the sibling tools (set_badge, get_upgrade_link) that would implement that path.

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=true, idempotentHint=false) by disclosing that the HMAC secret is returned only once, that delivery is best-effort with a specific 3-attempt retry schedule (immediate, 500ms, 2s), that HTTP 2xx terminates the loop, that non-public targets are not retried, and that each attempt has a 5s socket timeout. This is exactly the operational context an agent needs and no annotation contradiction exists.

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

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

Front-loads the registration purpose and inputs, then layers limits and delivery semantics in short declarative sentences. Dense but each sentence carries operational value; the trailing docs URL is the only 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 mutating, non-idempotent registration tool with no output schema, the description covers quotas, target restrictions, retry/timeout behavior, and return values (webhook id plus one-time HMAC secret). An agent can call it correctly without consulting external docs.

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 url, token, and events are already fully documented, including enum values and 'omit for all'. The description restates the inputs and adds plan limits, but does not add syntax or clarify the distinction between the input bearer token and the returned HMAC secret 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 ('Registers') and resource (an http/https URL for a webhook) plus the exact event set, so an agent immediately distinguishes it from list_webhooks and delete_webhook. The scope of what is being created 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?

Gives practical preconditions: plan-based webhook quotas (1/5/20) and the rejection of private, internal, and localhost targets. It does not explicitly name sibling alternatives or say when to use list_webhooks/delete_webhook instead, but the creation framing makes those choices obvious.

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, yet the description adds genuinely new consequences: permanence, hostname detachment, and the slug becoming reusable. It does not cover auth failure modes or how to recover a deleted site, so it stops short of a 5.

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

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

The irreversible consequence is front-loaded in the first sentence and the total length is three short sentences. The final 'Inputs: slug and token' line is redundant with the schema and does not 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 two-parameter tool with no output schema, the description supplies the key consequences (permanent, hostnames detached, slug freed). Missing only failure behavior, such as what happens when the slug does not exist or the token is invalid.

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

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

Schema description coverage is 100%, so the baseline is 3. The trailing 'Inputs: slug and token' merely restates parameter names and adds no semantics beyond the schema's own ownership and bearer-token text.

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 removes a slug'), and adds distinguishing detail that it detaches custom hostnames, which separates it from remove_domain and delete_webhook. It never names a sibling explicitly, 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 implied by 'permanently removes ... owned by the token', but there is no explicit when-to-use or when-not-to-use guidance, and no pointer to alternatives such as update_site or set_site_access for non-destructive changes.

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 disclose that the operation is not read-only, not idempotent, not destructive, and open-world. The description adds meaningful behavioral detail beyond that: it writes the refreshed status, returns status values (pending_dns, verifying, issuing_cert, active, error), includes dns_records and error reasons, and notes that a transition to active can notify a domain.active webhook. These additions are consistent with the annotations.

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

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

The description is front-loaded with the core action and then efficiently lists output states and side effects. Most sentences earn their place, though the 'Inputs: slug, domain, and token' sentence is somewhat redundant given the fully described 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?

Because there is no output schema, the description carries the burden of explaining return values; it does so by naming the status values, dns_records, error reason, and webhook side effect. It is nearly complete for an agent to call and interpret the tool, though it does not describe the exact response shape.

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

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

Schema description coverage is 100%, so slug, token, and domain are already documented in the input schema. The description merely restates that slug, domain, and token are inputs and does not add syntax, format, or conditional meaning 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 uses a specific verb and resource: refreshes verification, DNS, and certificate state for a custom domain, then stores and returns it. This clearly distinguishes the tool from siblings such as add_domain, list_domains, and remove_domain, which manage domains rather than refresh their live status.

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 tool is used to check or refresh an existing custom domain's status, but it does not explicitly state when to use it versus list_domains or after add_domain. No alternatives or exclusions are named, leaving the agent to infer the workflow 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 destructiveHint=true, idempotentHint=true and openWorldHint=true; the description adds real substance on top by disclosing the slug lock, the all-or-nothing semantics ('writes nothing' on stale version), and three named error outcomes with their triggers. It stays consistent with the annotations — committing a version is both destructive and idempotent per the hints. It doesn't say whether the session is consumed after success.

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 action clause followed by a compact inputs list and a terse error table; nearly every clause carries information. The 'Inputs:' enumeration is the one segment that mostly duplicates 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 destructive, no-output-schema commit tool, the description covers the locking model, atomicity, and the three failure outcomes an agent must branch on. The remaining gap is what a successful response returns and whether the upload session survives it, which matters for retry logic.

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

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

Schema coverage is 100%, so all five parameters are already documented in the input schema, including the redaction and header-override rules. The description's 'Inputs:' list largely restates that, adding only the expected_version-to-version_conflict mapping, which the schema also states. Baseline 3 fits.

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 concrete three-step verb chain — checks hashes, screens bytes, commits one version under the slug lock — so the agent knows this is the terminal step of a write flow, not a read or a plan. It never names plan_upload, so the boundary with the closest sibling is only inferable from the word 'commits'.

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 'upl_...' session prefix and the commit framing imply this runs after a planned upload, and the three named failure modes sketch the preconditions. But there is no explicit 'call this after plan_upload / after uploading parts' instruction and no statement of when not to use it or what to do instead on failure.

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 readOnly/idempotent annotations by disclosing the null-signature edge case when the server has no signing key, the URL where verification keys live, and the no-token auth requirement. These are exactly the facts an agent needs before trusting the returned signature.

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 behavior, then inputs, then auth — a sensible order with no filler. Minor waste in the 'Inputs:' sentence, which duplicates 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 no output schema, the description correctly enumerates the manifest's fields and the nullable signature, plus the key-publication endpoint. Nothing an agent needs to call it correctly or interpret the result is missing.

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

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

Schema coverage is 100%, and the schema already describes slug and version including the omit-for-live behavior. The description's 'Inputs: slug, and optional version' largely restates that, adding no new syntax or format detail.

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

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

States a specific verb and resource ('Returns the canonical manifest for a site version') and enumerates the payload fields, which clearly separates it from list_versions or get_site. It never names a sibling explicitly, so differentiation is inferred from content 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?

Clarifies the key decision point ('When version is omitted, the result is the live site') and removes an auth question with 'No token is required.' It does not say when to prefer this over list_versions or get_site, so there is clear context but 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 readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description meaningfully adds that no token is required and enumerates exactly what is returned, which matters because there is no output schema; it does not cover error behavior for an unknown 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?

Three short sentences, front-loaded with the return payload and no filler. 'Input: slug' is mildly redundant with the schema but the phrasing is tight overall.

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 carries the burden of describing return fields, and it notes the auth situation. For a one-parameter read tool this is close to complete, missing only failure behavior for a nonexistent slug.

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

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

Schema coverage is 100% and the single parameter is documented in the schema, so the baseline of 3 applies. The description's 'Input: slug' merely restates the schema without adding format or lookup-resolution details.

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 (returns) and a specific resource (a site's liveness plus URL, version, size, timestamps), which an agent can easily distinguish from list_sites or delete_site. It stops short of naming a sibling explicitly, but the field-level detail makes the scope 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?

Usage is only implied — an agent can infer this is the single-slug lookup versus the listing tool, but there is no explicit statement of when to prefer it over list_sites or get_manifest, and no exclusions or prerequisites beyond the token note.

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 say readOnlyHint=false and openWorldHint=true, so this is a mutating external call. The description adds substantial context beyond the annotations: the call itself does not charge, an open checkout returns the same session (session_reused:true), upgrade_url lasts 30 days while checkout_url lasts 24 hours, paid-plan tokens return portal_url, and the token's plan.id updates after payment. The 100% schema coverage means the description's extra behavioral detail matters more than restating input params.

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 key trigger and safety rule (never pay without approval) come first, which is good, but the description runs long and mixes core mechanics with marketing copy (platform link, support email, detailed plan-limit lists). The plan-comparison section is useful, yet the density makes it hard to scan and some of the badge and Pro benefits text feels 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?

There is no output schema, so the description must describe returns: upgrade_url, checkout_url, session_reused, portal_url, plan_options, and the token's plan.id afterward. It does this, leaving little ambiguity for an agent, though the sheer volume means some edge behavior (e.g., what happens if token and slug mismatch) 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%, so the baseline is 3, but the description still adds meaning: omitted plan means the next plan up, plan=clean requires slug because it is a $9 one-time per-site purchase, how_heard maxes at 200 characters and is stored on the owner, and upgrade_trigger should carry the limit field from the error. These details make the enum/optional behavior more actionable than the schema alone.

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: "Creates a Stripe Checkout URL that upgrades this token's owner to Hobby ($3/mo) or Pro ($15/mo)." It also covers the clean-publish variant and clearly separates this tool from siblings like set_badge or 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?

It states exactly when to call (user asks to upgrade, or after a plan-limit error with upgrade_url/user_message), when not to pay without explicit human approval, and the alternatives: portal_url for already-paid tokens, and plan=clean for a one-site badge removal versus hobby/pro subscriptions. It also gives plan-recommendation logic (Hobby vs Pro) so the agent can choose.

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, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds two genuinely useful facts beyond that: the result is scoped to 'live' sites only, and auth may arrive either as a parameter or a bearer header. It says nothing about pagination, ordering, or behavior with an expired 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 short sentences with zero waste: the return content and scope come first, the auth fallback second. Nothing is repeated 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 single-optional-parameter read tool with full annotation coverage, the definition gives enough to call it correctly: what comes back (URLs and versions), which records are included (live only), and how to authenticate. Without an output schema, a bit more on result shape or empty-list behavior would be nice but is not essential.

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 description's single parameter remark ('token, or an Authorization bearer header') restates what the schema property already explains in more detail. The baseline of 3 applies since the schema does the heavy lifting.

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

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

The description states a specific verb and resource ('Returns every live site') plus the payload shape ('URLs and versions'), which cleanly separates it from get_site, list_domains and list_versions. It stops short of naming any sibling explicitly, relying on scope wording alone to differentiate.

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

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

There is no explicit when-to-use guidance and no mention of when not to use it or which sibling to prefer for a single-site lookup (get_site) versus a domain listing (list_domains). The only actionable hint is the authentication input format, which is invocation detail, 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?

Goes well beyond annotations, which already declare readOnly/idempotent/non-destructive. It discloses plan-based retention caps (Free 10, Hobby 50, Pro uncapped), what removes a version (pruning, deletion, site deletion), cache staleness, v1 URL reuse, and the explicit caveat that this is not a permanent archive.

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

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

Front-loads the core return description, then enumerates entry fields, then the retention caveats. It is somewhat dense but each sentence (caps, pruning, cache, URL reuse) carries real information rather than padding.

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

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

With no output schema, the description compensates by enumerating the returned entry fields (version, created_at, file_count, bytes, kind, restored_from, permalink). Combined with the stability and pruning notes, it is complete for an agent to call and interpret results 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 slug and token are already documented in the schema. The description's 'Inputs: slug and token' merely restates them and adds no format or constraint 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: returns every retained version of a slug owned by the token, newest first. The scope ('retained') and ordering distinguish it clearly from siblings like get_manifest and 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 retention and pruning notes hint at when the list is useful, but there is no explicit when-to-use guidance or named alternative (e.g., restore_version, get_manifest). Usage must be inferred from the retention discussion.

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?

Since no output schema exists, the description usefully discloses the return shape (per-hash upload URLs, session id, ready-made curl commands) and the operational constraint to run from the site folder with $DEEDPAGE_TOKEN. That goes well beyond the annotation set (readOnlyHint=false, destructiveHint=false, openWorldHint=true). It omits session/URL expiry and what happens if a PUT fails, which matters for a multi-step upload workflow.

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 most decision-relevant fact—what comes back—followed by inputs, eligibility threshold, and workflow caveat. Every sentence is functional, though the enumerated input list is largely redundant against a fully documented 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 9-parameter, no-output-schema tool, the description supplies the missing return contract, the size/hash preconditions, and the fact that a finalize step is still required. An agent has enough to decide whether to call it and how to proceed afterward; residual gaps (expiry, retry behavior) are secondary.

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 every parameter including the nested file entry shape. The description's 'Inputs:' sentence mostly restates the parameter list and the {path, sha256, size, content_type?} shape without adding semantics such as how merge interacts with expected_version. Baseline 3 applies when the schema carries the load.

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

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

States a concrete verb and resource ('accepts a file manifest and returns which hashes are already stored') and enumerates the exact return payload: upload URLs, session id, and curl commands. It also separates itself from publishing ('Does not publish by itself'), which distinguishes it from publish_site and finalize_upload.

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 activation threshold: 'Applies when the files are larger than about 4 MB, or when each sha256 is already known.' It also warns 'Does not publish by itself,' which tells the agent another step is required. It does not name the alternative sibling (publish_site for small files, finalize_upload for completion) explicitly, leaving the agent to infer it from 'the last line finalizes the upload.'

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 version_conflict semantics (including racing publishes without expected_version), content_rejected for malware/tunnel redirects/credential harvesting, the acceptable-use policy, that .bin is blocked by file type, that a lost token is unrecoverable, and the badge-removal upsell rule requiring human approval before payment. Annotations only mark it destructive/open-world; the description supplies the actual risk and failure surface.

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 long undifferentiated paragraph that front-loads a redundant parameter inventory while burying the operationally critical 3.5 MB limit and the plan_upload alternative at the very end. Content policy, billing upsell, token recovery, and file-type screening are interleaved with no structure, and 'listed defaults to false' duplicates a constraint also stated in 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 15-parameter write tool with no output schema, the description compensates by naming the return fields (url, path_url, slug, version, listing, analytics_url, token), documenting the domain-specific URL shape, and covering the main error outcomes. An agent has what it needs to call this correctly or to route to plan_upload.

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

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

Schema coverage is 100%, so the schema already documents every parameter in depth; the description mostly restates the parameter names in a list. It adds a small amount of extra meaning (listed defaults to false keeps the slug out of the gallery, password-protected sites cannot be listed, a recovery email may be attached to a token), but most of the semantics live in the schema.

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

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

Opens with a specific verb and resource ('Publishes websites... to a public HTTPS URL at a slug') and enumerates the content types it accepts (games, demos, reports), which distinguishes it from siblings like update_site or set_listing that modify metadata rather than content.

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

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

Gives an explicit when-not and names the alternatives: 'If the files total more than about 3.5 MB, do not call publish_site. Call plan_upload, run `commands`, then finalize_upload.' It also implies the merge path for updating existing paths. What is missing is routing guidance against siblings such as update_site or set_listing for metadata-only changes.

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 already flag destructive and non-idempotent, and the description adds real context beyond them: no file re-upload, the operation is conditional (version_conflict with 'nothing is written', implying atomicity), and the previous permalink keeps serving while the version is kept. It does not explain why the tool is flagged destructive or what the successful result looks like.

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 mechanism is front-loaded in the first sentence, followed by the conflict rule and the permalink consequence; no filler. The trailing permalink sentence is dense but earns its place by explaining live-site behavior.

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

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

For a 4-parameter mutation tool with no output schema, the description covers the mechanism, the failure mode, and the side effects on the live site. The main remaining gap is what a successful call returns (new version identifier?), which an agent would need to chain further calls.

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

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

Schema coverage is 100%, so the schema already documents all four parameters including expected_version's conflict behavior. The description's 'Inputs:' list largely restates the schema and adds no syntax or format detail beyond it, 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 ('Creates a new version whose files equal a retained version') plus the key differentiator 'without uploading those files again', which separates it from publish_site, plan_upload and finalize_upload 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?

Usage is implied: this is the path when you want a previously retained version's file map live again. The conflict condition for expected_version is spelled out, but there is no explicit when-not guidance and no alternative tool named (e.g., when to publish_site fresh instead).

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

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

Annotations 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?

Beyond annotations, it discloses the plan_required error contract, the upgrade_url in message/user_message, the grandfathered exception (badge off before 2026-10-25 is kept), the return payload, and clarifies it writes only the setting and contacts no outside system. This is rich behavioral context that annotations alone (readOnly=false, idempotent=true) cannot convey.

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

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

Front-loads the core distinction (Free shows badge, Hobby/Pro never) before the mechanics, so a reader gets the gist immediately. It is a single dense block with minor redundancy ('show true shows it again' echoed) and a slightly run-on error sentence, but little is wasted.

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

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

For a mutation tool with no output schema, the description still specifies the return value (stored setting and whether shown), the error path, and the no-outside-contact guarantee. 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 description coverage is 100% and each property already documents its meaning and plan behavior, so the schema carries the load. The description's extra param detail (slug scope, token optionality with Authorization header) largely restates the schema, so baseline 3 is appropriate.

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

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

States a specific verb+resource ('set_the_badge'-style operation on the published-with badge) and distinguishes behavior by plan tier. An agent can immediately tell this controls badge visibility on deed.page, unlike any sibling tool.

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

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

Explicitly explains scoping: 'With slug, the setting applies to that site; without slug, it applies to every site of the token.' It also spells out the plan-dependent outcomes (Free refused, Hobby/Pro no-op) with a concrete do-not-retry directive on plan_required, leaving nothing to inference.

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

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

Beyond annotations, the description explains that listed false removes the slug from the gallery immediately, password-protected sites cannot be listed, new site versions re-run gallery checks, and text may be moderated via deed.page and the OpenAI moderation API. This adds meaningful side-effect, eligibility, and validation context for a destructive mutation.

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

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

The description is front-loaded with the main action and then covers inputs, returns, removal behavior, eligibility, and moderation checks. It is appropriately sized for the tool's complexity, though some summarized parameter details duplicate 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 seven parameters, no output schema, and rich annotations, the description supplies the missing return-field overview, conditional requirements, immediate-removal behavior, and listing constraints. It gives an agent enough context to invoke the tool correctly.

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

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

Schema coverage is 100%, so the schema already documents parameters, enums, and constraints. The description summarizes conditional requirements and the token, but largely repeats what the schema provides rather than adding substantial new 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?

The description names a specific verb and resource: setting or clearing a public gallery listing for a slug. It is distinct from sibling tools like set_badge or set_site_access, and an agent can identify the operation without opening the schema.

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

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

The description gives clear conditions: listed true requires category/title/description, listed false removes the slug immediately, and password-protected sites cannot be listed. It does not explicitly compare against alternatives, but no obvious sibling alternative exists and the usage context is well 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?

Goes well beyond the annotations by saying exactly what is mutated (a scrypt hash written into or removed from the site record), that no outside system is contacted, and how plan gating fails with the plan_required error. With destructiveHint=true already flagged, this tells the agent the concrete effect of the destructive path, which is the useful part.

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

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

Four tight sentences, front-loaded with the action and effect before constraints. The 'Inputs: slug, password, and token' clause is the only mildly redundant piece against a fully documented schema, but it is short and orients the reader.

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

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

Covers mutation effect, auth source, and plan-gated failure, and annotations carry the safety profile, so an agent can call it correctly. With no output schema, it never indicates what a successful response looks like, which is the remaining gap.

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

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

Schema description coverage is 100%, so the schema already documents slug, token, and password including the clear semantics. The description restates the input list and the password length/clear rule, adding little 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?

States a specific verb and resource: it changes the access setting (password) stored for a slug on deed.page, and the title clarifies it both sets and clears. The scope is precise, though it never names a sibling such as update_site to distinguish this narrow write from general site updates.

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 explains the input contract (8-200 chars, or empty/null to clear) and gives concrete plan constraints: setting requires Hobby or Pro and Free returns plan_required, while clearing works on every plan. It lacks explicit 'use this instead of X' routing against siblings, but the when-to-use context is solid.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds substantial context beyond them: auth via token or Authorization header, the plan_required error with an upgrade link for out-of-plan requests, the 'accuracy' field's under-counting caveat, and a privacy statement that no raw IP or full user agent is stored. These are exactly the behavioral facts an agent needs before calling.

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

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

Front-loaded with the return payload, then inputs, then error behavior, then the accuracy/privacy caveats — each sentence carries distinct information. It is dense and packs several facts per sentence, which is slightly taxing to scan but wastes no words.

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

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

There is no output schema, yet the description names the returned dimensions (daily views, paths, referrer hosts, crawler families), explains the accuracy field, and describes csv row structure. Combined with the plan-limit and auth details, an agent has everything needed to invoke and interpret results 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; the description earns above that by restating the date defaults (last 7 days), the 90/365-day caps tied to plan, and the csv-is-Pro-only rule, which are constraints the schema does not express. The csv row shape (date,kind,key,views) is also surfaced.

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 owner-only cookieless counts for a slug') and enumerates exactly which metrics come back: views per UTC day, top paths, top referrer hosts, AI crawler counts by UA family. This clearly separates it from sibling tools like get_site or list_sites, which deal with site metadata rather than analytics.

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 access, default range of the last 7 days, and per-plan range caps (90 days Free/Hobby, 365 Pro) with csv gated to Pro. It does not name a sibling alternative or state when-not-to-use it, but the plan/precondition guidance is unusually concrete.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety bar is met. Beyond that the description discloses real behavior the annotations don't: the bot/headless/asset filter, the plan-gated range limits and the plan_required response with upgrade link, and the privacy posture (no raw IP or full user agent stored).

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 lead sentence front-loads what is returned and the key scope constraint; the remaining sentences are dense but each carries distinct information (filter rules, plan gate, privacy, dashboard equivalent). Slightly list-like but no wasted sentences.

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

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

For a read-only analytics call with full schema coverage and no output schema, the description covers defaults, filtering semantics, the plan-limit error path, and privacy. The main gap is that the return shape ('daily unique visitors') is only loosely sketched, but that is minor given annotations already establish the operation's safety profile.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds meaning beyond the schema: the concrete plan window durations (7/30/90 days) that the schema only alludes to as 'the plan window', plus the token's header fallback. This is genuine added value rather than repetition.

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 (human HTML page views and daily unique visitors for a slug) with scope qualifiers (owner-only, excludes bots/assets). It does not distinguish itself from the sibling site_analytics, which sounds closely related, so an agent cannot tell the two apart from the description 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?

It mentions owner-only access and the plan-linked error case, but gives no guidance on when to use this versus site_analytics or the other analytics-adjacent siblings. No exclusions, prerequisites, or alternative routing 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 destructive and idempotent, and the description earns credit on top by spelling out what actually happens on conflict: version_conflict with nothing written, race detection even without expected_version, gallery checks re-running on a new listed version, and listed=false removing the slug immediately. It also flags the password-protected listing restriction and the payload ceiling, none of which are derivable from annotations.

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

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

Front-loads the core replace/merge semantic before edge cases, and each constraint sentence (conflict, size limit, listing rules) carries real information. The 'Inputs: slug, files, and optional ...' clause is largely redundant with the schema and is the one paragraph that does not 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 13-parameter destructive write with a nested files object and no output schema, the description covers the return payload (url, path_url, slug, listing, new version), conflict and race behavior, listing constraints, and the large-payload escape hatch. Nothing an agent needs to call it safely is missing.

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

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

Schema coverage is 100%, so baseline is 3. The description enumerates the parameter set and adds a few behavioral notes (listed defaults to false, password-protected sites can't be listed, expected_version conflict semantics), but the enumeration itself mostly restates the schema and it omits idempotency_key from the list of 13 parameters, so it does not add much net meaning.

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 and two precise modes: full replacement of a slug's files, or additive merge when merge is true. It never distinguishes itself from the sibling publish_site, which also targets a slug's files, so an agent must infer the boundary between first publish and update.

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 hard when-not rule with a concrete alternative path: over ~3.5 MB, don't call this; use plan_upload -> shell `commands` -> finalize_upload, or the publish-large script with its URL. Also states the version_conflict precondition and that omitting expected_version is still safe under races. Only the publish_site vs update_site choice is left unaddressed.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior. The description adds useful output context by naming the plan values and quota-related counts, though it does not describe error behavior or response shape in detail.

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

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

The description is short and front-loads the returned information before the usage note. The final 'Input: token' sentence is slightly redundant with the schema but does not materially hurt readability.

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

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

With no output schema, the description appropriately explains the main return values: plan, limits, site count, and hostname count. It is sufficient for an account/quota lookup, though exact response structure and limit details are not specified.

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 token parameter is fully documented as optional when the client sends an Authorization header. The description merely repeats 'Input: token' and adds no meaning 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?

The description clearly states that the tool returns the account plan, limits, owned-site count, and custom-hostname count. It is specific about the resource, though it does not explicitly differentiate this tool from siblings such as list_sites or agent_seats.

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 concrete use case: confirming a plan change after payment. It does not name alternatives or exclusions, but the intended context is clear enough for an agent to select it appropriately.

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