Agent tools
Give an agent the workflow and exact contract it must implement.
Last updated:
Use Markdown to explain the task and OpenAPI to define the call. Neither replaces server-side validation.
Available sources
llms.txtlists the public APIs and guides.llms-full.txtcollects public documentation in one file.- A page menu can copy or open its Markdown.
Chopper in Admin
Chopper is Ecomiq's AI assistant. Admin chat uses the ecomiq-ai service, which
runs the model, calls authorized tools and stores the conversation. Its routes
live under /v1/assistant; this chat is not an MCP interface.
Capabilities depend on the mode, permissions and configured services. Merchant chat can read products and variants, recommendations, price history, full orders, fulfillment orders, claims, customers, carts, inventory, publications, webhooks, taxes and settings. Search results provide the IDs used to open details. Documentation cannot grant permissions or turn an Admin operation into a chat tool.
To count products from a provider such as VTEX, Chopper finds import sources by
providerId and sends their IDs together as sourceIds to catalog_count_products.
The result counts distinct products linked to those sources, using neither brands
nor image URLs to infer origin and without counting synchronization rows as products.
In the store editor, enabled tools can propose draft changes, generate campaign images and, when the workbench is configured, inspect reference URLs and candidate designs. Inspecting a reference is different from general web search. A proposal does not publish the store.
Editing products in chat
With catalog read and update permissions, Chopper can propose edits to existing products and specific variants: text, tags, status, SKUs and prices. It can also select and reorder attached images or change the primary image. The card shows Before and After; Approve and save applies the edit in .NET. Omitted variants are preserved.
catalog_product_edit_propose creates a proposal and catalog_product_edit_get
checks its status. Neither tool approves it. The server rechecks actor, store,
seller, permissions and versions, with idempotency and auditing. A changed product
requires a new proposal. If any part fails, the entire edit is rolled back.
This flow does not adjust stock or create or delete variants.
Product images
The product form includes an image generation action. The merchant reviews the result and applies it to the form. Generation consumes credits; applying the image stores it as an asset and adds it to the product's images. It becomes the primary image automatically only when there were no previous images. To replace an existing primary image, select the new primary image and save the product.
Generating, uploading, assigning and saving are separate steps. Chat currently has no tool that completes this entire workflow. The editor's campaign tool does not replace product images either. Generation requires a configured image provider.
Generated images may be used in the catalog. They should faithfully represent the item; a generated illustration alone does not verify the real product's appearance. This distinction is not a ban on image generation.
MCP API for external agents
The public MCP belongs to Api.Agent, a .NET service separate from chat. Connect
to /mcp on the Agent deployment configured for your environment. ecomiq-ai
does not expose that endpoint or proxy it.
The client uses OAuth with scope api_agent and audience
the canonical MCP URL (https://chopper.ecomiq.pe/mcp in production). Do not forward an api_admin bearer. Agent validates
the installation, user, tenant, store, seller and permissions; a prompt cannot
change that scope. Use the service's OAuth metadata and live tools/list catalog.
The public catalog provides:
| Tool | Result |
|---|---|
organization_current_store_get | Reads the store bound to the validated OAuth installation. |
catalog_products_list | Lists or searches products by name, description, SKU or variant barcode, with cursor pagination. |
catalog_products_count | Counts products using the same filters and reports whether the result is exact or a lower bound. |
catalog_product_get | Reads a product's description, prices, status, tags, images, specifications and variants. |
catalog_product_draft_propose | Creates an idempotent draft-product proposal for human review. |
catalog_product_draft_proposal_get | Reads a proposal owned by that installation. |
analytics_metrics_list | Lists available metrics and dimensions. |
analytics_metrics_query | Queries metrics by date range and dimensions, with comparisons. |
orders_list | Lists orders in the connected store and seller scope. |
orders_get | Reads an order's amounts, items, payments and status. |
channels_sources_list | Lists import sources and their status. |
channels_source_get | Reads source synchronization status and errors. |
channels_list | Lists sales channels. |
channels_product_publications_list | Reads a product's origins and publications. |
channels_listings_list | Lists a channel's products and publication blockers. |
channels_mappings_list | Reads category, brand and attribute mappings for an explicit direction and owner. |
channels_mapping_candidates_list | Lists unresolved source mapping candidates. |
storefront_project_get | Reads the store's project. |
storefront_draft_get | Reads the draft and its version. |
storefront_theme_catalog_get | Reads the theme manifest and schemas. |
storefront_draft_patch_propose | Proposes theme changes with a preview and approval URL. |
storefront_draft_patch_get | Reads a theme proposal's status and receipt. |
Product queries require catalog:read for both the application and the user.
Store and seller come from the connection and cannot be changed through tool
arguments. New dynamic OAuth registrations request catalog read/create, analytics,
orders and channels read, and content read/update,
limited to the user's permissions. Older connections with only catalog:create
need updated application permissions or a new OAuth registration with read
access. Refreshing a token or authorizing the same client again does not add it.
Metrics require analytics:read; orders require order:read; sources, channels
and mappings require channel:read. Theme reads require content:read and
proposals also require content:update. Sources, channels, mappings and themes
require store-wide access without a seller scope. Product publications use the
catalog scope and catalog:read.
Read the project, draft and theme manifest before proposing up to 50 operations
with their current versions. The proposal returns a preview and approvalUrl for
review in Ecomiq. Check storefront_draft_patch_get; only succeeded with
responseAudit confirms that the draft changed. Publishing is a separate action.
Theme proposals are also available from internal chat without opening the builder.
For catalog_products_list, omit options.search to list products or supply it
to search. Pages default to 20 products and allow up to 100. Send nextCursor as
options.cursor with the same filters to continue. Drafts are included; include
archived products with options.includeArchived: true or
options.status: "archived". catalog_product_get accepts a productId from
the list, including archived products. These tools read catalog data; they do
not return inventory availability. Filter by import source using options.sourceIds.
Counts return total, precision and limit. The default limit is 10,000 and
can be increased to 100,000. precision: "exact" identifies an exact total;
precision: "atLeast" must be reported as a lower bound, never an exact total.
The number of results on one page is not the catalog total.
Creating the proposal does not create or publish the product. Approval occurs in
the authenticated first-party interface; execution preserves permissions,
idempotency and domain auditing. A delegated client cannot approve its own
proposal. Tools registered internally in ecomiq-ai are not automatically part
of the public MCP catalog.
MCP returns structured operations and data; the external client's model writes the response. In Chopper's Admin chat, Ecomiq runs the model. Documentation-search embeddings retrieve passages; they do not write responses or execute changes.
Connect from ChatGPT or Claude
Add https://chopper.ecomiq.pe/mcp as a custom connector, sign in to Ecomiq,
and choose the store. You need permission to connect applications and catalog
read access to query products. The client and Ecomiq handle dynamic OAuth
registration, consent, PKCE, and token refresh. Do not paste passwords or tokens
into a chat.
Each installation keeps its store and permission boundary when other merchants use the same client. Create a new connection to select another store. To revoke access, open Settings → Developers → Apps and choose Disconnect. Refresh stops working; an issued access token may remain valid for up to ten minutes. Disconnecting one store does not disconnect others.
Try “Which store did I connect?”, “Find SKU …”, “How many products do I have?”, or “Prepare a product proposal”. Availability in the ChatGPT and Claude directories depends on their review. A working custom connector does not mean it has been published in either directory.
Data sharing
The connector receives tool arguments and the OAuth identity needed to check permissions. It returns the requested store, products, orders, metrics, sources, channels, mappings, theme content or proposals to the external client. It does not automatically receive the full conversation. ChatGPT or Claude process tool responses under their own policies. Ecomiq retains data and records under its privacy policy. Disconnecting does not delete existing proposals or audit records.
OpenAPI contracts
Provide only the contract for the API the agent will use. Admin, Storefront, Auth, and UCP do not share every authentication, context, pagination, or error rule.
What to take from each source
| Source | Use it for |
|---|---|
| Markdown guide | Workflow order, decisions, and operating constraints. |
| OpenAPI | Method, path, parameters, body, schemas, responses, and published security. |
| Endpoint page | Readable presentation of that operation's contract. |
If a permission, example, or rule is absent from these sources, the agent should mark it as unknown. It must not invent one from the endpoint name.
Recommended instruction
Implement this operation from the attached guide and OpenAPI.
Preserve the method, path, operationId, parameters, and schemas.
Do not invent fields, permissions, responses, or examples.
Distinguish Admin, Storefront, Auth, and UCP.
Before retrying, check whether the operation is idempotent.Workflow
- Choose one API and one operation.
- Attach the workflow guide and the OpenAPI fragment for that operation.
- Ask for a typed client that uses only fields from the contract.
- Run it with development credentials and data.
- Compare the actual request and response with the published contract.
Do not infer authorization
An operation appearing in OpenAPI does not grant access. Use published security and the server response; do not assume permission names the contract does not declare.
Do not share a client_secret, access token, personal data, or production
response in the prompt. Replace values before attaching examples.