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

Annotations already mark this as a write (readOnlyHint=false, destructiveHint=true), and the description adds meaningful behavioral context: the page is never live, publishing is separately gated, and first use may require manager approval with a clear 'card is the yes' convention. There is 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 core behavior is front-loaded in the first sentence, and the approval/routing details are important for correct agent behavior. The 'Routing:' line is slightly redundant with the opening paragraph, which prevents a perfect score, but the description is not bloated.

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?

Despite having no output schema, the description covers everything an agent needs for a correct first invocation: what the tool does, the live/draft safety model, approval behavior, and routing intent. It is complete for a simple 3-parameter creation 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?

The input schema already provides complete descriptions for all three parameters (title, body_html, companyId), so the description's restatement of 'title and body HTML' adds little semantic value. With 100% schema description coverage, 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 description opens with a specific verb and resource: creating a new page in the connected Shopify store, and immediately adds the crucial qualifier that it is an UNPUBLISHED draft, never live. It also names the fields it sets (title and body HTML), which cleanly separates it from sibling tools like publish_shopify_page and create_shopify_product.

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 use context ('building out site content') and clearly states that publishing to buyers is a separate approval-gated step, so an agent knows not to expect this call to expose content live. It does not explicitly name the alternative tool for updating an existing draft or publishing, but the routing line makes the intent strongly implied.

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