Reliable Tool Context
Use this skill to build reliable tool context whenever command output will be
analyzed by the model and correctness matters. Capture once, query from
artifacts, and return compact answers without copying raw payloads into model
context.
CLI Decision Rule
Use Sift to establish reliable tool context when any of these are true:
- - Output will be consumed by the model (analysis, transformation, or follow-up
querying).
- - Pagination exists or may exist (
pagination.next.kind=="command"). - JSON schema/root confidence is low, or rows may be heterogeneous (even for
small payloads).
- - You need reproducibility, redaction discipline, or auditability.
Use direct CLI only when all of these are true:
- - Output is clearly small.
- Schema/root path is obvious.
- It is a one-off human inspection with no follow-up model reasoning.
Required workflow
- 1. Capture output as an artifact:
CODEBLOCK0
- 2. Keep only
artifact_id plus a short summary in prompt context. - Handle pagination explicitly only when present. If
pagination.next.kind=="command", continue with:
CODEBLOCK1
- 4. Query artifacts with explicit root path and compact output:
CODEBLOCK2
- 5. Resolve root path from response hints, not guesswork:
- - Current
run behavior uses canonical root path $; use $ for follow-up
code queries.
- - If
response_mode=="schema_ref" and schemas are present, use schema
root_path as the source of truth.
- - Treat
sample_item as a preview row only.
Schema discovery protocol
- - Do not use
jq '.[0]' (or equivalent "first-item" shortcuts) to infer schema
or root path. Many payloads are object-wrapped, have multiple candidate roots,
or include heterogeneous rows where first-item heuristics are misleading.
- - In Sift responses,
sample_item is emitted only when Sift can verify
consistent item shape across the resolved list. If
sample_item is absent,
inspect
schemas; for current
run captures, schema
root_path should be
$.
- - If
sample_item_text_truncated is true, treat long text fields as truncated
previews and confirm details with a focused code query.
Guardrails
- -
sift-gateway code defaults to --scope all_related; start with
--scope single for anchor-only analysis and widen scope only when needed.
- - Start with
run(data, schema, params); move to run(artifacts, schemas,
params) only when cross-artifact joins are required. - Use pure Python first; do not assume optional packages are available.
- Return aggregates or top <= 20 rows; avoid full-record dumps.
- Never paste raw captured payloads back into context.
- Do not claim completeness until
pagination.retrieval_status == COMPLETE.
可靠工具上下文
当命令输出将由模型分析且正确性至关重要时，使用此技能构建可靠工具上下文。一次性捕获，从工件中查询，并返回简洁答案，无需将原始负载复制到模型上下文中。
CLI 决策规则
当以下任一条件成立时，使用 Sift 建立可靠工具上下文：
- - 输出将由模型消费（分析、转换或后续查询）。
- 存在或可能存在分页（pagination.next.kind==command）。
- JSON 模式/根路径置信度较低，或行可能异构（即使负载较小）。
- 需要可重现性、编辑规范或可审计性。
仅当以下所有条件成立时，使用直接 CLI：
- - 输出明显较小。
- 模式/根路径明确。
- 属于一次性人工检查，无需后续模型推理。
必要工作流程
- 1. 将输出捕获为工件：
bash
sift-gateway run --json --
- 2. 在提示上下文中仅保留 artifact_id 和简短摘要。
- 仅在存在分页时显式处理分页。如果 pagination.next.kind==command，继续执行：
bash
sift-gateway run --json --continue-from id> -- params-applied>
- 4. 使用显式根路径和紧凑输出查询工件：
bash
sift-gateway code --json $ --code def run(data, schema, params): return [{id: row.get(id), status: row.get(status)} for row in data[:20]]
- 5. 从响应提示中解析根路径，而非猜测：
- - 当前 run 行为使用规范根路径 $；后续代码查询使用 $。
- 如果 responsemode==schemaref 且存在 schemas，使用模式 rootpath 作为事实来源。
- 仅将 sampleitem 视为预览行。
模式发现协议
- - 不要使用 jq .[0]（或等效的首项快捷方式）来推断模式或根路径。许多负载是对象包裹的，具有多个候选根路径，或包含异构行，其中首项启发式方法会产生误导。
- 在 Sift 响应中，仅当 Sift 能验证解析列表中一致的项目形状时才发出 sampleitem。如果 sampleitem 缺失，检查 schemas；对于当前的 run 捕获，模式 rootpath 应为 $。
- 如果 sampleitemtexttruncated 为 true，将长文本字段视为截断预览，并通过聚焦的代码查询确认详情。
防护措施
- - sift-gateway code 默认使用 --scope allrelated；从 --scope single 开始进行锚点分析，仅在需要时扩大范围。
- 从 run(data, schema, params) 开始；仅在需要跨工件连接时使用 run(artifacts, schemas, params)。
- 优先使用纯 Python；不要假设可选包可用。
- 返回聚合结果或最多 20 行；避免完整记录转储。
- 切勿将原始捕获的负载粘贴回上下文中。
- 在 pagination.retrievalstatus == COMPLETE 之前，不要声称完整性。
