Query Guide

1. 01
   query_metrics

   Default route when the dataset, fields, and filter values are already known. Bundle compatible analyses in one request.

2. 02
   search_values

   Resolve user-supplied brand, shop, and category names that are not exact IDs, standard URLs, or raw values already returned in this conversation.

3. 03
   describe(dataset)

   Recover after a field, capability, or version error. Do not use it as routine preflight.

4. 04
   list_datasets

   Use only when the target dataset cannot be inferred from the user's question.

Rules

• Before the first business-tool call, write one concise, self-contained task_query in the user's language and reuse it verbatim for every Asklear call serving that task, including docs and recovery calls. Do not include credentials or direct personal identifiers.
• User-supplied brand, shop, and category names are inputs to align, not normalized entities. Use eq for one relevant platform raw value and in for multiple relevant values. If identity is uncertain, verify representative products instead of silently merging values.
• Treat search_values status=ambiguous or requires_clarification=true as a stop condition. Ask the user which candidate they mean; if the ambiguity is only discovered after querying, disclose the exact raw value used.
• Keep requested scope, resolved scope, entitled scope, and data watermark distinct. Never silently crop, substitute, zero-fill, or omit unavailable periods. data_range_unavailable is a range error, not a 503 capability failure.
• Compare results only after checking platform, time, filters, metrics, and group_by. A cross-dataset comparison uses a separate query_metrics call for each dataset, reports each resolved month, and never assumes a shared watermark.
• group_by is the result grain. A Top N product list is a sample, not the full market, and an ASP change does not by itself prove same-product price movement.
• Distinguish server metrics, Agent calculations, and Agent judgments. Verify important or counter-intuitive conclusions with product- or SKU-level evidence when the capability is available.

Tool boundaries

Time and scope

• For latest/current use time.last_complete_months=1 separately for each dataset; for recent N complete months use N.
• Send an explicit shared range unchanged to each dataset and report each dataset's actual resolved range and data_through.

Interpretation and validation

• Do not infer full-market conclusions from a truncated or Top N result.
• Explain metric definitions and separate composition changes from same-item changes.

Cost and recovery

• approval_required returns a maximum charge; actual debit is charged_credits after execution.
• Prefer aggregation and drill into product details only when necessary. Failed requests are not charged; do not loop on the same error.
• For query_too_broad narrow time, filters, fields, or result grain; for unknown_field read supported fields; for data_range_unavailable explain requested and available ranges.

User-visible query scope

• State dataset and platform, resolved time and watermark, aligned raw values, metric definitions, filters, group_by, and whether results are complete or Top N.
• Call out missing data, ambiguity, limitations, and any scope change; do not narrate routine internal tool calls.

Output policy

• Lead with the business conclusion in the user's language.
• State the dataset and platform, resolved time and data watermark, aligned raw values, metric definitions, filters, group_by, and whether the result is complete or Top N.
• Distinguish server metrics, Agent calculations, and Agent judgments.
• Explain relevant missing data, ambiguity, limitations, approvals, or scope changes without narrating routine tool calls.

Optional capabilities

Call examples

{
  "dataset": "jd",
  "field": "category_l3",
  "kw": "示例品类",
  "limit": 10,
  "task_query": "分析京东某品类最近一个完整月的品牌销售额排名"
}

{
  "dataset": "jd",
  "filters": [
    {
      "field": "category_l3",
      "op": "eq",
      "value": "示例品类"
    }
  ],
  "group_by": [
    "brand"
  ],
  "limit": 10,
  "metrics": [
    "gmv"
  ],
  "order_by": [
    {
      "dir": "desc",
      "field": "gmv"
    }
  ],
  "task_query": "分析京东某品类最近一个完整月的品牌销售额排名",
  "time": {
    "last_complete_months": 1
  }
}

{
  "input": {
    "output_format": "markdown",
    "urls": [
      "https://example.com/"
    ]
  },
  "task_code": "raw_html_v1",
  "task_query": "获取示例网页内容并用于当前研究任务"
}

{
  "idempotency_key": "web-research-1",
  "input": {
    "output_format": "markdown",
    "urls": [
      "https://example.com/"
    ]
  },
  "max_credits": 2,
  "quote_token": "<estimate_collection 返回的 quote_token>",
  "task_code": "raw_html_v1",
  "task_query": "获取示例网页内容并用于当前研究任务"
}

{
  "job_id": "<start_collection 返回的 job_id>",
  "task_query": "获取示例网页内容并用于当前研究任务"
}

Asynchronous collection

Retrieve fresh public information through an estimated, approved, and traceable asynchronous task.

Use collection only when its operations appear in the current tools/list response.

Workflow

1. 01
   list_collection_tasks

   Discover the task code and current entitlement.

2. 02
   estimate_collection

   Estimate the task and show upper_bound_credits plus the expected duration to the user.

3. 03
   start_collection

   After explicit approval, start with the estimate values and a new idempotency_key.

4. 04
   get_collection_job

   Poll only after poll_after_seconds and stop at succeeded or failed.