Create Web Page

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

Annotations already declare readOnly, idempotent, and non-destructive behavior, so the safety profile is covered. The description adds genuinely new context beyond the annotations: that no editToken is required, which is an authorization fact the schema and annotations do not express.

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

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

Two short sentences with the read/no-editToken fact front-loaded, and no wasted words. The closing phrase 'manage a durable website' is somewhat abstract and could be tighter, but overall it is efficient.

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. For a single-parameter read tool with full annotation coverage, the description supplies the authorization context and the usage trigger, leaving only the sibling comparison unaddressed.

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 the single pageId parameter is fully documented in the schema, including its uuid format. The description adds nothing about the parameter, so the baseline of 3 applies when structured fields carry the load.

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

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

States a specific verb and resource ('Read a claimed account page') and adds a distinguishing constraint ('without requiring an editToken') that separates it from the editToken-gated siblings like page_get. The title 'Manage Claimed Page' and the name 'account_page_manage' imply mutation, but the description correctly clarifies it is a read.

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

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

Gives a situational trigger ('Use after OAuth when the user wants to manage a durable website') but never names the alternative tools it should be chosen over, such as page_get or account_pages_list. The editToken remark implies a contrast with page_get, but the routing decision is left to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint and non-destructive, so safety is covered. The description adds real behavioral context beyond them: an anonymous call returns ok=true, authenticated=false and an empty list rather than an error, and sign-in is only needed for later keep/manage operations. That edge-case disclosure is genuinely useful.

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

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

Front-loads the purpose and keeps the auth behavior in the second sentence, but the mid-sentence pivot to 'then create the page directly with page_create_from_brief' is slightly awkward and mixes usage guidance into the purpose statement.

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

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

For a simple read-only list with one optional parameter, an output schema, and annotations covering safety, the description supplies everything an agent needs: scope, auth behavior, and the fallback tool for the create path.

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 the single optional 'limit' parameter is fully documented in the schema with min/max. The description adds no further meaning about the parameter, 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 ('List') and resource ('landing pages saved to the signed-in account'), and the account scoping separates it from page_get/page_preview which operate on a specific page. An agent can identify the operation and its scope 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?

Explicitly covers when this is safe to call (no sign-in required), what happens in that case, and routes the agent to the alternative page_create_from_brief when the goal is actually creating a page. Both the usage condition and the alternative are named.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds the non-obvious behavioral fact that the account may be 'anonymous expiring' — a state an agent should anticipate before calling follow-up tools. Return shape is left to the output schema.

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

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

Two sentences, both front-loaded with the operation then the selection guidance. No filler, no redundancy with the title.

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

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

For a zero-parameter identity probe with full annotation coverage and an output schema, the description supplies everything the agent needs: what it returns conceptually and the decision it informs. Nothing is missing that the structured fields don't already carry.

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; there is nothing for the description to clarify beyond confirming no input is required. No misleading hints about arguments are present.

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 pairs a specific verb+resource ('Return the current Create Web Page account context') and is intrinsically distinguishable from every sibling, all of which operate on pages, blocks, media, or layouts rather than account identity. An agent can tell immediately that this is the identity/introspection call.

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

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

It states a clear use case: 'Use this to check whether the user is authenticated or using an anonymous expiring demo.' That is a genuine when-to-use signal rather than restated purpose. No alternatives are named and no when-not condition is given, but no sibling overlaps this capability, so the gap is minor.

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

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

Annotations only declare it as a non-idempotent, non-destructive write. The description adds substantial context beyond them: the server generates the block id and returns it, edits to already-published pages only save an unpublished latest revision, and the response includes nextSteps hints. These are the behaviors an agent needs to drive the workflow correctly.

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

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

Purpose and type list are front-loaded, and every element is relevant. The publish/unpublish constraint is spread across several sentences that partially repeat the same instruction, which is slightly more verbose than needed.

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 complex 14-variant mutation with a nested schema and an output schema present, the description covers the workflow, draft semantics, id generation, and response hints. Return-value formatting need not be explained because an 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?

Schema description coverage is only 33%, and the description mostly restates the type enumeration already present in the schema's oneOf variants. Neither editToken (likely an auth/edit credential) nor pageId semantics are explained in the description, so the low-coverage params are not fully compensated for.

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 ('Append a new content block to a link-in-bio page') and enumerates all 14 allowed types plus the strict-props requirement. This clearly distinguishes it from siblings like block_update and block_reorder 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?

