---
document_id: agent.for_agents
schema_version: 1
---

<!-- Generated by scripts.build_agent_guide; do not edit. -->

# MCP integration and query reference / MCP 接入与查询参考

MCP integration and query reference: connection, query rules, dataset contracts, error recovery, and credits.
MCP 接入与查询参考：接入、查询规则、数据集契约要点、错误恢复与 Credits 计费。

## Connect / 接入

Configure the Asklear MCP server, then verify with one authenticated call.
配置 Asklear MCP server，然后用一次认证调用验证接入。

```json
{
  "mcpServers": {
    "asklear": {
      "type": "http",
      "url": "<YOUR_API_BASE_URL>/mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_ASKLEAR_API_KEY>"
      }
    }
  }
}
```

- Client-specific steps / 各客户端步骤: [Getting started / 开始接入](/docs/agent/getting-started.md)

## Workflow rules / 工作流规则

- Exact reference or known fields: `query_metrics` (1 call)
  精确引用或已知字段：`query_metrics`（1 次调用）
- User-supplied brand, shop, or category name: `search_values` → `query_metrics` (2 calls)
  用户提供的品牌、店铺或品类名称：`search_values` → `query_metrics`（2 次调用）
- Multiple analyses: one bundled `query_metrics` call
  多个分析：合并为一次 `query_metrics` 调用
- Unknown dataset or capability error: discover/describe, then retry once
  数据集未知或能力错误：先 discover/describe，再重试一次

- For latest/current, send time.last_complete_months=1 separately for each dataset. A JD/Tmall cross-dataset comparison uses separate query_metrics calls, reports each resolved month from meta.resolved_query, and never assumes a shared watermark.
  当前或最新对每个 dataset 分别发送 time.last_complete_months=1。JD/Tmall 跨数据集比较使用分开的 query_metrics 调用，分别报告 meta.resolved_query 中的实际月份，不假设共用数据水位。
- For an explicit shared range, send the unchanged range separately to each dataset; do not silently crop it.
  用户明确指定公共时间范围时，将原范围分别发送给每个数据集，不得静默裁剪。
- Explain data_range_unavailable to the user. Do not crop, substitute months, zero-fill, or silently omit unavailable data; this is a range error, not a 503 capability failure.
  向用户解释 data_range_unavailable；不得裁剪、替换月份、补零或静默省略不可用数据。这是范围错误，不是 503 能力不可用。
- Declared metrics, groupable dimensions, filters, and sorting compose freely; recipes are examples, not allowlists.
  契约声明的指标、可分组维度、筛选和排序可自由组合；recipe 是示例，不是白名单。
- group_by is the exact result grain; include month for trends and entity identity fields for shop or product results.
  group_by 即实际结果粒度；趋势包含 month，店铺或商品结果包含实体身份字段。

- Full decision routes / 完整决策路径: [Developer workflow / 开发者工作流](/docs/agent/workflow.md)

## Dataset contracts / 数据集契约要点

Each dataset entry below states the public contract; authenticated runtime access is environment and tenant scoped.
下面每个数据集条目说明公开契约；运行时访问以认证后的环境和租户状态为准。

### Douyin / 抖音 → Douyin Monthly Product Sales / 抖音商品月度销量明细表 → `dataset=douyin`

- `dataset=douyin` · time grain / 时间粒度 `month` · [full contract / 完整契约](/docs/agent/datasets/douyin.md)
- Metrics / 指标: `gmv`, `units`, `asp`
- Filter fields / 可筛选字段: `product_id`, `shop_id`, `brand`, `category_l1`, `category_l2`, `category_l3`, `category_l4`, `shop`
- Data is partitioned by calendar month; product detail supports daily queries within a month range. / 数据按自然月分区；商品明细支持在月份范围内按日查询
- Product filtering supports exact product_id only; names, aliases, product URLs, and fuzzy search are not supported. / 商品筛选仅支持精确 product_id，不支持名称、别名、商品链接或模糊搜索
- Shops accept an exact shop_id or a shop name aligned with search_values. / 店铺可使用精确 shop_id 或经 search_values 对齐后的店铺名
- Reviews, traffic, inventory, causal explanations, and other platform data are not provided. / 不提供评价、流量、库存、因果解释或其他平台数据
- YoY, MoM, share, contribution, and cross-period set differences are computed by the Agent from atomic query results. / 同比、环比、份额、贡献度和跨期集合差异由 Agent 基于原子查询结果计算
- Metric definitions, coverage volume, refresh timing, and access entitlement are pending upstream confirmation. / 指标口径、覆盖量级、更新时间和访问授权仍待上游确认
- The current release contains only the first four days of 2026-06 and is incomplete. / 当前仅含 2026-06 前四天数据，数据不完整

