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

With no annotations, the description carries the full burden of behavioral disclosure, and it does so thoroughly. It reveals quota consumption, 402/429 failure modes, finality of 409/403/410 errors, claim_token consumption, and the fact that a claim is effectively a publish.

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

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

The definition is long but dense; nearly every clause carries operational information. It front-loads the core action and token requirement, then layers in side effects, exceptions, and terminal error semantics with no filler.

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

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

The description thoroughly covers invocation context, side effects, error codes, and credential lifecycle. Without an output schema, it stops just short of explicitly describing the successful claim response shape, though the mention of re-claiming returning true offers some signal.

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 a baseline of 3 applies, but the description adds meaningful context beyond the schema. It establishes that both parameters come from the same anonymous publish response, emphasizes that claim_token is sensitive, and explains what claiming does to the token's role.

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: 'Adopt a page that was published without an account into the account this key belongs to.' It clearly differentiates claim_site from siblings like publish_html and update_site by tying it to anonymous publish responses and the claim_token.

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

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

It explicitly states when to use this tool: 'Do this whenever you published anonymously and a key is now available.' It also covers exclusions and alternatives, noting that wallet-paid pages are an exception and that update_site takes over after claiming.

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

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

With no annotations, the description carries the full behavioral burden and handles it well: it discloses idempotency (existing space by name/slug in any casing returns instead of duplicating), the permanence of the returned slug, and that later renames affect display name only. It also conveys the safe create-once side-effect model.

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 dense sentences with no filler; the main action and rare-use caveat are front-loaded, and every subsequent sentence adds either behavioral or usage information that earns its place.

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

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

For a single-parameter creation tool with no output schema, the description is complete enough to guide invocation: it explains return significance (permanent slug), duplicate behavior, and the auto-create alternative. An agent has what it needs to call correctly without further clarification.

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 the display name and case-insensitive identity, so the baseline is 3. The description adds value by clarifying that matching can occur by slug as well as name, any casing, and that the same casing/slug rules as publish_html apply, which goes beyond the schema.

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

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

The description states a specific verb and resource ('Create a client space') and distinguishes it from publish_html, which auto-creates the space with a client argument. It also clarifies that the tool is rarely needed, so an agent can differentiate it from sibling tools without opening schemas.

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

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

Explicitly tells the agent when to use: only when setting a client up ahead of the published work, and when not to: publish_html with a client argument already auto-creates the space. This is a direct when/when-not guideline with a 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?

With no annotations provided, the description carries the burden of behavioral disclosure. It discloses that opens are attributed to the label in the dashboard and read-receipt email, that the link bypasses the page passcode, and that it can be independently revoked. These are meaningful behavioral traits beyond a generic 'create' statement.

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

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

The description is three dense sentences with no filler. The primary action is front-loaded, and each sentence adds distinct value: purpose, behavioral consequences, and usage boundaries. The mail-merge alternative is also stated without extra explanation.

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

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

The description is strong for the core use case and for distinguishing from alternatives, but it is incomplete for a 4-parameter tool with no output schema. Three parameters remain semantically unexplained, and the return value of the tool is not described, leaving gaps an agent must infer.

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

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

Schema description coverage is only 25%, so the description must compensate for undocumented parameters. It enriches the meaning of label (attribution and read receipts), but it does not explain id_or_slug, max_uses, or expires_in_hours at all, leaving major parameter semantics unresolved.

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 the specific action 'Mint a share link addressed to one person,' clearly identifying the resource and its one-recipient scope. It also distinguishes itself from siblings like revoke_share_link and list_share_links by describing a creation workflow and explicitly contrasting with the mail-merge approach.

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 explicit guidance: use this tool for one share link per recipient after publish_html, and use the alternative '?to={{name}}' URL approach for a whole mail-merge. This directly tells the agent when to pick this tool over another method.

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

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

With no annotations present, the description carries the full behavioral burden, and it delivers: it discloses that pages survive as floating pages, the portal/address stop resolving, viewer gates are removed, and unprotected pages can become accessible to anyone with the link. This level of side-effect and security disclosure is exemplary.

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 long but every sentence earns its place: the critical 'NOT deleted' caveat is front-loaded, destructive consequences are enumerated, and the archiving alternative is introduced exactly where it is needed. There is no filler or redundancy.

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

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

