Drop2Run

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 already declare destructiveHint=true and idempotentHint=false, but the description adds material context not in annotations: the deletion is irreversible, the subdomain stays permanently reserved, and a confirm mismatch refuses the call. The owner-only authorization rule and the 'ask the person, don't infer' instruction are exactly the behavioral disclosure this dimension rewards. It stops short of describing the returned result, though an output schema exists to cover that.

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 destructive outcome and irreversibility are front-loaded, and the alternative routing and permission rules follow in a logical order. It is dense but nearly every clause carries a distinct rule; the permission 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?

Covers the destructive scope, the irreversibility, the confirm-safety contract, the alternatives, and the authorization model, which is everything needed for a two-parameter irreversible mutation. Return values are handled by the output schema, so their absence from the description is not a 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%, so the baseline is 3, and the description earns above that by giving operative meaning to `confirm`: it must repeat the site's own subdomain exactly, and the agent should obtain it from the person rather than synthesizing it from known context. That is procedural guidance the schema does not carry.

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 plus concrete scope: 'Takes a site down permanently — its files, its history and its subdomain.' This distinguishes it from pause_site and rollback_site, which are named later, so an agent can route 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?

Names alternatives and the condition that selects them: 'To take a site off the air and keep it, use pause_site instead; resume_site brings it back.' It also states a hard precondition — only an account owner may delete — and tells the agent what to do when the caller is a team 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 destructiveHint=false, so safety is covered. The description adds genuinely useful behavior beyond that: versions are returned newest-first with the currently served one marked, and settings excluded by the account's plan are reported. It does not mention permissions/scope needed or any pagination limits, keeping it short of a 5.

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

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

Two sentences, front-loaded with the verb and resource, with zero filler. The parenthetical field list is dense but every item conveys what comes back; slightly list-heavy phrasing keeps it from a 5.

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

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

An output schema exists, so return-value explanation is optional — yet the description still tells the agent the shape of the payload (current settings, version ordering, plan-gap flags), which is exactly what an agent needs to decide to call it. Nothing material is missing for a single-param read 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 coverage is 100% and the schema itself documents the single 'site' parameter as 'Subdomain or site id, from list_sites.' The description adds no further detail on accepted identifier forms, so it does not exceed the schema baseline.

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

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

