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

Annotations only say destructive/openWorld/not-readOnly; the description adds several traits beyond that: the old subdomain keeps working via redirect and is reserved against takeover, quotas are limited and consumed even by a change back to an old name, signed-in visitors and password users must re-authenticate, and owner permission is required. This is exactly the extra behavioral context the annotations 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-loaded with the action, then consequences, then the parameter requirement, then permissions. Every sentence carries distinct information, but the run-on sentences mixing quota and confirm semantics could be tighter.

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?

An output schema exists, so return values need not be described. Given a 3-parameter mutation with full schema coverage, the description covers redirect behavior, quota, re-authentication, confirm semantics, and authorization — nothing material an agent needs before calling 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 the baseline is 3. The description restates what the schema already says about `confirm` (repeat the current subdomain exactly, mismatches are refused) and adds only the process hint 'ask the person rather than filling it in.' Useful, but largely duplicative of the structured field descriptions.

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

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

The first sentence gives a specific verb and resource: 'Moves a site to a new subdomain.' That is unambiguous and clearly distinct in subject matter from delete_site, pause_site, or update_site. However, it never explicitly names or contrasts a sibling for cases where the user wants something else (e.g., renaming a display name via update_site), so it lands at 4 rather than 5.

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

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

It gives strong when-to-use gating: 'use this only when the person named the new address,' plus prereqs ('Only an owner of the account can change an address') and a quota warning. The missing piece is an explicit alternative route ('if the person did not name an address, use X instead'), so there is no named sibling to route to.

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

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

Annotations only flag destructiveHint=true; the description goes well beyond that by stating the operation is irreversible, that the subdomain stays reserved forever, and that a mismatched confirm refuses the call. It also discloses the ownership/permission constraint, which annotations do not cover.

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

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

Front-loads the consequence ('Takes a site down permanently') before the mechanics, and each sentence carries actionable content. It is dense and slightly long, but there is no filler or repetition.

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

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

Covers the destructive consequence, the confirmation protocol, the ownership constraint, and the alternatives, which is everything an agent needs before calling. An output schema exists, so return values need not be explained.

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

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

Schema coverage is 100%, so both parameters are already documented, but the description adds real behavioral meaning to confirm — that the person must supply it rather than the agent inferring it from prior context. That is beyond the schema's 'repeated exactly' wording, though it stops short of extra detail on the site identifier.

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 ('Takes a site down permanently') plus the exact scope of destruction — files, history, subdomain. It also names the sibling it is not (pause_site) and the tool that reverses that alternative (resume_site), so an agent can distinguish it 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?

Explicit when-not guidance: 'To take a site off the air and keep it, use pause_site instead; resume_site brings it back.' It also names the prerequisite that only an account owner can delete, and tells the agent what to say on a team where the user is merely a member.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds real behavioral context beyond that: versions are returned newest first, the currently served version is marked, and the response flags settings the account's plan excludes — all useful for interpreting the result without guessing.

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

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

One front-loaded sentence led by the verb and resource, with the field enumeration tucked into an em-dash clause. No filler, no repetition of the title, and the most important information (what is read, from how many sites) comes first.

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?

An output schema exists, so return values need not be spelled out, yet the description still previews the response shape (settings, ordered versions, served marker, plan-gated settings). Combined with the annotations and 100% schema coverage, an agent has everything needed to call this 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?