### JD / 京东 → JD Monthly Product Sales / 京东商品月度销量明细表 → `dataset=jd`

- `dataset=jd` · time grain / 时间粒度 `month` · [full contract / 完整契约](/docs/agent/datasets/jd.md)
- Metrics / 指标: `gmv`, `units`, `asp`
- Filter fields / 可筛选字段: `product_id`, `shop_id`, `brand`, `category_l1`, `category_l2`, `category_l3`, `shop`
- Only monthly-grain data is available. / 仅支持月粒度数据
- Products require an exact product_id or a standard item.jd.com URL; names, aliases, fuzzy search, and short links are unsupported. / 商品仅支持精确 product_id 或标准 item.jd.com 商品链接，不支持名称、别名、模糊搜索或短链
- Shops accept an exact shop_id, a standard mall.jd.com URL, or an exact shop name resolved with search_values. / 店铺可使用精确 shop_id、标准 mall.jd.com 链接或经 search_values 对齐后的店铺名
- Reviews, traffic, inventory, causal explanations, and other platforms are not provided. / 不提供评价、流量、库存、因果解释或其他平台数据
- YoY, MoM, share, contribution, and cross-period set differences must be computed by the Agent from atomic query results. / 同比、环比、份额、贡献度和跨期集合差异由 Agent 基于原子查询结果计算

### PDD / 拼多多 → PDD Monthly Product Sales / 拼多多商品月度销量明细表 → `dataset=pdd`

- `dataset=pdd` · time grain / 时间粒度 `month` · [full contract / 完整契约](/docs/agent/datasets/pdd.md)
- Metrics / 指标: `gmv`, `units`, `asp`
- Filter fields / 可筛选字段: `product_id`, `shop_id`, `brand`, `category_l1`, `category_l2`, `category_l3`, `shop`
- Only monthly data is supported. / 仅支持月粒度数据
- Product filtering supports exact product_id only; names, aliases, and fuzzy search are not supported. / 商品筛选仅支持精确 product_id，不支持名称、别名或模糊搜索
- Shops accept an exact shop_id or a shop name aligned with search_values. / 店铺可使用精确 shop_id 或经 search_values 对齐后的店铺名
- Reviews, traffic, inventory, causal explanations, and other platform data are not provided. / 不提供评价、流量、库存、因果解释或其他平台数据
- YoY, MoM, share, contribution, and cross-period set differences are computed by the Agent from atomic query results. / 同比、环比、份额、贡献度和跨期集合差异由 Agent 基于原子查询结果计算
- Metric definitions, coverage volume, refresh timing, and access entitlement are pending upstream confirmation. / 指标口径、覆盖量级、更新时间和访问授权仍待上游确认
- The current release contains only a single 2026-06 month. / 当前仅含 2026-06 单月数据

### Tmall / 天猫 → Tmall Monthly Product Sales / 天猫商品月度销量明细表 → `dataset=tmall`

- `dataset=tmall` · time grain / 时间粒度 `month` · [full contract / 完整契约](/docs/agent/datasets/tmall.md)
- Metrics / 指标: `gmv`, `units`, `asp`
- Filter fields / 可筛选字段: `product_id`, `shop_id`, `brand`, `category_l1`, `category_l2`, `category_l3`, `shop`, `is_live`, `has_bybt`, `bc_type`
- Only monthly-grain data is available; 2026-06 is the first published waterline, not a subscription start month. / 仅支持月粒度数据；2026-06 是首发水位，不是订阅起始月份
- Products and shops require exact IDs or confirmed HTTPS Taobao links. / 商品和店铺只支持精确 ID 或已确认的 HTTPS 淘宝链接格式
- NULL and empty strings consistently mean unknown, not no. / NULL 和空字符串统一表示未知，不等同于否

## Error recovery / 错误恢复

Read the `.md` URL in `error.documentation.url` and follow its Agent action; failed requests are not charged.
读取 `error.documentation.url` 指向的 `.md`，按其中的 Agent 动作恢复；失败请求不扣费。

