Create Web Page

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

Annotations already declare readOnly, idempotent, and non-destructive hints. The description adds relevant auth context ('without requiring an editToken') and a post-OAuth condition, which are not captured by 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 sentences with no redundancy; the action is front-loaded and the usage context follows 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?

With one simple parameter, an output schema, and annotations covering safety, the description supplies the remaining context needed (auth requirement and when to use), making it functionally 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 schema fully describes the sole parameter `pageId` (100% coverage), so the baseline of 3 applies; the description doesn't add further parameter details but also doesn't need to.

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 ('a claimed account page'), with a key qualifier 'without requiring an editToken.' It is distinguishable from page_get by the editToken condition and the 'claimed' scope, though no sibling is named.

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 provides a usage context: 'Use after OAuth when the user wants to manage a durable website.' This tells the agent when the tool applies but does not mention exclusions or alternative 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?

Even with annotations marking readOnlyHint, idempotentHint, and destructiveHint=false, the description adds valuable behavioral context: anonymous sessions return ok=true with an empty list and authRequired=true as a non-error state. This prevents a likely misinterpretation of the tool's response.

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

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

The description is compact and information-dense. Every sentence earns its place: core purpose, anonymous behavior, and routing guidance are all included without unnecessary filler or repetition.

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

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

The description is complete for this tool's complexity: one optional parameter, full schema coverage, an output schema, and annotations already cover safety. It adds the crucial auth edge case and next-step alternatives, so an agent knows exactly when and how to invoke it correctly.

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

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

The only parameter, limit, is fully described in the schema with min/max and meaning, so the description does not need to add much. It provides no extra detail about limit behavior, but the schema already covers semantic coverage entirely at 100%.

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

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

The description opens with a specific verb and resource: 'List landing pages claimed by the signed-in account.' It clearly defines the tool's scope and distinguishes it from related actions by noting that sign-in is needed to claim or manage pages, not to list them.

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

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

The description gives explicit guidance on when to call this tool and what to do instead: it explains the anonymous demo case, tells the agent not to treat authRequired=true as an error, and directs the agent to page_intake_start or page_create_from_brief when there are no saved pages.

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 indicate read-only, idempotent, and non-destructive behavior. The description adds context about the returned data (authentication vs anonymous demo), which goes beyond what annotations provide. It does not contradict any 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 sentences with zero waste. The primary action and use case are front-loaded, and every word adds value. It is compact and easy to parse.

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 whoami tool with no parameters and an output schema, the description fully covers what the tool does and why to use it. No additional context is needed for an agent to invoke it correctly.

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

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

The tool has zero parameters, and the schema coverage is effectively 100% (empty schema). The description doesn't need to explain parameters; the baseline for zero-parameter tools is 4, and the description adds no parameter-specific info but doesn't need to.

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

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

The description clearly states the tool returns the current Create Web Page account context and explicitly mentions its use for checking authentication status. This distinguishes it from sibling tools that manage pages or blocks.

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 provides a clear 'when to use' by stating it checks whether the user is authenticated or using an anonymous expiring demo. It doesn't explicitly state when not to use or name alternatives, but the purpose is so specific that no alternatives are needed.

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, the description discloses key behavioral details: the server generates the block id, edits to published pages only create an unpublished revision, and the response includes nextSteps hints that should be shared with the user. It also clarifies publish/unpublish sequencing, which is critical for an agent to avoid unintended live-page changes.

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

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

The description is long but information-dense and mostly front-loads the core action before moving to workflow constraints. There is some redundancy around publish/unpublish waiting behavior, and the 13-vs-14 type-count error adds avoidable confusion, but most sentences contribute meaningful operational 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 complex tool with a large oneOf schema, the description covers the behavioral contract very well: draft-only saves, server-generated ids, nextSteps, and publish sequencing. However, it omits the save_contact variant entirely, miscounts the allowed types, and leaves editToken's purpose undefined, which are notable gaps given the schema's size and the need for precise invocation.

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

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

The description adds useful meaning for the block parameter by emphasizing strict per-type props and server-generated ids, but it does not explain pageId or editToken, and with only 33% schema description coverage those unexplained parameters remain a gap. The schema itself carries most of the per-variant detail, so the description adds moderate value but does not fully compensate.

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

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

