Create effective prompts

This guide covers best practices for writing MCP prompts that work reliably across different AI clients and produce consistent results.

Anatomy of a good prompt

A well-structured prompt has three parts:

1. What to do — a clear goal statement
2. How to do it — specific instructions with table names, column names, query patterns, API endpoints
3. How to present results — output format (table, summary, list)

Vague prompt (bad):

Show me bestselling products.

Specific prompt (good):

Show top bestselling products.
Limit: use {{limit}} if provided, otherwise default to 10.

Query sales_order_item table:
- Filter: parent_item_id IS NULL (exclude child items of configurables/bundles).
- Group by sku and name.
- Select: name AS product_name, sku, SUM(qty_ordered) AS total_qty_sold,
  ROUND(SUM(row_total), 2) AS total_revenue.
- Order by total_qty_sold DESC.
- Limit to the requested number.

Format results as a table.

The AI does not need to guess which tables to use or how to structure the query. Every detail is spelled out.

Be specific about database queries

When your prompt involves database access, include exact table and column names. The AI may know Magento's schema, but explicit instructions produce more reliable results and prevent errors.

Include:

• Table names (sales_order, catalog_product_entity, cataloginventory_stock_item)
• Column names and their meaning (parent_item_id IS NULL to exclude configurable children)
• JOIN conditions (JOIN sales_order ON sales_order.entity_id = sales_order_item.order_id)
• WHERE filters with real column values (status = 1 for enabled, visibility IN (2, 3, 4) for visible products)
• EAV attribute lookups when needed (attribute_code = 'status' AND entity_type_id = 4)

Example — checking Magento config values:

Step 1 — Get the global notify threshold:
SELECT value FROM core_config_data
WHERE path = 'cataloginventory/item_options/notify_stock_qty'.
If no row exists, the Magento default is 1.

This tells the AI the exact config path and what to do when no value is set.

Be specific about REST API calls

For prompts that modify data, include the exact endpoint, HTTP method, and request body:

Use the REST API to set status = 2 (disabled) for each confirmed product.
Use endpoint PUT /V1/products/{sku} with body: {"product": {"status": 2}}.

Without this, the AI might try a different endpoint or body format.

Arguments best practices

Use single-word values

MCP clients split user input by spaces and map tokens positionally to declared arguments. Multi-word values like "last month" get truncated to "last". Design arguments to accept single-word values:

Instead of	Use
period accepting "last month"	months accepting a number (e.g. 6)
period accepting "last year"	days accepting a number (e.g. 365)
status accepting "out of stock"	status accepting a code (e.g. outofstock)

Write clear default behavior

Always explain what happens when an argument is not provided. Use this pattern in your content:

Limit: use {{limit}} if provided, otherwise default to 10.

When the argument is empty, the {{limit}} placeholder is removed and the AI reads: "Limit: use if provided, otherwise default to 10." — it understands the default from context.

Do not write defaults like this:

Limit: {{limit}} (default 10).

When the placeholder is stripped, this becomes "Limit: (default 10)." which reads awkwardly.

Required before optional

Required arguments must be listed before optional ones in the arguments list. The system automatically reorders them on save — required arguments move to the top, preserving relative order within each group. This matters because clients map input positionally: the first word goes to the first argument, the second word to the second, and so on.

Argument descriptions

The Description field for each argument is visible to both the user and the AI client. Keep it concise and include the default value:

• "Number of bestsellers to display (default 10)"
• "Number of months to look back (default 0 = lifetime)"
• "Number of days after which an order is considered stuck (default 3)"

Multi-step prompts

For prompts that read data and then modify it, structure the content as numbered steps with explicit confirmation gates:

Step 1 — Identify candidates:
Query catalog_product_entity joined with cataloginventory_stock_item.
Find enabled products where stock quantity is 0 and no sales in the last 6 months.
Show results as a table.

Step 2 — Ask the user to confirm.
Do NOT proceed without explicit confirmation.

