先搜再查
覆盖全目录的标准流程是两步：search_datasets用自然语言找数据集——例如搜「国会议员交易」「short interest」「IV rank」「期权资金流」。返回匹配的 command id、参数说明，需要响应结构时提高detail档位。dataset_query按 command id + 参数执行——例如{ "command": "congress.recent_trades" }。
search_datasets，但直接先搜索省一轮往返。
Dealer GEX snapshot/history 与 Heatmap snapshot 可用直达工具一步到位；Dealer Heatmap history 仍通过下面的检索执行流程调用。
查询期权最新报价
先用search_datasets 查找 options.quote / options.quotes，参数与响应见最新报价。
将以下对象作为 dataset_query 的参数；批量 contracts 是逗号分隔的字符串，不是数组：
quoted_at，不要仅凭响应成功就称它为当前可成交价格。 报价时间的含义见数据新鲜度。
批量要检查 unavailable：只对可恢复的失败合约按提示退避重试，保留已成功结果，避免整批重复计费。not_found / response_too_large 不应原样自动重试，见逐项处理。
处理 202（数据准备中）
部分按需准备数据的 command 首次查询冷门标的时，dataset_query 会返回普通结果文本（不是错误）说明数据正在准备、几秒后重试。这是设计行为：agent 应按提示等待后重试同一调用，通常一两轮内命中。不要把它当失败放弃。期权最新报价不走这个 202 流程。机制说明见数据新鲜度。
控制响应体积
dealer_gex_snapshot固定最多返回五个产品可见节点；dealer_heatmap_snapshot固定为每个到期日正 Top 10 + 负 Top 10，不接受format参数，也不返回完整网格。- 查询 Heatmap 历史时，通过
dataset_query调用derived.dealer_heatmap_history，并提供一个expiration；每页最多 24 个五分钟采样点。 dataset_query对超大结果会返回可自纠的错误文案（如何收窄查询）；按提示降低limit、缩短时间范围即可。options.chain_snapshot与options.contract_volume_profile可以把返回的next_cursor原样交给下一次dataset_query，逐页读取完整集合；每一页分别计一次 weight。- Flow 的列表与 bucket 都是有界结果。看到
truncated=true时，应明确告诉用户源窗口已经达到上限，不要把最后一页误报为完整全集。 - Dealer GEX / Heatmap 历史省略
from时只覆盖最近三个 NYSE 交易时段；其它历史类查询仍应让 agent 明确给出时间范围。
配额意识
- 会话开头用
discover_datasets自检一次（免费），拿到剩余配额与可用能力。 - 计量数据调用成功返回时扣额度，包括缓存命中；报价按成功返回的合约数计。目录搜索、
202响应、参数错误不扣额度；后续重试成功仍计费（见配额与限流）。