products_bulk_update

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

The description gives no behavioral context beyond the verb 'update'. The schema reveals a destructive operation (`bulk-delete-products`) and various mutation types, but the description does not disclose this capability or any side effects, permissions, or reversibility. While annotations indicate non-read-only, the description adds no information about what can happen during execution.

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 phrase that offers no valuable information; it is under-specified rather than concise. For a tool with nested objects and multiple enums, it does not front-load critical operational details (e.g., required `type` and `productIds`) that an agent needs to safely invoke it.

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 10 parameters, nested objects, and a multi-option enum, the description is grossly incomplete. It fails to explain the filter mechanism, how the `type` selects the operation, or any return behavior. Combined with the lack of an output schema, an agent would have to fully parse the schema to understand usage, making this definition inadequate for a complex 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?

All 10 parameters have descriptions in the schema (100% coverage), so the description's lack of parameter details is mitigated. The baseline of 3 applies because the schema already documents each parameter, and the description does not add any extra meaning about parameter relationships, defaults, or usage patterns.

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 'Bulk Update Products' is essentially a rephrasing of the tool name, offering no specificity about the types of bulk updates (price, availability, collection, delete, currency) that the schema's `type` enum lists. It lacks a clear verb-resource distinction and does not distinguish this tool from sibling tools like `products_bulk_edit` or `products_update_product_by_id`.

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?

There is no guidance on when to use this tool versus alternatives. No conditions are provided (e.g., 'when updating multiple products at once' or 'when using filters instead of explicit product IDs'). The description is silent on selection criteria, leaving agents to guess based on the name alone.

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