States a specific verb and resource ('Reads one site's settings and state') and then enumerates the concrete data returned — serving mode, password, forms, scheduled takedown, folder, paused — plus versions. This makes it clearly distinct from the sibling list_sites (list) and update_site (write).

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 singular 'one site's settings' implicitly frames this as the per-site read, and the schema points to list_sites for obtaining the identifier. But the description never explicitly says when to use this versus list_sites or update_site, and gives no prerequisites or exclusions.

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

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

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 already declare readOnlyHint=true, destructiveHint=false, openWorldHint=true, so the safety profile is covered. The description adds real context the annotations cannot: comments originate from untrusted site visitors, should be treated as requests rather than instructions, and require asking a person before acting on anything beyond editing this site's pages. It omits pagination behavior, but schema and output schema carry that.

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 first sentence front-loads what the tool returns, followed by default behavior, the incremental-cursor pattern, and a short trust warning. It is tight overall, though the prompt-injection sentence is a long compound clause that could be trimmed without losing 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?

With an output schema present and full parameter coverage, the description needn't explain the shape of results. It covers purpose, default filtering, incremental fetching, and the untrusted-content caveat; only pagination via the `page`/`more` loop is left implicit in the schema.

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

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

Schema description coverage is 100%, so all five parameters, including the status enum and the page cursor, are already documented. The description restates the `status` default and the `since` cursor workflow without adding syntax or format detail beyond the schema, so baseline 3 applies.

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

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

A specific verb (reads) plus resource (comments on a site's pages) with the grain of the return data spelled out: the page, the text/element each thread anchors to, and the comments in it. The thread-at-a-time framing separates it cleanly from the write-side siblings reply_comment, resolve_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?

'Open threads by default' tells the agent what the default filter is, and the `since` instruction gives an explicit incremental-polling pattern. It stops short of naming when to reach for a sibling such as get_site or reply_comment, but the read/write split is unambiguous from the verb.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds genuine scope context beyond that: this is a read-only enumeration and folder mutation lives outside the toolset. It does not discuss result size, ordering, or account scoping nuances, so the added value is modest.

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

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

Two tight sentences with zero filler, and the core enumeration plus its purpose is front-loaded before the scope caveat about dashboard-managed folders.

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 input parameters, full annotation coverage, and a declared output schema, nothing further is required. The description supplies exactly the missing pieces an agent needs: why the output matters and where folder management actually happens.

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 the baseline is 4. The description does useful adjacent work by explaining what the returned folder path is for (the publish `folder` argument), which frames how the output is consumed.

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 immediately adds the payload's purpose: each folder comes with the path that a publish's `folder` argument accepts. It also distinguishes itself from absent siblings by declaring no tool here creates a folder, so an agent will not hunt for a create_folders 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 makes the use case clear (you need this to obtain valid `folder` values before publishing) and closes off a dead end by saying folders are created and rearranged in the dashboard. It stops short of naming a specific sibling such as publish_files as the follow-up call, so a 4 rather than a 5.

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

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

Annotations already cover readOnlyHint, destructiveHint=false, and openWorldHint, so the safety profile is set; the description still adds real context beyond that — the exact enumeration of per-person permission values, the 'has opened it yet' signal, and the important semantic that the list governs site access only in invite-only mode. It stops short of noting auth requirements, ordering, or pagination behavior, which keeps it out of 5 territory.

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 core action and payload, with the conditional access-gating caveat placed after the essentials. The second sentence is somewhat dense with nested clauses ('which it does only while the site is invite-only'), costing a little readability, but 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?

For a one-parameter read tool with an output schema, the description covers the important ground: what the list contains, what each entry carries, and the invite-only caveat that would otherwise mislead an agent into treating the list as an ACL. Empty-state behavior and any access prerequisites are the only notable omissions.

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 required parameter ('site') and the schema description coverage is 100%, with the schema itself telling the agent to source it from list_sites. The description adds no format or sourcing 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?

The description names a specific verb and resource ('Lists the people on a site's list') and immediately disambiguates what that list is by tying it to 'the ones invite_people added'. It also previews the payload — permission level (`view` or `comment`) and whether each person has opened it — so an agent can tell this apart from siblings like list_comments, list_folders, and list_sites 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 establishes clear usage context by anchoring the tool to invite_people as the writer and clarifying the condition under which the list is authoritative ('only while the site is invite-only'). It doesn't name an alternative to use instead when the site is public or when you want site metadata rather than collaborators, so there are no explicit exclusions.

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

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

Annotations already cover the safety profile (readOnly, non-destructive, open-world), yet the description still adds hard operational facts: results are ordered newest first, capped at 100, and there are no additional pages to fetch. The no-pagination disclosure is exactly what prevents an agent from looping on a nonexistent cursor.

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 the tool returns, then the result bounds, then the sibling pointer. 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?

With zero parameters, an output schema, and full annotation coverage, the only gaps an agent could hit are ordering and pagination limits — both are stated explicitly. Nothing needed to invoke 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, so there is nothing to disambiguate and the baseline is 4. The description correctly implies the call is unfiltered and account-scoped.

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 ('Lists') plus resource ('the sites on this account'), with ordering ('newest first') and a stated purpose ('so a publish can go to one of them'). It explicitly contrasts with the sibling get_site, so an agent can choose between them 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 the selecting condition (find a site to publish to) and names the alternative for a different need ('Use get_site for one site's settings and versions'). It doesn't state exclusions such as 'do not use when you already know the site id', but the routing guidance 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 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?

Adds real constraints beyond the annotations: text-only (no PDF, image, or Office files), always returns a URL, and no empty sites are possible. Annotations already declare destructive/non-idempotent/openWorld, so the bar is lower; the description could go further in spelling out what gets overwritten when publishing over an existing site.

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

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

Front-loaded with the core action and return value, then layered with constraints and workflow. It is longer than most definitions but each sentence carries a distinct rule; the middle clause about markdown serving through the documents viewer is the only slightly expendable part.

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 content-type limits, the new-site vs existing-site flows, the placeholder pattern, and the empty-site impossibility, and an output schema exists so return-value detail is unnecessary. For a destructive, open-world publish tool, little 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 coverage is 100%, so the baseline is 3, but the description adds genuine meaning: the subdomain-vs-site decision, the placeholder-then-overwrite workflow, and the warning that a guessed subdomain is costly and changeable only a few times. File path/content semantics are left to the schema, which is acceptable.

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 — publishes files as a site and returns its URL — plus the accepted content types. It clearly separates itself from siblings like update_site and get_site by describing the create/publish action rather than retrieval or modification.

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 conditional guidance: use a placeholder index.html plus `subdomain` when an address is needed before content exists, then publish the real files with `site`, and notes an empty site is impossible. It stops short of naming update_site/rollback_site as alternatives for later content edits, though the schema's `folder` field covers the update_site routing.

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

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

Annotations already declare destructiveHint=true 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 safety profile (not read-only, idempotent, non-destructive, open-world), so the bar is lower. The description adds meaningful context beyond them: the thread must already be resolved, and the caller acts 'as its owner', implying an ownership/authorization requirement that the annotations do not 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?

A single sentence with the action front-loaded and zero filler. Every clause (resolved state, site scope, owner identity) 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?

The tool is a simple two-parameter state mutation with full schema coverage, rich annotations, and an output schema, so return values need not be described. The description covers the essential preconditions; only explicit routing to resolve_comment as the counterpart 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?

Both parameters are fully documented in the schema (100% coverage), including where each value comes from (list_sites, list_comments). The description adds no additional parameter semantics, 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?

The description gives a specific verb (opens/reopens) and resource (a resolved comment thread) plus scope (on a site), so an agent can tell it is the inverse of resolve_comment without opening the schema. It stops short of naming the sibling tool explicitly, which keeps it from a 5.

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

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

Usage is implied: it is for threads that are already resolved, and the 'as its owner' clause hints at a permission precondition. However, there is no explicit statement of when to use this versus resolve_comment or reply_comment, and no stated exclusions or failure conditions.

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: the reply is publicly visible under the owner's name, thread participants are emailed (an external side effect consistent with openWorldHint), the thread remains open by default, and there is a permission restriction. These are exactly the side effects and constraints an agent needs before invoking a write 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?

Five short sentences, each carrying distinct behavioral or usage information, with the visibility/notification effect stated up front and the resolve policy last. No filler or restatement of the name.

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 write tool with an output schema (so return values need no explanation), the description covers visibility, notification side effects, permissions, and the resolve policy. 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%, so the baseline is 3, but the description adds real policy semantics for `resolve` beyond the schema's 'Resolve the thread with the reply': it explains the default behavior (thread stays open) and the condition under which resolving is appropriate. `site` and `thread` provenance is already covered by the schema.

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

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

States a specific verb+resource ('Answers a comment thread on a site as its owner') and clarifies the acting identity. It implicitly differentiates from siblings like resolve_comment and reopen_comment by explaining that the thread stays open unless `resolve` is true, though it never names those alternatives 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?

Gives explicit when/when-not guidance: publish the fix before replying that it is fixed, and resolve only when the commenter asks. It also states the precondition that only the account owner can reply, so an agent can decide before calling whether it is allowed to act.

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

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

Annotations already cover readOnly, idempotent, and destructive flags, so the bar is lower, yet the description adds real context: the owner-only authorization ('as its owner') and the state transition to the resolved set of the currently served version. It stops short of describing failure modes or propagation timing.

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 compact sentences that lead with the action and follow with the behavioral and usage constraints; each sentence earns its place. The phrasing is slightly idiosyncratic ('the version the site serves now') 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?

An output schema exists, so return values need not be explained, and the two required parameters are fully covered by the schema. The description supplies the ownership and usage context an agent needs; only failure/permission behavior is left 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 description coverage is 100%, so both parameters are already documented with their sources (list_sites, list_comments). The description adds no syntax or format detail beyond that, making the baseline 3 appropriate.

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

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

States a specific verb ('marks... resolved'), the resource ('a comment thread on a site'), and the actor scope ('as its owner'). It is clearly distinguishable from reopen_comment and reply_comment in the sibling list.

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

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

Gives explicit when-to-act guidance ('Resolve when the person asks') and an explicit when-not condition ('otherwise leave it for the commenter to confirm the fix'). It also names the undoing sibling tool, so the agent can route between them 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?

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?

Annotations already declare destructive=true and idempotent=true, and the description goes well beyond them: it discloses propagation latency without republishing, that settings outside the plan are rejected with an explanation, and that invented credential values are prohibited. This is the kind of operational context an agent needs before touching a destructive multi-field update.

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, each with a distinct job: what it does, propagation, refusal behavior, and the safety guardrail. The patch semantic is front-loaded and there is 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?

Given a 13-parameter, destructive tool with a full output schema and exhaustive parameter descriptions, the description covers what the schema cannot: patch semantics, latency, plan gating, and a behavioral guardrail. Minor gaps remain around whether existing settings conflict (e.g. password vs invitedOnly interaction is only in the schema), but nothing critical is missing.

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

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

Schema coverage is 100% and the nested env/upstream objects are thoroughly documented inline, so the schema carries the parameter burden. The description only echoes the password/date warning already present in the schema and adds no new naming, format, or interaction detail, so baseline 3 applies.

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

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

States a specific verb and resource ('Changes one or more settings of an existing site') and adds the crucial patch semantic that omitted fields are untouched. It does not explicitly contrast with siblings like change_subdomain, pause_site, or delete_site, so sibling selection still requires inference, 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?

Gives real operating conditions: changes propagate to every edge in about a minute without republishing, and plan-excluded settings are refused with a reason. The closing instruction 'Only change what the person asked for — never invent a password or a date' plus per-parameter 'change it only when the person asked' rules establish clear usage boundaries, though no alternative tool is named.

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