Cockatoo

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the agent knows this is a safe, self-contained read. The description is consistent with that and adds that the payload is a fixed set of building blocks plus a starter document to fill in. It does not state size, pagination, or whether the catalog is environment/config dependent, so it adds only modest context beyond annotations.

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

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

Two short sentences with zero filler, and the action directive ('Start here') is front-loaded ahead of the payload description. Every clause carries information.

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

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

With no output schema, the description carries the burden of explaining return contents, and it does so by naming the four payload categories. The one gap is workflow linkage: it never says what to do with the returned starter document (presumably create_site/save_site), leaving the agent to work out the next hop from sibling names alone.

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, which is the best-case baseline, and the schema confirms an empty properties object. There is nothing for the description to disambiguate, and it correctly signals that the call needs no input to be worth making.

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 concrete verb (returns) and enumerates the concrete resource set: templates, industries, style presets, and a starter document. That is far more specific than the opaque name 'catalog', which alone would tell an agent nothing. It does not explicitly distinguish itself from create_site or get_site, so it stops short of a 5.

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

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

'Start here to build a website' gives an unambiguous entry-point directive that a sibling-heavy toolset (create_site, preview_site, publish_site) would otherwise leave ambiguous. It gives no when-not condition and never names the natural next call (create_site), so the sequencing has to be inferred.

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, and destructiveHint=false. The description adds the constraint that it fails if the owner already has a site, and clarifies that it does not publish. It does not describe authentication needs, side effects, response behavior, or rate limits beyond what annotations provide, so the added context is useful but moderate.

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

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

Three short sentences, front-loaded with the primary action and immediately followed by critical constraints. Every sentence earns its place, and there is no wasted wording.

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 complex: it takes a deeply nested document object and has no output schema. The description covers the core action, non-publishing behavior, and the owner-existence failure condition. However, it does not address what the document must contain, what success returns, or how to handle the idempotency key beyond the schema's own description. It is adequate but leaves clear gaps for such a complex mutation.

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

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

Schema coverage is 50%: idempotencyKey is documented in the schema, but the large nested 'document' parameter has no description. The description says 'structured draft' but does not explain the document structure, required fields, or how to populate it. It does not compensate for the uncovered core parameter.

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

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

The description states a specific verb and resource: 'Create one structured draft.' It also distinguishes the tool from publishing via 'Does not publish' and adds an important constraint: 'Fails if the owner already has a site.' However, it does not explicitly name a sibling like save_site as the alternative for updating, so it does not reach full sibling differentiation.

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

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

The description implies when to use the tool by stating it creates a draft and does not publish. The failure condition ('Fails if the owner already has a site') adds useful context. But it does not explicitly say when to use create_site versus save_site or publish_site, nor does it name alternatives, leaving some usage inference to the agent.

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, and destructive=false, so the safety profile is covered. The description adds useful context beyond that: a prerequisite (owner approval) and a security obligation ('keep returned credentials private'), and it discloses that the operation yields credentials. It does not address failure modes or retry behavior explicitly, keeping it at a 4.

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

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

Two tightly written sentences with zero waste; the prerequisite and core action are front-loaded, and the security note is a fitting closer.

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

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

For a mutation tool with idempotent annotations and no output schema, the description conveys the essential workflow and return nature (an API token). However, it leaves the required 'id' parameter unaddressed and gives no guidance on error or retry semantics beyond the schema's idempotency key note, leaving clear gaps.

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

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

Schema coverage is only 33%, with just idempotencyKey documented in the schema. The description alludes to the continuationCredential ('private continuation credential') but leaves the 'id' parameter entirely unexplained and adds no format or constraint detail for the required credential, so it does not compensate for the low coverage.

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 outcome: exchange a private continuation credential for an API token. This clearly distinguishes it from siblings like start_onboarding and onboarding_status, which handle other phases of the flow.

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 'After owner approval' gives a concrete precondition for when to invoke this tool, which implies it should not be called before approval. However, it does not name an alternative tool or state explicit exclusions, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the safety profile is covered. The description adds value by disclosing the return content ('site and current revision') and the state semantics ('draft or live'), which is useful because there is no output schema. It could go further in describing the site object's contents, but it adds meaningful context beyond the annotations.

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

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