- `retry`: [billing_unavailable](/docs/agent/errors/billing_unavailable.md), [concurrency_limited](/docs/agent/errors/concurrency_limited.md), [idempotency_failed](/docs/agent/errors/idempotency_failed.md), [idempotency_in_progress](/docs/agent/errors/idempotency_in_progress.md), [pricing_snapshot_mismatch](/docs/agent/errors/pricing_snapshot_mismatch.md), [pricing_unavailable](/docs/agent/errors/pricing_unavailable.md), [query_queue_full](/docs/agent/errors/query_queue_full.md), [query_queue_timeout](/docs/agent/errors/query_queue_timeout.md), [rate_limited](/docs/agent/errors/rate_limited.md), [task_not_supported](/docs/agent/errors/task_not_supported.md), [upstream_busy](/docs/agent/errors/upstream_busy.md)
- `narrow_query`: [cap_exceeded](/docs/agent/errors/cap_exceeded.md), [data_range_unavailable](/docs/agent/errors/data_range_unavailable.md), [invalid_query](/docs/agent/errors/invalid_query.md), [query_too_broad](/docs/agent/errors/query_too_broad.md), [unknown_field](/docs/agent/errors/unknown_field.md)
- `ask_user`: [approval_stale](/docs/agent/errors/approval_stale.md), [dictionary_unavailable](/docs/agent/errors/dictionary_unavailable.md), [invalid_reference](/docs/agent/errors/invalid_reference.md), [max_credits_required](/docs/agent/errors/max_credits_required.md)
- `stop`: [download_cap_exceeded](/docs/agent/errors/download_cap_exceeded.md), [forbidden](/docs/agent/errors/forbidden.md), [idempotency_conflict](/docs/agent/errors/idempotency_conflict.md), [idempotency_replay](/docs/agent/errors/idempotency_replay.md), [insufficient_credits](/docs/agent/errors/insufficient_credits.md), [not_found](/docs/agent/errors/not_found.md), [pricing_unconfigured](/docs/agent/errors/pricing_unconfigured.md), [unauthorized](/docs/agent/errors/unauthorized.md), [value_search_unsupported](/docs/agent/errors/value_search_unsupported.md)

## Credits · Cost and approval / 费用与确认

- Require explicit approval only when approval_required=true, meaning the upper bound exceeds the access key's approval_threshold_credits (default 200 Credits).
  仅当 approval_required=true，即费用上界超过访问密钥的 approval_threshold_credits（默认 200 Credits）时，才要求用户明确同意。
- Present upper_bound_credits as the maximum charge; actual Credits follow the execution result.
  将 upper_bound_credits 表述为最多消耗；实际 Credits 以执行结果为准。
- For completed paid operations, use charged_credits as the actual debit and balance_after.available as the spendable balance shown by Dashboard. credits and priced_credits are the calculated price; when billing_mode=shadow, charged_credits is zero and the wallet is unchanged. balance_after.total is the gross wallet before reserved and refund_holds are removed.
  付费操作完成后，以 charged_credits 作为实际扣点，以 balance_after.available 作为与 Dashboard 一致的可用余额。credits 与 priced_credits 表示计算价格；billing_mode=shadow 时 charged_credits 为 0，钱包不扣减。balance_after.total 是尚未扣除 reserved 和 refund_holds 的钱包总额。
- When approval is required, bind execution to the server-provided upper bound with max_credits; retry without approval whenever analytical parameters change.
  需要同意时，使用 max_credits 绑定服务端返回的上界；任何分析参数变化后都要不带确认重新请求。
- The scan implementation is server-selected; use returned plan metadata as the execution fact.
  扫描实现由服务端选择；以返回的计划元数据作为执行事实。
- Treat insufficient credits, cap rejection, denied access, and unsupported capability as terminal results.
  余额不足、预算上限拒绝、权限拒绝和能力不支持属于终止结果。

Current credit pricing / 当前生效价格:

- [JD Monthly Product Sales / 京东商品月度销量明细表](/api/public/credit-pricing?dataset=jd&format=markdown)
- [Tmall Monthly Product Sales / 天猫商品月度销量明细表](/api/public/credit-pricing?dataset=tmall&format=markdown)
- Douyin Monthly Product Sales / 抖音商品月度销量明细表: no public pricing is listed here; runtime pricing and query entitlement are returned only for authenticated available datasets.
- PDD Monthly Product Sales / 拼多多商品月度销量明细表: no public pricing is listed here; runtime pricing and query entitlement are returned only for authenticated available datasets.

## Common pitfalls / 常见陷阱