The description clearly states a specific action and resource: append a new content block to a link-in-bio page, which distinguishes it from block_delete, block_update, and block_reorder. It also enumerates the allowed block types, though the count is inaccurate—it says 13 while the schema defines 14 types including save_contact.

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 unusually explicit when-to-use guidance: for already-published pages it only saves an unpublished latest revision, and it instructs the agent not to call page_publish in the same turn, to wait for explicit user confirmation before publishing, and not to call page_unpublish unilaterally. This provides strong operational guardrails that go well beyond the schema.

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 this as destructive and idempotent, but the description adds critical behavioral detail: for already-published pages, the tool 'saves an unpublished latest revision only' and leaves the live page public. It also clearly warns against publishing or unpublishing in the same turn offers safety context beyond the annotations. There is no contradiction with 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 front-loaded with the core action and the stable-blockId detail. The subsequent sentences are long but each carries important safety and workflow context. It is somewhat verbose, especially the multi-clause instruction about waiting for a separate user message, but that verbosity is justified given the risk of accidentally modifying a live page.

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

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

The description covers the primary deletion behavior, the published-page revision behavior, and important sequencing constraints. An output schema exists, so the return value does not need to be explained. However, editToken is left completely unexplained in both the schema and the description, and the behavior for unpublished pages is only implied. These gaps mean an agent may not know when to supply editToken or what exactly happens in the non-published case.

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

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

The input schema provides no descriptions for pageId, blockId, or editToken, and schema description coverage is 0%. The description only clarifies that blockId is stable and suggests page_get when unsure. It does not explain the role of editToken, why pageId is needed, or any constraints around them. The description does not adequately compensate for the missing schema-level parameter documentation.

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 exactly what the tool does: 'Delete one block by stable blockId.' The verb is specific, the resource is clear (a single block), and it is easily distinguished from siblings like block_add, block_update, and block_reorder. The mention of 'stable blockId' also clarifies the type of identifier used.

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

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

Explicitly tells the agent to call page_get first if unsure which block to remove. It also gives clear rules about not calling page_publish in the same assistant turn, waiting for an explicit user request to publish, and avoiding page_unpublish unless the user explicitly asks to take the page down. This is strong, unambiguous routing and sequencing guidance.

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

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

The annotations only indicate readOnlyHint=false, idempotentHint=true, and destructiveHint=false. The description adds meaningful behavior beyond those flags: it explains that published pages are not altered live, only an unpublished latest revision is saved, and that the live page should remain public. This is exactly the kind of contextual behavior an agent 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?

The core operation is front-loaded in the first sentence, followed by compact, high-value constraints. Every sentence earns its place, and there is no filler or redundant schema repetition.

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

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

Given the complexity of the publish workflow and the presence of an output schema, the description is complete enough. It covers the draft-only behavior, the critical guardrails around page_publish and page_unpublish, and the expected assistant behavior after the edit. An agent has what it needs to invoke the tool 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 description coverage is 0%, so the description must compensate. It does clarify that toIndex is zero-based and that the operation targets the page's main slot, but it does not explain editToken or add explicit semantics for pageId and blockId beyond what their names imply. Partial compensation is present, but not complete.

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

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

States a specific verb and resource: 'Move a block to a new zero-based index in the page main slot.' This clearly distinguishes block_reorder from sibling block tools like block_add, block_delete, and block_update, whose purposes are different.

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 workflow constraints: for already-published pages it saves an unpublished revision only, and it explicitly instructs not to call page_publish in the same turn, not to call page_unpublish, and to wait for a separate user request before making changes public. This is strong when-to-use and when-not-to-use guidance.

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

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

Annotations establish idempotent/non-read-only safety, but the description adds critical behavior beyond them: partial merge semantics, strict per-type validation, draft-only revision for published pages, and the publish/unpublish workflow constraints. No contradiction with 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 long but not padded; every sentence carries either merge semantics, validation behavior, or high-stakes publishing workflow. The core action is front-loaded before the caveats.

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

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

The description covers the key behavioral and sequencing facts, and an output schema exists so returns need not be described. The only notable gap is editToken, which appears in the schema with no description anywhere and isn't explained in the tool description.

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, so the baseline is 3, but the description adds useful meaning: props are 'merged into existing props' and blockId is stable. The 'and/or a new type' phrasing is slightly imprecise because type is required by the schema, though the variant descriptions clarify that current type should be passed unless changing it.

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

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