The description is two short sentences with zero waste. The core action and resource are front-loaded, and the state detail follows efficiently.

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

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

For a zero-parameter read tool with annotations covering safety and idempotency, the description provides enough to call it correctly. It discloses the returned artifacts (site, revision, draft/live state) but does not explain what the site object contains, which is a minor gap given no output schema exists.

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 no parameter documentation needed. With no parameters, the baseline of 4 applies; the description does not need to compensate for any schema gaps.

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

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

The description states a specific verb ('Read') and resource ('owner's site and current revision'), making the tool's purpose immediately clear. It does not explicitly name sibling tools or contrast with them (e.g., preview_site, publication_status), but the read-specific framing is distinct enough for an agent to differentiate.

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

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

The description implies usage by saying it reads the site and current revision and notes that state is draft or live, but it does not explicitly state when to use this tool versus alternatives like preview_site or publication_status. The guidance is implied rather than spelled out.

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

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

The annotations already state readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, covering the safety profile. The description adds useful scoping with "retained" and "owned by this site," but it does not disclose pagination, ordering, or response behavior.

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

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

The description is a single front-loaded sentence with no wasted words. It states the action, resource, retention condition, and ownership scope immediately.

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 parameterless read-only list operation with complete annotation coverage, the description is nearly sufficient. It could say more about what "retained" means or what the returned image list contains, but the core invocation context is complete.

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

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

The tool has zero parameters, so there are no parameter meanings for the description to clarify. Per the baseline for zero-parameter tools, the schema itself fully covers the input shape.

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

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

The description uses a clear verb+resource phrase: "List retained uploaded images." It also scopes the result to images "owned by this site," which helps distinguish it from write-oriented siblings such as upload_image, though it does not explicitly contrast with every sibling.

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

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

The wording implies the tool is used to retrieve the site's existing images, but it gives no explicit when-to-use, when-not-to-use, or alternative-tool guidance. For a parameterless list tool the usage is relatively obvious, so this is adequate but not strong.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, covering safety and side-effect behavior. The description adds only that the continuation credential is private, without explaining status values, errors, or credential handling.

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

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

A single front-loaded sentence with no wasted words. However, its brevity contributes to under-specification rather than efficient completeness.

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

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

For a tool with two required parameters, 0% schema description coverage, and no output schema, the description is too thin. It does not explain what "id" identifies, what status information is returned, or how errors/expired credentials are handled.

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

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

Schema description coverage is 0%, so the description should compensate. It references the continuation credential but says nothing about the required "id" parameter or the credential's format/length, leaving both parameters largely undocumented.

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: "Read onboarding status." An agent can tell this retrieves status rather than starting/exchanging onboarding, though the description does not explicitly differentiate it from sibling tools like start_onboarding.

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?

Mentions using the "private continuation credential," implying a post-onboarding-start context, but gives no explicit when-to-use guidance, prerequisites, or alternatives among sibling 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 already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds one genuinely non-obvious behavioral fact — enquiry submission is disabled in the returned HTML — but says nothing about access requirements for private drafts or how the preview relates to saved vs. unsaved edits.

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 compact sentence with the return value front-loaded and a qualifier appended. No filler, no repetition of the tool name or annotations.

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

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

For a zero-argument, read-only tool with rich annotations and no output schema, the description covers what is returned and one behavioral caveat. It omits what happens when no draft exists and how the result differs from get_site, which are the remaining questions an agent would have before calling it.

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

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

The tool takes zero parameters, so there is nothing the description needs to disambiguate at the argument level. Baseline of 4 applies for a no-parameter 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: 'Return private draft preview HTML', which is clearly distinct from mutating siblings like publish_site or save_site. It doesn't explicitly contrast with get_site, so the agent has to infer the draft-preview vs. live-site distinction.

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 word 'preview' and 'draft' imply the use case (inspecting unpublished content before publishing), but there is no explicit when-to-use statement, no mention of prerequisites, and no named alternative such as get_site for published content. Usage is inferable rather than stated.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds one piece of real information beyond that — that the read returns the published revision, not just a status flag — but says nothing about scoping (which site it reads) or what states are possible.

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. It is efficient to the point of being slightly thin, but nothing in it is redundant with structured fields.

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

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

With no output schema, the description carries the burden of describing return values and only sketches them ('state' and 'published revision') without listing possible states or format. It also leaves open whether the read applies to the ambient site context or requires an external identifier, which matters next to siblings like get_site.

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 no parameter semantics to explain and the baseline is 4. The description correctly does not waste space restating an empty input schema.

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

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

States a specific verb and resource ('Read publication state and published revision'), which is clearly distinguishable from the mutating siblings publish_site/unpublish_site. It stops short of explicitly naming a sibling alternative, 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?

The verb 'Read' and the subject 'publication state' make the intended use inferable, but there is no explicit when-to-use guidance, no mention of prerequisites, and no routing versus get_site or the publish/unpublish pair.

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 idempotentHint=true, destructiveHint=false and openWorldHint=true, so the description is not carrying the safety burden alone. It still adds real context beyond them: the auth scope required and the fact that the effect is making content publicly reachable at a hosted address — a consequential, externally visible side effect. It omits what happens to a previously published revision or how conflicts are handled.

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 outcome, with the auth requirement trailing as a precondition. Nothing is wasted, though a single extra clause on `slug` would have cost little.

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

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

No output schema exists, so the description should say something about the resulting published address, which it only alludes to. Annotations cover the mutation/idempotency profile, but a publish operation that exposes content publicly leaves the agent guessing about the optional slug and the revision contract.

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

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

Schema description coverage is only 33%: only idempotencyKey is documented in the schema. The description hints that `revision` refers to an already-saved revision, but never explains the `slug` parameter (the published address identifier) even though the phrase 'public hosted address' gestures at it. With low schema coverage, the description should compensate and does not.

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 ('Publish the saved revision') plus the observable outcome ('to a public hosted address'), which is enough to tell it apart from save_site and preview_site. It stops short of explicitly naming the sibling it replaces or the sibling that reverses it (unpublish_site).

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

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

The required scope (sites:publish) is a useful gating condition, and 'the saved revision' implies the site must already be saved. However, there is no explicit guidance on when to publish vs. preview_site or when to check publication_status, and no mention that unpublish_site is the inverse.

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, but they cannot say what is destroyed; the description adds that valuable scope — the draft is replaced while the live publication is untouched. It does not disclose what happens when the supplied revision is stale (conflict/rejection), which is the main behavioral risk for a destructive overwrite.

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, front-loaded with the action and followed by the critical scope constraint — no wasted prose. The second sentence earns its place; the first is slightly compressed to the point of ambiguity ('current revision').

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

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

This is a destructive, full-document write with a nested object schema, no output schema, and no explanation of the revision precondition, conflict behavior, retry/idempotency flow, or what the caller gets back (e.g., a new revision number). Given the tool's complexity, the two-sentence description leaves too much for the agent to infer.

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

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

Schema description coverage is only 33% — only idempotencyKey is documented in the schema. The description does not explain that `document` is a complete, non-partial replacement (additionalProperties: false, many required fields) nor that `revision` is an optimistic-concurrency token that must match the current draft revision; 'using the current revision' is the only hint and it is vague. An agent could plausibly send a partial document or a stale revision and be surprised.

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?

"Replace the draft using the current revision" names a specific verb (replace) and resource (draft), and the second sentence separates it from publish_site/publication_status by stating it does not affect the live publication. What remains ambiguous is what 'the draft' is scoped to (the whole site document vs. a page) and what 'current revision' means operationally.

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 clause "Does not change the live publication" implicitly routes publishing intent to publish_site, which is useful. But there is no explicit statement of when to call save_site versus create_site, preview_site, or publish_site, and no precondition guidance such as needing the latest revision from get_site before saving.

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 mutation/idempotency/safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false). The description adds meaningful context beyond that: the write lands as a private draft, not a live site, and no email is dispatched, which sets correct expectations for the caller and the user.

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

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

