Grips Intelligence MCP Server
Servidor MCP de Grips Intelligence (v2)
Un servidor de Protocolo de Contexto de Modelo (MCP) que expone la API de datos de comercio electrónico de Grips Intelligence a cualquier cliente MCP: Claude Desktop, Cowork, Claude Code, etc.
v2 es una reconstrucción limpia de la v1 con manejo defensivo de datos integrado desde el primer día. Corrige la clase de errores ".map is not a function" que la v1.x necesitaba un parche en tiempo de ejecución para solucionar: los dominios con poca información o desconocidos ahora se degradan a una respuesta limpia de "sin datos" en lugar de bloquear la llamada a la herramienta.
Qué incluye
Herramienta | Qué hace |
| Ingresos mensuales / transacciones / sesiones / coste publicitario / AOV / CR / CPC para uno o más dominios |
| Ingresos diarios / transacciones / sesiones (cobertura limitada) |
| Desglose de búsqueda orgánica / de pago / directa / referencia / social — series temporales + agregados |
| Gasto en medios pagados, clics y CPC — series temporales + agregados |
| Ingresos, sesiones, CR, AOV de móvil / escritorio / tableta |
| Extracción paralela por dominio con clasificación de tabla de posiciones; los errores por dominio están aislados |
| Vía de escape: envía una consulta GraphQL de Grips arbitraria |
Todas las herramientas utilizan por defecto la salida en markdown para facilitar la lectura. Pase format: "json" para obtener una salida legible por máquina.
Instalación
npm installEl script prepare compila automáticamente dist/ cuando ejecutas npm install.
Configuración
Establece tu clave de API de Grips en la configuración del servidor del cliente MCP. Para Claude Desktop, es ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"grips": {
"command": "node",
"args": [
"/ABSOLUTE/PATH/TO/grips-mcp-server-v2/dist/index.js"
],
"env": {
"GRIPS_API_KEY": "your-api-key-here",
"GRIPS_DEFAULT_COUNTRY": "US"
}
}
}
}Entorno requerido:
GRIPS_API_KEY: tu token de API de Grips (enviado como el encabezadogrips-api-key).
Entorno opcional:
GRIPS_DEFAULT_COUNTRY:US,GBoDE. Por defecto esUSsi no se establece o no es válido.
Después de editar la configuración, cierra completamente Claude Desktop (Cmd+Q, no solo cerrando la ventana) y vuelve a abrirlo.
Qué es diferente de la v1
La v1 fallaba con una forma de respuesta de API específica: cuando Grips devolvía un dominio con poca cobertura o desconocido, el campo timeseries devolvía {} en lugar de null, undefined o []. El código usaba (data.timeseries ?? []).map(...), que solo protege contra null/undefined, no contra {}. Resultado: "data.timeseries ?? []).map is not a function".
La v2 enruta cada campo de carga útil a través de toArray<T>() (para matrices) o toObject<T>() (para respuestas con forma de diccionario como el endpoint de dispositivos) antes de su uso. Cualquier valor que no sea una matriz o un objeto pasa a un valor predeterminado vacío seguro, y la herramienta devuelve una respuesta limpia de "sin datos" en lugar de lanzar un error.
Otros cambios:
La normalización de fechas es consistente (cada fecha se convierte a
YYYY-MM-DDen UTC) en todas las herramientas, por lo que las filas no se desplazan entre los límites de los días en zonas horarias que no son UTC.Los formateadores de moneda / enteros / porcentajes muestran
—para los valores faltantes en lugar de$NaNo0.00%.Los mensajes de error ahora incluyen sugerencias procesables: 401 → "comprueba tu clave de API", 429 → "límite de tasa alcanzado, reduce tu ventana", etc.
Aislamiento de errores por dominio en
grips_compare_domains: un dominio con poca información en una comparación de 8 dominios ya no rompe los otros siete.Truncamiento del presupuesto de caracteres: las respuestas se limitan a ~200 KB con un aviso visible para que las extracciones de múltiples dominios no saturen la ventana de contexto.
Desarrollo
npm run dev # watch mode, rebuilds on change
npm run build # one-shot build to dist/Pruebas desde la línea de comandos
Prueba que el servidor arranca sin errores (se cerrará al recibir EOF desde stdin):
GRIPS_API_KEY=your-key node dist/index.js < /dev/nullDeberías ver [grips-mcp] grips-mcp-server v2.0.0 ready (default country: US). en stderr y ningún bloqueo.
Para pruebas interactivas, utiliza @modelcontextprotocol/inspector:
npx @modelcontextprotocol/inspector node dist/index.jsReferencia de la API
Grips documenta su esquema público en https://gripsintelligence.com/knowledge-base/api. Las consultas que utiliza este servidor están copiadas literalmente de esa página.
Países admitidos actualmente: US, GB, DE. Cualquier otro dará error en la API.
Licencia
Privada: no apta para distribución externa.
Available Tools
7 toolsgrips_compare_domainsCompare multiple domains side-by-sideARead-onlyIdempotent
Fetches per-domain performance in parallel and returns a leaderboard ranked by the chosen metric (revenue, sessions, AOV, etc.). Per-domain failures are captured in an errors section — one thin or unknown domain won't block the rest of the comparison.
| Name | Required | Description | Default |
|---|---|---|---|
| domains | Yes | Two or more domains to compare head-to-head. | |
| date_from | Yes | Start of reporting window (YYYY-MM-DD). | |
| date_to | Yes | End of reporting window (YYYY-MM-DD). | |
| country | No | Two-letter country code. Grips supports US, GB, DE. | |
| format | No | Response format. 'markdown' is human-readable; 'json' is machine-parseable. | markdown |
| sort_by | No | Metric to sort the leaderboard by. Defaults to total revenue. | transactionrevenue |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds value beyond annotations by disclosing parallel fetching, leaderboard ranking, and non-blocking error handling. No contradiction with annotations (readOnly, idempotent). This fills gaps that annotations alone do not cover.
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?
Two well-structured sentences: first states core functionality, second adds critical fault-tolerance behavior. No redundant 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?
Given no output schema, the description sufficiently hints at return format (leaderboard with errors). All six parameters are covered in schema; description adds behavioral context (parallel, non-blocking). Complete for its complexity level.
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 100%, and the description does not add new meaning beyond what schema descriptions already provide. The mention of 'chosen metric' is echoing the sort_by enum. Baseline 3 is appropriate.
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 uses a specific verb ('Fetches') and resource ('per-domain performance'), and highlights the unique parallel leaderboard aspect, clearly distinguishing it from siblings like grips_get_domain_performance (single domain) and grips_get_daily_performance (daily data).
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 comparing multiple domains side-by-side, and the fault-tolerance note ('one thin or unknown domain won't block') provides context. However, it does not explicitly state when to avoid this tool or suggest alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
grips_get_adwordsGet AdWords spend over timeARead-onlyIdempotent
Returns paid-media spend, ad clicks, and CPC for one or more domains — monthly timeseries plus an aggregated roll-up. Use this to evaluate paid-spend trends, auction-cost inflation, or total investment in paid search.
| Name | Required | Description | Default |
|---|---|---|---|
| domains | Yes | One or more domains (e.g. ['adidas.com', 'nike.com']). Protocol and trailing slash are stripped automatically. | |
| date_from | Yes | Start of the reporting window, inclusive, as YYYY-MM-DD. Example: '2024-01-01'. | |
| date_to | Yes | End of the reporting window, inclusive, as YYYY-MM-DD. Example: '2024-12-31'. | |
| country | No | Optional country filter. Defaults to the server's GRIPS_DEFAULT_COUNTRY (usually 'US'). | |
| format | No | Response format. 'markdown' is human-readable; 'json' is machine-parseable. | markdown |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds context on the output format (monthly timeseries + roll-up), which complements the annotations without contradiction.
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?
Two sentences, front-loading the return value and purpose. Every sentence adds value, with no redundancy or fluff.
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 well-documented schema and annotations, the description covers the essential context: what data is returned and in what structure (monthly timeseries + roll-up). Could briefly mention pagination or limitations but overall sufficient.
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 100%, so the schema already documents all parameters. The description adds general context about the return values but does not provide additional parameter-specific semantics beyond what the schema offers.
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 paid-media spend, ad clicks, and CPC for domains as monthly timeseries plus a roll-up. It distinguishes itself from sibling tools by specifying the exact metrics and output structure.
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?
Explicitly lists use cases: evaluating paid-spend trends, auction-cost inflation, or total investment. Does not include when-not-to-use or mention alternatives, but the guidance is clear enough for an agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
grips_get_channelsGet channel breakdown (Organic, Paid, Direct, etc.)ARead-onlyIdempotent
Returns revenue, sessions, transactions, CR, and AOV broken out by marketing channel (Organic Search, Paid Search, Direct, Referral, Social) for one or more domains. Use this to understand channel mix, evaluate paid-vs-organic balance, or spot a channel shift over time. Response includes both a monthly timeseries and an aggregated roll-up.
| Name | Required | Description | Default |
|---|---|---|---|
| format | No | Response format. 'markdown' is human-readable; 'json' is machine-parseable. | markdown |
| country | No | Optional country filter. Defaults to the server's GRIPS_DEFAULT_COUNTRY (usually 'US'). | |
| date_to | Yes | End of the reporting window, inclusive, as YYYY-MM-DD. Example: '2024-12-31'. | |
| domains | Yes | One or more domains (e.g. ['adidas.com', 'nike.com']). Protocol and trailing slash are stripped automatically. | |
| channels | No | Optional list of channels to include. Defaults to all Grips-supported channels: Direct, Organic Search, Paid Search, Referral, Social. | |
| date_from | Yes | Start of the reporting window, inclusive, as YYYY-MM-DD. Example: '2024-01-01'. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is clear. The description adds that the response includes a monthly timeseries and an aggregated roll-up, which provides useful behavioral context beyond annotations.
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?
Three sentences effectively convey the output, use cases, and response structure. Every sentence adds value, with no redundancy or fluff.
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 rich annotations (readOnly, idempotent) and the detailed explanation of the response structure (monthly timeseries + roll-up), the description is largely complete for a read-only aggregate report. No output schema exists but the description covers the important aspects.
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 100%, so every parameter is already documented. The description does not add significant new meaning for parameters beyond what the schema provides, meeting the baseline for high coverage.
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 returns revenue, sessions, transactions, CR, and AOV broken out by marketing channel for one or more domains, listing specific channels. It also provides use cases, clearly distinguishing it from sibling tools like grips_get_devices or grips_get_daily_performance.
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 advises when to use the tool (understand channel mix, evaluate paid-vs-organic balance, spot channel shift) but does not explicitly mention when not to use it or provide alternatives among siblings. This is clear context for use, but lacks explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
grips_get_daily_performanceGet daily performance (revenue / transactions / sessions)ARead-onlyIdempotent
Returns a daily timeseries of revenue, transactions, and sessions for one or more domains. Useful for spike/dip detection, promo windows, and day-of-week patterns. Note: Grips only offers daily data for a subset of domains — smaller sites often return empty. Defaults to markdown output.
| Name | Required | Description | Default |
|---|---|---|---|
| domains | Yes | One or more domains (e.g. ['adidas.com', 'nike.com']). Protocol and trailing slash are stripped automatically. | |
| date_from | Yes | Start of the reporting window, inclusive, as YYYY-MM-DD. Example: '2024-01-01'. | |
| date_to | Yes | End of the reporting window, inclusive, as YYYY-MM-DD. Example: '2024-12-31'. | |
| country | No | Optional country filter. Defaults to the server's GRIPS_DEFAULT_COUNTRY (usually 'US'). | |
| format | No | Response format. 'markdown' is human-readable; 'json' is machine-parseable. | markdown |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide safety and idempotency hints. The description adds value by noting the default format (markdown) and the empty result behavior for smaller domains, but doesn't cover auth or rate limits. Burden partially shared with annotations.
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?
Three concise sentences, front-loaded with the main action, followed by use cases and a critical caveat. No wasted 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 lacking an output schema, the description adequately explains the return shape (daily timeseries of specific metrics) and important caveats (empty results). For a straightforward time-series tool, this is nearly complete.
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 covers all 5 parameters with 100% coverage, so baseline is 3. The description adds minimal extra meaning beyond the schema, such as implying daily granularity and the empty result hint, but does not significantly enhance parameter understanding.
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?
Description clearly states the tool returns a daily timeseries of revenue, transactions, and sessions for one or more domains, with specific use cases (spike/dip detection, promo windows, day-of-week patterns). It distinguishes from siblings like grips_get_domain_performance (likely aggregate) and grips_compare_domains (comparison).
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?
Provides explicit use cases and notes data availability limitations ('smaller sites often return empty'), but does not name alternative tools for exclusion. The context helps an agent decide when to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
grips_get_devicesGet device mix (mobile / desktop / tablet)ARead-onlyIdempotent
Returns device-level revenue, sessions, transactions, CR, and AOV for one or more domains aggregated over a date window. Use this to understand where a competitor's traffic and conversions come from — mobile vs desktop split, AOV by device, etc.
| Name | Required | Description | Default |
|---|---|---|---|
| domains | Yes | One or more domains (e.g. ['adidas.com', 'nike.com']). Protocol and trailing slash are stripped automatically. | |
| date_from | Yes | Start of the reporting window, inclusive, as YYYY-MM-DD. Example: '2024-01-01'. | |
| date_to | Yes | End of the reporting window, inclusive, as YYYY-MM-DD. Example: '2024-12-31'. | |
| country | No | Optional country filter. Defaults to the server's GRIPS_DEFAULT_COUNTRY (usually 'US'). | |
| format | No | Response format. 'markdown' is human-readable; 'json' is machine-parseable. | markdown |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds specific metrics returned (revenue, sessions, etc.) and the aggregation over a date window, which extends beyond the annotations.
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 two sentences with no wasted words. The first sentence states functionality, the second provides usage context.
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 lacks an output schema, but the description lists the key metrics. No mention of pagination or date range limits, but overall it is sufficiently complete for a read-only data retrieval tool.
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 100% with descriptions for all 5 parameters. The description does not add new parameter details beyond the schema, so it meets the baseline.
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 it returns device-level metrics (revenue, sessions, transactions, CR, AOV) for domains over a date window, and explicitly says 'Use this to understand where a competitor's traffic and conversions come from', which distinguishes it from siblings like grips_get_domain_performance.
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 when-to-use guidance ('Use this to understand where a competitor's traffic...') but does not explicitly mention when not to use or list alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
grips_get_domain_performanceGet domain performance (monthly)ARead-onlyIdempotent
Returns a monthly timeseries of revenue, transactions, sessions, ad cost, AOV, CR, and CPC for one or more domains over a date range. Use this for anything like 'how did adidas.com perform in Q1 2024' or 'compare nike.com and puma.com session volume YoY'. Defaults to markdown output; pass format='json' for structured data.
| Name | Required | Description | Default |
|---|---|---|---|
| domains | Yes | One or more domains (e.g. ['adidas.com', 'nike.com']). Protocol and trailing slash are stripped automatically. | |
| date_from | Yes | Start of the reporting window, inclusive, as YYYY-MM-DD. Example: '2024-01-01'. | |
| date_to | Yes | End of the reporting window, inclusive, as YYYY-MM-DD. Example: '2024-12-31'. | |
| country | No | Optional country filter. Defaults to the server's GRIPS_DEFAULT_COUNTRY (usually 'US'). | |
| format | No | Response format. 'markdown' is human-readable; 'json' is machine-parseable. | markdown |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, destructiveHint, idempotentHint, and openWorldHint, covering safety and idempotency. The description adds useful context about default output format ('Default to markdown output; pass format='json' for structured data') and the metrics included. No contradictions with annotations, but no additional behavioral specifics (e.g., rate limits, data source constraints) are provided.
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 concise two sentences: the first defines core functionality, the second provides usage examples and a format option. No unnecessary words, front-loaded with key information, and each sentence serves a purpose. Ideal brevity for an AI 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?
With 100% schema coverage, rich annotations, and no output schema, the description covers the key aspects: what metrics are returned, how to query (examples), and format options. It does not detail the JSON response structure, but that is acceptable without an output schema. The tool is relatively simple, and the description is sufficient for effective use.
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?
Input schema has 100% description coverage, with each parameter already well-documented (e.g., domains stripping protocol, date format, country enum). The description adds minimal extra meaning—only the format parameter hint about human-readable vs. machine-parseable output is slightly beyond the schema's 'description'. Baseline 3 is appropriate given the schema's thoroughness.
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 monthly timeseries of key e-commerce metrics (revenue, sessions, etc.) for one or more domains over a date range. Examples of natural language queries are provided, and the title includes 'monthly' to distinguish from daily granularity. The purpose is specific and unambiguous.
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 offers concrete usage examples ('how did adidas.com perform in Q1 2024', 'compare nike.com and puma.com session volume YoY'), which help the agent understand when to invoke this tool. However, it does not explicitly mention when not to use it (e.g., for daily data should use grips_get_daily_performance) or compare with alternative sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
grips_raw_querySend a raw Grips query (escape hatch)ARead-onlyIdempotent
Sends an arbitrary Grips GraphQL-like query and returns the raw JSON response. Use this only when the purpose-built tools (domain performance, channels, adwords, devices, daily, compare) don't cover what you need. The response is returned verbatim with no formatting — you are responsible for parsing it.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | A Grips-flavoured GraphQL-like query string. See https://gripsintelligence.com/knowledge-base/api for the schema. | |
| variables | No | Optional variables object. Grips queries usually expect a top-level `filters` key containing `domain`, `date`, and `country`. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, so no behavioral surprises. The description adds that the response is returned verbatim with no formatting, which is useful beyond annotations.
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?
Three sentences, each serving a distinct purpose: what it does, when to use, and what to expect. No filler, well-organized.
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 no output schema, the description explains the raw JSON response and the user's responsibility for parsing. It also provides a link for further schema details. Covers all necessary aspects for an escape hatch tool.
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 100%, but the description adds valuable context: it explains that 'query' is a Grips-flavored GraphQL-like string with a link to the schema, and that 'variables' often expects filters with domain, date, and country. This goes beyond the schema.
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 it sends an arbitrary Grips query and returns raw JSON, and explicitly distinguishes from sibling tools by positioning itself as an escape hatch when purpose-built tools don't suffice.
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 explicitly says 'use this only when the purpose-built tools... don't cover what you need', providing clear when-to-use and when-not-to-use guidance, and mentions that the user is responsible for parsing the response.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
7 tool updates
v2.0.0- First observed
grips_compare_domains - First observed
grips_get_adwords - First observed
grips_get_channels - First observed
grips_get_daily_performance - First observed
grips_get_devices - First observed
grips_get_domain_performance - First observed
grips_raw_query
TDQS
Scored across 7 tools
Each tool targets a distinct data dimension (domain performance, adwords, channels, devices, daily performance, comparison, raw query) with clear separation. No two tools have overlapping purposes.
All tools follow a consistent `grips_<verb>_<noun>` pattern in snake_case, with verbs like 'get' and 'compare', and a single exception 'raw_query' still fits the pattern. No mixing of conventions.
With 7 tools, the set is well-scoped for an analytics server covering multiple metrics and dimensions. Not too few to be limited, not too many to be overwhelming.
Core analytics needs are covered, and the raw query tool fills potential gaps. Minor missing areas like product-level data exist, but the surface is largely complete for the stated purpose.
Related MCP Connectors
Commerce intelligence for AI agents. Diagnose drop-offs, fix checkouts, optimize pricing.
Beta. Pay-per-call eCommerce competitive intel for AI agents: pricing, promos, readiness & more.
Ask questions across Shopify, Klaviyo, GA4 and 20+ e-commerce sources in plain English.
Read-only access to your Consequential eCommerce marketing analytics and attribution data.
