update_store

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

Annotations are minimal (false for all hints). The description adds critical behavioral details: authentication via API key, max 10 concurrent requests, and respect for read-only/dry-run modes. It also clarifies that only supplied fields are changed, which is beyond annotation content.

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 well-structured with a clear action statement, usage context, authentication/limit info, and parameter details. It is concise for the amount of information provided, though slightly longer than minimal. Still, every sentence adds value.

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?

Given the tool has an output schema (returns JSON updated store object), the description covers return format adequately. It also covers parameter details, usage context, and behavioral limits. The description is sufficiently complete for an update operation.

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 has 0% description coverage, so the description must compensate. It does so thoroughly: store_id is clearly identified, additional_fields is explained with examples (name, currency_code, domain, etc.), and account is described as optional with naming convention. This adds significant meaning beyond the schema.

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 updates an existing e-commerce store's name, currency, connected audience, or metadata. It distinguishes from other store-related tools by specifying it's for manual writes in custom or headless storefronts, which sets it apart from automated sync tools.

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 description explains when to use this tool: for custom or headless storefronts where automatic syncs (via Shopify/WooCommerce) are not appropriate. It also notes only fields in additional_fields are changed, providing partial update behavior. While it doesn't explicitly name alternative tools, the context is clear.

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