Two tightly packed sentences with the core action and the required follow-up (give the link) front-loaded. No filler, though the second clause about verification and email could be tightened.

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

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

With no output schema, the description correctly surfaces the key return value (approvalUrl). But for a tool taking a deeply nested document payload with 25% schema coverage, it omits any guidance on what the document must contain or what happens on failure, leaving gaps for a complex call.

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

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

Only 25% of parameters carry schema descriptions, and the description explains none of them beyond a passing hint that the user 'signs in with this email.' The semantics of agentName and, critically, the large nested document object are left entirely to the schema, so the description does not compensate for the coverage gap.

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 ('Create the user's website') and goes on to describe the visible outcome (private draft plus approvalUrl). However, it never distinguishes the tool from the sibling create_site, which by name appears to do something very similar, so a caller cannot tell them apart without opening both 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?

The post-call workflow is clear (hand the approvalUrl to the user, who signs in with this email and approves), and it rules out verification/email steps. But there is no explicit guidance on when to use this versus create_site, save_site, or the exchange_onboarding/onboarding_status pair, leaving the selection to inference.

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

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

The annotations already flag this as destructive (destructiveHint=true), idempotent, and not read-only; the description adds the material detail that only the public publication is removed while the draft and enquiries survive, which directly quantifies what is destroyed. It does not say what happens if there is no current publication or whether authorization is required, so it falls short of a 5 even with the annotations.

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

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

Two short sentences with no filler, and the destructive action is front-loaded ahead of the retention caveat. Every clause imparts information the agent needs.

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

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

For a two-parameter destructive mutation with full annotations and no output schema, the description covers the essential outcome and the retained state. The gaps are secondary: the role of 'revision', and whether an error is returned when no publication exists.

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

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

Schema coverage is 50%. The idempotencyKey contract, including its retry-reuse rule, is fully documented in the schema, and the description says nothing about parameters. However, 'revision' stays a bare integer with no meaning given in either the schema or the description, so the description does not compensate for that gap. A 3 reflects that the schema carries most of the weight while the description adds nothing.

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: 'Remove the current public publication.' That is unambiguous and implicitly the inverse of the publish_site sibling, though no sibling is named. It also clarifies the scope of removal, which prevents the agent from over-estimating the blast radius.

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?

'Remove the current public publication' plus 'Draft and enquiries are retained' implies a precondition (a publication must currently exist) and limits the effect of the operation, but neither is explicit. There is no statement of when to prefer unpublish_site over publish_site, preview_site, or publication_status, and no guidance for what to do if no publication exists.

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

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

Annotations already declare the safety profile (readOnly=false, destructive=false, idempotent=true). The description adds a size cap and return value, but doesn't cover retry semantics for idempotencyKey, failure modes, or what happens to orphaned uploads — modest added value over annotations.

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

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

Two short sentences, front-loaded with the constraints an agent needs before calling. No filler.

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

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

For a 3-required-param mutation with no output schema and low schema coverage, the description covers formats, size, and return but leaves the base64 parameter and target-document context unexplained, which is the main remaining gap.

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

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

Schema description coverage is only 33%; only idempotencyKey is documented in the schema. The description hints at mime via the format list but says nothing about the required base64 parameter (encoding, content expectations) or how the size limit maps to base64 maxLength.

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 (upload) and resource (image), with concrete constraints: formats and 5 MiB cap, plus return value assetId. It is clearly distinguishable from siblings like list_images.

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 verb, but the description never says when to use this versus list_images or how it relates to a document/site workflow. No exclusions or prerequisites (auth, upload target) are stated.

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