Explicit when/when-not guidance with named alternatives: do not call page_publish in the same assistant turn, wait for an explicit user request, and do not call page_unpublish. It names the exact sibling tools and the conditions that select them, leaving nothing to inference.

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

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

Annotations already mark the tool as destructive and idempotent, but the description adds crucial behavioral context beyond them: it specifies that for already-published pages the edit saves an unpublished latest revision only, and that the live page should remain public. It also defines the required handoff behavior around page_publish and page_unpublish, which prevents accidental live deployment.

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

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

The description is front-loaded with the core deletion action and organized around the most important constraints. It is somewhat long and repeats the publish-wait rule in different words, but every section still earns its place given the destructive nature of the tool.

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. The description covers the critical behavioral sequencing and side-effect context for a destructive tool, but the missing pageId and editToken parameter explanations leave a gap 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 description coverage is 0%, so the description must carry parameter meaning. It explains blockId as a stable identifier discoverable via page_get, but it never explains the required pageId parameter or the optional editToken parameter. Partial compensation for one of three parameters is insufficient at this coverage level.

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: 'Delete one block by stable blockId.' It clearly distinguishes this destructive operation from sibling tools like block_update, block_add, and block_reorder by specifying deletion of a single block. The added note about saving an unpublished revision for published pages further clarifies the exact scope.

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

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

It gives explicit when-to-use guidance: call page_get first if unsure which blockId to remove. It also provides explicit when-not-to-use guidance and alternatives: do not call page_publish in the same turn, do not call page_unpublish, and wait for a separate user message before publishing. This is exactly the routing and exclusion information an agent needs.

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 state readOnlyHint=false, destructiveHint=false, and idempotentHint=true, so the safety profile is covered. The description adds genuinely useful mutation semantics — that published pages only get an unpublished latest revision and the live page stays public — but it does not describe the response shape or what happens to surrounding blocks' indices when one moves.

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

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

The core action is front-loaded in the first sentence, followed by the workflow constraints. It is efficient, though the publish guidance is somewhat repetitive across two long sentences that 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?

An output schema exists, so return values need no explanation, and the description does cover the crucial workflow caveats for a mutation on a live page. The main gap is the undocumented editToken parameter, which an agent needs to understand to invoke the tool successfully.

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% across 4 parameters, so the description carries the full load. It only explains toIndex ('new zero-based index'), leaving blockId, pageId, and especially editToken — apparently an auth/authorization token — completely undefined in both schema and description.

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 precise verb and resource ('Move a block to a new zero-based index in the page main slot'), and the scope qualifier ('main slot') further anchors what is being reordered. It is trivially distinguishable from block_add, block_update, and block_delete, and it names the publish siblings it must not be combined with.

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

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

Explicit when/when-not guidance: do not call page_publish in the same turn, stop and tell the user the draft was updated, and wait for an explicit user request before publishing. It also states the negative case for page_unpublish ('the live page should stay public; only unpublish when the user explicitly asks'). Nothing is left to inference.

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

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

Annotations cover only safety hints (idempotent, non-destructive), while the description adds genuinely new behavioral context: props are shallow-merged rather than replaced, values are validated against a strict per-type schema, and for published pages the edit lands in an unpublished revision only. The publication workflow constraints are disclosed upfront and materially change agent 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?

Front-loaded with the core purpose and merge behavior, then the publish-safety instructions. The publish guidance is slightly repetitive across sentences ('Stop and tell the user…' / 'do NOT call page_unpublish'), but each clause carries operational weight and none is filler.

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

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

An output schema exists so return values need not be explained. Combined with 100% schema coverage, the description supplies everything an agent needs for a mutation tool: merge semantics, validation behavior, draft-vs-live consequences, and the publish hand-off protocol.

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 every oneOf variant, enum, and field is documented in-schema, so the baseline is 3. The description adds real value beyond it by explaining merge semantics of the props patch (only changed fields need to be supplied) and that the type may be intentionally changed — meaning not present in the schema text.

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

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

