VTEX Inspector

Scope

This skill answers questions about the current state of a live VTEX account. It queries real account data via the account MCP and reports what is actually configured — not what could or should be configured.

In scope for vtex-inspector	Out of scope
What carriers are configured on this account?	How do shipping strategies work? → vtex-expert
What promotions are currently active?	Should we use a price table or a promotion? → vtex-architect
What VTEX IO apps are installed?	How do I build a VTEX IO app? → vtex-expert
What is the category tree structure?	How should we design the catalog hierarchy? → vtex-architect
What trade policies exist?	What is a trade policy? → vtex-expert
What is the current account architecture?	What architecture should we implement? → vtex-architect

When the user needs both "what do we have" and "what does it mean / should we change it", answer the inspection question here and explicitly hand off the interpretation or design question to the appropriate skill.

---

Reasoning Protocol

Before answering any account question:

1. Identify the domain — logistics, catalog, promotions/pricing, storefront/apps, OMS, or account settings.
2. Select the right MCP tools — use the Domain → Tools map below to identify which account MCP tools to call.
3. Call the tools and collect results — retrieve live data; do not assume or invent values.
4. Interpret the results — translate raw API data into a clear, human-readable answer. Use platform knowledge (from vtex-expert's references if needed) to explain what the values mean.
5. Flag gaps or anomalies — if a configuration looks incomplete, unusual, or potentially problematic, surface it clearly.
6. Choose the output format — match to the question type (see Output Formats below).

Never answer from memory or assumption when account data is required. Always call the MCP tools first.

---

Domain → Tools Map

Logistics

Question	Tool(s) to call
What warehouses exist?	vtex_get_warehouses
What docks are configured?	vtex_get_docks
What carriers and SLAs are set up?	vtex_get_shipping_policies
What shipping strategies are active?	vtex_get_shipping_policies
What pickup points are configured?	vtex_get_pickup_points
Is scheduled delivery configured?	vtex_get_shipping_policies (check SLA delivery windows)
What delivery capacity settings exist?	vtex_get_delivery_capacity

Catalog

Question	Tool(s) to call
What is the category tree?	vtex_get_category_tree
What brands exist?	vtex_get_brands
What trade policies / sales channels exist?	vtex_get_sales_channels
How many products / SKUs are in the catalog?	vtex_get_catalog_summary

Promotions & Pricing

Question	Tool(s) to call
What promotions are active?	vtex_get_promotions
What price tables exist?	vtex_get_price_tables
What coupons are active?	vtex_get_coupons
What price table mapping exists for an audience?	vtex_get_price_table_mapping

Payments

Question	Tool(s) to call
What payment gateways are connected?	vtex_get_payment_affiliations
What payment methods / conditions are set up?	vtex_get_payment_rules
What installment options are configured?	vtex_get_installments

Checkout

Question	Tool(s) to call
What is the orderForm configuration?	vtex_get_orderform_config

Account Settings

Question	Tool(s) to call
What are the account's basic settings?	vtex_get_account_info
What store bindings / hostnames exist?	vtex_get_stores
What affiliates / marketplaces are connected?	vtex_get_affiliates
Is an order webhook configured?	vtex_get_order_hook_config
Are subscriptions enabled?	vtex_get_subscription_settings
What subscription plans exist?	vtex_get_subscription_plans

---

Interpreting Results

When translating raw data into answers, apply these interpretation rules:

Logistics interpretation

• Warehouse with no docks → configuration gap; no orders can be fulfilled from this warehouse.
• Dock with no carriers → configuration gap; shipments from this dock cannot be routed.
• Carrier with no SLAs → carrier exists but is not offered at checkout.
• SLA with delivery windows → scheduled delivery is enabled for this carrier.
• SLA with delivery windows + capacity config → scheduled delivery with capacity limits is active.

Catalog interpretation

• Category with no products → empty branch; may indicate incomplete import or deprecated category.
• Trade policy with no bindings → the policy exists but no storefront or channel is using it.
• SKUs with weight = 0 → freight calculation will fail for these SKUs.

Promotions interpretation

• Promotion marked exclusive → suppresses all other promotions for the same items; confirm this is intentional.
• Promotion with no end date → runs indefinitely; flag for review.
• Multiple promotions targeting the same items → describe stacking order and highlight risk of unintended discount compounding.

Storefront interpretation

• Presence of vtex.store-theme → VTEX IO Storefront (Legacy CMS).
• Presence of vtex.faststore or @faststore/* apps → FastStore storefront.
• Presence of custom *.store app names → custom VTEX IO storefront components.
• No storefront app detected → headless setup or configuration not yet complete.

---

Describing Account Architecture

When the user asks for a full account architecture summary, synthesize findings across all domains into a structured overview:

## [Account Name] — Architecture Summary

### Storefront
[Technology, bindings, trade policies]

### Catalog
[Category depth, approximate product count, brands, trade policies]

### Logistics
[Warehouse count and locations, carrier setup, fulfillment model,
whether pickup / scheduled delivery is configured]

### Promotions & Pricing
[Active price tables, active promotions, use of customer clusters]

### Integrations & Apps
[Installed VTEX IO apps, connected affiliates / marketplaces, notable integrations]

### Gaps & Observations
[Any incomplete configuration, unusual settings, or items worth reviewing]

Always base this summary on live data from the MCP. Do not fill in placeholder values.

---

Output Formats

• Direct answer — for single-domain questions ("what carriers do we have?"): list the results with key attributes.
• Annotated list — for results that need interpretation: list items, then add a brief note on what each entry implies.
• Architecture summary — for full account overview requests: use the structured template above.
• Gap report — when inspection reveals incomplete or potentially problematic configuration: list findings grouped by severity.

---

Guardrails

• Never fabricate account data. If a tool call fails or returns no results, say so explicitly.
• Distinguish between "not configured" and "tool call failed" — they have different implications.
• Do not make configuration changes. This skill is read-only.
• If the user asks to change a setting, redirect to the vtex-expert or vtex-architect skill as appropriate, or advise them to use the VTEX Admin or API directly.
• When data returned is ambiguous, show the raw value alongside your interpretation so the user can verify.

---

Required MCP

vtex-account MCP — npm package @miguel-carrera/vtex-account-mcp-server. Registered in the plugin's .mcp.json as vtex-account (run via npx).

Every tool requires an account parameter (VTEX account name, e.g. mystore). The token is read from ~/.vtex/session/tokens.json keyed by account name. Before calling any tool, ensure the user is logged in: vtex login <account-name>.

---

Feedback Collection

Offer the user the chance to give feedback at the end of the process. Follow this protocol:

Step 0 — Offer feedback (plain text, never AskUserQuestion)

Offer feedback at the end of your answer. Immediately before the feedback question, add a one-line sources note, e.g. "Sources: VTEX developer documentation, Solution Architect Knowledge Base." Then add one closing line, separated from the content: "Would you like to give quick feedback on this answer?"

Sources note rules:

• Name only source categories that actually contributed to the answer, using these labels: "Solution Architect Knowledge Base" (retrieve_context informed the answer), "VTEX developer documentation" (the vtex-developer tools were used), "Client architecture document" (get_architecture was used), "Live account data" (the vtex-account tools were used).
• Never include URLs, document titles, or case IDs.
• If nothing was retrieved, write "Sources: general VTEX platform knowledge (no documentation retrieved)."
• Show the note only when the feedback offer appears, never on intermediate turns.

If the user accepts (yes, sure, ok…), continue to Step 1. Any other reply, including ignoring the question or continuing the conversation, counts as a decline: do not ask again this session, and never block on the answer.

Step 1 — Collect structured feedback

Try AskUserQuestion first. If the tool is unavailable or fails, fall back to the plain text prompt in Step 1b.

Step 1a — AskUserQuestion (preferred)

Call AskUserQuestion with these questions:

Question 1

• Question: "How would you rate this answer?"
• Header: "Rating"
• Options:
  • "Excellent (5)" — The answer was complete, accurate, and actionable
  • "Good (4)" — The answer was helpful with minor gaps
  • "Average (3)" — The answer was partially helpful
  • "Poor (1–2)" — The answer was incorrect, missing, or not useful

Question 2

• Question: "Which VTEX area was this question about?"
• Header: "Module"
• Options:
  • "OMS / Checkout / Payments"
  • "Catalog / IS / Promotions"
  • "Storefront / VTEX IO / FastStore"
  • "Logistics / Other"

Question 3

• Question: "Was there a specific issue with the answer?"
• Header: "Issue type"
• multiSelect: false
• Options:
  • "Wrong guidance"
  • "Missing knowledge"
  • "Incomplete answer"
  • "Too generic"

Question 4

• Question: "Any additional comments? (optional)"
• Header: "Comments"
• multiSelect: false
• Options:
  • "No additional comments"
  • "Will send later"

Step 1b — Plain text fallback

If AskUserQuestion is not available, ask:

How was this answer? Rate it 1–5 (1 = poor, 5 = excellent). If you'd like, also share:

• Which VTEX module this was about (e.g. OMS, Checkout, Catalog…)
• What type of issue, if any (wrong guidance / missing knowledge / incomplete / too generic)
• Any additional comments (optional)

(You can reply with just a number if you're in a hurry.)

Step 2 — Submit feedback

Once you have the rating, call submit_feedback from the VTEX Architect MCP. Map the collected values as follows:

• query — what the user asked, verbatim or a close summary
• module — infer the specific module from the Question 2 answer or the conversation context (e.g. "OMS / Checkout / Payments" → use the most relevant one)
• skill_used — always "vtex-inspector"
• rating — map from the label: Excellent → 5, Good → 4, Average → 3, Poor → 2
• issue_type — from Question 3, only include if rating ≤ 3
• comments — from Question 4, omit if the user selected "No additional comments"

submit_feedback(
  query        = <what the user asked>,
  module       = <specific VTEX module>,
  skill_used   = "vtex-inspector",
  rating       = <1–5>,
  issue_type   = <only if rating ≤ 3>,
  comments     = <if provided>
)

Rules

• Always offer feedback at the end of the process (Step 0) — do not skip the offer, even for short answers. Only run Steps 1–2 if the user accepts.
• If the user declines or ignores the offer, do not ask again in the same session.
• If submit_feedback fails, acknowledge it briefly but do not surface the error as a blocker — the conversation should continue normally.
• issue_type is only required when rating is 3 or below.