For a destructive tool with one parameter, no annotations, and no output schema, the description is remarkably complete. It covers survival of pages, loss of portal/address, security implications of gate removal, pre-deletion safety steps, and the preferred non-destructive alternative. An agent has enough context to invoke the tool correctly and warn the user appropriately.

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

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

The lone parameter id_or_slug is already fully documented in the schema, including the source (list_client_spaces) and the 'not the display name' caveat. The tool description does not add further parameter-level semantics, so the baseline 3 for high schema coverage 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 specific verb and resource — 'Delete a client space' — and then sharply distinguishes it from update_client_space by describing the archiving alternative. The extensive side-effect inventory makes it unmistakable what operation this is and how it differs from its sibling.

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

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

It gives explicit when-not-to-use guidance: for a finished client, prefer update_client_space with archived: true, with the trade-offs spelled out (keeps portal/address live, frees plan slot, undoable). It also provides actionable preconditions — warn the user and set_password on pages that must stay private — which directly informs safe invocation.

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

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

With no annotations provided, the description carries the full behavioral disclosure burden, and it does so thoroughly. It reveals immediate link death, 30-day retention, permanent destruction after that, non-recoverability, already_deleted idempotency, and the restorable_until field semantics. This is exemplary transparency for a destructive tool.

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

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

The description is dense but every sentence carries critical operational information: consequences, restore behavior, free-plan implications, idempotency, and response handling. It is front-loaded with the primary action and then layers necessary caveats. No filler is present.

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

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

Despite having no annotations and no output schema, the description covers the key context an agent needs: what happens to the URL, what happens to the content, restore semantics, plan-specific behavior, already-deleted handling, and how to read the response. It is unusually complete for a mutation tool and leaves little room for dangerous assumptions.

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

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

Schema description coverage is 0% and the description does not directly explain the id_or_slug parameter. It mentions 'id' and 'slug' in the context of restore_site, which offers some indirect signal, but it never states that the parameter accepts either a page ID or slug or how to obtain them. Given the low coverage, the description should compensate but largely leaves parameter semantics to the property name.

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

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

The description opens with a clear, specific action: 'Take a page down.' It unambiguously names the resource (a page/site) and the operation (delete/unpublish), and it differentiates delete_site from the sibling restore_site by describing the delete-and-restore lifecycle. An agent can immediately tell this tool exists to make a page unavailable.

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 strong usage direction: it explicitly mentions restore_site as the recovery alternative, emphasizes that this is not a preview, and instructs the agent to tell the user the link stops working now. It also explains the 30-day restore window and the free-plan slot consequence, so an agent knows when deletion is appropriate and what caveats to communicate.

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

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

With no annotations provided, the description carries the full burden and handles it well. It reveals that html is returned byte-for-byte, that text strips markup/CSS/scripts/SVG, that deleted or expired pages may still be readable until the restore window closes, and that abuse-taken-down pages are not readable.

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?

Although the description is longer than average, every sentence carries operational value: default behavior, format differences, access scope, edge cases, and a critical warning. The main purpose is front-loaded, and the rest is dense but not 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?

Given that there is no output schema and no annotations, the description covers the essential context: input formats, ownership restrictions, lifecycle edge cases, and a dangerous misuse to avoid. An agent has enough information to select and invoke this 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?

The schema describes id_or_slug but leaves format's meaning undocumented. The description compensates thoroughly: it defines both enum values, states the default, and explains the concrete behavioral difference between html and text, adding meaning far beyond the bare 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 clear verb and object: 'Read a page's content back.' It also distinguishes the two output formats and relates them to editing via update_site, making the tool's purpose and differentiation from sibling tools clear.

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 explicitly states when to use each format: html is for the exact editable content to pass to update_site, while text is for reading, summarising, or quoting without token waste. It also gives a strong when-not instruction: never edit and publish the text form.

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

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

With no annotations provided, the description carries the full burden, and it does so well. It clearly indicates a non-mutating fetch operation ('Fetch'), discloses the guide's internal contents (assess-first workflow, quality floor, CSP constraints), and explains how the tool should influence subsequent behavior. There is no hidden side effect or ambiguous 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 core purpose, then adds the critical usage precondition, a summary of the guide's contents, and an explicit workflow. Every sentence contributes actionable information and none is filler or 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?