The description opens with a specific verb and resource: 'Patch one content block by stable blockId.' It immediately distinguishes block_update from sibling block_add/block_delete/block_reorder and names the two inputs that matter (props patch and type change).

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 guidance: for already-published pages it only saves an unpublished revision, and it instructs not to call page_publish in the same turn, to wait for a separate user request, and not to call page_unpublish. This is exactly the kind of cross-tool sequencing 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 establish that the operation is read-only, idempotent, and non-destructive. The description adds useful state information by noting the current supported set is limited to link_in_bio, which prevents the agent from assuming a broader catalog exists. This is meaningful behavioral 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?

Two short sentences deliver the main purpose first and the current-state caveat second. Every word earns its place; there is no fluff or repetition 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?

For a zero-parameter, read-only list tool with an output schema present, this description is complete. It tells the agent what the tool returns, the current scope, and that the result set may be limited. There is no missing information needed to invoke it correctly.

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

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

The tool has zero parameters and the schema description coverage is 100%, so there is no parameter documentation burden for the description to carry. The baseline for a no-parameter tool is 4, and 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 uses a clear verb and resource: 'List supported page layouts.' The phrase 'Currently ships link_in_bio only' further specifies the expected scope. It is more informative than the title, though it does not explicitly differentiate from potentially similar siblings like presets_list.

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

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

The description implies the tool should be used when an agent needs to enumerate available page layouts, especially since it states only one layout currently exists. However, it gives no explicit when-to-use or when-not-to-use guidance and does not mention 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 this is a mutating (readOnly=false), idempotent, non-destructive operation. The description adds useful placement behavior: gallery_item is appended and falls back to the first gallery when no blockId is given. It does not contradict 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?

One dense sentence with the core action first, followed by placement semantics; no filler. The semicolon-separated list earns its place.

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

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

The rich schema, output schema, and annotations cover parameters and safety, so the description need only provide the core workflow. It omits header_photo and unassigned placements, but those are fully enumerated in the schema; overall the agent has enough to invoke correctly.

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

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

With 100% schema coverage, the schema already documents all six parameters. The description adds a little extra placement/blockId behavior ('otherwise the first one is used') but mostly paraphrases the schema, so the baseline 3 is appropriate.

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

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

The opening phrase 'Attach a ready media asset to the page' names a specific action, an existing media resource, and a target page, and 'ready' distinguishes it from media_upload/media_delete. The placement explanations further clarify the resource 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?

The description establishes when to use the tool by requiring a 'ready' asset and explaining placement-specific constraints such as blockId being required for block_image and optional for targeting a gallery. It does not explicitly name sibling tools, but the context and schema references to media_upload/media_upload_link_create make the intended workflow clear.

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

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

The description adds meaningful behavioral context beyond the annotations: it clarifies that the deletion is 'soft' (not a hard delete) and that it removes all references from page content, which is a side effect not captured by the destructiveHint or idempotentHint annotations. This is transparent and consistent 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?

The description is a single, well-structured sentence that front-loads the key action ('soft-delete') and immediately states the important side effect. Every word earns its place.

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

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

Given that an output schema exists and annotations cover destructive/idempotent behavior, the description is nearly complete. It explains the operation type and side effects; the only minor gap is not elaborating on what 'soft-delete' means for recovery, but that is not essential for correct invocation.

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

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

The input schema already documents all three parameters with descriptions (pageId, editToken, mediaAssetId) at 100% coverage. The description adds no parameter-level detail, so the baseline of 3 is appropriate; the schema carries the semantic weight.

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 clear verb ('soft-delete') and resource ('media asset'), and adds the specific effect of removing references from page content. This distinguishes it from sibling tools like media_upload or media_attach, which are about adding media, and from block_delete, which targets blocks.

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

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

The description implies the tool is for deleting media assets that are referenced in page content, but it does not explicitly state when to use it over alternatives, mention prerequisites (e.g., needing an editToken for anonymous pages), or note when not to use it. This leaves some 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?

Beyond the annotations (which only indicate non-readonly, non-idempotent, non-destructive), the description reveals key behaviors: the server fetches imageUrl with no size limit, large base64 payloads are rejected by request-size limits, and successful uploads may or may not already display the image. This adds substantial real-world behavior context and contains no contradiction with 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 dense but every sentence earns its place: preferred mode, size constraint, safety rule, sibling routing, and follow-up action. It front-loads the core purpose and uses formatting (PREFERRED, ONLY, never) to draw attention to critical constraints.

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 an output schema exists and the input schema covers 100% of parameters, the description fills the remaining practical gaps: when to use which input mode, size limits, device-file routing, and the required attach step. Nothing an agent needs 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 coverage is 100%, so the baseline is 3. The description adds meaningful semantics on top by explaining the size-limit tradeoff between imageUrl and imageBase64, the 'never paste photo bytes' rule, and routing device files to a different tool. This goes beyond the schema's descriptions, though it doesn't add per-parameter detail for all eight parameters.

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 ('Add an image to a page') and immediately differentiates from sibling tools by naming media_attach (placement) and media_upload_link_create (device files). An agent can tell exactly what this tool does without opening the schema.

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

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

