create_modifier

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

Discloses crucial behavioral traits beyond annotations: existence check with error handling, numeric bounds, dry-run behavior, confirmation workflow, and permission requirement. This significantly exceeds the annotation hints.

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 compact and organized into three short segments (generic purpose, specific operation, critical execution details). No wasted words, though 'Modifies merchant data' could be removed without loss.

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 an output schema exists, return-value documentation is not needed. The description covers preconditions, error cases, constraints, preview/confirm flow, and permissions, making it complete for a mutation tool with moderate complexity.

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?

With 0% schema coverage, the description compensates by explaining price_cents bounds, dry_run/confirm semantics, and referencing modifier_group_id in the pre-check. 'name' is not explicitly described but is self-explanatory. Missing detail on some parameters but overall helpful.

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 'Create a new modifier within a modifier group' which is a specific verb+resource, and distinguishes from the sibling 'create_modifier_group'. The opening 'Modifies merchant data' is generic but immediately clarified.

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?

Provides actionable guidance: pre-check for modifier group existence (404 error), bounds on price_cents, dry_run preview, confirmation via elicitation or confirm=True, and required permission INVENTORY_W. Does not explicitly name alternatives but clearly scopes when to use.

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