For a zero-parameter, no-output-schema documentation fetcher, the description is complete. It tells the agent what the tool returns conceptually, when to invoke it, what constraints it reveals, and how to apply its output to the broader site improvement workflow.

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

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

The tool has zero parameters and the schema is trivially complete, so there is nothing for the description to add about parameter meanings. Per the baseline for zero-parameter tools, a score of 4 is appropriate because the description handles the no-parameter case cleanly without needing to invent 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 opens with a specific verb and resource: 'Fetch the Stacktree house design guide for improving a published page.' It clearly identifies the tool as a read operation that supplies design guidance, and it distinguishes its role from sibling tools like update_site or get_site by framing it as the guide that precedes and drives those actions.

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 explicitly states when to call it: 'Call this BEFORE any request to make a page look better, more polished, more professional, or beautiful.' It also tells the agent what the guide contains, including when NOT to restyle, and provides the exact follow-up workflow: get_site → assess → rebuild or elevate → update_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?

With no annotations, the description carries the burden of behavioral disclosure. It explains this is a read-only introspection call, enumerates what it returns, and notes that limits are plan-dependent. It does not explicitly state side-effect-freedom, but the 'READ' framing and account-inspection purpose make that clear.

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 compact yet information-dense. It front-loads the core purpose, then provides a critical warning, and then lists concrete decision points for when to call. Every sentence earns its place.

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

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

Given zero parameters and no output schema, the description still tells the agent what fields to expect, why plan discrepancies matter, and how to use this tool to answer common questions. It is fully adequate for an agent to decide when to invoke it.

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

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

The tool has zero parameters and the input schema already fully covers this with 100% coverage. The description therefore has no parameter semantics to add, and the baseline of 4 is appropriate.

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

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

The description clearly states this tool reports identity and plan information: 'Who this key publishes as, and what its plan actually allows: plan, signed-in email, pages held, lifetime publishes spent, and a limits object.' This is specific and distinguishes get_me from sibling tools that manage sites, publishing, or client spaces.

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 explicit when-to-use guidance: call before promising a permanent link, before promising a passcode or email gate, after a 402 or 429, and to diagnose missing pages. It also warns not to quote limits from other tool descriptions, which prevents a common mistake.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It meaningfully reveals that the tool returns the exact stored index.html, not rendered or text-stripped, and preserves CSS and inline charts. It does not cover authentication failures or ownership edge cases, but the key return behavior is well disclosed.

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 with no wasted words. The core read behavior and return format are front-loaded, and the workflow context is included without 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?

This is a simple one-parameter read tool with no output schema, and the description covers the return value, the exact format, what is preserved, and the intended edit workflow. Nothing critical is missing for an agent to invoke 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?

The input schema already provides 100% coverage for id_or_slug, including its type and description. The tool description does not add parameter-specific semantics beyond the schema, so the baseline score of 3 is appropriate.

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

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

The description states a specific verb ('Read') and resource ('current HTML source of a site you own'), and clarifies that it returns the exact stored index.html, not a rendered or text-stripped version. This clearly distinguishes it from siblings like get_content or list_sites.

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 explicitly frames the tool as the read step before editing: 'so you can edit it and update_site in place.' It names update_site as the paired write tool, providing clear workflow context, though it does not explicitly discuss when to prefer related read tools like get_content.

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

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

With no annotations, the description carries the behavioral disclosure burden. It reveals a stateful two-call protocol, the signing scheme (personal_sign / EIP-191), and the ownership/adoption side effects. It could additionally mention failure modes or whether the operation is reversible, but core behavior is transparent.

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

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

Three sentences, each earning its place: purpose first, then prerequisite, then the step-by-step protocol. It is front-loaded and contains no filler.

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

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

For a multi-step, stateful tool with no annotations and no output schema, the description covers the prerequisite, both calls, and the signature method well. It does not describe the second call's response or error conditions, but it is sufficient for an agent 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 only 33%, but the description fully compensates: code is defined as a LINK-XXXX code from the human, wallet is the signing wallet, and signature is the personal_sign/EIP-191 output. The exact call sequence clarifies the role of each parameter beyond the bare 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 opens with a specific verb and resource: 'Link your wallet to a Stacktree account.' It also states the outcome: pages published become owned there and previously published pages are adopted. This clearly distinguishes it from sibling tools like claim_site or publish_html.

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

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

