firestarter_connect_shopify

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

Annotations are limited (readOnlyHint=false, openWorldHint=true, destructiveHint=false), so the description carries the burden and does so well. It explains the two invocation modes (no args for status, with shop_handle for link creation), what the responses contain, and that the catalog syncs automatically. It doesn't explicitly warn about side effects like 'a connection is initiated', but it implies a non-read-only action, and nothing contradicts 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 every sentence earns its place: it opens with the purpose and flow, then explains the two calling conventions, gives usage triggers, explains the handle format, and names the alternative. It's well-structured, front-loaded, and avoids repetition of schema details.

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 no output schema, the description appropriately describes return outcomes (connection status/store name/last sync time vs. missing-handle report). It covers the tool's place in the flow, the optional parameter, and how to obtain it. Given the complexity (dual modes, integration with Shopify), this is complete 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?

Schema coverage is 100% (shop_handle is fully described), so baseline is 3. The description adds value by explaining the dual behavior: omitting the parameter checks status, while providing it triggers the link minting. It also elaborates on how the seller can find the handle, which goes beyond the schema. This justifies a 4.

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 action (connect a Shopify store) with a clear resource (Firestarter) and positions it as step 1 of a defined flow, naming the subsequent siblings (firestarter_listings, firestarter_sync_shopify, etc). It distinguishes itself from firestarter_sync_shopify by function, so an agent can easily tell them apart.

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 says 'Use this whenever a seller mentions Shopify, wants to connect/link their store, or asks why their products aren't showing up' and directs to firestarter_sync_shopify for refreshing an already-connected store. This gives clear when-to-use and when-not-to-use guidance with an alternative named.

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