create_shipping_class

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

The annotations only include openWorldHint: false, which provides minimal safety information. The description does not disclose any behavioral traits such as whether creation is idempotent, permissions required, uniqueness constraints, or what happens on duplicate names. The only added context is the assignment workflow via update_product, which is more about post-create usage than the create call itself. Thus the description carries the burden but fails to disclose expected mutation behavior.

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 two sentences, front-loaded with the primary action, and every word serves a purpose. It explains the what, the why, and the follow-up action (assign via update_product) without any fluff.

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 simple create tool with only one required parameter and full schema coverage, the description provides sufficient contextual grounding: it names the resource, gives examples of use, and explains the relationship to products. It does not cover edge cases like duplicate names or required field constraints, but that is likely acceptable given the tool's simplicity and the schema's required field declaration.

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 100%, so the schema already documents all parameters. The description adds example values for the shipping class name ('bulky', 'fragile') but does not attach them to a specific parameter or clarify the format of slug, fields, or description beyond the schema. Therefore it meets the baseline but adds little extra semantic value.

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 opens with 'Create a product shipping class,' which is a specific verb+resource statement. It also distinguishes this create tool from the sibling tools list_shipping_classes and delete_shipping_class by implying creation only, and provides an example use case ('bulky', 'fragile') to clarify the resource's function.

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 this tool is useful: to create a shipping class that can later be assigned to products via update_product. It gives clear context and a concrete grouping use case. However, it does not explicitly state when not to use it or mention alternatives like updating existing classes, but the sibling creation vs management distinction is implicit.

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