Syncs orders between Odoo ERP and multiple marketplaces, with traceability and incident resolution capabilities.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@retail-order-sync-hub trace order 12345 to see why it failed to sync to MercadoLibre"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Sistema de sincronización de órdenes entre Odoo ERP y múltiples marketplaces (MercadoLibre sandbox + paris-mock), construido con outbox pattern, DLQ, observabilidad end-to-end y un MCP server que permite a un agente IA trazar y operar incidentes de sincronización.
"¿Por qué la orden ML-98345 no apareció en MELI?" → El agente responde con el trace completo y puede reintentar el envío con los permisos correctos.
Un lunes con el equipo de Comercio Exterior:
Las órdenes en Odoo no aparecen en los marketplaces.
Los webhooks llegan pero nadie sabe si se procesaron.
El equipo de soporte no tiene visibilidad — necesita abrir un ticket a IT.
Este repo resuelve ese escenario end-to-end:
Odoo como fuente de verdad de órdenes.
Sync confiable a MercadoLibre y Paris con retry exponencial y DLQ.
Webhooks idempotentes con deduplicación y firma HMAC.
Bronze/Silver/Gold en BigQuery para analytics (dbt).
Observabilidad con OpenTelemetry, Grafana y alertas.
MCP server con IAM por scope y audit log — el agente puede responder y actuar.
Related MCP server: yt-mcp-server-odoo
┌─────────────────────────────────────────────────────────────────────────────┐
│ Retail Order Sync Hub │
│ │
│ ┌─────────┐ outbox ┌──────────────┐ ┌────────────┐ │
│ │ Odoo │──pattern──▶│ Outbox Worker│───▶│ Adapters │──▶ MercadoLibre│
│ │ (ERP) │ │ retry/DLQ │ │ ML · Paris │──▶ paris-mock │
│ └─────────┘ └──────────────┘ └────────────┘ │
│ ▲ │ │ │
│ │ sync.dlq webhooks │
│ reconcile (Pub/Sub) (signed · idempotent) │
│ │ │ │
│ ┌────┴────────────┐ ┌─────────▼──────┐ │
│ │ Subscriber + │◀── marketplace ────│ Webhook │ │
│ │ Reconciler │ .events │ Receiver │ │
│ │ (silver orders) │ (Pub/Sub) │ (bronze · dedup)│ │
│ └────────┬────────┘ └────────┬────────┘ │
│ │ │ │
│ ┌─────▼──────────────────────────────────────▼──────┐ │
│ │ BigQuery │ │
│ │ bronze (raw) → silver (clean) → gold (SLA/KPIs) │ │
│ │ dbt models · contracts · singular tests │ │
│ └─────────────────────────┬──────────────────────────┘ │
│ │ │
│ ┌────────────────────────────▼──────────────────────────┐ │
│ │ MCP Server │ │
│ │ get_order_status · trace_order · get_dlq_depth │ │
│ │ get_sla_metrics · find_failed_orders │ │
│ │ replay_dlq_message · retry_failed_sync · drain_dlq │ │
│ │ IAM (scopes: orders.read / dlq.replay / dlq.admin) │ │
│ │ Audit log (mcp_audit_log, transacción separada) │ │
│ └────────────────────────────▲──────────────────────────┘ │
│ │ MCP protocol (stdio) │
│ Claude Code / Desktop │
│ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ Observabilidad: OTel Collector → Prometheus + Tempo │ │
│ │ Grafana: Comex Ops dashboard · Pipeline Health │ │
│ └──────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────┘Diagrama Mermaid completo: docs/diagrams/architecture.mmd
Capa | Tecnología |
Runtime | Python 3.11, uv, ruff, mypy strict |
API | FastAPI + Pydantic v2 |
DB | PostgreSQL (psycopg3) + SQLAlchemy 2.x + Alembic |
Broker | Google Cloud Pub/Sub (emulator local, real en GCP) |
Outbox | Patrón outbox con |
DLQ | Pub/Sub topic |
Analytics | BigQuery + dbt (bronze/silver/gold, contratos, tests singulares) |
AI | FastMCP 2.x, stdio transport, MCP_STATIC_TOKENS IAM |
Observabilidad | OpenTelemetry SDK + Collector → Prometheus + Tempo → Grafana |
Infra local | Docker Compose (stack + obs stack separados) |
CI | GitHub Actions (ruff + mypy + pytest, coverage ≥ 85%) |
Para demos sin tocar la terminal: un panel Streamlit local con botones para levantar el stack, ver el estado de cada contenedor en vivo y abrir Grafana/Prometheus.
make console # abre http://localhost:8501Botones para up / migrate / seed / chaos / obs-up, badges de estado por
servicio, accesos directos a los dashboards y health checks. Corre local (ejecuta
make/docker en tu máquina) — no exponer públicamente.
Docker Desktop
Python 3.11 (uv lo gestiona automáticamente)
uv instalado: curl -LsSf https://astral.sh/uv/install.sh | sh
git clone https://github.com/JulioPradenas/retail-order-sync-hub.git
cd retail-order-sync-hub
uv sync --devmake up # Odoo, Postgres, Pub/Sub emulator, paris-mock
make migrate # aplica migraciones Alembic
make seed # carga órdenes demo en OdooEl primer make up descarga ~2 GB de imágenes. Odoo tarda ~60 s en iniciar.
# Check de código + tests (85%+ cobertura)
make check
# Odoo disponible en
open http://localhost:8069 # admin / admin
# Paris-mock en
curl http://localhost:9100/orders -H "X-API-Key: change-me"
# Webhook receiver
curl http://localhost:8000/healthmake obs-up # Grafana + Prometheus + Tempo + OTel Collector
open http://localhost:3000 # Grafana — admin / adminDashboards disponibles:
Comex Ops — webhook throughput, sync outcomes, DLQ depth, latencia p95
Pipeline Health — OTel spans, FastAPI requests, Prometheus targets
make up && make migrate
ROSH_INTEGRATION=1 uv run pytest -m integration -vcp dbt/profiles.yml.template ~/.dbt/profiles.yml
# Edita con tu project_id y credenciales
cd dbt && uv run dbt run && uv run dbt testEl MCP server expone 8 herramientas a Claude Code o Claude Desktop para trazar y operar incidentes de sincronización.
{
"mcpServers": {
"retail-order-sync-hub": {
"command": "uv",
"args": ["run", "python", "-m", "src.mcp_server"],
"cwd": "/ruta/al/retail-order-sync-hub",
"env": {
"MCP_STATIC_TOKENS": "mi-token:orders.read,metrics.read,outbox.retry,dlq.replay",
"APP_DB_HOST": "localhost",
"APP_DB_PORT": "5433"
}
}
}
}Guía completa: docs/mcp-setup.md
Herramienta | Scope requerido | Descripción |
|
| Estado actual de una orden en Postgres silver |
|
| Timeline completa: webhooks → outbox → silver |
|
| Cantidad de órdenes en DLQ |
|
| p50/p95 de latencia de sync desde BigQuery gold |
|
| Órdenes sin sync en un período |
|
| Resetea una entrada DLQ a pending (auditado) |
|
| Re-encola todas las entradas DLQ de una orden (auditado) |
|
| Lista o limpia en bulk el DLQ (dry_run por default, auditado) |
¿Por qué la orden ML-12345 no llegó a MercadoLibre?
trace_order("ML-12345")¿Cuántas órdenes están bloqueadas en DLQ en este momento?
get_dlq_depth()Hay 3 órdenes atascadas — reintentar todas con retry
retry_failed_sync("12345")Tres roles predefinidos para configurar tokens:
Rol | Scopes |
viewer |
|
operator | + |
admin | + |
Cada operación write queda registrada en mcp_audit_log con user_id, scope, params, resultado y latencia. Referencia completa: docs/iam.md
Documento | Contenido |
Scopes, roles, tokens, audit log | |
Configuración Claude Desktop, demo prompts | |
Stack OTel, catálogo de métricas, dashboards | |
Contratos de adapters, retry policy | |
Narrativa FDE: decisiones, trade-offs, contexto | |
Deploy a GCP (Cloud Run, Pub/Sub, BigQuery Sandbox) | |
Análisis de costos GCP (objetivo <$10/mes) | |
Security review checklist | |
Outbox vs CDC, idempotencia, IAM del MCP | |
Architecture Decision Records (5 ADRs) | |
Modelos dbt, contratos de schema, tests singulares |
src/
adapters/ # Paris + MercadoLibre adapters (Protocol-based)
bq_sync/ # BigQuery watermark sync (bronze)
common/ # Config, DB, models, logging, OTel, signing
mcp_server/ # FastMCP server (read + write tools, IAM, audit)
outbox_worker/ # Outbox processor con retry exponencial + DLQ
paris_mock/ # Mock del marketplace Paris (FastAPI)
reconciler/ # Reconciliación silver → Odoo
subscriber/ # Pub/Sub subscriber → normalize → silver
webhook_receiver/ # Inbound webhooks (HMAC, dedupe, bronze)
infra/
docker-compose.yml # Stack operacional
docker-compose.obs.yml # Stack de observabilidad
grafana/ # Dashboards y datasources
dbt/ # Modelos bronze/silver/gold + contratos
migrations/ # Alembic migrations
tests/
unit/ # 141 tests unitarios (85%+ cobertura)
integration/ # Tests contra el stack real (ROSH_INTEGRATION=1)
docs/
adr/Fase | Descripción | PR |
0 | Setup repo, ADRs, CI | #1 |
1 | Odoo + Postgres + OTel collector | #2 |
2 | MercadoLibre OAuth + paris-mock | #3 |
3 | Webhook receiver + idempotencia + bronze | #4 |
4 | Adapter + outbox + outbound sync | #5 |
5 | Subscriber + reconciliación + silver | #6 |
6 | Observabilidad (OTel + Grafana) | #7 |
7 | BigQuery + dbt + gold | #8 |
8 | MCP read tools + IAM estático | #9 |
9 | MCP write tools + audit log | #10 |
10 | Tests unitarios + chaos (85% coverage) | #11 |
11 | Docs + narrativa FDE | #12 |
Artefactos de despliegue listos y verificados localmente. El deploy en vivo es un
comando con cuenta GCP autenticada (ver docs/deploy-gcp.md).
Sub-fase | Descripción | PR | Verificación local |
V2.1 | Cloud Run: Dockerfile productivo + Secret Manager | #15 |
|
V2.2 | Pub/Sub real + IAM least-privilege (Terraform) | #16 |
|
V2.3 | dbt scheduled (cron) + switch a Cloud Trace | #17 | YAML válido, |
V2.4 | Cost analysis + security review + blog técnico | #18 | docs |
BigQuery Sandbox corre sin tarjeta; Cloud Run / Pub/Sub / Secret Manager requieren billing activo.
MIT
List (dry_run=True) or bulk-reset (dry_run=False) all DLQ outbox entries. Scope: dlq.admin. Audited.
| Name | Required | Description | Default |
|---|---|---|---|
| dry_run | No | ||
| api_token | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses that actions are audited and requires admin scope. However, it does not specify the irreversibility of the bulk-reset action, error behavior, or idempotency, which are important for a potentially destructive operation.
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-loads the key behavior. It packs useful information into a single sentence. Could be slightly more structured, but it efficiently conveys purpose and mode.
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?
Given the presence of an output schema, return values are covered. The description includes scope and auditing. However, it lacks details on pagination, failure handling, or consequences of the bulk-reset action, making it somewhat incomplete for the tool's complexity.
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 0%, so the description must explain parameters. It explains the dry_run parameter's function but completely omits the api_token parameter. Only half of the parameters receive semantic context.
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 dual purpose: listing (dry_run=True) or bulk-resetting (dry_run=False) all DLQ outbox entries. It identifies the specific resource and verb, distinguishing it from siblings like _find_failed_orders and _get_dlq_depth.
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 provides clear guidance on when to use each mode via the dry_run parameter. It mentions the scope (dlq.admin) indicating access requirements. However, it does not explicitly state when not to use this tool compared to alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find orders that were created but never successfully synced to a marketplace.
| Name | Required | Description | Default |
|---|---|---|---|
| since | No | 24h | |
| api_token | No | ||
| marketplace | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It only hints at a read operation ('Find') but does not confirm whether it is read-only, requires authentication (beyond the api_token parameter), or has rate limits or other constraints.
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 a single concise sentence with no wasted words. However, it omits important details about parameters and usage, so it does not fully earn its place in terms of completeness.
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?
The tool has an output schema, so return values need not be explained. However, the three parameters are undocumented in both schema and description. The description lacks context on how to use the tool effectively, leaving moderate gaps.
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 0%, yet the description does not explain any parameters. The meanings of 'since,' 'api_token,' and 'marketplace' are left to inference. This is insufficient compensation for the lack of schema descriptions.
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 verb 'Find' and the resource 'orders that were created but never successfully synced to a marketplace.' It implicitly distinguishes from sibling tools like _get_order_status and _retry_failed_sync by specifying the failure condition, but does not explicitly differentiate.
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?
No guidance on when to use this tool versus alternatives. It does not mention prerequisites, context, or exclusions. The description only states what it does without any usage advice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return the number of orders currently stuck in the DLQ.
| Name | Required | Description | Default |
|---|---|---|---|
| api_token | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. The description only states it returns a count but does not disclose if it's read-only, requires authentication, or any side effects. It is minimal.
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 a single concise sentence with no filler, but it is too minimal for a tool with a parameter and output schema. It could include more structure.
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 simple tool with one parameter and an output schema, the description is incomplete. It does not explain the parameter or mention the output format, relying on the schema alone.
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 0%, and the description does not explain the 'api_token' parameter. The agent gets no help understanding what to provide.
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 verb 'return' and the resource 'number of orders currently stuck in the DLQ'. It distinguishes itself from sibling tools like _drain_dlq and _replay_dlq_message which perform different actions.
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?
No guidance on when to use this tool versus alternatives. The description does not mention prerequisites, context, or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return the current status of an order from the silver layer.
| Name | Required | Description | Default |
|---|---|---|---|
| order_id | Yes | ||
| api_token | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It implies a read operation but does not state idempotency, error behavior (e.g., missing order), or authorization needs. The term 'silver layer' hints at data tier but lacks clarity.
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 a single sentence with no wasted words, but it under-specifies key details. It is concise but not sufficiently informative for the agent.
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?
Given the presence of an output schema, the description does not need to detail return values, but it lacks guidance on parameter usage and error states. The tool is simple, but the description feels incomplete for effective invocation.
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 0%, and the description adds no meaning to parameters. It does not explain the format of order_id or the purpose of api_token, forcing the agent to guess.
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 verb 'Return' and the resource 'current status of an order', specifying the data source 'silver layer'. This is distinct from sibling tools like _trace_order or _get_dlq_depth, which focus on different aspects.
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 provides no information on when to use this tool versus alternatives such as _trace_order or _find_failed_orders. There is no mention of prerequisites, context, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return SLA metrics (avg, p50, p95 sync time in seconds) for a marketplace from the BigQuery gold layer.
| Name | Required | Description | Default |
|---|---|---|---|
| window | No | 7d | |
| api_token | No | ||
| marketplace | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It mentions querying a specific data source and returning aggregated metrics, but does not disclose authentication requirements (api_token), potential costs, rate limits, or whether the operation is read-only. The description is minimal for a tool with no annotation support.
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 a single sentence with no superfluous words. It is front-loaded with the core action and resource. However, it could be slightly more structured by detailing parameters or return format.
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?
Given that an output schema exists, the description does not need to detail return values, but it does not mention the return format or time range scope. It covers the high-level purpose but lacks depth on parameter usage and behavioral context.
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 coverage is 0%, so the description must explain parameters. It explains 'marketplace' (implied by 'for a marketplace') but fails to describe 'window' (default '7d') or 'api_token' (default ''). No additional meaning is provided beyond what the schema names offer.
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 action ('Return'), the resource ('SLA metrics'), and the specific metrics (avg, p50, p95 sync time in seconds). It also mentions the data source ('BigQuery gold layer'), which distinguishes it from sibling tools focused on DLQ and order operations.
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 implicitly indicates this tool is for retrieving SLA metrics, which contrasts with sibling tools (e.g., _drain_dlq, _retry_failed_sync). However, it does not explicitly state when to use it or when to avoid it, nor does it mention prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Reset a DLQ outbox entry back to pending so the worker retries it. Scope: dlq.replay. Audited.
| Name | Required | Description | Default |
|---|---|---|---|
| api_token | No | ||
| outbox_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must disclose behavioral traits. It declares the tool is mutative ('Reset'), scoped (dlq.replay), and audited. However, it does not detail potential side effects (e.g., impact on retry count, duplicate handling) or required permissions beyond the scope note. Adequate but not comprehensive.
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 extremely concise at 20 words, conveying purpose, scope, and audit status in two short sentences. Every phrase adds value without redundancy or unnecessary detail.
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?
Given the tool has 2 parameters (one undocumented in schema and description) and an output schema not referenced, the description lacks completeness. It does not mention prerequisites (outbox_id must exist), how the output signals success, or any constraints (e.g., rate limits). The presence of siblings is ignored, missing an opportunity to contrast.
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 two parameters (api_token, outbox_id) with 0% description coverage, and the tool description adds no parameter explanations. The 'outbox_id' is not described as the identifier for the DLQ entry, nor is 'api_token' clarified. The description fails to compensate for the schema's lack of documentation.
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 action ('Reset a DLQ outbox entry back to pending') and the effect ('so the worker retries it'), making the purpose unambiguous. It also includes scope (dlq.replay) and audit note, distinguishing it from read-only siblings like _get_dlq_depth or batch operations like _drain_dlq.
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 implies usage for replaying a single DLQ message but does not provide explicit when-to-use or when-not-to-use guidance. No alternatives are mentioned, though siblings exist (e.g., _drain_dlq for bulk removal). The agent must infer context from the name and description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Force re-enqueue of an order into the outbox for all active adapters. Scope: outbox.retry. Audited.
| Name | Required | Description | Default |
|---|---|---|---|
| order_id | Yes | ||
| api_token | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the burden. It states 'force re-enqueue' and 'audited' but fails to disclose side effects, permissions, rate limits, or whether the operation is reversible.
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 very short at one sentence plus two fragment notes. While concise, it sacrifices completeness and structure, such as listing parameters or describing behavior.
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?
Given the tool has 2 parameters and an output schema (not shown), the description omits crucial details about return values, error handling, and post-conditions, making it incomplete for an agent.
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 coverage is 0%—the description does not mention either parameter (order_id, api_token). It provides no additional meaning beyond the schema's basic types and defaults.
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 explicitly states the tool's action ('Force re-enqueue of an order into the outbox for all active adapters') and includes scope and audit info, clearly distinguishing it from sibling tools like _replay_dlq_message.
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?
No guidance is given on when to use this tool versus siblings (e.g., _replay_dlq_message, _drain_dlq). The description lacks context about prerequisites or conditions for use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return a cross-source timeline for an order: inbound webhooks → outbox pushes → silver state.
| Name | Required | Description | Default |
|---|---|---|---|
| order_id | Yes | ||
| api_token | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must convey behavioral traits. It states 'Return' implying read-only, but does not disclose permissions, rate limits, data freshness, or side effects. Minimal transparency for a read operation.
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 a single, well-structured sentence that conveys the core purpose without any extraneous words.
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?
Despite having an output schema (not shown), the description does not explain the timeline content (e.g., timestamps, statuses) or how to interpret results. For a diagnostic tool, more detail is needed for completeness.
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 0% and the description does not explain the parameters (order_id, api_token). The optional api_token role is unclear, and no format or usage guidance is given.
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 returns a cross-source timeline for an order, listing specific sources (inbound webhooks, outbox pushes, silver state). This distinguishes it from sibling tools like _get_order_status (status only) and _find_failed_orders (finding failures).
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 implies this tool is used for tracing order flows across sources, but it does not explicitly state when to use it versus alternatives, nor does it provide exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0_drain_dlq_find_failed_orders_get_dlq_depth_get_order_status_get_sla_metrics_replay_dlq_message_retry_failed_sync_trace_orderScored across 8 tools
Each tool has a distinct and clear purpose, from draining the DLQ to tracing an order's timeline. There is no overlap or ambiguity between tools.
All tools use snake_case with a leading underscore, but the verb-noun structure varies (e.g., 'drain_dlq' vs 'get_dlq_depth' vs 'retry_failed_sync'). Still, the pattern is largely consistent and readable.
With 8 tools, the server covers essential admin operations for order sync—DLQ management, order status, retries, and traces—without being bloated or insufficient.
The tool set focuses on debugging and manual intervention but lacks general monitoring or management tools (e.g., listing all orders, viewing sync history). Some functionality for updating or deleting orders is missing.
MCP server unifying ERPs, CRMs, APIs and knowledge base for Claude, ChatGPT and Gemini.
MCP server enabling AI agents to manage Bitrix24 features via standardized protocol
Hosted MCP for e-commerce: live product catalog, stock, and pricing for AI agents.
Unified MCP server for 70+ eCommerce platforms: products, orders, customers, and more.