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

Annotations already disclose the safety profile with readOnlyHint=false, destructiveHint=true, and openWorldHint=true. The description adds useful context that operations occur on real Shopify data, aligning with the destructive annotation, but it does not explain side effects, what data may be changed, or how preview differs from run beyond the schema's execute flag.

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. It is efficiently structured, though its extreme brevity leaves substantial gaps that belong under completeness rather than conciseness.

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 destructive, open-world tool with 7 parameters, nested objects, no output schema, and 0% schema description coverage, this one-sentence description is not sufficient. Annotations cover safety, but the description does not compensate for missing parameter, mode, connection, or PII details.

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

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

Schema description coverage is 0% across 7 parameters, including nested objects, so the description carries the full burden but explains almost none of them. 'Preview or run' loosely maps to the execute boolean and 'automation' hints at one parameter, but workspace, draft, include_pii, resource_id, and shopify_connection remain undocumented.

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

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

The description states a clear action and resource: preview or run an automation on real Shopify data. It distinguishes preview vs run, but does not explicitly differentiate this tool from siblings such as shopify_automations_list, shopify_automations_runs, or shopify_automations_save.

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

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

The phrase 'Preview or run' implies two usage modes and suggests when this tool is useful, but the description gives no explicit guidance on when to use it versus related sibling tools. There are no exclusions, prerequisites, or alternative-tool references.

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