It gives a clear workflow and prerequisite: obtain a LINK-XXXX code from the human at stacktr.ee/wallets, call once with only the code to get the message, sign it, then call again with code, wallet, and signature. It does not explicitly name alternatives or when-not-to-use cases, but the context is unambiguous.

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

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

With no annotations, the description carries the full burden and it delivers useful behavioral detail: it is an account-level list, empty results have a specific meaning, spaces are auto-created by publish_html, and hostname/portal configuration is external. It does not spell out read-only status or pagination, but 'List' plus the semantic explanation covers the main expectations.

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 fields, then uses two short follow-up sentences to clarify empty-list meaning and out-of-band portal setup. Every sentence carries useful information without repetition or filler.

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

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

For a zero-parameter list tool with no output schema, the description covers the domain concept, the returned fields, empty-list behavior, how spaces come into existence, and where related configuration happens. Minor omissions such as output formatting or ordering are not critical for invoking 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?

The tool has zero parameters and 100% schema description coverage, so the baseline is 4; there are no parameter semantics for the description to add. The field-level detail in the description addresses what the output contains instead, which is appropriate for a no-input list tool.

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 leads with a specific verb and resource ('List the client spaces on this account') and enumerates the exact fields returned, which clearly identifies what the tool does. The definition also distinguishes the concept from related resources by explaining spaces group published pages per client, so it is not confusable with list_sites or the create/update/delete siblings.

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 clear contextual guidance: an empty list means nothing has been filed yet, publish_html auto-creates spaces, and portal/address setup happens in the dashboard. It does not explicitly name alternatives or state when not to use the tool, but the context makes the appropriate use apparent.

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

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

With no annotations provided, the description carries the burden of behavioral disclosure. It does reveal that the tool is read-only and that unresolved items are returned first. However, it does not mention pagination, authentication, or failure behavior, leaving some behavioral uncertainty.

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

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

The description is two concise sentences with no wasted words. It front-loads the core action and resource, then adds item details, ordering behavior, and the orchestration loop, all of which earn their place.

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

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

For a simple one-parameter read tool, the description covers the key output fields, the unresolved-first ordering, and the relevant workflow with sibling tools. It omits pagination and error behavior, but those are not glaring gaps given the simple input schema and read-only nature.

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

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

Schema description coverage is 100% and already documents id_or_slug as 'Site id, slug, or unlisted token.' The description adds only contextual framing about the site and workflow, so it is adequate but does not meaningfully improve parameter understanding 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 opens with 'Read viewer feedback left on a site via the Agentation toolbar', clearly stating the verb, resource, and source context. It also enumerates what each item contains and distinguishes this read operation from the sibling resolve_feedback 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?

The description provides a clear workflow: list_feedback → get_site/update_site → resolve_feedback, which signals when this tool is appropriate in a broader process. It does not explicitly state when not to use it or name alternatives directly, but the loop makes the intended usage fairly clear.

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

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

With no annotations, the description carries the burden of behavioral disclosure, and it does so well by clarifying output semantics: opens counts human page opens, use_count is the raw max_uses counter and not a read metric, and opens is null on plans without viewer numbers. This prevents misinterpretation of returned data. It does not discuss permissions or side effects, but listing is a non-mutating operation and the key caveats are surfaced.

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

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

The description is two sentences with no filler. The core statement is front-loaded, and the second sentence provides necessary caveats about opens and use_count. Every sentence earns its place.

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

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

There is no output schema, so the description appropriately explains the key return field semantics and the null condition. It could be more complete by stating what share link fields are returned or mentioning pagination/ordering, but for a simple one-parameter list operation the essential information is present.

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

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

Schema coverage is 0%, so the description must compensate, and it adds only modest context by saying the share links are 'on a page.' This implies id_or_slug refers to a page, but the description does not explicitly explain the id_or_slug format or that it is required. For a single self-named parameter, this is adequate but not thorough.

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

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

The description clearly identifies the resource (share links on a page) and distinguishes the tool's focus by highlighting attributed opens and last-opened time. It lacks an explicit verb like 'lists' or 'returns,' though the tool name supplies that action. It does not explicitly differentiate from sibling tools, but the resource and metric focus are clear enough.

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 should be used when you need share links with opens and last-opened metrics, but it does not explicitly state when to use it versus siblings like create_share_link, revoke_share_link, or set_expiry. There is no exclusion or alternative routing, so an agent must infer the usage 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?