The description gives explicit when-to-use guidance: PREFERRED for web images via imageUrl, imageBase64 only for very small inline images, and a direct instruction to use media_upload_link_create for device files. It also states the required follow-up call to media_attach, making the usage workflow unambiguous.

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

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

Annotations provide no safety hints (all false), so the description carries the full burden. It discloses key behaviors: the link expires (referencing expiresAt), the page automatically resizes and attaches the image, and the flow requires user interaction. This is useful behavioral context beyond the bare operation, though it does not mention permissions or failure modes.

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

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

The description is dense but every sentence earns its place: purpose, usage condition, required params, workflow, expiration, and follow-up verification. It is front-loaded with the core decision ('the right tool whenever...') and avoids filler or redundancy.

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

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

Given the tool's interactive flow and the presence of an output schema, the description covers all necessary context: when to use it, how to invoke it, what to do with the result, what not to do afterward, and how to confirm success. No critical operational detail is missing for an agent to call it correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds minor value beyond the schema—clarifying the interactive workflow and giving placement examples (header_photo)—but it does not substantially enrich parameter meanings beyond what the schema already states (e.g., editToken required for demo pages, placement enum meanings).

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: 'Get an upload link for a photo on the user's own device'. It explicitly distinguishes itself from siblings: 'the right tool whenever the image is not already at a public URL', and warns 'do NOT call media_attach afterward'. This makes the tool's purpose and boundary unambiguous.

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

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

The description gives explicit when-to-use guidance (image not at a public URL), required parameters (pageId, editToken for demo pages, placement), and follow-up steps (show link to user, call page_get to confirm). It also provides an exclusion ('so you do NOT call media_attach afterward'), leaving no ambiguity about the correct 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?

The description adds important behavioral context beyond the annotations: it requires the signed-in user's OAuth, and an anonymous session will get an OAuth-required error. This is exactly the kind of consequence disclosure that helps an agent avoid failed calls. The annotations (readOnlyHint false, idempotentHint true) do not contradict the description.

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

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

The description is compact and front-loaded: it opens with the core purpose, then explains the auth constraint, then gives a concrete usage directive. Every sentence contributes actionable information without padding.

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

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

For a two-parameter tool with a complete schema and an output schema, the description covers all essential context: what the tool does, when to call it, when not to call it, the auth failure mode, and the correct alternative flow. Nothing needed for correct invocation is missing.

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

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

Schema coverage is 100%, so the input schema already fully documents pageId and editToken, including their origin from page_create. The description adds no new parameter-level meanings, but it does not need to; the baseline of 3 applies because the schema carries 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?

The description states the exact action and resource: claiming an anonymous demo page into an authenticated account. It also differentiates this from related flows by explicitly referencing page_create/page_publish and the claimUrl alternative, so an agent can distinguish it without opening the schema.

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

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

The description gives explicit when-to-use and when-not-to-use guidance: it tells agents not to call this in a normal agent conversation to 'save' a demo page, instead directing them to share claimUrl. It also specifies the only valid calling context: 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?

Since all annotations are false, the description carries the full burden and shoulders it well. It discloses the empty placeholder state, the need to fill via block_update, the absence of a publish action in the response, and the expiration of anonymous demo 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?

Four dense sentences, with purpose first, then input guidance, then behavioral guardrails. Every sentence contributes operational value and there is no filler or repetition of schema boilerplate.

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 an output schema exists, return values do not need describing; the description covers the create workflow, the no-publish constraint, and post-call behavior. It is slightly less than complete because the schema leaves initialPrompt undocumented and the description does not clarify it, but an agent can still call the tool correctly.

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

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

Schema description coverage is high (89%), so the schema already documents most parameters. The description adds useful semantics by explaining that preset can be 'auto' inferred from businessType/style and by naming title, displayName, and preset as key inputs. One minor issue: 'Provide title, displayName, and a preset' overstates displayName as required when it is optional in the schema.

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

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