States a specific verb and resource ('Patch one content block by stable blockId') and immediately clarifies the two mutation modes (props patch merged into existing props and/or a new type), which separates it from block_add and block_delete. An agent knows exactly what this 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?

Gives explicit when-not guidance for downstream tools (do not call page_publish in the same turn; do not call page_unpublish) plus a required wait-for-user workflow. It does not, however, address when to choose this over sibling block tools (block_add, block_reorder) or the editToken requirement, so it falls short of full alternative routing.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely new context by disclosing the current catalog state ('ships link_in_bio only'), which tells the agent the result set is minimal and may change.

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 resource, then the one extra fact an agent needs. 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?

With an output schema covering return values, rich annotations, and zero parameters, this is nearly complete. It omits only ordering/refresh semantics, which are minor for a static enumeration.

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 are zero parameters, so per the baseline this scores 4. Schema coverage is 100% and there is nothing parameter-level for the description to add.

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 (List) and resource (supported page layouts), which is distinct from siblings like presets_list, block_*, and page_*. However, it never names or contrasts a sibling, so differentiation is left to the reader's inference.

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

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

The description gives no when-to-use guidance, no prerequisites, and no alternatives. An agent can infer it is for discovering layouts before creating a page, but nothing in the text states this or excludes any scenario.

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

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

Annotations already declare the mutation profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false), so safety is covered structurally. The description adds placement-effect context (avatar goes to header, gallery_item is appended, background is theme background), but says nothing about permissions, what happens to a previously attached asset at the same placement, or the editToken/auth requirement for anonymous pages.

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 dense sentence, front-loaded with the core action before the placement enumeration. The inline parentheticals carry real information rather than filler, though the run-on structure makes it slightly harder to scan than a short bulleted mapping would be.

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

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

With annotations, a full output schema, and 100% schema coverage, the description only needs to add placement routing and it does so competently. The omission of header_photo and unassigned from the placement list and the absence of the prerequisite narrative are minor relative to the structured fields that cover them.

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

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

Schema description coverage is 100%, so the baseline is 3. The description restates placement semantics already documented in the schema and, notably, enumerates only four of the six enum values (omitting header_photo and unassigned), so it neither compensates for nor extends the schema meaningfully.

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 ('Attach') and resource ('a ready media asset to the page'), and the word 'ready' implicitly separates it from the upload siblings. The placement breakdown gives the agent an immediate sense of what the operation does to the page.

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?

Explains the conditional routing for placement (block_image requires blockId, gallery_item optional blockId, otherwise first gallery used), which is genuinely useful usage context. However, it never states when to use this tool versus media_upload or media_upload_link_create, nor that a media asset must already exist, so the agent must infer prerequisites from the schema descriptions.

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 genuine context beyond them: that the deletion is a 'soft-delete' (implying recoverability rather than permanent erasure) and that it cascades to remove page-content references. It stops short of stating how/whether the asset can be restored.

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, front-loaded with the action and followed by the scope of effect. No filler or redundant restatement of 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. For a destructive tool the description covers the key behavior (soft-delete, reference cleanup) and annotations cover reversibility/idempotency signals. The only minor gap is not surfacing the anonymous-page editToken requirement.

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 pageId, editToken, and mediaAssetId are fully documented in the schema itself. The description adds nothing about parameter syntax or the editToken condition, 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 ('soft-delete a media asset') plus the consequential side effect ('remove all references to it from the page content'). This clearly distinguishes it from siblings like media_attach and media_upload, though it never names an alternative 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?

There is no guidance on when to use this versus media_attach/media_upload, no prerequisites called out (e.g. the anonymous-page editToken requirement lives only in the schema), and no exclusions. The agent must infer usage entirely from the tool name.

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

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

Annotations declare write/non-idempotent/open-world but say nothing about limits or side effects; the description fills that gap by disclosing that the server fetches imageUrl directly with no size limit, that base64 payloads are rejected by request-size limits, and that a follow-up attach call is normally required. It does not restate auth/permission needs beyond the editToken already covered by the schema, so 4 rather than 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?

Front-loaded with the action, then the parameter preference, the anti-pattern warning, the alternative tool, and the follow-up step — no sentence is filler and nothing is repeated from the schema 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?