With no annotations, the description carries the full behavioral burden, and it delivers extensively: plan-gated viewer fields, the meaning of deleted_at, delete_reason semantics including non-restorable abuse takedowns, the old-worker missing-field quirk, and exact pagination behavior. This goes well beyond a typical description.

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 but every sentence carries a specific operational instruction or caveat. It front-loads the core purpose and then logically proceeds through gating, deletion semantics, legacy-worker behavior, and pagination without filler.

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

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

Given the tool's complexity, the absence of annotations, and the absence of an output schema, the description is remarkably complete. It tells the agent how to interpret returned fields, avoid dead links, handle non-restorable sites, and paginate correctly, leaving little to guesswork.

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 0%, so the description must compensate, and it does for client, before, and before_id by explaining their roles in filtering and pagination. The limit parameter is not explained, but it is self-evident as a page size; overall the gap is minor.

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: "List sites owned by this API key," which clearly states what the tool does. It does not explicitly name sibling tools like get_site or list_client_spaces, so it stops short of full sibling differentiation, but the scope 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?

The description provides rich usage context: filtering by client, pagination loop mechanics, and how to handle deleted or expired sites. It does not explicitly state when to prefer this tool over siblings or when not to use it, but the operational guidance is clear and actionable.

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

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

With zero annotations, the description carries the full burden and delivers extensively: return shape { url, id, expires_at }, unlisted token URL, plan-aware expiry (permanent on paid, 7-day ceiling on free), 409 expiry_clamped with accept_clamp semantics, idempotent retries via idempotency_key, PII scan modes, strict CSP, X-Robots-Tag: noai, and the free-plan 3-page lifetime cap with 402 error. It even instructs never to report a page as permanent unless expires_at is null.

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?

Long but information-dense: nearly every sentence carries an operational fact, from error codes to plan limits to idempotency guarantees. The structure is logical and front-loaded (purpose first, usage triggers second, operational details after). It borders on heavy, but the length is justified by the tool's plan-dependent and error-rich 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?

With no output schema and no annotations, the description supplies the return format, both documented error modes with explicit user-facing instructions (report 402 rather than retry; explain the plan cannot make a permanent link), plan ceilings, and retry semantics. For a 12-param tool with plan-dependent behavior, this is about as complete as a description can be; only the minor self-evident params lack explicit semantics.

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

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

Schema description coverage is only 8%, so the description must compensate — and it does for the riskiest params: expires_in_hours ('never' semantics, clamping, 409 refusal), idempotency_key (same-page retry guarantee), pii_check ('warn' publishes despite sensitive data), and accept_clamp (take the ceiling). However, client, filename, password, agentation, client_path, public_slug, and burn_after_read get no semantic detail in either the schema or description; their names hint at meaning but the semantics are not stated.

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

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

The opening sentence states the transformation precisely: 'Turn HTML into a link a person can open in a browser.' It names a specific verb (publish) and resource (HTML→URL), and the output artifact (a browser-openable link) is distinct from sibling tools that manage sites, set expiry, or create share links for existing resources.

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

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

Gives explicit trigger conditions: any page produced for someone outside the conversation, user phrases like 'publish this', 'share this', 'send it to X', or preview-link requests. It also states the when-not explicitly: 'A rendered preview inside a tool is not a link: if it has to travel, publish it.' This is direct routing guidance an agent can act on without 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?

With no annotations, the description carries the full burden of disclosing behavior. It states the state change but does not say whether the action is reversible, whether permissions are required, what status transitions occur, or whether any side effects (e.g., notifications) are triggered. This is a notable gap for a write operation.

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

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

Two concise sentences, front-loaded with the core action, with no filler. The note option is mentioned efficiently.

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

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

The tool is simple with only two parameters, and the description covers the primary action and the optional note. However, without annotations or an output schema, the lack of information about return values, reversibility, and side effects leaves some uncertainty for an agent deciding whether and how to invoke it.

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

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

The schema describes feedback_id as coming from list_feedback, and the description explains the note parameter as 'a note describing the change.' Together, both parameters receive meaningful semantic guidance despite the schema-only coverage being 50%.

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 the action ('mark as addressed') and the resource ('feedback item'), and the context 'after fixing the page' provides situational framing. It is not explicitly differentiated from sibling tools like list_feedback, but the mutation intent is unmistakable.

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

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