Step 3 — Disable confirmed products via REST API:
For each SKU, call PUT /V1/products/{sku} with body: {"product": {"status": 2}}.
Report: how many disabled, any errors.

The confirmation gate in Step 2 is critical — it prevents the AI from making bulk changes without user approval.

Use Magento's own settings

When possible, reference Magento's configuration rather than hardcoding values. For example, the Low stock alert prompt reads the store's own notify_stock_qty setting instead of using an arbitrary threshold:

Step 1 — Get the global notify threshold:
SELECT value FROM core_config_data
WHERE path = 'cataloginventory/item_options/notify_stock_qty'.
If no row exists, the Magento default is 1.

Step 2 — Query products below their effective threshold:
...
WHERE cisi.qty <= CASE
  WHEN cisi.use_config_notify_stock_qty = 1 THEN {global_threshold}
  ELSE cisi.notify_stock_qty END

This respects both global and per-product overrides.

Filter out noise

Magento's data model has nuances that can produce misleading results if not handled:

• Configurable/grouped/bundle parents have qty = 0 by design — filter with type_id = 'simple' for stock queries
• "Not Visible Individually" products (visibility = 1) are simple children of configurables — filter with visibility IN (2, 3, 4) for catalog queries
• Canceled orders should typically be excluded — filter with state NOT IN ('canceled', 'closed')
• Child order items appear alongside parent items — filter with parent_item_id IS NULL

Required tools

Always set the Required tools field to match the tools your prompt actually uses. This serves two purposes:

1. Access control — users who don't have access to the required tools won't see the prompt
2. Clarity — it documents which tools the prompt depends on

Common combinations:

• Database queries only: builtin_system_dbreader
• Read then write: builtin_system_dbreader, builtin_system_restapi
• Store info check: builtin_system_getstoreinfo, builtin_system_dbreader

Turn any conversation into a reusable prompt

When you have a conversation with your AI client that produces useful results — a complex query, a multi-step workflow, a report you'll want to run again — you can save it as a prompt directly from the conversation. No need to switch to the admin panel.

Ask your AI client something like:

"Considering all findings from the last performed task, create a prompt in the MCP module with the code 'weekly_refund_report' and a 'days' argument that defaults to 7."

The AI will take the queries and logic from your conversation, structure them into a prompt template, and call POST /V1/mcp/prompts through the REST API tool. The next time you need that report, just type /weekly and select the weekly_refund_report prompt from autocomplete instead of explaining the task again.

Example conversation flow:

1. You ask: "Show me all refunds from the last 7 days grouped by reason, with total amounts"
2. The AI builds the query, runs it, shows results
3. You say: "That's exactly what I need every Monday. Save this as a prompt called 'weekly_refund_report' with a 'days' argument defaulting to 7"
4. The AI calls the REST API:

   POST /V1/mcp/prompts
   {
       "title": "Weekly refund report",
       "content": "Show refunds for the last {{days}} days...",
       "description": "Refunds grouped by reason with totals",
       "arguments": "[{\"name\":\"days\",\"description\":\"Number of days (default 7)\",\"required\":false}]",
       "requiredTools": "builtin_system_dbreader",
       "isActive": true
   }
5. After reconnecting, the prompt appears in your client's autocomplete when you type /weekly

note

The prompt becomes available in prompts/list immediately, but most AI clients discover prompts at session start. You may need to reconnect or restart your client to see the new prompt in the slash command menu.

You can also update or delete prompts through conversation:

• "Update the weekly_refund_report prompt to also include the product SKU" — the AI calls PUT /V1/mcp/prompts/:id
• "Delete the test_prompt I created earlier" — the AI calls DELETE /V1/mcp/prompts/:id

This workflow turns your AI client into both the prompt author and the prompt runner.

Testing your prompt

After creating a prompt:

1. Check the Validation column in the grid — it should show "OK"
2. Open the prompt edit page — any warnings appear at the top
3. Invoke the prompt from your AI client and verify the output
4. Test with and without arguments to ensure defaults work correctly
5. For multi-step prompts, verify the confirmation gate works — the AI should stop and ask before modifying data