With an output schema present, return values need no explanation; the description covers what matters for correct invocation: source-parameter choice, size constraints, the alternative tool for device files, and the required attach follow-up. Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes further by explaining the trade-off between imageUrl and imageBase64 (server-side fetch vs. size-limited inline bytes) — meaning that the schema's one-line field descriptions do not convey. That preference logic directly shapes which parameter an agent picks.

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

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

The description opens with a specific verb+resource ('Add an image to a page') and immediately differentiates this tool from siblings by naming media_upload_link_create as the alternative for device files and media_attach as the follow-up step. An agent can place this among the media_* family 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?

It states explicit routing rules: imageUrl is PREFERRED for web-hosted images, imageBase64 is ONLY for very small inline images, and device files go to media_upload_link_create. It also prescribes the post-upload step (call media_attach unless content already shows the image), which is exactly the when-to-use guidance an agent needs.

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

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

Annotations declare the mutation/idempotency profile, and the description adds substantial behavior beyond them: the page resizes and attaches the image automatically, no media_attach call is needed, the link expires (expiresAt), and the agent must surface uploadPageUrl to the user as a clickable link and confirm via page_get. This is real operational context for an interactive flow.

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 the routing decision in the first sentence, followed by the call parameters and the user-facing follow-up. Slightly long due to the multi-step workflow, but nearly every clause carries actionable 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?

An output schema exists, so return-value details need not be described, yet the description still references uploadPageUrl and expiresAt to wire the agent's flow. Combined with the required/optional parameter handling and the follow-up page_get check, nothing needed 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 description coverage is 100%, so pageId, editToken, altText, and the placement enum are already fully documented. The description restates that pageId and editToken (for demo pages) plus placement should be passed, adding only a single example value (header_photo) beyond the schema. Baseline 3 is appropriate.

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

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

States a specific verb+resource ('Get an upload link for a photo') with a precise scope: images on the user's own device rather than a public URL. Explicitly names the sibling media_attach and says not to use it here, so the agent can distinguish it from media_attach/media_upload 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 an explicit when-to-use condition ('the right tool whenever the image is not already at a public URL') and an explicit when-not/alternative ('you do NOT call media_attach afterward'). It also routes the post-upload verification step to page_get.

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

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

Beyond the annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false), the description discloses the OAuth prerequisite and the concrete failure mode ('an anonymous chat/agent session cannot call it and will get an OAuth-required error'), which is exactly the behavioral context an agent needs before attempting the call.

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

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

Four tightly packed sentences with no filler: purpose, auth constraint and failure mode, the alternative workflow, and the calling condition. The most important constraint (do not call from an anonymous session) is front-loaded.

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

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

With an output schema present, return values need not be described, and the description already covers the two things that matter for this tool: the auth precondition and the correct alternative when that precondition fails.

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 are already documented in the schema (pageId, editToken from page_create), so the description adds no syntax or format detail beyond what the structured fields provide. Baseline 3 applies when the schema carries the parameter burden.

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 states a specific verb and resource ('Claim an anonymous demo page') plus the scope ('into an AUTHENTICATED account'), which immediately separates it from page_create/page_publish siblings that produce pages rather than transfer ownership of one.

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

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

It gives explicit when-not-to-use guidance ('do NOT call this to save a demo page'), names the correct alternative workflow (share the claimUrl from page_create/page_publish for the user to open and sign in), and states the precise precondition for calling it ('Only call page_claim when the request already runs under the owner's OAuth').

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

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

Annotations cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), so the bar is lower, yet the description still adds substantial context: draft-only creation, no publish action returned, placeholder blocks to be filled, and anonymous demo expiry. It does not detail authentication or rate limits, but the behavioral disclosure is well 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 critical caveat (low-level/legacy) and the alternative are front-loaded, and every subsequent sentence carries a distinct actionable instruction (fill via block_update, draft only, stop and show preview, publish condition, demo expiry). No sentence is filler.

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

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

An output schema exists, so return values need no explanation; the description covers the remaining gaps—draft-only semantics, the follow-up block_update step, and the publish guardrail. Nothing needed to call this tool correctly is missing.

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

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