The description provides a clear condition for use ('after fixing the page'), which is a meaningful usage guideline. It does not mention alternatives or exclusions, but for this simple mutation the context is sufficient.

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

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

With no annotations, the description carries full disclosure burden and fully delivers: it reveals that abuse takedowns and past-window pages both answer 404 with the same body deliberately, explains restored_for 'grace' vs 'plan' semantics, clarifies what 402 plan_site_limit_exceeded means for the account, and warns that a retry answering 404 may actually mean the earlier restore succeeded because a restored page is no longer restorable.

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?

Core behavior is front-loaded in the first sentence, and the error-code and retry guidance that follows is dense but each sentence carries distinct operational value. Slightly verbose with minor redundancy in restating the 30-day window and the non-restorable cases twice, but nothing is filler.

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

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

For a single-parameter tool with no annotations and no output schema, this is exhaustive: it covers 404/402/409 handling, names the response fields to read (expires_at, restored_for), specifies the 48-hour grace behavior, gives user-facing messaging guidance, and provides retry fallback logic. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100% — id_or_slug is already documented as accepting a site id, slug, or unlisted token that still resolves while the page is down. The description reinforces this ('Same id, same token') but adds no parameter 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?

Opens with an action verb and precise resource: 'Put a page back at the same URL after it was deleted or ran out of time.' It establishes the distinguishing invariants — same id, token, slug, and read history — so every existing link works again, which clearly separates it from publish_html.

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

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

Gives an explicit trigger condition ('whenever update_site, set_expiry, set_password or another settings call answers 409 site_deleted'), an explicit excluded alternative ('Call this, and never publish_html'), and a reason why publishing is wrong: it mints a different URL, strands link holders, and spends a lifetime page while restore spends none. It also names eligibility boundaries (30-day window, owner-deleted or expired only).

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It effectively explains what gets destroyed (one share link) and what remains unaffected (the page, all other links). The word 'kill' strongly implies irreversibility, though explicit mention of permanence or permission requirements would have made it fully transparent.

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

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

A single, front-loaded sentence with no wasted words. It starts with the core action, then provides the essential scope clarification. Every phrase contributes meaning.

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

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

For a simple one-parameter tool with no output schema, the description covers the purpose, the scope of effect, and the social context. It does not mention edge cases like already-revoked links or error behavior, but those are not essential for correct invocation.

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

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

The schema description fully covers the single parameter, stating that share_link_id is 'The id from create_share_link or list_share_links.' Since schema coverage is 100%, the description adds no additional parameter meaning, but the baseline of 3 applies.

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

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

The description uses a specific verb ('Kill') and specific resource ('one share link'), making the operation immediately clear. It also distinguishes itself from page-level or bulk operations by stating that 'the page and every other link keep working.'

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 conveys the exact scenario: 'cut off one recipient without re-issuing to the rest.' This gives clear context for when to use the tool, though it does not explicitly name sibling alternatives like set_expiry or exclude them.

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

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

With no annotations, the description carries the behavioral burden. It does disclose the key conditional behavior: when on, viewer annotations are collected and can later be read. But it does not mention whether toggling off preserves or deletes existing feedback, what permissions are required, or whether enabling the toolbar affects the live page experience.

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 just two short sentences with no filler. The primary action is front-loaded, and the follow-up workflow is compactly appended. Every clause earns its place.

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

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

For a simple boolean toggle on a resource, the description conveys the main purpose and workflow. However, because there is no output schema, no annotations, and 0% param coverage, the missing id_or_slug semantics and lack of persistence/side-effect details make it only minimally 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 0%, so the description must clarify both parameters. It only implicitly explains 'enabled' via 'When on'; it never defines what 'id_or_slug' refers to, leaving a required parameter ambiguous. This is a meaningful gap for an agent selecting or invoking the tool.

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 ('Toggle') and a specific resource ('the on-page Agentation feedback toolbar'), immediately stating what the tool does. It also distinguishes itself from feedback-related siblings by framing it as the tool that starts/stops collection, while list_feedback, update_site, and resolve_feedback are the downstream steps.

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

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

The description provides clear context: enable the toolbar to collect viewer annotations, then read/fix/resolve them. It names the relevant follow-up tools, which helps the agent understand where this fits in the workflow. However, it does not explicitly state when NOT to use this tool or how it compares to direct alternatives like list_feedback or resolve_feedback.

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

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