There is a single parameter and schema description coverage is 100%, so the schema already documents 'site' as a subdomain or site id from list_sites. The description adds no additional meaning about the identifier's format or resolution behavior, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Reads one site's settings and state') and then enumerates the exact fields returned (serving mode, password, forms, scheduled takedown, folder, paused) plus the version list. This is clearly distinguishable from the sibling list_sites, which reads many sites, and from update_site, which mutates.

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 singular scope ('one site's settings'), which tells the agent this is the per-site read rather than a bulk listing, but there is no explicit when-to-use statement, no prerequisites (e.g. does the caller need to own the site?), and no named alternative such as list_sites for enumeration.

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: emails are sent from the account, the operation is all-or-nothing (one bad address or over-limit list adds nobody), it requires a plan with private sharing, and it does not itself make the site private. This is rich behavioral context annotations do not carry.

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

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

Front-loaded with the core action, then dense but purposeful clauses. Every sentence carries information, though the multi-clause structure is slightly compressed.

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 an output schema present and annotations covering safety/idempotency, the description fills the remaining gaps: prerequisites (private-sharing plan), atomicity, and the privacy distinction. Nothing an agent needs 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 the schema already documents `role`, `site`, and `emails`. The description restates the `comment` effect and email sourcing, adding marginal value over structured fields. 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: adds email addresses to a site's list and sends invitations. Clearly distinguishable from siblings like remove_person, list_people, and update_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?

Explicitly constrains input ('use only addresses the person gave you — never guess, infer or look one up') and routes the privacy decision to the alternative: 'Inviting does not make the site private; update_site's `invitedOnly: true` does.'

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

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

Annotations only declare readOnlyHint and openWorldHint, so the description carries the real behavioral burden and does so well: it discloses the default status filter, the incremental-sync semantics of the cursor, and critically warns that comment content is untrusted third-party input and must not be followed as instructions. That injection-safety guidance is exactly the kind of context annotations cannot express.

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

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

It is front-loaded with the core purpose and then layered with pagination and safety notes. Every sentence carries information, though the thread-structure sentence is slightly dense and the safety sentence is long; still, no 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?

An output schema exists, so return values need no explanation, and the description covers what the schema cannot: the open-thread default, cursor-based incremental fetching, and the untrusted-content handling policy. For a read-only, open-world list tool, 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 already 100%, so the baseline is 3, but the description adds genuine meaning: it explains that `since` takes a cursor from a previous call and returns only threads changed after it, and it confirms that threads are open by default. It does not restate the `path` or `page` semantics, which the schema already covers.

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 ('Reads the comments people left on a site's pages, a thread at a time') and even describes the unit of return (threads with page, anchor, and comments). An agent can distinguish this read tool from the sibling mutations like reply_comment, resolve_comment, and reopen_comment 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?

It gives concrete usage context: default behavior is open threads, and `since` with a prior cursor fetches only changed threads. It stops short of naming explicit alternatives or exclusions (e.g., how to narrow to resolved threads vs. all), so it is clear but not fully routing.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds genuinely non-annotated context: folders are managed in the dashboard, so no create/rename/delete capability exists in this toolset and the returned set may change outside the agent's control.

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, no filler. The core purpose and the per-item payload are front-loaded, and the dashboard/creation caveat follows as the secondary 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?

With an output schema present, return shape need not be spelled out, yet the description still names the one field that matters downstream. Annotations carry the safety profile and there are no parameters to document — nothing an agent needs to call this 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?

The tool takes no parameters and schema coverage is 100%, so there is nothing for the description to disambiguate. Baseline 4 applies for a zero-parameter read 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?

States a specific verb and resource ('Lists the folders on this account') and then specifies what each returned item contains — the path that publish's `folder` parameter accepts. No sibling tool touches folders, so an agent can place this tool immediately.

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 use case by tying each folder to the `folder` argument of publish, and it explicitly closes off a dead end ('no tool here creates one' — created in the dashboard). It stops short of an explicit 'call this before publish_files to obtain a valid folder path' instruction.

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

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

Beyond the readOnlyHint/openWorldHint annotations, the description discloses return semantics (per-person permission level and whether they've opened the site) and a non-obvious conditional behavior: the list governs site access only while the site is invite-only. That invite-only caveat is real behavioral context the annotations do not convey, though permission/access requirements for calling it are not stated.

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

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

Two sentences, front-loaded with the resource and its scope, and every clause adds information (entry origin, per-person permission, opened status, invite-only caveat). The second sentence is slightly convoluted but not wasteful.

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 annotations covering the safety profile, a full output schema covering return values, and 100% schema coverage for the lone parameter, the description only needs to add domain nuance — which it does via the permission values and the invite-only conditional. Nothing needed to call this 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 there is a single required 'site' parameter documented in the schema with its source (list_sites), so the description adds no parameter detail. Baseline 3 applies when the schema fully carries parameter 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?

States a specific verb (lists) and resource (people on a site's list) and immediately scopes it to entries added by invite_people, which separates it from siblings like list_sites, list_comments, and remove_person. It also names the per-entry data returned (view/comment permission, opened status), so an agent knows exactly what this tool yields.

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 ties the tool to its companion write operation by noting the entries are 'the ones invite_people added', which implicitly tells the agent this is the read counterpart to invite_people/remove_person. It gives clear context but no explicit when-not-to-use or exclusion against other listing tools.

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

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

Annotations only cover read-only/open-world safety; the description adds the traits that actually affect agent behavior: newest-first ordering, a hard 100-result cap with the account total, and the fact that no further pages exist. That pagination/truncation disclosure is exactly the kind of context annotations cannot provide.

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 what it returns, then the cap/pagination constraint, then the sibling handoff. No sentence is filler.

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

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

An output schema exists, so return values need not be spelled out, yet the description still flags the 100-item cap and total count — the details an agent needs to know it is not being paginated. Nothing required for 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The description correctly adds no parameter noise.

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 (lists sites on this account) plus scope and ordering (newest first). It also names the sibling it is not — get_site — so an agent can separate the two without opening either schema.

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

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

Gives a concrete reason to call it (to choose a publish target) and explicitly routes the single-site case to get_site. Both the use case and the alternative are stated rather than left to inference.

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

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

Annotations only cover safety hints (readOnlyHint=false, openWorldHint=true, non-idempotent, non-destructive). The description adds what the annotations cannot: a human approval step in a browser on this machine, a stored token consumed by every other tool, retry-until-approved semantics, and no CLI or pasted token required. That is substantive 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?

Front-loaded with the core action, then prerequisites, then the retry rule, then the alternative. It runs slightly long with em-dash asides, but each sentence carries distinct information (mechanism, retry behavior, no-token requirement, fallback tool) rather than restating the title.

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

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

For an auth tool with no output schema, the description covers the interaction model, the expected 'not approved yet' response, the retry expectation, and the environment-based fallback. An agent has everything needed to call it correctly and interpret the ambiguous response.

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

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

Schema description coverage is 100%, so both parameters (replace, waitSeconds) are already fully documented in the schema, including defaults and ranges. The description adds no parameter-level detail, so the baseline of 3 is appropriate.

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

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

States a specific verb and resource ('Signs in through a browser on this machine and stores an access token') and immediately names the sibling it is not — login_code — with the condition that selects it. An agent can distinguish it from every other tool in the sibling list without opening a schema.

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

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

Gives explicit routing: use login normally, use login_code where no browser can open (container, remote host). It also covers the non-obvious retry case — 'call it again to keep waiting — that is not a failure' — which prevents an agent from abandoning a valid flow.

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

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

Annotations only tell the agent this is a non-idempotent, open-world, non-destructive write. The description adds the essential protocol the annotations cannot convey: the first call returns a short code and URL, the second call blocks waiting for approval and stores the token. That two-phase behavior is critical and 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, zero padding, and the use-case constraint is front-loaded before the flow explanation. 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?

There is no output schema, and the description competently explains what the first call returns (code + URL). It leaves minor gaps – what the token persistence means, error/timeout behavior after the wait window – that would round out the picture for a state-changing auth tool.

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

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

Schema description coverage is 100%, so both parameters (replace, waitSeconds) are already documented with ranges and defaults in the schema. The description hints at the 'waiting call' polling behavior but adds no syntax or semantics beyond what structured fields provide – the correct baseline when the schema does the work.

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

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

States a specific verb and resource ('Signs in') and immediately narrows the operating context to machines without a browser (container, remote host). It implicitly distinguishes itself from the sibling 'login' tool by environment, though it never names the alternative, so an agent must infer the routing.

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?

Clearly describes when to use it ('where no browser can be opened on this machine — a container, a remote host') and lays out the two-call flow. It stops short of an explicit 'use login instead when a browser is available' exclusion, leaving the sibling comparison to inference.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=true, openWorldHint=true, and destructiveHint=true; the description adds the consequences the annotations cannot convey — visitor-visible paused state, retention of files/versions/subdomain, and a reversible counterpart. The 'without deleting anything' framing sits in mild tension with destructiveHint=true (the tool does take a live site offline), though it is technically about data retention rather than disruption, so it is clarification rather than 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?

Two compact sentences, front-loaded with the core effect and followed by the retention guarantee and the inverse-tool pointer. No filler, and the closing clause buys routing value.

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

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

With one required parameter, full schema coverage, an output schema, and rich annotations, the description covers effect, retention, and the reversing tool. Minor gaps remain (immediacy of the pause, any auth/permission prerequisites, effect on already-published content), but nothing essential for 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 coverage is 100% and the single parameter 'site' already documents 'Subdomain or site id, from list_sites.' The description says nothing about the parameter, which is acceptable at baseline 3 when the schema fully carries the load, but it adds no incremental 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?

Names a specific verb and resource (pause a site) and immediately defines the scope of the effect: site goes offline, nothing is deleted, files/versions/subdomain remain. It also distinguishes itself from delete_site (implicitly) and resume_site (explicitly), so an agent can separate it from its closest siblings without opening a schema.

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

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

Provides clear routing context by naming the inverse operation ('resume_site puts it back') and clarifying the non-deletion semantics versus delete_site. It does not state an explicit when-to-use trigger or prerequisites (e.g., permission requirements, whether the site must be published first), but the selection 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?

Annotations already declare destructiveHint=true, idempotentHint=false and openWorldHint=true, so the agent knows publishing is public and mutating. The description usefully adds the content requirements that determine whether the operation succeeds, but never discloses what happens when publishing over an existing site (overwrite/replace semantics), which is the main behavioral risk here.

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

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

Two sentences, front-loaded with the action and result, followed immediately by the one constraint that governs success. 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?

An output schema exists so return values need no explanation, and the content precondition is covered. However, for a destructive, non-idempotent publish that can target an existing site via `site`, the description omits what publishing over an existing site does to prior content, leaving a meaningful gap.

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

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

Schema coverage is 100% and the parameters carry unusually rich descriptions (e.g., folder's refusal behavior, subdomain's change budget and ask-rather-than-invent guidance). The description adds nothing parameter-specific, so the baseline 3 is appropriate.

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

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

States a specific verb ('Publishes') and resource ('a folder from disk') and names the outcome ('returns its URL'). It also disambiguates the content requirement (index.html or reader-served documents), which separates it from the publish_files sibling, though it never names that sibling directly.

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 states the folder's content precondition but gives no when-to-use versus alternatives guidance, and never mentions publish_files or when a folder publish is preferred over a file publish. Usage must be inferred from the precondition 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 flag destructive/openWorld/non-idempotent, and the description adds real behavioral context: single-page vs single-doc routing to index.html or the documents viewer, the overwrite semantics of publishing 'over' a site, and the scarcity of subdomain changes. It stops short of explicitly stating that publishing over an existing site replaces existing content, which is the crux of the destructiveHint.

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 purpose and URL return before constraints. Dense but every sentence carries a rule or exclusion; slightly long, though nothing is clearly redundant.

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

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

With an output schema present, the description needn't explain return values, yet it confirms the URL return. For a 4-param destructive tool with rich schema coverage, all the decision-critical context (routing, placeholder technique, exclusivity) 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 100%, so the baseline is 3, but the description adds meaning beyond the schema: it clarifies the subdomain/site mutual exclusivity as a workflow, warns not to invent a subdomain, and explains folder is only for new sites while moving uses update_site's folder.

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 (publishes) and resource (files written here) and names exactly what content types are accepted. It explicitly differentiates from the sibling publish_dir, noting that PDFs and images must come from disk with publish_dir.

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 routing rules: use publish_files for text written in-session, publish_dir for binary-from-disk. It also gives a concrete workflow for reserving an address (placeholder index.html with subdomain, then republish with site) and states the hard exclusion 'There is no way to create an empty site.'

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds genuinely new behavioral detail: on invite-only sites access ends within a minute, and restoration requires a fresh invitation and email — useful reversibility cost. It does not explain what happens on non-invite-only sites, leaving a gap.

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

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

Two sentences, no filler, with the core action front-loaded and the consequence trailing. Every clause carries information.

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

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

Output schema exists so return values need no explanation, and annotations carry the destructive/idempotent profile. The description supplies the missing human-relevant context (timing and reversibility), making the definition sufficient to invoke 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 both parameters are documented with their source tools (list_sites, list_people). The description's 'one address off a site's list' merely echoes the schema semantics without adding syntax or format 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 (remove/take off), the resource (a site's list), and the scope (one address), which cleanly separates it from invite_people and the list_* siblings. An agent can tell what it does without opening the schema.

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

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

The description frames the operation's purpose (ending someone's access) and its cost ('putting them back is another invitation'), which steers the agent toward using it only when removal is intended. It stops short of an explicit when-not-to-use or a named alternative, but the context is clear.

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

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

Annotations already declare the mutation and idempotency profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false). The description adds a genuine constraint beyond them: the action is performed 'as its owner', signalling an ownership/authorization requirement the agent must satisfy.

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

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

A single front-loaded sentence with no filler; the actor constraint is placed at the end where it reads naturally.

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 an output schema present, return values need not be described, and the annotations cover safety/idempotency. Ownership and precondition are covered; only explicit failure behavior (e.g. reopening a non-resolved thread) is left unstated.

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

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

Schema description coverage is 100% and both parameters ('site', 'thread') are documented in-schema with their source tools. The description adds no format or syntax detail beyond that, so the baseline 3 applies.

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

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

States a specific verb (reopen) plus resource (resolved comment thread) and scope (on a site). It implicitly contrasts with the resolve_comment sibling via 'resolved ... again', though it never names the counterpart explicitly.

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

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

The phrase 'opens a resolved comment thread ... again' implies the precondition (thread must already be resolved) but gives no explicit when/when-not guidance and does not name resolve_comment or reply_comment as 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?

Beyond the annotations (which only cover read-only/idempotency/open-world flags), the description discloses side effects the schema cannot: the reply is publicly attributed to the owner, thread participants are emailed, and the thread's state changes depending on `resolve`. It also states the permission requirement, which is exactly the kind of context annotations here do not carry.

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

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

Four short sentences, front-loaded with the action and then the constraints; every sentence carries a distinct rule (side effects, sequencing, resolve behavior, permission). Slightly dense with interleaved policies, but nothing is 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?

An output schema exists, so return values need no explanation. For a write tool with an email side effect and a thread-state toggle, the description covers authorization, sequencing, and the effect of each mode, leaving no meaningful gap for an agent deciding whether and how to call 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?

Schema coverage is 100%, so `body`, `site`, and `thread` are already documented and the baseline would be 3. The description adds real semantic value for `resolve` by explaining its consequence (thread closes, versus staying open for the commenter) and warning against using it unprompted, which is more than the schema's one-line 'False by default'.

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 ('Answers a comment thread on a site as its owner') and immediately frames the scope as the owner's own voice on the page. It is clearly distinct from the sibling resolve_comment/reopen_comment tools, which manage thread state rather than posting 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 explicit preconditions ('Publish a fix before replying that it is fixed'), explicit exclusions ('resolve only when the person asks'), and an authorization gate ('Only the account's owner can reply'). It also tells the agent the default behavior of leaving the thread open so the commenter can resolve it themselves.

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=false, idempotent=true, destructive=false, openWorld=true, so the safety profile is covered. The description adds real behavioral context: the thread moves from open to resolved in 'the version the site serves now', and the action is performed as the thread owner. It does not state explicit permission requirements beyond the ownership hint, keeping it just 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?

Three short sentences, zero filler, with the core action and state transition front-loaded and the routing guidance following. 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?

An output schema exists, so return values need no explanation. The description covers what changes, the version scoping, and the reversal path; only the precise authorization model ('as its owner') is somewhat 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% and both parameters already name their source tools (list_sites, list_comments) in the schema. The description adds no parameter meaning beyond that, so the baseline 3 applies.

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

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

Specific verb+resource ('Marks a comment thread on a site resolved') with the actor qualifier ('as its owner') and the resulting state transition. It is clearly distinguishable from siblings reply_comment and reopen_comment.

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?

'Resolve when the person asks; otherwise leave it for the commenter to confirm the fix' gives an explicit when-to-use and when-not-to-use condition, and 'reopen_comment undoes it' names the reversal alternative. Nothing is left to inference.

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

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

Annotations already declare write, idempotent, non-destructive, open-world behavior, so the bar is lower; the description still adds real value by enumerating the three refusal conditions (plan capacity, past-due account, Drop2Run suspension) and noting the reason is surfaced. It stops short of describing permissions or the exact resulting site state.

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

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

Two sentences, front-loaded with the action and followed by the failure modes. Every clause earns its place 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?

Output schema exists, so return values need not be explained, and annotations cover the safety profile. For a single-parameter state-transition tool, purpose plus explicit refusal conditions is sufficient 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 100% and the one parameter's description ('Subdomain or site id, from list_sites') already carries the semantics. The description only implies the site must currently be paused, adding marginal meaning beyond the schema; baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb+resource ('Puts a paused site back on the air') that an agent can immediately distinguish from the inverse sibling pause_site. No ambiguity about what operation is performed.

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 name and first sentence (call it when a site is paused), but there is no explicit when-to-use/when-not routing or comparison to siblings such as pause_site. The refusal conditions describe server-side failures, not how to choose this tool over an alternative.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is partly covered. The description adds context annotations don't carry: no publish action is triggered, and the rollback target is constrained by how its files were collected. It doesn't explain what happens to the currently served version or any auth requirements, so it is not a 5.

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

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

Two short sentences, both earning their place: the first defines the operation and its scope, the second supplies the lookup path and the key restriction. Nothing is padded or repeated from the title.

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

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

An output schema exists, so return values need no explanation, and the description covers what the tool does, where the version id comes from, and the main constraint. The only gap is the effect on the currently served version, which is minor given the annotation coverage.

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

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

Schema description coverage is 100%, and both parameters (site, deployId) are already documented in the schema, including the get_site/list_sites provenance. The description's mention that get_site lists versions reinforces the deployId source but adds no syntax or format detail beyond the structured fields, 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 states a specific verb and resource — serving an earlier version of a site again — and immediately scopes it with 'without publishing anything.' It also distinguishes itself from the sibling get_site by assigning version listing to that tool, so an agent can tell the two apart without opening either schema.

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

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

It names get_site as the source of valid versions and gives one explicit precondition (versions whose files were collected cannot be targeted), which is a meaningful when-not rule. It stops short of stating broader when-to-use/when-not conditions or naming alternatives for related operations like publish_files.

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

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

Adds real value beyond the annotations: propagation timing ('takes effect on every edge within about a minute, without publishing again') and refusal behavior for plan-gated settings ('Settings the plan does not include are refused with the reason'). The annotations already flag destructive/idempotent/open-world, so the remaining gaps (auth requirements, reversibility of individual changes) are minor.

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 front-loaded sentences; the merge-semantics and propagation-timing facts come first, with the guardrail last. Dense but every sentence carries a distinct fact, so nothing is padding. A slightly tighter phrasing of the last sentence would make it 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 12-parameter mutation tool with nested objects, an output schema, and full annotation coverage, the definition supplies the one thing structured fields cannot express: that this is a patch-merge, that effects propagate globally within a minute, and how plan-gated settings fail. Return values are covered by the output schema, so nothing essential 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 the baseline is 3, but the description contributes cross-parameter semantics the schema cannot: the omitted-fields-stay contract and the caution against fabricating password/date/expiry values. It does not restate individual field syntax, which is correct given the schema already carries it.

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

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

States a specific verb and resource ('Changes one or more settings of an existing site') and immediately clarifies the partial-update contract ('anything left out stays as it is'). It is clearly distinct from delete_site, pause_site, and change_subdomain, but it never names a sibling to route the agent, so it stops short of the top band.

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

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

Offers scoping guidance ('Only change what the person asked for — never invent a password or a date'), which is useful behavioral steering, but gives no explicit when-to-use vs. when-to-use-an-alternative framing against change_subdomain, pause_site, or invite_people. Usage is implied rather than stated.

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