Schema description coverage is 89%, so the schema already documents all nine parameters including enums and the 'auto' inference. The description only references title, displayName, and preset/'auto' at a level the schema already supplies. Baseline 3 is appropriate when structured fields do 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 and resource ('create a blank link-in-bio scaffold from a style preset') and immediately scopes it as 'low-level/legacy'. It explicitly distinguishes itself from the sibling page_create_from_brief, so an agent can choose between them without opening either schema.

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

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

Gives explicit when-to-use ('Not for normal page requests'), names the alternative (page_create_from_brief), and adds an exclusion for page_publish with the exact condition that permits it. The block_update follow-up and stop-and-show-preview instruction cover the rest of the workflow.

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

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

Annotations only declare a non-read-only, non-destructive, non-idempotent, closed-world write. The description adds substantial behavioral context: it creates a private draft, returns previewUrl/pageId/editToken/claimUrl/expiresAt, anonymous pages are deleted after expiresAt unless claimed, starter blocks are seeded and pruned, and nextSteps severity controls publishing. This far exceeds the annotation coverage.

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

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

The core purpose is front-loaded, but the body is a dense multi-clause run-on with many conditional branches (actions, fallback forms, personal pages, claiming, nextSteps) that is hard to parse. The content is largely relevant, yet the structure is a wall of text rather than scannable guidance.

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 29-parameter tool with nested objects, this is thorough: it explains the draft lifecycle, return values, publish gating, anonymous-page expiry, fallback-form constraints, and sparse-brief handling. An agent has enough to invoke and follow up 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 high (83%) and already documents most parameters, but the description adds real meaning: which fields are planning-only and never rendered as body copy, that onboardingMainCategory selects a template, and that fallbackLeadForm requires destinationEmail to deliver. It compensates for the gaps rather than repeating 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 and resource ('The main tool for creating a page') and describes the brief-to-draft flow in detail. However, it never explicitly distinguishes itself from the sibling page_create, so an agent must infer which of the two creation tools applies.

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-use conditions ('call it directly when the request already has the business/page name and the main visitor action with its real destination'), the vague-request branch pointing to page_intake_start, and clear routing rules to page_publish and page_preview. Alternatives and exclusions are named.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds useful context by noting the editToken requirement for anonymous demo pages and that the latest content JSON is included, which goes 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 tightly written sentences with no wasted words. The key purpose is front-loaded, followed by a relevant conditional detail.

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

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

Given that an output schema exists and annotations already convey the safety profile, the description is nearly complete. The main omission is any explanation of pageId, though it is a required UUID and may be self-evident from the name and format.

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

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

Schema description coverage is 0%, so the description must compensate. It partially explains editToken ('For anonymous demo pages, include the editToken') but completely omits pageId, the required parameter. This leaves a significant gap in parameter understanding.

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 ('Read') and resource ('landing page draft') and clarifies that the returned content includes the latest content JSON. It does not explicitly differentiate from siblings like page_preview or account_pages_list, but the scope is clear enough.

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

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

Provides conditional guidance for the editToken parameter ('For anonymous demo pages, include the editToken'), but does not say when to use this tool versus alternatives such as page_preview or account_pages_list. Usage is implied rather than explicit.

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

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

Annotations only declare readOnly=false, idempotent=true, destructive=false. The description adds the critical state effect that on published pages the edit produces an unpublished latest revision, plus explicit guardrails against cascading publish/unpublish calls — 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-loads the field list, which is good, but the publish/unpublish paragraph is repetitive — three sentences restate the same wait-for-user-confirmation rule. Still, every part is actionable rather than 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 12 params, one required, an output schema present, and a mutation that has cross-tool side effects, the description covers the field set, the draft/live distinction, and the required follow-up workflow. Nothing an agent needs to call it safely is missing.

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

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

Schema coverage is 75% and the schema already documents null-clearing semantics, maxLengths, and the display enum meanings. The description mostly restates field names (displayName, bio, verified, label, photoUrl) and repeats the photo_hero/avatar distinction, adding little beyond the schema.

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

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

Names the specific resource (link-in-bio page header) and enumerates the exact fields it edits, so an agent can immediately distinguish it from siblings like page_meta_update and page_theme_update.

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

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

Explicitly states to pass only fields being changed, explains the draft-revision consequence for published pages, and gives a hard rule against calling page_publish/page_unpublish in the same turn, including what to tell the user and what user message must precede publishing.

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

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