The description opens with a specific verb+resource: 'Create a hosted link-in-bio page draft from a style preset.' It further separates itself from sibling tools by emphasizing it creates a draft only and does not return a publish action, and by contrasting 'style preset' creation with brief-based creation.

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 tells the agent what inputs to provide, to not invent content, to stop after the tool and show the preview URL, and to avoid page_publish unless the user explicitly asks to publish. It even conditions the exception on exact user intent, which is unusually actionable.

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

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

Annotations are all false and provide no safety signal, so the description carries the full burden. It discloses many behaviors: previews are customer-facing, planning fields must not become public copy, sparse briefs must not be padded with invented facts, missing CTA destinations require either asking or fallbackLeadForm, anonymous pages expire unless claimed, and the draft seeds starter blocks that are pruned if empty.

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

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

The description is long but front-loaded with the core purpose and organized into distinct behavioral and workflow concerns. It is dense rather than padded, though some warnings overlap with schema-level field descriptions, keeping it from a perfect score.

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, nested-object tool with an output schema and no meaningful annotations, the description is remarkably complete. It covers creation constraints, public-copy guardrails, CTA fallback behavior, page expiration, next steps, and the post-call workflow, so an agent has enough context to invoke it correctly.

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

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

Schema coverage is high at 83%, so the schema already documents individual parameters. The description adds meaningful cross-parameter semantics by grouping fields into planning-context versus final-audience publicSections, and by explaining that public contact fields must come from user-supplied or public sources. It does not enumerate every parameter, but the high-level grouping is valuable.

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

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

The description opens with a specific verb and resource: 'creates a hosted landing page draft from a structured brief.' It also clearly distinguishes this tool from nearby siblings by stating it is draft-only, steers vague requests toward page_onboarding_start, and notes page_preview is unnecessary.

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

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

The description gives explicit when/when-not guidance: prefer page_onboarding_start for vague first-page requests, pass onboardingMainCategory otherwise, do not call page_publish in the same turn unless the user explicitly asks to publish, and use the returned previewUrl directly instead of page_preview. This makes tool selection actionable.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds value by stating that the tool returns 'latest content JSON' and by flagging the need for an editToken on anonymous pages—details 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?

Two concise sentences with no filler. The core purpose is front-loaded ('Read a landing page draft...') and the additional condition about editToken is stated directly. Every sentence earns its place.

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

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

Given the rich annotations (readOnly, idempotent, non-destructive) and the presence of an output schema, the description is largely complete for a read operation. It covers the key edge case (anonymous pages) and the return content. It could arguably mention that it retrieves drafts specifically, but the title already implies that.

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

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

The schema has no parameter descriptions (coverage 0%). The description adds meaning for editToken ('For anonymous demo pages, include the editToken') but does not explain pageId, though its name is reasonably self-explanatory. It partially compensates for the schema gap but not fully.

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 a clear resource ('a landing page draft') and adds what is returned ('latest content JSON'). It distinguishes itself from sibling operations like page_create or page_publish by being explicitly a read operation, and the mention of 'anonymous demo pages' and 'editToken' further differentiates it.

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

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

The description provides a clear condition for when to include the editToken ('For anonymous demo pages'), which is a usage guideline. However, it does not explicitly state when to prefer this tool over its read siblings like page_preview or when not to use it, though the read-only nature is implied.

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 description discloses the critical non-obvious behavior: for published pages, edits create an unpublished draft revision rather than mutating the live page. It also explicitly warns against calling page_publish or page_unpublish in the same turn, which is essential behavioral context that annotations alone do not convey. The idempotentHint annotation is consistent with the 'use only the fields you want to change' partial-update semantics, and the description adds the draft-vs-live distinction that makes the tool safe to invoke.

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 dense paragraph that front-loads the resource and field list, then moves into usage constraints. It is longer than ideal, but every sentence earns its place: the field enumeration, the partial-update note, the draft-revision behavior, and the publish/unpublish guardrails are all necessary. The structure could be improved with line breaks, but the content is well-ordered and free of fluff.

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

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

