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

With no annotations provided, the description carries the full disclosure burden and delivers: it reveals that the code is 'inert until the code is shared', explains the security rationale for excluding automatic discounts, and discloses the sensitive-tier approval flow (manager approval on first use, from-now-on vs just-once modes). This exceeds typical descriptions for a mutation tool, though it could go further on write-scope details or Shopify-side side effects.

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 main purpose is front-loaded in the first sentence, followed by a crisp differentiator (why automatic discounts are excluded) and a one-line usage directive. The routing and sensitive-tier notes earn their place as they affect tool selection and invocation. Slightly verbose with the parentheticals, but every information chunk serves a functional purpose.

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 5-param tool with no output schema and no annotations, this description is thorough: it covers the discount type, activation behavior, exclusions and reasons, routing, and approval requirements. It's complete enough for an agent to decide when to invoke it and what to expect. A minor gap is no mention of a return value (e.g., the created discount ID), but that's not a blocker given the rubric.

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 baseline is 3. The description adds minimal parameter-level meaning beyond the schema (the only echo is the concept of the buyer-entered 'code' in the purpose sentence). The schema already documents each param well (e.g., format for code, bounds for percentage, ISO format for ends_at), so no penalty is warranted, but the description doesn't enrich semantics either.

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 states a specific verb+resource+scope: 'Create a CODE discount in the connected Shopify store (percentage off, applies when a buyer enters the code...)' It clearly distinguishes CODE discounts from automatic discounts, and the parenthetical explains exactly what the discount does and its behavior. This fully disambiguates it from sibling tools like list_shopify_discounts and create_shopify_product.

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 gives a clear use case ('Use for building promotions the operator will distribute') and an explicit when-not: 'Automatic discounts are deliberately not available here (they change every checkout unprompted and need approval).' The routing line 'Shopify: create a percentage discount CODE (never automatic discounts)' reinforces when to use it, though it never names a specific alternative sibling tool to use instead.

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