Annotations already declare readOnly, idempotent, and non-destructive, so safety is covered. The description adds real behavioral context beyond them: it returns 'at most one round of questions', is call-limited to once per request, and explicitly 'Does not create a page', clarifying the side-effect-free nature.

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 primary purpose, then progressively adds return behavior, skip conditions, and constraints. Slightly dense but each sentence carries distinct information; 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?

With an output schema present and rich annotations, the description need not explain return values yet still describes their shape ('one round of questions'). Combined with clear usage routing and a no-side-effect statement, 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 description coverage is 100%, so the schema carries the parameters and a baseline of 3 applies. The description adds meaning by enumerating the intake content (name, main visitor action and its destination, must-have facts) which maps onto businessName, primaryGoal, and the destination concept, giving the agent a sense of what inputs it should already have.

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 function: an optional intake step that returns at most one round of clarifying questions for a vague page request. It clearly distinguishes itself from siblings by naming page_create_from_brief (the actual creation path) and source_import (the link-reading path).

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

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

Explicit when-to-use (vague request lacking name/action destination), when-to-skip with a named alternative ('call page_create_from_brief directly'), and an alternative handling path for public links ('read it yourself or use source_import'). Also constrains frequency ('Call at most once per request').

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 non-destructive and idempotent, but the description adds critical behavior they cannot express: for already-published pages only an unpublished latest revision is saved, and the live page remains public until an explicit publish. This is exactly the workflow-level context a mutation tool needs.

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

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

Purpose is front-loaded in the first sentence and the following sentences are guardrails rather than filler. Slight redundancy between the 'do not call page_publish' and 'do not call page_unpublish' instructions, but each still carries distinct 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, return values need no explanation, and annotations cover the safety profile. The description supplies the remaining risk-relevant knowledge an agent needs: the draft-vs-live distinction and the required user-confirmation gate.

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 67%; the description names title, slug, and SEO fields, which partially maps to the schema but adds no syntax, format, or constraint detail beyond what the property descriptions already say. pageId and editToken are unaddressed, so this is baseline-adequate rather than additive.

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 and enumerates exactly which fields are mutated: internal title, URL slug, SEO title/description. This is sufficient to distinguish it from page_header_update and page_theme_update 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?

Gives explicit when-not-to-use guidance naming siblings page_publish and page_unpublish, plus the exact sequencing rule: stop, report the draft/preview update, and wait for a separate user message explicitly requesting publication before calling page_publish. Nothing is left for the agent to infer.

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 this as a safe, idempotent, non-destructive local read, but the description adds substantive flow behavior beyond them: the flow is STATELESS, page_onboarding_update retains nothing, and each update must resend the full selection set. This is high-value context that no annotation conveys and directly prevents incorrect call sequences.

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 purpose, then usage, then the stateless caveat, then the stop condition — a logical progression where each sentence carries a distinct instruction. It is dense and all-caps emphasis is heavy, but no sentence is dead weight.

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 annotations cover the safety profile. The description supplies the missing usage and statefulness context, leaving nothing an agent needs to invoke this correctly unexplained.

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 low (33%), so the description needs to compensate but largely doesn't. It hints at what suggestedSelection should hold ('category, layout, palette, primary action' and 'resend the FULL set of selections + knownFields'), but leaves originalRequest undocumented and gives no field-level syntax. Partial compensation warrants a mid-low score.

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 (guided visual setup) and immediately scopes it with 'does NOT create a page,' which contrasts it against page_create_from_brief and the other page-creation siblings. An agent can distinguish this tool from its neighbors 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?

Gives explicit when/when-not guidance ('Use it ONLY when the user explicitly wants to choose the style/layout step by step') plus the alternative and its own protocol ('for normal requests call page_create_from_brief, asking at most one round of questions first'). It even names the terminating condition ('as soon as you have a business name and a primary action, stop'), so the routing decision is fully determined.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds the non-obvious behavioral trait that matters most here — STATELESS with no memory of prior calls — and explains the concrete consequence ('earlier choices will look missing'), which is exactly the kind of context 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 one-line purpose, then the STATELESS constraint and the routing hint in priority order. It is longer than average, but every sentence targets a distinct failure mode (dropped state, unnecessary looping), so the length is largely earned.

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 a nested schema, an output schema (covering return values), and informative annotations, the description supplies the critical missing piece — statelessness and full-state resubmission — plus the hand-off to page_create_from_brief. Minor gaps remain around stepId semantics and step progression, but nothing an agent needs to invoke it correctly is absent.

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?