For a 12-parameter mutation tool with an output schema and rich annotations, the description covers the essential operational context: what fields change, how partial updates work, how published pages are affected, and what the agent must do after the call. The only minor omission is the meaning of editToken, but the schema and the tool's overall context make it inferable, and the description's guardrails are the most important completeness element.

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 description adds meaning by grouping the parameters into a coherent mental model (displayName, bio, verified, QR, display style, role label, labelPosition, photo). It also clarifies the photoUrl null-removes behavior and the display enum values, which are already in the schema but reinforced. The description does not add detail for photoAlt, photoObjectPosition, or editToken, but the schema already documents those adequately, so the marginal gap is small.

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

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

The description opens with a specific verb and resource ('Update the link-in-bio page header') and enumerates the exact fields it affects, which clearly distinguishes it from sibling tools like page_meta_update or page_theme_update. It also names the two display styles and the photo behavior, so an agent knows precisely what this tool owns.

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

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

The description gives explicit when-to-use guidance: 'Use only the fields you want to change' and 'For already-published pages, this saves an unpublished latest revision only.' It also provides strong when-not-to-use guidance by instructing the agent not to call page_publish or page_unpublish in the same turn, and to wait for explicit user confirmation before publishing. This is exemplary routing and sequencing guidance.

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

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

Annotations already mark the tool readOnly, idempotent, and non-destructive; the description reinforces this with 'Does not create a page' and adds useful context that the tool returns questions rather than creating anything. It also notes it is a planning/helper step, adding workflow behavior beyond the annotations. No contradiction exists.

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

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

The description is compact and front-loaded, starting with 'RECOMMENDED first step' and packing the outcome, alternative tools, call frequency, skip condition, and negative guarantee into a few sentences. It is slightly dense in the parenthetical, but every clause contributes decision-relevant 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?

For a read-only planning tool with a full output schema and fully described parameters, this description closes the main workflow gaps: when to call it, what to call next, and when to skip it. Edge cases are not discussed in detail, but annotations cover idempotency and the output schema covers return values.

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

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

The input schema has 100% coverage: all 7 optional parameters include descriptive text. The description's mentions of business name, primary visitor action, key content, and optional source link mirror schema fields without adding new constraints or formats, so the schema carries the parameter-semantics 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 description names a concrete action ('start landing page intake'), states what it returns ('few questions worth asking'), and explicitly differentiates from siblings: it says to 'then call page_create_from_brief' and notes page_onboarding_* tools are 'stateless planning helper, not required.' It also ends with 'Does not create a page,' which removes ambiguity about its role.

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 spelled out directly: 'RECOMMENDED first step for building a page,' 'prefer it,' 'Call once per creation request; skip if the user already gave you a source URL.' It also names the downstream tool to call and contrasts with page_onboarding_* as optional alternatives, giving an agent clear when/why guidance.

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

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

Beyond the annotations, the description discloses the key non-obvious behavior: for already-published pages it saves only an unpublished latest revision and leaves the live page public. It also sets the expectation that the result is a draft/preview update, not a live 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?

The description is longer than average but every sentence carries essential operational instruction. Purpose is front-loaded, and the workflow constraints are sequenced clearly without repetition or filler.

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

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

The description addresses the most important contextual traps, especially accidental publish/unpublish, and an output schema exists to cover return values. However, it leaves a small gap by not defining editToken semantics or behavior for pages that are not already published.

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 description reiterates title, slug, seoTitle, and seoDescription semantics that the input schema already documents. It does not explain the editToken parameter or clarify how pageId affects published-versus-draft behavior, so it adds little beyond the schema's own descriptions.

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

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

The opening sentence names the exact verb and resource: 'Update internal page title, URL slug, and SEO title/description.' This is more specific than the generic title and clearly distinguishes the tool's field scope from sibling tools like page_header_update or 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?

The description explicitly forbids calling page_publish in the same assistant turn and instructs waiting for a separate user message asking to publish or make changes public. It also explicitly forbids page_unpublish to keep the live page public, providing clear when-to-use and when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false. The description adds critical behavioral context: it emphasizes the tool is stateless and that page_onboarding_update does not remember earlier calls, requiring full resends. It also clarifies it does not create a page. No contradiction with annotations; the description enriches the behavioral picture significantly.

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 well-structured and front-loaded. The first sentence states purpose and non-create, the second gives the alternative, the third warns about statelessness, and the fourth gives the stopping condition. Every sentence adds value without redundancy.

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

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

The description covers when to use the tool, when to stop, and the statelessness behavior, which are critical for correct invocation. Although it does not explain parameters, the output schema exists and the annotations cover safety. The main gap is parameter clarification, but the description is otherwise complete for decision-making.

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%, with originalRequest lacking any description. The description does not explain the input parameters (locale, originalRequest, suggestedSelection) or how they map to the output choices. Since coverage is low, the description should compensate but does not, leaving agents uncertain about what to provide.

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

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