With no annotations, the description carries the behavioral burden and does well: it discloses auto-creation of client spaces, detaching to a floating page on null, and the one-site-one-call constraint. It does not cover permissions, return values, or reversibility, but the key side effects are explicit.

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 with no filler; the primary action is front-loaded and the null case follows immediately. The cross-reference to set_password is compact and useful for an agent familiar with that sibling.

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 two-parameter mutation with no output schema, the description is largely complete: it identifies both parameters' roles, the auto-creation side effect, and the detach behavior. It omits return/error details, but those are not required for correct invocation and no output schema exists to document them.

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

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

Schema coverage is only 50%; the description adds meaning to `client` by explaining it can be a client-space name/slug, is auto-created, or null for detaching. `id_or_slug` is left to the schema, but the description's coupling to 'existing site' reinforces its purpose.

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?

Description uses a specific verb ('File'), names the resource ('an existing site under a client space'), and covers both attach/detach modes with 'pass client: null to detach it to a floating page.' It is clear enough to distinguish from sibling tools even without 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?

It conveys the core usage scenario and the special null case, but it does not explicitly say when to choose this over sibling tools such as set_agentation or update_client_space. The phrase 'Mirrors set_password: one site, one call' hints at a pattern but does not state exclusions or alternatives.

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

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

No annotations exist, so the description carries the full burden of behavioral disclosure, and it does so richly. It explains the strict-equal matching, one-time magic link verification, the null value to clear the gate, mutual exclusivity with set_password, and the exact 402 error code for free keys. This gives the agent a complete picture of side effects and error behavior.

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

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

Three tight sentences, each adding unique value: the core purpose and match semantics, the verification and exclusivity behavior, and the clearing mechanism plus error condition. The most important behavioral constraints are front-loaded and no sentence 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 two-parameter tool with no annotations and no output schema, the description covers what the tool does, how the domain gate behaves, how to clear it, the interaction with set_password, and the free-tier error. Nothing essential for correct invocation is missing, and even error handling is 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 description coverage is 0%, so the description must add meaning. It thoroughly explains the 'domain' parameter: strict-equal matching and null-to-clear. It does not explain 'id_or_slug', but that name is self-descriptive and consistent with sibling tools. The core semantic parameter receives excellent treatment, leaving only a minor gap for id_or_slug.

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: 'Restrict viewer access to a specific email domain'. It immediately distinguishes itself from siblings by stating the strict-equal match condition and the mutual exclusivity with set_password. An agent can clearly understand what this tool does and how it differs from related tools.

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

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

The description gives clear context: it is for restricting access by email domain and is mutually exclusive with set_password. It also discloses the paid-feature requirement and the 402 error on free keys. However, it does not explicitly state 'use set_password for password-based gating' or list conditions for when not to use it beyond the mutual exclusivity note. Still, the guidance is strong.

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

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

With no annotations, the description carries the full burden, and it delivers: it discloses ceiling clamping with 409 expiry_clamped and 'nothing changed', the invariant that a shortened page can never be reported permanent, the acceptance of accept_clamp as the escape hatch, and the instruction to quote expires_at_iso rather than the requested value. This transforms a surprising, plan-dependent API into a predictable contract.

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 is front-loaded in the first sentence and every subsequent clause conveys a load-bearing behavior or instruction; nothing is filler. However, it is one long monolithic paragraph mixing clamping, refusal, retry, and quoting rules, which could be clearer if split by scenario. Dense and efficient, but structurally improvable.

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 tool with no output schema and no annotations, the description covers the error contract, the retry flow, and the correct response field to use — remarkably complete for the tricky plan-dependent cases. The one real gap is id_or_slug, a required parameter whose target resource is never stated, forcing inference from the parameter name.

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 0%, so the description must compensate. It does for two of three parameters: expires_in_hours ('hours-from-now' semantics, 'null for never', ceiling behavior) and accept_clamp ('take the ceiling'). However, id_or_slug — a required parameter — receives zero elaboration; the agent must infer from the name alone what resource it identifies.

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: 'Set hours-from-now expiry, or null for never.' This unambiguously states the operation, the resource, and the two allowed modes. No sibling handles expiry, so the tool is clearly differentiated from the site/client/share-link management tools around it.

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

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