Top-level schema coverage is only 25%, so the description must carry weight, and it does: it enumerates the accumulated selection fields (mainCategory, subCategory, layout, palette, primaryAction) and knownFields (name, description, action destination), and explains why full state must be resent. It omits stepId, locale, recommendedBlock, and the remaining knownFields flags, which are only partly documented in the schema.

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

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

States a specific verb and resource: 'Validate onboarding selections and return the remaining checklist.' This is clearly distinguishable from page_onboarding_start and names page_create_from_brief as the downstream tool, so an agent can place it in the flow without opening either schema.

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

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

Gives explicit when-to-use instructions ('every call must include the FULL accumulated selection… plus all knownFields') and an explicit exit condition ('once you have a name and a primary action, call page_create_from_brief'). It even tells the agent not to loop to 'ready', removing a plausible wrong behavior.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety bar is covered. The description adds real behavioral context beyond them: the operation can fail for anonymous demo pages when editToken is missing, and the token must come from the create result. It does not discuss caching or expiry of the returned URL, which is the main remaining unknown.

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

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

Three short sentences, front-loaded with the return value, then the routing advice, then the failure condition. No filler; each sentence changes agent behavior.

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

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

With an output schema present, return values need not be explained, and the description covers the two things that matter for correct invocation: when not to call it and the editToken requirement for anonymous pages. Complete for a two-parameter 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 already documents editToken as 'Required for anonymous demo pages.' The description paraphrases that same constraint rather than adding format, sourcing, or edge-case detail, so the baseline 3 applies.

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

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

States a specific verb and resource ('Return the current preview URL for a page') and immediately positions itself against siblings page_create and page_create_from_brief, which already return a previewUrl. An agent can tell why this tool exists and when the others make it redundant.

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 says 'You usually do not need this' and names the two alternatives that supply previewUrl already. It also gives the one condition that forces this call — anonymous demo pages needing editToken — plus the failure mode if that token is omitted.

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 idempotency, safety, and closed-world scope, so the burden is light. The description adds genuinely new behavior: the editToken must be supplied for anonymous demo pages, and the response's nextSteps field must always be surfaced to the user (claim reminder, remaining improvements). It does not restate the annotation hints.

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 sentences, front-loaded with the action, then trigger, then anti-trigger, then the token/response handling. No sentence is filler; each carries a distinct constraint.

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?

A plus an output schema covers return values, and the description still flags the one response behavior that matters (always relay nextSteps). Nothing needed to call or act on this tool is missing.

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

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

Schema coverage is 100% and the schema already documents both parameters, including that editToken is required for anonymous demo pages — the description largely repeats that. It adds only workflow framing (where the token came from) rather than new semantics, so the baseline 3 applies.

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

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

States a specific verb and resource ('Publish the latest page revision') with scoping detail that separates it from page_unpublish and the page_create family. An agent can identify the operation without opening the schema.

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

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

