firestarter_connect_shopify

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

Annotations say readOnlyHint=false and destructiveHint=false, and the description aligns by detailing the stateful behavior: checking existing connection, minting an install link, and triggering automatic catalog sync. It also reveals expected return values (connection status, store name, last sync time) and the no-token-paste aspect, adding genuine context beyond annotations.

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

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

The description is a single dense paragraph, but every sentence carries necessary process information. It's front-loaded with the main purpose and then flows into the step-by-step logic. Slightly long relative to simpler tools, but justified by the multi-step behavior.

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

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

The tool is step 1 of a Shopify integration flow, and the description covers the full sequence: connect → automatic sync → listings → sync → orders → ship. It explains prerequisites, the two-call pattern, what happens after the seller clicks the link, and mentions the return status when a store is already connected. Given 0 required params and no output schema, this is 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?

Schema coverage is 100% and the description enriches the parameter meaning substantially: omitting shop_handle checks status; providing it mints the install link; it accepts bare handle or full domain and normalizes it; and it gives instructions for finding the handle. This goes far beyond the schema property description.

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

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

The description clearly states the tool connects a seller's Shopify store to Firestarter, with a specific verb ('Connect') and resource ('a seller's Shopify store'). It distinguishes itself from siblings like firestarter_sync_shopify and firestarter_connect_tiktok/connect_store by explicitly mapping out the Shopify flow.

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

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

Explicit guidance is provided: 'Use this whenever a seller mentions Shopify...' and it tells the agent to use firestarter_sync_shopify instead for refreshing an already-connected store. It also explains the two-step invocation (first call with no args, then with shop_handle).

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