The description clearly states the tool's function: it returns category/layout/palette/primary-action choices and a quality checklist, and explicitly says it does NOT create a page. This distinguishes it from page_create_from_brief and other page creation tools. It also names the alternative flow, making it easy to differentiate among siblings.

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

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

The description explicitly states when to use this tool ('Use it only if you want those pickers') and when not to ('otherwise page_intake_start → page_create_from_brief is the simpler path'). It also gives a concrete stopping condition: 'As soon as you have a business name and a primary action, stop and call page_create_from_brief.' This is excellent guidance.

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

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

Annotations already declare readOnlyHint and idempotentHint, but the description adds a critical behavioral trait: STATELESS. It explains the consequence of omitting prior state and warns that earlier choices will look 'missing'. This goes well beyond what annotations or schema could 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?

The description is front-loaded with purpose, then delivers the critical statelessness warning, then gives a concrete exit condition. Every sentence earns its place 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?

The definition covers the essential operational details: statelessness, full-state requirement, and handoff to page_create_from_brief. With an output schema present, return values need no explanation. It leaves locale and stepId partly to schema inference, but the tool is still safely invocable.

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?

With 0% schema description coverage, the description compensates by enumerating the exact fields needed in selection and knownFields. It omits locale and stepId semantics, but the stepId enum is reasonably self-descriptive and the main risk around state accumulation is well covered.

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

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

The description opens with a specific verb and resource: 'Validate onboarding selections and return the remaining checklist.' It clearly identifies what the tool does and distinguishes itself from page_create_from_brief by explicitly stating when that sibling should be called instead.

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

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

The description gives explicit usage rules: every call must include the FULL accumulated selection and knownFields, not just the latest answer. It also states when to stop using this tool and call page_create_from_brief instead, which is strong when-to-use versus alternative guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds useful behavioral nuance beyond annotations by warning that calling with pageId alone fails for anonymous demo pages and that editToken must come from the create result.

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, front-loaded with the core behavior, and every sentence adds value. The key alternative and the token requirement are presented clearly with no filler.

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

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

For a simple read-only tool with a robust annotation set and an output schema, the description covers all essential decision-making information: what it returns, when it is unnecessary, when it requires an extra token, and what failure mode to expect.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description adds meaningful context by clarifying the consequence of omitting editToken on anonymous demo pages, which goes beyond the schema's 'Required for anonymous demo pages' phrasing.

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 action and resource: 'Return the current preview URL for a page.' It also distinguishes itself from page_create and page_create_from_brief by noting those already return a previewUrl, making the tool's niche clear.

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

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

It explicitly says 'You usually do not need this' and names the alternatives that already return a previewUrl. It also provides a specific condition for when this tool is required: anonymous demo pages must pass the editToken from the create result.

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 call as mutating and idempotent; the description adds consent-based guardrails ('only when explicitly asked', 'do not call immediately') and the mandatory nextSteps-handling behavior. It does not describe what happens to a previously published revision, but the output schema covers response content.

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 with zero filler: purpose, trigger condition, exclusion, anonymous-token rule, and response handling. Front-loaded with purpose and each subsequent sentence earns its place.

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

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

Even with a small schema and output schema present, the description provides all operational context an agent needs: when to call, when not, how to handle anonymous pages, and what to do with nextSteps. Nothing crucial is missing.

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

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

Schema covers both parameters at 100%, so the baseline is met. The description adds meaningful provenance and condition for editToken (required for anonymous demo pages, returned by page_create), which is exactly the kind of extra context needed.

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 the core action with a specific verb ('Publish') and resource ('latest page revision'), and separates it from page_unpublish and page_preview. The mention of 'make the page live' reinforces the intent. This clearly identifies what the tool does without relying solely on the title.

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 conditions invocation on the user's latest message expressing publish/live/share-link intent and prohibits auto-calling after page_create or page_create_from_brief. This removes ambiguity against siblings and sets a clear trigger rule.

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

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

Beyond the annotations, the description reveals a non-obvious behavior: for already-published pages, the update saves only an unpublished latest revision. It also documents the required sequencing around publishing and the need to wait for explicit user confirmation. This is exactly the kind of context an agent 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?

