shopify_create_page

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

Annotations (readOnlyHint=false, destructiveHint=true, idempotentHint=true) already signal a mutating, idempotent write. The description adds non-obvious behavioral context beyond that: the 'effect' parameter is verified by Spring, and 'approval_ref' is needed when resuming a write, revealing an approval-gated execution flow. No contradiction 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 purpose is front-loaded in a single sentence, followed by a clean, alphabetized Args list where each line is short and informative. It is longer than ideal due to the ten parameters, but every line earns its place given the zero schema coverage.

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 output schema exists, so return-value documentation isn't required, and the description covers purpose, parameters, and the approval/effect mechanics. However, it creates confusion by marking title and body_html as 'required' while the input schema lists zero required parameters with null defaults, and it omits guidance on which platform parameters are prerequisite or how the approval-resume flow is initiated.

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 carries the full burden and documents all 10 parameters. The functional parameters are genuinely helpful ('handle: URL handle (defaults to a slug of the title)', 'is_published: Publish immediately (default true)'). The six platform parameters get terse labels ('Authenticated Project UUID', 'Exact project correlation reference') that add some meaning but don't explain where the agent obtains these values.

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 line, 'Create an Online Store content page (e.g. About, FAQ, Services)', states a specific verb and resource with concrete examples. It clearly distinguishes this creation tool from page-management siblings like shopify_get_page, shopify_list_pages, and shopify_update_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?

Usage context is implied by the verb 'Create' and the content-page examples, but there is no explicit when-to-use/when-not-to-use guidance. The description never names alternatives such as shopify_update_page for modifying existing pages or page_builder_create for non-Shopify pages, leaving the agent to infer selection.

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