一个通过 stdio 运行的只读 MCP 服务器，让 AI 智能体能够回答关于在线商店 SQLite 数据库（customers、products、orders、order_items）的分析性问题——而它永远无法修改该数据库。
完整的设计依据（决策日志、schema、安全模型、测试策略）见 SPEC.md。
Node.js >= 24.10.0（node:sqlite 的 setAuthorizer 需要此版本，用于实现下文的只读保证）。运行 node --version 检查。
除 npm ci 安装的内容外，没有其他运行时依赖。
Related MCP server: Read-Only SQLite Shop Database MCP Server
npm ci
npm run build
SHOP_DB_PATH=./shop.db npm startshop.db 已随仓库提供，开箱即用。如果需要从 schema 确定性重建它，请运行 npm run seed（见下文 数据库）。
SHOP_DB_PATH 是可选的；默认值是当前工作目录下的 shop.db。源码中没有任何位置硬编码绝对路径。
服务器仅通过 stdio 执行 MCP 通信——没有 HTTP 服务器，也没有其他需要运行的东西。
两个客户端的配置示例见 config/：
config/claude-code.mcp.json——将其复制到项目的 .mcp.json 中，或使用其中的 shop-analytics 条目运行 claude mcp add-json。请先为 args/env 填入绝对路径。
config/codex.mcp.toml——将 [mcp_servers.shop-analytics] 表复制到 ~/.codex/config.toml（或项目级的 .codex/config.toml），或使用该文件头部注释里的 codex mcp add 命令。
如果不想特定依赖某个具体的智能体，而想手动试验这个服务器，可以使用不依赖特定工具的 MCP Inspector：
SHOP_DB_PATH=$(pwd)/shop.db npx @modelcontextprotocol/inspector node dist/src/index.js服务器恰好暴露 8 个专门的只读工具——没有任何工具接受或执行任意 SQL。每个成功响应都是 { "data": [...], "meta": {...} }；每个错误都是一个简单、安全、人类可读的消息（不含 SQL、文件路径或堆栈跟踪），并以 isError: true 标记。
工具 | 可回答的问题 | 关键参数 |
| “显示所有表格和它们包含的内容。” | （无） |
| “有多少顾客来自德国？” |
|
| “哪个国家的顾客最多？” |
|
| “谁花的钱最多？” |
|
| “销量最高的前 5 个产品是什么？” |
|
| “按营收排名前 3 的类别是什么？” |
|
| “我们 2025 年产生了多少营收？” |
|
| “哪个顾客下的订单最多？” |
|
from/to 采用 YYYY-MM-DD 格式，定义了一个半开 UTC 区间 [from, to)；from 必须严格早于 to。所有财务和计数指标都会排除状态为 cancelled 的订单。每个工具的完整契约（确切的响应结构、并列规则）见 SPEC.md §4。
三层独立、纵深防御的机制保证数据库永远不会被修改，即使面对一个对抗性提示词，例如 “删除所有已取消的订单”：
SQLite 连接通过 readOnly: true 打开。
打开后立即设置 PRAGMA query_only = ON。
有一个 SQLite authorizer 明确拒绝对所有写/DDL 操作，例如（INSERT、UPDATE、DELETE、DROP、ALTER、CREATE、ATTACH、DETACH、事务等，并有显式拒绝事务的机制）。
此外，没有任何工具接受原始 SQL、表名或列名，所有查询都是固定的预编译语句，所有输入都经过 zod 校验，并作为绑定参数传入，从不做字符串插值。
shop.db 由 database/schema.sql 通过一个确定性的 seed 脚本生成，每次重新运行都会产生逐字节一致的数据（固定 PRNG 种子，不依赖墙钟时间）：
npm run seed # builds, then (re)writes ./shop.db from schema.sql + the seed scriptseed 脚本还会在生成时断言数据集没有歧义的排行榜（例如唯一的最佳国家、唯一的最大消费者），并且 2025 年的营收不为零——见 SPEC.md §3。
npm run build # tsc + copy database/schema.sql into dist/
npm run test:unit # business logic, in isolation, against fixture databases
npm run test:integration # spawns the built server over stdio via the MCP SDK client
npm test # both本项目以 TDD 方式构建：对每个模块，先编写失败的测试，再是工具逐项实现。集成测试套件端到端覆盖了全部 8 个验收场景、SQL 注入形态的输入、无效参数组合，并断言每次运行后数据库文件的 SHA-256 哈希值不变。
database/ schema.sql + the deterministic seed generator
src/
db.ts read-only SQLite connection (see Safety above)
errors.ts error taxonomy, safe error formatting
validation.ts zod schemas shared across tools (dates, limits, periods)
period.ts half-open period SQL clause builder
tools/ one module per tool: pure query function + types
server.ts registers all 8 tools on the MCP server
index.ts stdio entrypoint
test/
unit/ one file per module/tool, fixture-based
integration/ spawns dist/src/index.js over stdio via the MCP SDK client
config/ example client configuration (Claude Code, Codex CLI)Returns how many customers are registered in a given country (case-insensitive match, e.g. 'germany' matches 'Germany'). An unknown country is a successful result with count 0, not an error. Use this to answer questions like 'how many customers are from Germany?'.
| Name | Required | Description | Default |
|---|---|---|---|
| country | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and discloses key behaviors: case-insensitive matching and that unknown countries return 0 rather than an error. This is valuable, though it omits details like return format or potential rate limits.
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 with zero waste. The main purpose is front-loaded, followed by two crucial behavioral notes and a usage example. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-parameter tool, this is complete: it explains what it returns, how the parameter behaves, and the edge case for unknown countries. The lack of an output schema is acceptable since the return type ('count') is implied, and no nested objects or enums exist.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides only a bare string parameter with no description (0% coverage). The description adds meaning by explaining case-insensitivity and the handling of unknown countries, which goes 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 verb 'Returns' and the resource 'how many customers are registered in a given country', making the tool's purpose unambiguous. It is distinguishable from siblings like 'get_top_countries_by_customers' by focusing on a single country count rather than ranking.
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 usage context with the example 'how many customers are from Germany?' and clarifies the unknown-country behavior. However, it does not mention when to use alternatives (e.g., ranking tools) or when not to use this tool, though the clear example partially compensates.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lists every business table (customers, products, orders, order_items), their columns (name, SQLite type, nullability, primary key) and foreign key relationships. Use this first to understand what data is available before calling the other tools. Takes no parameters.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It clearly states the tool is a listing operation (read-only) and enumerates exactly what is returned (tables, columns, types, keys). It does not mention side effects, but none are plausible for a schema query; the transparency is adequate.
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 with no filler. The first sentence front-loads the core functionality and enumerates what is listed; the second gives usage priority. Every word earns its place.
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 zero parameters and no output schema, the description must fully specify both the return content and usage context. It does: lists the table names, column attributes, foreign keys, and explicitly directs to use it first. Nothing needed to call the tool correctly is omitted.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes no parameters and the schema is empty. The description explicitly says 'Takes no parameters.' Per the baseline rule for zero-parameter tools, a score of 4 is appropriate; no additional semantic explanation is needed.
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 is a specific verb-resource pairing: 'Lists every business table...' naming tables, columns, and foreign keys. It clearly differentiates from sibling tools, which are all specific analytical queries, by describing a schema-wide introspection operation.
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 instructs 'Use this first to understand what data is available before calling the other tools.' This tells the agent when to use it relative to all siblings and sets expectation of a preliminary step.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Sums revenue (quantity * unit_price) across all orders in the requested period, or the whole dataset if no bounds are given. Orders with status 'cancelled' are always excluded from this metric. A period with no matching orders is a successful zero-revenue result, not an error. Optional half-open UTC interval [from, to). Both are 'YYYY-MM-DD'. Omitting a bound leaves that side open (e.g. only 'to' means "everything before to"). 'from' must be strictly earlier than 'to' or the call is rejected. Use this to answer 'how much revenue did we generate in 2025?' (pass from='2025-01-01', to='2026-01-01').
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | ||
| from | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses cancellation exclusion, zero-revenue success behavior, half-open interval semantics, date format, optionality of each bound, and the rejection condition when 'from' is not strictly before 'to'. This is exceptionally transparent for an unannotated tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured paragraph: the core action leads, followed by exclusions, edge-case behavior, interval semantics, and an example. Every sentence adds value, and the formatting of dates and bounds is precise without 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 a simple two-parameter tool with no output schema or annotations, the description covers parameter semantics, behavioral edge cases, and a concrete use case. It omits nothing needed to call the tool correctly. The return value (a sum) is implicitly numeric, so no further clarification is required.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%; both parameters are just strings with no description. The description fully explains that both are 'YYYY-MM-DD' dates, optional, define a half-open interval, and that 'from' must precede 'to'. This adds all needed meaning, going far beyond the bare 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 states a clear action: 'Sums revenue (quantity * unit_price) across all orders in the requested period', with specifics on exclusions and interval semantics. It is distinct from siblings like 'get_top_customers_by_spend' or 'get_top_selling_products', all of which target different aggregates. The resource is unambiguous and the verb 'sums' is precise.
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 a concrete example ('Use this to answer "how much revenue did we generate in 2025?"') and explains when the tool applies (with or without bounds). It does not explicitly state when not to use it or name alternatives, but given sibling scope, no overlapping tool exists. This is clear usage context without exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Ranks product categories by revenue (sum of quantity * unit_price for their products), descending (ties broken by category name ascending). Orders with status 'cancelled' are always excluded from this metric. Defaults to the top 3 categories. Optional half-open UTC interval [from, to). Both are 'YYYY-MM-DD'. Omitting a bound leaves that side open (e.g. only 'to' means "everything before to"). 'from' must be strictly earlier than 'to' or the call is rejected. Use this to answer 'what are the top 3 product categories by revenue?'.
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | ||
| from | No | ||
| limit | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It transparently explains the metric calculation, exclusion of cancelled orders, default limit, half-open interval semantics, date format, open-bound behavior, and rejection condition. This is comprehensive and leaves little ambiguity about the tool's side effects or constraints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single dense paragraph that front-loads the core purpose and then adds necessary details like exclusion, defaults, and date semantics. Every sentence contributes essential information without repetition or fluff. It is concise yet thorough, striking an ideal balance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (3 parameters, no output schema, no nested objects), the description covers all necessary operational details: sorting order, tie-breaking, exclusion, defaults, date range behavior, and validation. An agent would have everything needed to call the tool correctly. The return format is implied by the ranking nature of the tool, so no further elaboration is required.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It fully explains the 'from' and 'to' parameters, including format, half-open semantics, and validation. For 'limit', it states 'Defaults to the top 3 categories', which strongly implies that limit controls the number of returned categories, but it does not explicitly say 'limit parameter'. Given the detailed handling of the other two parameters, this is a minor gap, hence a 4 rather than a 5.
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's function: ranking product categories by revenue with a precise formula (sum of quantity * unit_price), ordering, and tie-breaking. It also provides a concrete example use case ('top 3 product categories by revenue'). This distinguishes it from sibling tools like get_top_selling_products (which ranks products, not categories) and get_revenue_for_period (which likely returns a total, not a ranking).
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 provides a usage example: 'Use this to answer "what are the top 3 product categories by revenue?"'. It does not explicitly contrast with sibling tools or state when not to use it, but the clarity of purpose makes the intended use clear. The exclusion of cancelled orders and date range handling also give context for when this tool is appropriate, though alternatives are not mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Ranks countries by number of registered customers, descending (ties broken by country name ascending). Defaults to the single top country; pass a higher 'limit' for a top-N leaderboard. Use this to answer 'which country has the most customers?'.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses the sorting order (descending by customer count, ascending by country for ties) and the default limit behavior. This goes beyond a simple 'returns top countries' and gives specific behavioral details.
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, both essential. The first sentence states the ranking logic, the second explains the default and usage. No filler words; information is front-loaded.
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?
This is a simple tool with one optional parameter and no output schema. The description covers the ranking order, tie handling, default behavior, and a usage example. There is no missing information an agent needs to invoke it correctly.
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?
Although the schema has no descriptions (0% coverage), the description explains the 'limit' parameter explicitly: default to 1, higher limit yields a top-N leaderboard. This adds meaning beyond the schema's numeric constraints (min, max, default) and clarifies the parameter's role.
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 states the precise action: ranks countries by number of registered customers in descending order, with ties broken by country name. It also explicitly connects to a question ('which country has the most customers?'), distinguishing it from sibling tools that rank by spend or orders.
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 specifies the default behavior (returns single top country) and how to get a top-N leaderboard by passing a higher 'limit'. It gives a concrete use case ('Use this to answer...'). It does not explicitly mention alternatives or when not to use it, but the purpose is clear enough for an agent to select it appropriately.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Ranks customers by how many orders they placed, descending (ties broken by customer id ascending). Orders with status 'cancelled' are always excluded from this metric. Defaults to the single top customer; pass a higher 'limit' for a top-N leaderboard. Optional half-open UTC interval [from, to). Both are 'YYYY-MM-DD'. Omitting a bound leaves that side open (e.g. only 'to' means "everything before to"). 'from' must be strictly earlier than 'to' or the call is rejected. Use this to answer 'which customer placed the most orders?'.
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | ||
| from | No | ||
| limit | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full behavioral burden. It discloses exclusions (cancelled orders), tie-breaking (customer id ascending), default limit, half-open interval interpretation, validation (from must be earlier than to), and the effect of omitting bounds. This is exceptionally transparent.
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 detailed but every sentence adds necessary information: ranking logic, exclusions, tie-breaking, defaults, interval semantics, validation, and intended usage. It is front-loaded with the core purpose and maintains a logical flow without redundancy.
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 covers all essential aspects for correct invocation: what the tool does, how parameters behave, edge cases, and validation. An agent could call this tool reliably with only the provided description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must fully explain parameters. It does: 'from' and 'to' are defined as YYYY-MM-DD with half-open interval semantics and omission behavior, and 'limit' is explained with default and purpose. This exceeds what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'ranks' with the resource 'customers by how many orders they placed', making the purpose immediately clear. It also implicitly distinguishes from siblings like get_top_customers_by_spend by specifying the metric (orders).
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 provides a use case ('which customer placed the most orders?') and explains the parameter behavior including defaults and interval semantics. It does not explicitly name alternative tools, but the unique metric and interval handling give clear context for when to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Ranks customers by total money spent (sum of quantity * unit_price across their orders), descending. Orders with status 'cancelled' are always excluded from this metric. Ties broken by customer id ascending. Defaults to the single top spender; pass a higher 'limit' for a top-N leaderboard. Optional half-open UTC interval [from, to). Both are 'YYYY-MM-DD'. Omitting a bound leaves that side open (e.g. only 'to' means "everything before to"). 'from' must be strictly earlier than 'to' or the call is rejected. Use this to answer 'who is the customer who spent the most money?'.
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | ||
| from | No | ||
| limit | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full responsibility for behavioral disclosure. It transparently covers exclusions ('cancelled' orders), tie-breaking (customer id ascending), interval semantics (half-open UTC, YYYY-MM-DD, open bounds), and rejection conditions (from must be earlier than to). This level of detail goes well beyond typical descriptions and leaves little ambiguity.
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 dense but every sentence adds essential information. It front-loads the core ranking logic, then systematically covers edge cases (exclusions, tie-breaking, defaults, intervals) and ends with a concrete usage example. There is no fluff or repetition; the structure logical and efficient.
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 description comprehensively explains behavior and parameters, but it does not specify the return format (e.g., what fields are returned for each customer). Since there is no output schema, the agent may not know if the result includes customer IDs, names, or just the spend amount. It also does not explicitly state that the interval applies to order dates, though this is reasonably inferred. These minor gaps prevent a perfect score.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must fully compensate. It explains 'limit' with default and usage (single top spender vs top-N), and thoroughly documents 'from' and 'to' including format, inclusivity, open-bound behavior, and ordering constraints. Every parameter is meaningfully described, adding significant value beyond the raw 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 states a specific verb ('Ranks customers by total money spent'), defines the metric precisely (sum of quantity * unit_price), and clearly differentiates from the sibling get_top_customers_by_orders by focusing on spend rather than order count. It also provides a concrete usage phrase ('who is the customer who spent the most money?'), making the tool's purpose 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 gives a clear when-to-use via the example question, and explains parameter adjustments and interval semantics, but it does not explicitly contrast with sibling tools like get_top_customers_by_orders or state when NOT to use this tool. The metric distinction is implied, but not spelled out, so the agent has to infer the appropriate alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Ranks products by units sold, descending (ties broken by revenue descending, then product id ascending). Orders with status 'cancelled' are always excluded from this metric. Defaults to the top 5 products. Optional half-open UTC interval [from, to). Both are 'YYYY-MM-DD'. Omitting a bound leaves that side open (e.g. only 'to' means "everything before to"). 'from' must be strictly earlier than 'to' or the call is rejected. Use this to answer 'what are the top 5 best-selling products?'.
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | ||
| from | No | ||
| limit | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and delivers: cancelled orders are always excluded, half-open UTC interval semantics, open-bound behavior when one bound is omitted, and the from<to validation rule. This is exemplary behavioral disclosure for a read-only reporting tool.
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?
Front-loaded with the core ranking behavior, then each subsequent sentence earns its place: tie-breaking, cancellation exclusion, default, interval semantics, bounds, validation, and a usage example. No filler or redundancy.
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?
Complete for a simple tool with zero required parameters and no output schema. Covers behavior, param semantics, defaults, validation, and usage. The implied return (ranked products with units sold) is sufficient for the stated question.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, yet the description fully documents from/to: the YYYY-MM-DD format, the half-open interval, open-side behavior, and the strict ordering validation. It also states the limit default of 5. It compensates comprehensively for a schema that lacks property descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb, resource, and metric: 'Ranks products by units sold, descending'. Defines tie-breaking (revenue then product id), distinguishing it from revenue-, customer-, and country-based siblings. Ends with an explicit usage example that pins the purpose.
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 an explicit when-to-use signal: 'Use this to answer "what are the top 5 best-selling products?"'. However, it does not name alternative siblings or state when NOT to use it, leaving the differentiation to the metric description rather than an explicit exclusion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.0get_customers_by_countryget_database_schemaget_revenue_for_periodget_top_categories_by_revenueget_top_countries_by_customersget_top_customers_by_ordersget_top_customers_by_spendget_top_selling_productsScored across 8 tools
Each tool targets a distinct analytics query—schema, country customer counts, leaderboards for customers, products, categories, and revenue periods. There is no overlap; an agent can unambiguously pick the right tool for a given question.
All tool names follow the same pattern: 'get_' followed by a descriptive phrase in snake_case (e.g., get_top_selling_products, get_revenue_for_period). The naming is perfectly consistent and immediately conveys the operation and focus.
With 8 tools, the server is well-scoped for a shop analytics domain. Each tool covers a distinct business question without redundancy, and the count is in the ideal range for usability and clarity.
The set covers core analytics needs: customer demographics, top customers by spend and orders, top products and categories, revenue totals, and schema discovery. Minor gaps exist (e.g., no per-product revenue breakdown or filtering by specific customers), but the surface is largely complete for typical analytics queries.
PostgreSQL, MySQL, and SQL Server in one session. 26 read-only MCP tools for AI agents.
Safe, read-only Postgres and MySQL access for AI agents. Audit log + column-level controls.
Read-only web analytics — AI traffic, revenue, goals, funnels — with the SQL behind every number.
Query 40 databases from Claude, ChatGPT, or Cursor — on any device. Read-only, encrypted, audited.