No sibling overlaps with expiry, so explicit exclusions are unnecessary. Instead the description gives scenario-based guidance: what to do when a number is clamped (response says so), what to do when null is refused (resend with accept_clamp: true or inform the user), and what value to quote. This is strong operational usage guidance, though it never states a generic 'when to use this tool' rule.

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

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

With no annotations, the description carries the behavioral disclosure burden. It discloses plan compatibility and a guarantee about clearing, but it does not mention side effects, permission requirements, response behavior, or potential failure modes when setting a passcode.

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 with no fluff. The main purpose is front-loaded and the important caveats are included efficiently.

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 two-parameter mutation tool with no output schema, the description covers the essential operation, parameter semantics, and a key condition (plan availability). It could be improved by noting return values or error behavior, but it is complete enough for correct invocation.

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

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

Schema coverage is 0%, so the description must explain parameters beyond the schema. It clarifies that null clears the passcode and a string sets it, and id_or_slug implies the target site, though it does not explicitly define id_or_slug's format or constraints.

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: set or clear a passcode on a site. It also clarifies the null semantics, which directly distinguishes this tool from sibling tools like set_agentation or set_client.

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

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

The description provides clear context for when the tool is usable, noting it works on every plan and that clearing a passcode always works. It does not explicitly name alternatives, but no password-specific sibling exists, so the guidance is sufficient.

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

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

With no annotations present, the description carries the full burden of behavioral disclosure, and it delivers: slug permanence, archive side effects (keeps serving, frees plan slot), unarchive 402-on-full-plan, gate inheritance to existing and future pages, null-to-remove convention, paid-feature restrictions, and 409 name_taken semantics. No behavioral trait an agent needs is left to inference.

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 front-loads the three operations in sentence one, states patch semantics in sentence two, then systematically elaborates caveats per field. At roughly 140 words for a 5-parameter, three-operation tool with multiple error branches, every sentence earns its place.

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

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

Given no annotations, no output schema, and high operational complexity, the description covers all invocation-critical knowledge: error codes (402 plan_password_not_available, 402 plan_viewer_gate_not_available, 402 on full plan, 409 name_taken), side effects, paid-feature conditions, and required-parameter sourcing from list_client_spaces. The only omission — success-response shape — is minor for a mutation tool whose failure modes are fully enumerated.

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

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

Schema coverage is only 20% (id_or_slug alone), so the description must compensate for the other four parameters, and it does comprehensively: name (display-only, slug immutable), archived (serving/plan-slot semantics), password and allowed_email_domain (scope, inheritance, null removal, paywall). The description adds meaning far beyond the bare type declarations 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?

The opening sentence names three concrete operations — rename, archive/unarchive, and viewer-gate setting — each bound to the client-space resource. This is specific enough to distinguish the tool from create_client_space, delete_client_space, and list_client_spaces 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?

The description gives clear context for use: mutate an existing space's name, archive state, or access gates, with 'omit a field to leave it untouched' framing the patch-style semantics. It does not explicitly name sibling alternatives or state when not to use it, but the operation list makes the boundary obvious. The 409 directive ('report that rather than retrying with a variation') is actionable 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?

With no annotations, the description carries the full burden and does so thoroughly. It discloses in-place replacement, PII pre-flight scan behavior with a default and override, the two 409 error variants with distinct meanings, and that direct edits to a managed_portal would be overwritten. This goes beyond basic mutation expectations.

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 but every clause serves a purpose: core behavior, sibling distinction, PII behavior, and error recovery. The primary action is front-loaded, and the exception handling is organized clearly. No filler or tautology.

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 mutable update operation with no output schema and no annotations, this description covers the key decision points an agent needs: when to call it, which alternative to avoid, how parameter overrides work, and how to recover from both documented 409 states. Nothing crucial 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 50%, and the description significantly enriches the pii_check parameter by explaining its MCP default (block) and how to override with 'warn'. It also reinforces the content parameter's role. However, neither the schema nor description elaborates on filename, so compensation is good but not complete.

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: 'Replace the HTML of an existing site in place.' It clearly differentiates from the sibling publish_html by contrasting the URL behavior and slot consumption, so an agent can distinguish it without examining the schema.

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

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

It explicitly states when to use this tool over publish_html ('every time you revise a page you have already published') and why not to use the alternative. It also covers the restore_site prerequisite for the site_deleted 409 and warns against re-publishing, which would create a new URL.

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