- Every Asklear business tool call must carry a valid task_query; a missing or invalid one is rejected with task_query_required or invalid_task_query and does not execute. Fix the task_query following the error hint, then retry with the original request parameters.
  每次 Asklear 业务工具调用都必须携带有效 task_query；缺失或无效会被 task_query_required 或 invalid_task_query 拒绝且不执行。按错误 hint 修正 task_query 后，使用原请求参数重试。
- JD and Tmall data watermarks are independent. A cross-dataset comparison must use separate query_metrics calls per dataset and report each dataset's actual resolved month from meta.resolved_query; never assume a shared watermark.
  JD 与 Tmall 的数据水位相互独立。跨数据集比较必须对每个数据集分开调用 query_metrics，并分别报告 meta.resolved_query 中各自的实际月份；不得假设共用数据水位。
- data_range_unavailable is a range error, not a 503 capability failure. Explain the unavailable months to the user instead of retrying; do not crop, substitute months, zero-fill, or silently omit unavailable data.
  data_range_unavailable 是范围错误，不是 503 能力不可用，不要当故障重试；应向用户解释不可用月份，不得裁剪、替换月份、补零或静默省略不可用数据。
- On approval_required, present upper_bound_credits as the maximum charge; actual Credits follow the execution result. After the user approves, retry the identical request once with max_credits and approved_plan_digest set from the returned plan_digest.
  收到 approval_required 时，将费用上界 upper_bound_credits 表述为最多消耗，实际 Credits 以执行结果为准。用户同意后，使用 max_credits，并把返回的 plan_digest 赋给 approved_plan_digest，对完全相同的请求重试一次。
- For dataset=tmall, 2026-06 is the first published coverage month (the initial watermark), not the subscription start month; do not present it as when the tenant's subscription began.
  对 dataset=tmall，2026-06 是首发数据水位（首个已发布覆盖月份），不是订阅起始月份；不要把它解释成租户订阅的开始时间。
- When you are unsure which exact rule, filter name, dataset limit, or error recovery applies, call the read-only `docs` tool in-session instead of guessing. It ships the same content as the developer docs site, is free, records no Usage, and runs no dataset query.
  不确定具体规则、字段名、数据集限制或错误恢复方式时，先在会话内调用只读 `docs` 工具查文档，不要靠猜。它与开发者文档站同源，免费、不计入 Usage、也不触发数据集查询。

## Output policy / 输出纪律

- Lead with the business conclusion in the user's language; include API fields or implementation details only when they help the user act.
  先用用户语言给出业务结论；API 字段名和实现细节只在有助于用户行动时说明。
- State the resolved time window and business scope, including when the result covers all available categories rather than one named category.
  说明服务端实际解析的时间范围和业务范围；未限定品类时，要明确结果覆盖全部可用类目。
- State the data coverage and metric definitions returned by the API.
  说明 API 返回的数据覆盖范围和指标口径。
- Distinguish server-returned metrics from Agent-computed results.
  区分服务端返回指标与 Agent 计算结果。
- Use only the currency, unit, precision, and scale returned by the dataset contract.
  币种、单位、精度和数量级以数据集契约返回值为准。
- Explain user-relevant limitations, approvals, or ambiguities without narrating routine discovery and retries.
  说明与用户有关的限制、授权或歧义，省略例行工具发现和内部重试。
- Keep API keys confined to MCP authentication.
  API Key 仅用于 MCP 认证。

## Client configuration template / 客户端配置模板

Copy this template into your client to configure Asklear MCP and verify the first query.
把这份模板放入客户端，完成 Asklear MCP 配置并验证第一次查询。

```text
Integrate the Asklear MCP data service for me, then run a first verified
query. Follow these steps in order:

1. Fetch <YOUR_DASHBOARD_ORIGIN>/docs/agent/llms.txt from the Asklear docs
   site to get the index of all Asklear agent documentation, and fetch any
   linked .md page you need while you work. <YOUR_DASHBOARD_ORIGIN> is the
   Asklear dashboard origin, which may differ from the MCP origin below.
2. Ask me for my business scenario and my target dataset:
   jd (JD), tmall (Tmall), or both.
3. Generate the MCP configuration (mcp.json) for my coding agent client,
   with my values filled into this template:

{
  "mcpServers": {
    "asklear": {
      "type": "http",
      "url": "<YOUR_API_BASE_URL>/mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_ASKLEAR_API_KEY>"
      }
    }
  }
}

4. Accept the integration only after one authenticated connection_status
   call succeeds, and show me its result.
5. Run the first query with query_metrics on my target dataset, then report
   the business conclusion and the resolved month from meta.resolved_query.
```