Skip to main content
Glama
systemsomicslab

ms-data-parser

dataset_export_differential

Idempotent

Exports a selected differential analysis result to a single InChIKey-annotated TSV for downstream pathway analysis, applying curation filters by default and rejecting stale results.

Instructions

指定した差次的結果を InChIKey 付きの 1 ファイルへ書き出す。

先に dataset_preprocess → dataset_differential を実行しておくこと。 出力は arf_export_differential と同一の契約(15 列 + contract_version メタ行)なので、下流のパスウェイ解析にそのまま渡せる。

apply_curation(既定 true): curation_submit で wrong を付けたスポットを 同定なしとして扱い、出力から外す。フラグがあればメタ行 # curation = ... で 適用状況を宣言する。フラグが無ければ出力は変わらない。成功 payload の curation は {state, wrong_excluded, suspect, orphaned}(arf_export_differential と 同じ形)。assign(curation_submit の候補付け)は同定を置き換え(name_source / inchikey_source = curation)、redundant は除外する。どちらかがあれば curation に assigned と redundant_excluded が足される。 フラグ記録に読めない行があれば書き出さずに CURATION_FLAGS_INVALID。

result_id: 書き出す結果を名指しする(省略時は直近の差次的結果)。 前処理をやり直した後の古い結果は書き出しません(STALE_ANALYSIS_RESULT)。 古い数字に現在の前処理条件のラベルが付いた TSV は、どちらも正しく見えて ずれが分からなくなります。

InChIKey は DatasetState.feature_metadata から取る(mzTab-M の database_identifier / InChI / SMILES 由来。.arf2 との結合は不要)。 濃縮解析の背景を保つため、有意な行だけでなく InChIKey が付いた全行を出す。 ontology と msi_level は mzTab-M に対応物が無いため空欄で、その旨をメタ行に 書く(空欄を「該当なし」と読み違えさせない)。メタ行には result_id と preprocess_id も入るので、あとから「どの計算の出力か」を辿れる。

Input Schema

NameRequiredDescriptionDefault
result_idNo
output_pathYes
apply_curationNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.3/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Goes far beyond the annotations: documents the 15-column + contract_version meta-row output contract, the exact `curation` payload shape, error codes (CURATION_FLAGS_INVALID, STALE_ANALYSIS_RESULT), that all InChIKey-bearing rows are emitted rather than only significant ones, and that ontology/msi_level are deliberately blank with a meta-row note. Annotations (readOnlyHint=false, idempotent=true) are consistent with this file-write behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose, then prerequisites, then output contract, then parameters — a sensible order. Most content earns its place, but the rationale sentence about mismatched TSVs and the parenthetical about mzTab-M field origins are wordier than needed for an agent to act.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, yet the description specifies the return contract and error paths in detail, plus the metadata provenance (result_id/preprocess_id in meta rows). For a three-parameter export tool with mutation behavior, nothing material is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must carry the load and largely does: result_id gets default behavior ('most recent') plus stale-result rejection, and apply_curation gets default true, exclusion semantics, and downstream payload effects. output_path is only implied by '書き出す...1 ファイルへ' and is never named as a parameter or described as a path format.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource: writing a specified differential result to a single file with InChIKeys. The prerequisite chain (dataset_preprocess → dataset_differential) and the reference to arf_export_differential's contract make the tool's role in the dataset_* family clear, though it never explicitly says 'use arf_export_differential instead when working with .arf input'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit precondition (run dataset_preprocess then dataset_differential first) and an explicit exclusion (stale results after re-preprocessing are not exported, raising STALE_ANALYSIS_RESULT). It does not name an alternative tool with a routing rule, so it stops short of a 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.