The description is dense but every sentence earns its place: purpose, constraints, tool alternative, publishing workflow, and safety rule. The most important behavioral caveat about unpublished revisions is stated early, and prohibitions are explicit rather than buried.

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 nested mutation tool, the description covers the key workflow, user-communication rule, publishing constraints, and unpublish safety behavior. The output schema is present, so return-value explanation is not needed. No critical behavioral gap remains for selecting and invoking the tool correctly.

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

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

The description conveys that the theme object is a partial patch and lists the enum-constrained categories, which helps, but it does not explain pageId or editToken semantics. Since the schema description coverage is only 33%, the description only partially compensates for the gaps and leaves the agent to infer the roles of those parameters from the schema.

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

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

The first sentence states a specific verb and resource: 'Apply a partial theme patch.' It also immediately signals the scoped nature of the operation, distinguishing it from a full restyle and from the related page_publish/page_unpublish siblings. The title reinforces the target resource clearly.

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

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

The description explicitly names the alternative tool (presets_list) for complete restyles and gives direct guidance about when to call page_publish, when not to, and how to converse with the user. It also forbids calling page_unpublish unless the user explicitly asks to take the page down. This is actionable and unambiguous.

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

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

Annotations already indicate destructiveHint=true and readOnlyHint=false, and the description complements this by specifying what is NOT destroyed ('keeping its draft and revision history'). This limits the destructive scope and is useful beyond the structured 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 a single, front-loaded sentence with no filler or repetition. It conveys the action, resource, and key preservation detail 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 low-complexity tool with an output schema and helpful annotations, the description covers the core behavior and retention semantics. The only notable gap is the absence of editToken guidance, which belongs to parameter semantics rather than overall context.

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

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

Schema description coverage is 0%, and the description does not mention either parameter (pageId, editToken) or explain what editToken is for. An agent has to infer meaning solely from the names, so the description adds no parameter semantics.

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

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

The description uses a specific verb ('Remove') and resource ('published landing page from public availability'), and further clarifies that it preserves the draft and revision history. This clearly distinguishes it from page_publish and from fully destructive operations like deletion.

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

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

The description gives clear context for when to use the tool: when a published page should be taken offline without losing draft or revision history. It does not explicitly name alternatives or state when-not-to-use, 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=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds the fact that there are exactly 8 curated presets, but it does not disclose return format, pagination, or any other behavioral nuances. Given the annotations, this is adequate but not rich.

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

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

Two sentences with zero waste. The core action and scope are front-loaded, and the usage guidance follows naturally. Every sentence contributes value.

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

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

For a simple read-only list tool with no parameters and an output schema, the description is complete. It states what it does and when to use it, and the output schema covers the return values. 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?

The tool has zero parameters, so schema coverage is trivially 100%. Per the rules, 0 params earns a baseline of 4. The description does not need to explain parameters because there are none.

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 ('List'), a specific resource ('the 8 curated style presets'), and clarifies their nature ('theme + starter blocks') and context ('for link-in-bio'). This clearly distinguishes it from sibling tools like layouts_list or page_theme_update, which handle different resource types.

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

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

The description gives explicit when-to-use scenarios: 'offer the user a choice' or 'confirm a preset:auto selection.' It does not explicitly mention when not to use or name alternatives, but the intended use cases are clearly stated, making it easy for an agent to decide when to call it.

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 carry readOnlyHint, idempotentHint, and destructiveHint flags; the description adds operational limits (public-only, no auth bypass) and confirms the successful return shape. No contradiction with 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?

Three sentences with front-loaded purpose, output, constraints, and downstream usage; 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 a rich output schema, full parameter coverage, and annotations, the description explains what the tool needs, what it returns, and how the result should be consumed. Nothing essential is missing for a read-only fetch 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 covers both parameters at 100%, so the description adds the useful 'public HTTP/HTTPS' constraint for sourceUrl but otherwise relies on the schema. It doesn't mention locale, but the schema already describes it.

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

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

The description names a specific verb and resource ('Fetch a public website URL and extract a structured brief'), enumerates concrete output fields (business name, description, contact links, suggested page blocks), and names the downstream sibling (page_create_from_brief). This differentiates it from nearby tools such as page_create or page_intake_start.

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

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

Clearly states it only works on public HTTP/HTTPS pages and explicitly notes it does not bypass login, CAPTCHA, or paywalls. It doesn't name alternatives or say when to prefer a sibling, but the boundary conditions are concrete enough to guide selection.

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