Gives an explicit trigger ('only when the user's latest message explicitly asks to publish, make the page live, or get a public share link') plus an explicit anti-trigger ('Do not call this immediately after page_create or page_create_from_brief just because the draft is publish-ready'). This is the when/when-not pattern at its best.

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

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

Annotations only declare the generic profile (readOnly=false, idempotent=true, destructive=false, openWorld=false). The description adds material behavior the annotations cannot: on already-published pages the edit writes only an unpublished latest revision, leaving the live page untouched, and it imposes a turn-boundary workflow constraint that prevents an agent from chaining a publish immediately after the edit.

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 and the field scope, then the workflow guardrails. Slightly long: the publish/unpublish prohibition is restated across three sentences (do not publish this turn, wait for an explicit request, do not unpublish either) where two would carry the same meaning, but each sentence still maps to a distinct failure mode.

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 the remaining risk areas for a mutation tool: partial-patch semantics, the draft-vs-live consequence for published pages, and the sibling tools that must not be chained. Nothing an agent needs to call this correctly is missing.

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

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

Schema description coverage is only 33%, so the description must carry weight; it names the enum-constrained field groups but does not explain the non-enum surface (the background oneOf branches for solid/gradient/image, or text_color/accent_color/muted_text_color). Since the nested schema properties do carry their own descriptions and enums, this is adequate but not compensating for the low coverage figure.

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 ("Apply a partial theme patch") and immediately scopes it by enumerating the enum-constrained theme groups it touches (button variant/radius/shadow, font family/weight, density, icon_size). This distinguishes it from sibling mutators like page_header_update and page_meta_update, which patch different regions of the page.

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

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

Gives an explicit alternative for a related intent ("Use presets_list first if the user wants a complete restyle") and two hard exclusions with their triggering conditions (do not call page_publish in the same turn; do not call page_unpublish unless the user explicitly asks to take the page down). It also prescribes the exact next step after the edit — stop and report the draft update, then wait for an explicit user request.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and openWorldHint=false. The description goes beyond them by scoping the destruction precisely: only public availability is removed, while the draft and revision history survive, which is exactly the consequence an agent needs to reason about before calling. It does not mention auth requirements or whether unpublishing an already-unpublished page is a no-op.

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 well-formed sentence with the outcome front-loaded and no filler. Every clause carries meaning: the action, the target, and the preserved state.

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 mutation with an output schema (so return values need not be described) and rich annotations, the description covers the essential behavioral outcome. The remaining gap is the undocumented editToken requirement, which is a meaningful omission for a write tool.

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

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

Schema description coverage is 0% and neither pageId nor editToken is documented in the schema. The description only implies that pageId must reference a published page; it says nothing about the editToken's role or format, so it fails to 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 (remove from public availability) and resource (published landing page), and implicitly separates itself from page_publish and from a hypothetical hard-delete by noting the draft and revision history are retained. An agent can identify the operation without opening the schema.

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

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

Usage is implied by the phrase 'published landing page' – the tool only applies to pages currently live. However there is no explicit when-to-use/when-not guidance and no mention of the page_publish alternative or of prerequisites such as holding a valid editToken.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description still adds real value beyond that: the list is a fixed, curated set of exactly 12 items composed of theme + starter blocks, which tells the agent this is a stable enumeration rather than a dynamic query.

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: the first front-loads what is returned and its composition, the second gives the usage condition. No filler and nothing redundant with the schema.

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

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

A zero-parameter, read-only enumeration with an output schema, so the description need not explain return values or parameters. What remains — what the tool returns and when to call it — is fully covered.

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 for the description to disambiguate. Baseline 4 applies for a zero-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 (list) and resource (the 12 curated style presets), plus what they contain (theme + starter blocks) and the domain (link-in-bio). It does not explicitly differentiate itself from the sibling layouts_list, which an agent could plausibly confuse with presets, so it falls short of a 5.

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

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

Gives two concrete usage contexts: offering the user a choice, or confirming a preset:auto selection. Clear when-to-use, but it names no alternative tool (e.g. layouts_list) for the case where the agent wants layouts rather than presets.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds real value beyond them: the network scope (public HTTP/HTTPS only) and the explicit failure boundaries (no login/CAPTCHA/paywall bypass), plus what the response contains. Rate limits, timeouts and error behavior are not disclosed.

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

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

Three sentences, each doing distinct work: what it extracts, what it will not do, and what it returns and feeds. The key scope constraint 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?

With an output schema present, return values need not be enumerated and annotations cover the safety profile, so the description is close to sufficient. It stops short of stating what happens when a URL is non-public or unfetchable, which would matter for an openWorld, network-dependent tool.

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

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

Schema description coverage is 100%, so sourceUrl and locale are already fully documented in the schema. The description restates the public-URL constraint but adds no syntax or format detail (e.g. locale behavior, URL normalization) 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?

States a specific verb (fetch/import) and resource (public website URL) plus the concrete payload it produces (business name, description, contact links, suggested page blocks). It also names the downstream consumer, page_create_from_brief, so the agent can place it in the workflow without opening a schema.

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

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

Gives explicit boundaries: only public HTTP/HTTPS pages, and it does not bypass login, CAPTCHA, or paywalls. It implies when to use it by naming page_create_from_brief as the follow-on, but does not name an alternative tool for pages behind auth or otherwise inaccessible sources.

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