Grips Intelligence MCP Server
MCP-сервер Grips Intelligence (v2)
Сервер протокола Model Context Protocol (MCP), который предоставляет API данных электронной коммерции Grips Intelligence любому MCP-клиенту — Claude Desktop, Cowork, Claude Code и т. д.
v2 — это полная переработка v1 с защищенной обработкой данных, внедренной с самого начала. Она исправляет класс ошибок ".map is not a function", для устранения которых в v1.x требовался патч времени выполнения — теперь при работе с малоизвестными или неизвестными доменами сервер возвращает корректный ответ "нет данных" вместо аварийного завершения вызова инструмента.
Что внутри
Инструмент | Что он делает |
| Ежемесячная выручка / транзакции / сеансы / расходы на рекламу / средний чек (AOV) / конверсия (CR) / цена за клик (CPC) для одного или нескольких доменов |
| Ежедневная выручка / транзакции / сеансы (ограниченное покрытие) |
| Разбивка по органическому поиску / платному поиску / прямым переходам / рефералам / социальным сетям — временные ряды + агрегированные данные |
| Расходы на платные медиа, клики и цена за клик (CPC) — временные ряды + агрегированные данные |
| Выручка, сеансы, конверсия (CR), средний чек (AOV) для мобильных устройств / компьютеров / планшетов |
| Параллельная выгрузка данных по доменам с ранжированием; ошибки по отдельным доменам изолированы |
| "Аварийный выход" — отправка произвольного GraphQL-запроса Grips |
Все инструменты по умолчанию выводят данные в формате markdown для удобства чтения. Передайте format: "json" для получения ответа в формате, пригодном для машинной обработки.
Установка
npm installСкрипт prepare автоматически собирает dist/ при выполнении npm install.
Конфигурация
Укажите свой API-ключ Grips в конфигурации сервера MCP-клиента. Для Claude Desktop это файл ~/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"
}
}
}
}Обязательные переменные окружения:
GRIPS_API_KEY— ваш токен API Grips (отправляется в заголовкеgrips-api-key).
Опциональные переменные окружения:
GRIPS_DEFAULT_COUNTRY—US,GBилиDE. По умолчанию используетсяUS, если значение не задано или неверно.
После редактирования конфигурации полностью закройте Claude Desktop (Cmd+Q — не просто закрытие окна) и откройте снова.
Отличия от v1
v1 аварийно завершался при получении ответа API определенной формы: когда Grips возвращал данные по домену с малым покрытием или неизвестному домену, поле timeseries приходило как {} вместо null, undefined или []. В коде использовалось (data.timeseries ?? []).map(...), что защищает только от null/undefined, но не от {}. Результат: "data.timeseries ?? []).map is not a function".
v2 пропускает каждое поле полезной нагрузки через toArray<T>() (для массивов) или toObject<T>() (для ответов в виде словаря, таких как эндпоинт устройств) перед использованием. Любое значение, не являющееся массивом или объектом, заменяется на безопасное пустое значение по умолчанию, и инструмент возвращает корректный ответ "нет данных" вместо выброса исключения.
Другие изменения:
Нормализация дат стала согласованной (каждая дата приводится к
YYYY-MM-DDв UTC) во всех инструментах, поэтому строки не смещаются между днями в часовых поясах, отличных от UTC.Форматировщики валют / целых чисел / процентов отображают
—для отсутствующих значений вместо$NaNили0.00%.Сообщения об ошибках теперь включают полезные подсказки — 401 → "проверьте свой API-ключ", 429 → "превышен лимит запросов, сузьте временной интервал" и т. д.
Изоляция ошибок по доменам в
grips_compare_domains— ошибка одного домена при сравнении восьми больше не ломает остальные семь.Ограничение по количеству символов — ответы обрезаются примерно на 200 КБ с видимым уведомлением, чтобы выгрузки по нескольким доменам не переполняли контекстное окно.
Разработка
npm run dev # watch mode, rebuilds on change
npm run build # one-shot build to dist/Тестирование из командной строки
Проверьте, что сервер запускается без ошибок (он завершит работу при получении EOF из stdin):
GRIPS_API_KEY=your-key node dist/index.js < /dev/nullВы должны увидеть [grips-mcp] grips-mcp-server v2.0.0 ready (default country: US). в stderr и отсутствие аварийного завершения.
Для интерактивного тестирования используйте @modelcontextprotocol/inspector:
npx @modelcontextprotocol/inspector node dist/index.jsСправочник API
Grips документирует свою публичную схему по адресу https://gripsintelligence.com/knowledge-base/api. Запросы, используемые этим сервером, скопированы дословно с этой страницы.
Поддерживаемые страны на текущий момент: US, GB, DE. Все остальные вызовут ошибку API.
Лицензия
Частная — не для внешнего распространения.
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.
