Grips Intelligence MCP Server
Grips Intelligence MCP 服务器 (v2)
一个模型上下文协议 (MCP) 服务器，将 Grips Intelligence 电子商务数据 API 暴露给任何 MCP 客户端（如 Claude Desktop、Cowork、Claude Code 等）。
v2 是对 v1 的彻底重构，从一开始就内置了防御性数据处理。它修复了 v1.x 需要运行时补丁才能解决的“.map is not a function”类错误——现在，对于数据稀疏或未知的领域，工具调用会降级为清晰的“无数据”响应，而不是崩溃。
包含内容
工具 | 功能 |
| 一个或多个领域的月度收入 / 交易量 / 会话数 / 广告成本 / 平均订单价值 (AOV) / 转化率 (CR) / 点击成本 (CPC) |
| 每日收入 / 交易量 / 会话数（覆盖范围有限） |
| 自然搜索 / 付费搜索 / 直接访问 / 引荐 / 社交渠道细分 — 时间序列 + 聚合数据 |
| 付费媒体支出、点击量和 CPC — 时间序列 + 聚合数据 |
| 移动端 / 桌面端 / 平板电脑的收入、会话数、转化率、平均订单价值 |
| 并行获取各领域数据并进行排行榜排名；各领域的错误相互隔离 |
| 逃生舱 — 发送任意 Grips GraphQL 查询 |
所有工具默认输出 Markdown 格式以提高可读性。传入 format: "json" 可获取机器可解析的输出。
安装
npm install当你运行 npm install 时，prepare 脚本会自动构建 dist/。
配置
在 MCP 客户端的服务器配置中设置你的 Grips API 密钥。对于 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— 你的 Grips API 令牌（作为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>()（针对设备端点等字典型响应）进行处理。任何非数组/非对象的值都会回退到一个安全的空默认值，工具会返回清晰的“无数据”响应，而不是抛出异常。
其他更改：
日期标准化：所有工具的日期格式统一为 UTC 下的
YYYY-MM-DD，因此在非 UTC 时区中，行数据不会跨越日期边界。货币 / 整数 / 百分比格式化程序：缺失值显示为
—，而不是$NaN或0.00%。错误消息：现在包含可操作的提示 — 401 → “检查你的 API 密钥”，429 → “速率受限，缩小查询窗口”等。
领域级错误隔离：在
grips_compare_domains中，8 个领域对比中某一个领域的数据缺失不再导致其他七个领域的结果中断。字符预算截断：响应上限约为 200KB 并带有可见提示，防止多领域拉取导致上下文窗口溢出。
开发
npm run dev # watch mode, rebuilds on change
npm run build # one-shot build to dist/命令行测试
测试服务器是否能无错误启动（它会在 stdin 收到 EOF 时退出）：
GRIPS_API_KEY=your-key node dist/index.js < /dev/null你应该在 stderr 中看到 [grips-mcp] grips-mcp-server v2.0.0 ready (default country: US). 且没有崩溃。
如需交互式测试，请使用 @modelcontextprotocol/inspector：
npx @modelcontextprotocol/inspector node dist/index.jsAPI 参考
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.
