---
document_id: agent.paths.agent.reference
schema_version: 2
parent_document_id: agent.paths.agent
section: querying
---

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

# MCP tool reference / MCP 工具参考

## Read as needed / 按需查阅

当前工具名、字段和权限以 tools/list、认证 discover 和实际响应为准。明确查询直接执行；不要为读参考重复发现已知内容。

Current tool names, fields and access come from tools/list, authenticated discover and actual responses. Run clear queries directly; do not rediscover known facts just to read a reference.

没有找到方法时继续发现能力。实时能力参考用 docs(page="agent.capabilities")；具体错误用响应中的 documentation 或[错误参考](https://docs.asklear.cn/errors)。

Continue discovery when no method matches. Use docs(page="agent.capabilities") for current capability references and the returned documentation or [error reference](https://docs.asklear.cn/en/errors) for specific failures.

connection_status 仅在连接不明确时检查，不是每次查询的心跳。task_query 是任务描述，不控制语言；语言由 Accept-Language 决定。

Use connection_status only when connection is uncertain, not as a per-query heartbeat. task_query describes the task; Accept-Language controls text.

轮询遵守 poll_after_seconds，并设置等待上限；超时后保留原任务供续查，不无限等待或重建任务。

Use bounded polling with poll_after_seconds. When the wait limit is reached, preserve the original task for later reads instead of waiting indefinitely or resubmitting.

## Tasks and saved results / 任务与结果续读

审批重放、超时或响应不确定时复用同一 idempotency_key；只按 poll_after_seconds 轮询，该值是建议，不是 ETA 或 SLA。

Keep the same idempotency_key after approval, timeout, or an uncertain response. Poll only after poll_after_seconds; this value is guidance, not an ETA or SLA.

读取已保存状态或结果不会再次执行或收费；执行结果 unknown 时不得自动重采。

Reading saved status or results does not start execution or charge again. Unknown execution outcomes must not be retried automatically.

新社媒 Task 快照逐条返回核心字段：完整可用正文、作者、发表时间、互动数和身份 ID。REST、MCP 与 CLI 读取同一份已存投影，不附完整来源 JSON。相对时间和格式化计数保留来源原文，长正文沿已存结果续读；旧快照保留原有字段。

New social Task snapshots return core fields per item: complete available text, author, publication time, engagement and identifiers. REST, MCP and CLI read the same saved projection without the full source JSON. Relative time and formatted counts remain source text; long text uses saved-result continuation. Existing snapshots keep their stored fields.

结果分页和长正文按返回的 next_result_ref 在原快照续读；不要为补齐正文重做来源请求。

Continue paginated results and long text with the returned next_result_ref on the original snapshot; do not execute a new source request to recover text.

## Search and enrichment scope / 搜索与补充内容

一次社媒搜索处理一个平台。页数、详情与评论参数以该操作的发现结果为准；试查范围不等于后续全量范围。include_details 开启后，按批准范围补详情，不静默改成固定样本。

A social search handles one platform. Use the operation contract for pages, details and comments; a pilot does not cap subsequent bulk scope. With include_details enabled, enrich the approved scope instead of silently imposing a sample size.

## Identity and query boundaries / 身份与查询边界

search_values 的 ambiguous 或 requires_clarification 必须让用户选择。商品名只用于 search_products 解析身份；销量筛选用已确认的 product_id，不拿搜索候选直接当销量。

Ask the user to resolve ambiguous or requires_clarification results. Product names go to search_products for identity; sales filters use confirmed product_id values, not candidate search results.

search_values 报 query_too_broad 时，缩短关键词不改变前缀扫描量；可按报价或预算上限使用单月品牌/店铺/品类分组查找，或借代表商品定位原始值。

If search_values returns query_too_broad, shorter terms do not reduce prefix scanning. Under a quote or budget limit, use a single-month brand/shop/category grouping or representative products to identify raw values.

只请求回答问题所需指标。meta.resolved_query 与 scope_summary 是实际口径；检查 truncated，Top N 不是完整市场。汇总、增长和比例用程序计算，区分数据、计算和判断。

Request only needed metrics. meta.resolved_query and scope_summary describe executed scope; check truncated and do not treat Top N as the whole market. Compute totals, growth and ratios in code and distinguish data, calculation and judgment.

复用适用契约和成功结果，未知结果先查原任务。task_query 同一任务保持一致且不含凭据；不披露内部来源和成本。run 的预算和批准字段按工具 schema 放置，不塞进业务 input。

Reuse applicable contracts and successful results; inspect the original task for unknown outcomes. Keep task_query consistent and credential-free, do not disclose private sources or costs, and place run budget/approval fields as its schema specifies rather than inside business input.

## Query rules / 查询规则

MCP discover() 列授权平台；platform 列能力摘要；operation_id 读完整契约，不限目录大小、不混用平台/分页。目录默认20条（1–50），JSON≤8KiB；保持 platform，按实际 next_offset→offset 翻页，null结束。

MCP discover(): platforms; platform: previews; operation_id: full uncapped contract, no platform/paging. Directories: 20/page (1–50), JSON≤8KiB; keep platform, actual next_offset→offset until null.

同一任务的 Asklear 调用（含 docs/恢复）逐字复用用户语言的简洁、自包含 task_query；省略则固定非用户归因。它不是 locale，Accept-Language 控制文案；不含凭据或个人标识。

Reuse one concise, self-contained task_query verbatim in the user's language for all task calls, including docs/recovery. Omit for fixed non-user attribution. Do not use task_query as a locale; Accept-Language controls text. Exclude credentials and personal identifiers.

用户提供的品牌、店铺和品类名称是待对齐输入，不是标准实体。一个相关平台原始值使用 eq，多个相关值使用 in；无法确认是否同一实体时抽取代表商品验证，不得静默合并。

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.

search_values 返回 status=ambiguous 或 requires_clarification=true 时必须停止并让用户确认候选；若查询后才发现歧义，需明确告知实际使用的平台原始值。

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.

query_too_broad 时不缩小关键词重试 search_values：前缀通配扫描量不变。改用 query_metrics：单月按 brand/shop/category_lN 做 group_by + contains（按扫描计费，先 quote/dry_run 或设 max_credits）；或从 category_l1 逐层 group_by，已解析上层用 eq 过滤。也可用代表商品的 search_products / query_details 反查精确值。

On query_too_broad, do not retry search_values with narrower keywords: its leading-wildcard scan is unchanged. Use query_metrics for one month with group_by and contains on brand, shop or category_lN (scan-priced; quote/dry_run or set max_credits), or drill category_l1 then lower levels with resolved parent eq filters. search_products / query_details on a representative product can reverse-resolve exact values.

区分用户请求范围、实际解析范围、授权范围和数据水位；不得静默裁剪、替换月份、补零或省略不可用时间。data_range_unavailable 是范围错误，不是 503 能力故障。

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.

比较结果前核对平台、时间、筛选、指标和 group_by；跨数据集比较对每个数据集分别调用 query_metrics、报告各自实际解析月份，不假设共同水位。

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 就是结果粒度。Top N 商品是样本，不代表完整市场；ASP 变化本身不能证明同款商品涨跌价。

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.

区分服务端指标、Agent 计算和 Agent 判断；重要或反直觉结论在能力可用时应通过商品或 SKU 级证据验证。

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.

已确认范围内，精确商品 URL、ID 或已解析值直接 query_metrics；未知品牌/店铺/品类用一次 search_values 后查询。不重复解析，也不无理由增加 discovery、describe 或 quote。

For a confirmed scope, send exact product URLs, IDs or resolved values to query_metrics. Resolve an unknown brand/shop/category once with search_values, then query_metrics. Do not repeat resolved values or add discovery, describe or quote without a stated need.

商品名称/标题用 search_products 检索；多个候选让用户选择，再将选定 product_id 传给 query_metrics/query_details。search_products 不返回 GMV 或销量。

Resolve product names/titles with search_products; let the user choose among multiple candidates, then send the selected product_id to query_metrics/query_details. search_products returns no GMV or units.

已知操作复用适用契约。connection_status 免费且非心跳；只用已暴露工具。

Reuse applicable contracts for known operations. connection_status is free, not a heartbeat. Use exposed tools.

已有结果直接保存文件并校验 JSON，不查客户端缓存或重做成功调用取证；汇总/增长用程序计算，保留要求的平台、时期、榜单和口径。

Save files from existing results; validate JSON. No client cache searches or rerunning successes for evidence. Compute totals/growth with code; preserve requested platforms, periods, rankings and scope.

远程 data MCP、Collection 与本地浏览器 MCP 分开；有界轮询 get_collection_job，已有 job_id 只恢复读取，不新建任务。

Keep remote data MCP, Collection and local browser MCP separate. Poll Collection with bounded get_collection_job calls; a known job_id only resumes reads.

只请求足以回答问题的最小指标。Asklear 计费 metadata 只解释返回的口径、水位、upper_bound_credits 和 charged_credits；不得请求或转述内部来源字段或费用细节。

Request only the smallest sufficient metrics. Interpret Asklear billing metadata as the returned scope, watermark, upper_bound_credits, and charged_credits; do not request or repeat private source fields or fee details.

Native HTTP 按每项已发布的 method、path 和对应版本 input schema 调用。data 原样保留完整业务响应，包括实际提供的完整正文、嵌套字段与 null；raw、need_format 可能改变结构。实际费用读取 meta.credits_charged。离线合成示例说明结构，不代表线上可用性或价格报价；业务字段、嵌套对象、数组、标量、原始分页及 URL 全部参数与签名完整保留。历史读取只从保留回执按 business-data-v1 恢复缺失字段；meta.data_recovery_status 明确原回执缺失时无法补回。原回执与摘要不变，不重复执行或扣费。

Native HTTP follows each published method, path and version-specific input schema. Its data contains the complete unchanged business response, including available full text, nested fields and null values; raw and need_format may change that layout. Use meta.credits_charged for the actual charge. Synthetic offline examples describe structure, not live availability or a price quote. All business fields, nested objects, arrays, scalar values, source pagination and complete URL parameters/signatures are retained. Historical reads restore missing fields only from retained receipts using business-data-v1; meta.data_recovery_status explicitly reports an unavailable original receipt. Original receipts and digests remain unchanged, with no new execution or charge.

Shopee Native HTTP 原样返回业务 Data：详情商品对象、搜索数组、列表 Page/PageCount/Products 对象。完整保留全部商品、原始字段、null 和签名链接参数，内部标准化或本地筛选后的索引不替代公开响应；历史读取复用原回执，不重新采购或扣费。

Shopee Native HTTP returns the original business Data unchanged: a product object for detail, an array for search, and a Page/PageCount/Products object for list. All returned products, source fields, nulls and signed URL parameters remain intact; internal normalized or locally filtered indices do not replace the response. Saved reads reuse the original receipt without new procurement or charges.

Task 结果在 source_data 中完整保留一次原业务页，包括嵌套字段、null、签名链接和原始分页；来源成功但标准化索引没有条目时也交付原业务页，不消耗工作流实体数量额度或生成实体引用。大对象沿用已有结果分片。历史读取和 JSONL 导出从保留回执按 business-data-v1 恢复，不改原快照、回执、摘要或扣费；data_task_source_data_unavailable 明确表示原业务页无法恢复。response_schema 描述实际返回；output_schema 及其摘要保留原执行合同。

Task results include the complete original business page once as source_data, including nested fields, nulls, signed URLs and source pagination. A successful page is also delivered when its normalized index has no items; this page does not consume the workflow entity limit or create an entity reference. Use the existing result fragments for large data. Saved Task reads and JSONL exports restore business-data-v1 from retained receipts without changing the original snapshot, receipt, digest or charge; data_task_source_data_unavailable means the original business page cannot be restored. Task response_schema describes the returned response; output_schema and its digests retain the execution contract.

对已批准的 Native 列表操作，顶层 include_comments 默认关闭。确认报价后才可开启；max_comment_items 表示为多少条搜索结果各取一页一级评论，默认 20，范围 1–128。恢复沿用原范围，不会重新购买另一页评论。

For the approved Native list operations, top-level include_comments is false by default. Set it to true only after confirming the quote; max_comment_items selects how many search results receive one first-level comment page, defaults to 20, and is bounded to 1–128. Recovery keeps the original scope and does not buy another page.

Native HTTP 发布 meta.next_input 时，把非 null 的完整对象复制为下一页请求的 input，使用新的 Idempotency-Key 与预算；null 表示未提供经校验的下一页。不要用原始响应 token 替代该游标合同；没有该字段时按该操作已发布的分页参数调用。某 HTTP 版本不可用不代表可以切换版本或创建 Agent Task。

When Native HTTP publishes meta.next_input, copy its complete non-null object into the next request's input and use a new Idempotency-Key and budget; null means no validated next page is provided. Do not substitute a raw response token for that cursor contract. If the field is absent, follow that operation's published pagination inputs. An unavailable HTTP version is not permission to switch versions or create an Agent Task.

付费单项重试复用原幂等键，只恢复已有记录。bundle 非原子且拒绝 key，additional_queries/additional_searches 勿传 key；独立品类搜索使用具体 category_lN。只重试结果明确的失败项，不重放成功项或付费结果未知项。审批控制不是业务数据：run 保留原 operation/input/幂等键，max_credits/approved_plan_digest 置顶层，勿加 task_ref/plan_version；wait_seconds=0–30。

Paid single-operation retries keep the same key and recover only saved idempotency records. Bundles are non-atomic and reject keys (including additional_queries/additional_searches); use concrete category_lN for keyed category searches. Retry known failed items only, never successes or unknown paid outcomes. Approval controls are not business data: replay run with the same operation/input/key and outer max_credits/approved_plan_digest, without task_ref/plan_version; wait_seconds=0–30.

MCP 普通失败使用 isError=true。遇到 collection_external_unknown 时停止且 no automatic replay；第一次结果未知时不得仅因不确定就再次发起付费调用。遵循返回的恢复动作及其上限。

Ordinary MCP failures are isError=true. For collection_external_unknown, stop with no automatic replay; never send a second paid call just because the first outcome is unknown. Follow the returned recovery action and its bound.

天猫/京东品牌先读 docs(page="agent.cookbook.sales_analysis") 确认范围，已有适用确认直接复用。

Tmall/JD brands first read docs(page="agent.cookbook.sales_analysis") when scope is unconfirmed; reuse applicable confirmed scope.

## query_metrics / query_metrics

聚合受支持的指标和维度。

Aggregate supported metrics and dimensions.

只查询回答问题所需内容；共同范围放 common_filters，兼容分析放 additional_queries。

Query only what is needed; place shared scope in common_filters and compatible analyses in additional_queries.

以 meta.resolved_query 作为实际执行口径，以 meta.truncated 判断结果是否完整。

Treat meta.resolved_query as the executed scope and meta.truncated as the completeness signal.

使用 meta.scope_summary 向用户简洁说明实际执行口径。

Use meta.scope_summary as the concise user-visible projection of that executed scope.

## search_values / search_values

查询前对齐可搜索的平台原始值。

Align searchable platform values before filtering.

类目层级未知时使用 field=category，再使用匹配结果回显的具体字段。

Use field=category when the category level is unknown, then use the concrete field returned by the match.

精确 ID、标准 URL 和本轮已返回的原始值无需重复发现。

Do not repeat discovery for exact IDs, standard URLs, or raw values already returned in the current conversation.

status 为 ambiguous 或 requires_clarification 为 true 时停止并让用户确认，不得静默合并候选。

Stop for clarification when status is ambiguous or requires_clarification is true; never silently merge candidates.

## search_products / search_products

在查询指标前，根据商品名称或标题查找商品身份候选。

Find product identity candidates from a product name or title before a metrics query.

tools/list 或认证 discover 返回时可用；只解析商品身份。

Use tools/list or authenticated discover; returns product identities, no sales metrics.

status=ambiguous 或返回多个候选时让用户选择，不得静默代选。

Ask the user to choose when status=ambiguous or more than one candidate is returned; never choose silently.

用户选定 product_id 后，再用这个精确身份调用 query_metrics 或 query_details。

After the user selects a product_id, call query_metrics or query_details with that exact identity.

## docs / docs

检索或读取与网页同源的正式文档。

Search or read the same documentation published on the web.

不知道文档 ID 时先读取页面索引。

Use the page index first when the required document ID is unknown.

## get_pricing / get_pricing

说明当前计价规则，不用于估算某个具体请求。

Explain current pricing rules, not a request-specific estimate.

将返回内容视为同一个版本化价格快照。

Use the response as one versioned pricing snapshot.

## list_datasets / list_datasets

仅在无法判断目标数据集时使用。

Use only when the target dataset cannot be inferred.

只能选择认证调用实际返回的数据集。

Select only a dataset returned by the authenticated call.

## describe / describe

词表不明或契约出错时按需读一次。

Read missing definitions once or recover after a contract error.

以认证后返回的字段、限制、时间范围和认证状态作为运行时事实。

Treat authenticated fields, limits, time range, and certification as runtime truth.

## query_details / query_details

能力由 tools/list 或认证 discover 返回时，下钻商品字段/标题。

Drill into product fields/titles when tools/list or authenticated discover exposes it.

必须提供明确的品牌、店铺、类目、商品引用或其他受支持的窄范围。

Use an explicit brand, shop, category, product reference, or other supported narrow scope.

## export / export

tools/list 暴露 export 时，创建或继续读取用户要求的导出文件。

Create or continue a user-requested file when tools/list exposes export.

query/format/idempotency_key 创建；job_id 续查。排队/运行等待，完成保存 url；过期复用，失败不重建。

Create query/format/idempotency_key; resume job_id. Wait queued/running; save url; reuse job_id if expired; never recreate.

## Time and scope / 时间与范围

当前或最新对每个数据集分别使用 time.last_complete_months=1；近 N 个完整月使用 N。

For latest/current use time.last_complete_months=1 separately for each dataset; for recent N complete months use N.

明确的公共时间范围应原样分别发送，并报告每个数据集实际解析范围和 data_through。

Send an explicit shared range unchanged to each dataset and report each dataset's actual resolved range and data_through.

## Interpretation and validation / 解释与验证

不得从被截断或 Top N 结果推断完整市场结论。

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 / 成本与恢复

upper_bound_credits 是最多消耗；approval_required 只表示是否需要用户确认。执行后的实际扣费以 charged_credits 为准。

upper_bound_credits is the maximum charge; approval_required only decides whether user confirmation is needed. The 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.

query_too_broad 应缩短时间或收窄筛选、字段和粒度；unknown_field 应读取支持字段；data_range_unavailable 应说明请求范围和可用范围。

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.

审批 control 只包含计划、上界和同 key 重试说明，不含业务数据。使用同一 idempotency key 对获批的相同请求最多重试一次；优先恢复已知幂等记录，不得重放结果未知的付费调用。

Approval controls contain the plan, bound, and same-key retry instructions but no data. Retry the identical approved request once with the same idempotency key; recover a known idempotency record instead of replaying an unknown paid call.

bundle 是 non-atomic。collection_external_unknown 时停止且不得自动重放；有已知 job_id 就读取，没有则在新尝试前询问。

Bundles are non-atomic. For collection_external_unknown, Stop. Do not automatically replay; read a known job_id when one exists and otherwise ask before a new attempt.

## Request quotas and concurrency / 请求配额与并发

Key 自查免费，返回自身配额、Credits 配置和当日占用；endpoint 仅为已记录调用。OAuth token 与账户余额接入见 https://docs.asklear.cn/oauth。

Key usage reads own quotas, credit settings, daily charges and holds. Free; endpoint adds partial business counts. OAuth tokens and account balances: https://docs.asklear.cn/oauth.

API Key 和租户共享的所有已配置限额同时生效：RPM 为每分钟请求数，可选 RPS 为每秒请求数，每日及账期配额统计准入请求数，并发限制进行中的 HTTP/MCP 调用。异步 Task 提交在调用结束时释放 HTTP 并发，worker 容量独立管理。

Every configured API-key and shared tenant limit applies: RPM counts requests per minute, optional RPS counts requests per second, daily and billing-period quotas count accepted requests, and concurrency limits in-flight HTTP/MCP calls. Async Task submissions release HTTP concurrency when the call ends; worker capacity remains separate.

默认值来自实际订阅 SKU。管理员租户覆盖、再到 Key 覆盖可替换继承的 Key 限额，但不得超过系统硬上限；租户聚合限额仍独立生效。override 为 null 表示恢复继承，套餐默认值为 null 表示关闭该维度。管理员覆盖可在硬上限内提高套餐限额。

Defaults follow the actual subscription SKU. Admin tenant overrides and then key overrides replace inherited key values, within system caps; tenant aggregate limits still apply independently. A null override restores inheritance; a null plan default disables that dimension. Overrides may raise plan limits within system caps.

每日配额按账户 billing timezone 的自然日重置。月度配额采用当前订阅账期；无订阅账户按该时区的自然月计算。购买多个月份不代表将其合并为一个请求配额账期。

Daily quotas reset at midnight in the account billing timezone. Monthly quotas use the current subscription billing period; accounts without a subscription use the billing-timezone calendar month. Buying several months does not combine them into one request-quota period.

速率、次数或并发拒绝不消耗每日及账期请求配额；准入后即计一次请求，即使后续业务失败。请求配额独立于 Credits、钱包和价格；Provider QPS 与 worker execution permit 也各自独立。

Rate, quota and concurrency rejections consume no daily or billing-period request quota. An admitted request counts once even if later business work fails. Request quotas are separate from Credits, wallet balances and prices; provider QPS and worker execution permits also remain independent.

Dashboard 只读展示生效限额，保留真实商业套餐名，另标注管理员定制限额。请求限额仅允许管理员修改，原有 Credits 自助控制独立保留。

Dashboard shows the effective limits read-only, keeps the real commercial plan name and labels Admin customization separately. Request-limit writes require Admin access; existing Credits self-service controls are separate.

客户限额 429 使用 rate_limited 或 concurrency_limited，error.metric 为 rpm、rps、daily_quota、monthly_quota、api_key_concurrency 或 tenant_concurrency。遵守以秒为单位的 Retry-After；X-RateLimit-Limit 表示触发的限额，X-RateLimit-Remaining 为 0，X-RateLimit-Reset 为窗口结束或并发建议重试时刻的 UTC Unix 时间戳。无法确认准入时返回 503。

Customer-limit 429 responses use rate_limited or concurrency_limited. error.metric is rpm, rps, daily_quota, monthly_quota, api_key_concurrency or tenant_concurrency. Honor Retry-After in seconds. X-RateLimit-Limit identifies the exhausted limit, X-RateLimit-Remaining is zero and X-RateLimit-Reset is a UTC Unix timestamp for the window end or suggested concurrency retry time. If admission cannot be verified, the service returns 503.

## User-visible query scope / 用户可读口径

说明数据集与平台、实际时间与水位、关键平台原始值、指标定义、筛选、group_by，以及结果是全量还是 Top N。

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.

## Asynchronous collection / 异步采集

仅当当前 tools/list 返回旧 Collection 工具时才使用；已具备统一能力的 Agent 社媒任务默认不走此路径。

Use these legacy Collection tools only when they appear in the current tools/list response; they are not the default path for eligible Agent social tasks.

list_collection_tasks: 获取任务代码与当前接入权限。

list_collection_tasks: Discover the task code and current entitlement.

describe_collection_task: 两个 task_code 看起来接近时，先读你选中的那个：描述会点名与它易混的任务，examples 和 limitations 就是入参契约。免费，比估错一次便宜。

describe_collection_task: When two task codes look alike, read the one you picked: its description names the task it is confused with, and its examples and limitations are the input contract. Free, and cheaper than a rejected estimate.

estimate_collection: 估算任务并遵循 approval_required；只有需要确认时才向用户展示费用上界与预计时长。

estimate_collection: Estimate the task and obey approval_required; only show the bound and duration when approval is required.

start_collection: approval_required=false 时不传 max_credits 直接启动；否则携带获批的 max_credits。逐字复用 quote_token，并使用新的 idempotency_key。

start_collection: Start immediately without max_credits when approval_required is false; otherwise start with the approved max_credits. Reuse quote_token exactly and use a new idempotency_key.

get_collection_job: 只按 poll_after_seconds 轮询，并在 succeeded 或 failed 时停止。

get_collection_job: Poll only after poll_after_seconds and stop at succeeded or failed.

upper_bound_credits 是安全上界；成功任务按不超过该上界的实际金额结算。

upper_bound_credits is a safety ceiling; a successful task settles the actual amount within that ceiling.

失败任务释放用户 Credits 预留，不结算用户扣费。

A failed task releases the user's Credits reservation and does not settle a user charge.

相同 idempotency_key 只用于同一任务；明确新建任务时才使用新的键。

Reuse an idempotency_key only for the same task; an intentionally new task requires a new key.

遇到 collection_external_unknown 时，执行结果无法确认；本次失败任务未扣取用户 Credits，预留已释放。禁止自动重试。先读取已知任务及 credits_charged，再由用户确认是否使用新的幂等键创建新尝试。

For collection_external_unknown, the execution outcome is unconfirmed; this failed task did not charge user Credits and its reservation was released. Do not retry automatically. Read the known job and credits_charged, and ask the user before a new attempt with a new idempotency key.

用 page=agent.error.<error_code> 处理终态错误；页面不存在时回退到 page=agent.errors。

Resolve a terminal error_code with page=agent.error.<error_code>; fall back to page=agent.errors when absent.

采集权限以运行时 tools/list 为准。

Runtime tools/list is authoritative for collection access.
