Skip to main content
Glama
systemsomicslab

ms-data-parser

arf_plot_species

Read-only

Plots selected lipid classes or molecular species as one panel per species, comparing sample values by group using share or peak-height values.

Instructions

選んだクラスを分子種(アラインメントスポット)に展開し、1 分子種 1 パネルで群ごとの試料別の値を並べる。

  • items: クラス名(.arf2 の Ontology に完全一致)は配下のスポットに展開、それ以外は分子種名。 同じ名前でも付加イオンが違えば別パネル(見出しに付加イオンと ID)。1 回 40 パネルまで。

  • groups: arf_plot_group_intensity と同じトークン規則(QC・ブランクは qc / blank を書いたときだけ)。

  • value: "share"(既定。試料ごとに 高さ ÷ 分母の合計 × 100。棒 = 群平均、ひげ = SD)/ "height" (PeakHeight を log10 で。横線 = log10 の平均、ひげ = SD、0 は軸の下端)。検定はしない。

  • share_basis: 割合の分母にする項目(省略時は items)。例: PG のページでも分母は ["PG", "DGDG", "MGDG", "CL"]。分母にも同じ除外を適用する。当たらない部品があると分母が変わるので 描かずにエラー。items に当たらない部品は caveats に書く。value="height" では share_basis は無視される。

  • 除外は arf_plot_group_intensity と同じ(内部標準・standard_samples だけにある分子種・ apply_curation の判断・exclude_auto_likely_wrong・arf_exclude したスポット)。require_msms=True で MS/MS の裏付けがない分子種も除く。除いたものは payload の excluded。

  • low_reliability_samples: 白抜きで描き、平均と SD から外す。菱形は gap-filled の値。

  • output: "image"(既定)/ "payload"(lipidmix.species_intensity.v1)。PNG ファイルは save_figure(kind="species")。

  • 入力の誤りは {"status": "error", "message": ...}。失敗した呼び出しの後は前回の図を破棄する。

Input Schema

NameRequiredDescriptionDefault
itemsYes
ncolsNo
titleNo
valueNoshare
groupsYes
outputNo
share_basisNo
require_msmsNo
apply_curationNo
standard_samplesNo
low_reliability_samplesNo
exclude_auto_likely_wrongNo

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?

Despite minimal annotations (readOnlyHint=true), the description discloses substantial behavior: a 40-panel-per-call cap, the full exclusion pipeline (internal standards, standard_samples-only species, apply_curation, exclude_auto_likely_wrong, arf_exclude, require_msms), error behavior ({"status":"error"}), and that the previous figure is discarded after a failed call. This is exactly the context annotations cannot provide.

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 purpose sentence followed by terse bullets keyed to parameter names, which makes scanning efficient. Some detail (e.g., 0-on-axis-lower-bound, SD whisker rendering) is niche, but nearly every sentence carries actionable semantics for a 12-parameter tool.

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

Completeness4/5

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

Complete enough for a complex 12-param plotting tool: behavior, defaults, exclusions, and error semantics are all present, and the payload schema name (lipidmix.species_intensity.v1) is given in lieu of an output schema. Gaps are limited to ncols/title semantics and the exact payload field layout.

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?

With 0% schema description coverage the description carries the burden, and it explains items (class expansion vs literal species names), groups token rules, value enum semantics, share_basis denominator behavior (ignored when value="height"), output modes, and the exclusion-related booleans. Only ncols and title are left unexplained, which are minor layout/formatting knobs.

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

Purpose5/5

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

States a specific verb+resource: expands selected classes into molecular species (alignment spots) and produces one-panel-per-species per-group per-sample plots. It also distinguishes itself implicitly from arf_plot_group_intensity by referencing it for shared token/exclusion rules, so an agent can distinguish the two.

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

Usage Guidelines3/5

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

Usage is implied through defaults (value="share", output="image") and references to arf_plot_group_intensity for shared rules, but there is no explicit 'use this when / prefer X instead' guidance. The agent can infer this is the species-level counterpart to the group-intensity plot, but must infer it.

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