wafle_stores_create

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

The description calls out a 'DESTRUCTIVE side effect' and lists provisioning side effects, but the annotations declare destructiveHint=false. This directly contradicts the annotation, which is a serious inconsistency. The word 'DESTRUCTIVE' is misleading because the listed side effects (API key, audit log, gateway slot) are additive, not destructive.

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 concise and front-loaded with the core purpose, followed by a useful workflow and side-effect disclosure. Every sentence serves a purpose, and it avoids unnecessary verbosity.

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 provisioning tool with no output schema, the description covers the onboarding workflow, required fields, and side effects well. It lacks return-value details, but the workflow guidance and side-effect disclosure give the agent enough context to select and invoke the tool. The annotation contradiction slightly undermines trust, but completeness is still strong.

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 100% parameter description coverage, so the baseline is 3. The description adds minimal semantic value by highlighting the three required parameters and referencing catalog_mode versus manual mode in the workflow, but it does not provide additional detail beyond what the schema already documents.

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 creates a brand new wafle store, distinguishing it from sibling tools like wafle_stores_update and wafle_stores_get. It also lists the required fields (slug, name, domain), making the purpose and scope immediately evident.

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?

It explicitly says to use this tool when onboarding a new client and gives a concrete post-create workflow, mentioning wafle_gateways_create and wafle_stores_settings_update, with a conditional alternative for product sync vs manual catalog. However, it does not explicitly state when not to use the tool or compare it directly to alternatives.

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