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

Adds significant context beyond readOnlyHint: it runs offline, returns only the first max_rows from the file start without intensity/MSI ordering, and reports total/remaining counts in the header row. It also discloses the conservative MSI evaluation due to missing MS/MS flags and accurate mass error, including has_msms=False and UNKNOWN band.

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

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

Front-loads the purpose, then uses a bolded caveat to highlight the most important limitation. Dense but every sentence is relevant; minor verbosity from the Japanese prose but no wasted sections.

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

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

Adequately complete for a read-only, no-output-schema tool: it explains the return format (TSV with header counts), pagination limits, ordering caveats, and MSI confidence limits. The main gap is the missing explanation of file_path and whether it is required for meaningful use.

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

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 parameter meaning. It thoroughly explains max_rows pagination and ordering semantics, but says nothing about file_path beyond the schema's type, leaving one of two parameters unexplained.

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

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

States a specific verb and resource: normalizing manual/auto-resolved ARF2 spot annotations to GOSLIN, RefMet/LIPID MAPS IDs, and MSI levels, returning a TSV table offline. It also names sibling tools (arf_parser, arf2_parser, verify_peak_annotation), making the tool distinguishable without opening schemas.

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

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

Explicitly routes filtering to arf_parser(annotation_keyword=...) or arf2_parser overview, and higher-confidence MSI evaluation to verify_peak_annotation. It does not state a direct 'use this when' condition for the tool itself, but the alternatives and caveats give clear context.

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

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

The readOnlyHint annotation covers safety and the description is consistent with it, while adding real behavioral context beyond the annotations: the file contains no per-sample intensity data, so multivariate analysis is impossible, and the return is a metadata summary. It does not describe output shape or failure modes for unreadable paths, which keeps it from a 5.

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

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

Three short sentences, each earning its place: what it does, what it cannot do, and when to reach for it. The capability statement is front-loaded and there is no filler.

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

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

With no output schema, the description must say something about returns, and it does (dataset overview/metadata summary). Combined with the explicit limitation warning, an agent has enough to call it correctly; only the null/unset file_path case is unaddressed.

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

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

There is one parameter (file_path) with 0% schema description coverage, so the description must carry the burden. It does imply the path must point to a specific .arf2 MS-DIAL catalogue file, which is meaningful, but it never explicitly ties this constraint to the file_path argument or discusses optionality (the param is not required and defaults to null).

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

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

The description names a specific verb (解析し…要約して返します) and resource (.arf2 file, MS-DIAL全体カタログ), and states what the output is: dataset overview metadata. It does not explicitly distinguish itself from the similarly-named sibling arf_parser, which an agent would likely confuse it with, so it falls short of a 5.

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

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

It gives a positive use case (把握するために使用します for overall quality and annotation status) and an explicit when-not: PCA and other multivariate analyses cannot be done with this file. It stops short of naming the alternative tool (e.g. arf_pca_* / arf_parser), so routing between siblings is still partly left to inference.

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

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

Annotations only declare readOnlyHint=true, so the description carries most of the load and does so well: it discloses the hard prerequisite and that violation produces an error rather than a silent fallback, and that overlapping Class ID resolution between the two groups is an error. It also justifies the log_transform default (intensity is approximately log-normal, raw-scale t-tests violate normality). It does not describe the shape of the returned results, which is the remaining gap.

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

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

The output is front-loaded with the core action, then prerequisite, then parameter semantics as a bullet list. The explanation of why ANOVA is blocked is slightly verbose but earns its place by preventing an agent from improvising a multi-group comparison. Minor redundancy between the multi-group paragraph and the group_a/group_b bullet.

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

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

Given five parameters at 0% schema coverage, no output schema, and only a readOnly annotation, the description covers the stateful prerequisite, the error paths, and the non-obvious pooling syntax. It is nearly complete, falling short only on the two filter thresholds and on what the result set contains.

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

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

Schema description coverage is 0%, so the description must compensate, and it does thoroughly for group_a/group_b (full Class ID like `24M_GF_F`, factor-token pooling such as `group_a="24M", group_b="9w"`, AND-composition of multiple tokens, error on identical Class IDs) and for log_transform (default True, log2(x+1) space, log2FC becomes a difference of group means in log space). However, q_threshold and log2fc_threshold — two of five parameters — receive no explanation at all, leaving the coverage incomplete.

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

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

The opening sentence names a specific verb and resource — two-group differential analysis with Welch t-test plus log2FC — computed on the preprocessed matrix. It is clearly distinguishable from sibling tools such as arf_preprocess (upstream) and arf_plot_volcano / arf_export_differential (downstream consumers).

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

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

It gives an explicit prerequisite (arf_preprocess must have produced session_state.session.arf.feature_matrix, otherwise it errors with no implicit fallback), an explicit exclusion (multi-group ANOVA is unsupported, with the reason it cannot be derived safely from MS-DIAL metadata), and an explicit workaround for 3+ groups (pool two groups via factor tokens). That is when-to-use, when-not-to-use, and an alternative in one place.

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

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

Adds substantial behavior beyond the readOnlyHint annotation: state is held in the session, filtered_features itself is untouched so mode=remove/clear restores it, and unmatched specifications go to unmatched_samples rather than aborting. This resolves what would otherwise look like a readOnly-versus-mutation tension by clarifying only session state changes.

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

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

Front-loads purpose and the non-destructive guarantee, then a prerequisite line, then a clean per-argument breakdown. Slightly long, but nearly every clause adds actionable detail; only marginal trimming would be possible.

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

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

No output schema exists, so the description proactively names the relevant return fields (resolved_samples, unmatched_samples) and the four modes, giving an agent everything needed to call and interpret the result correctly.

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

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

Schema description coverage is 0%, so the description carries the full burden, and it does: exclude_samples token syntax (`"ILG_6h"` resolves across Class ID and sample names), exclude_spots as MasterAlignmentID ints, and all four mode values with their meanings. This is far beyond what the bare schema conveys.

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

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

States a specific verb pair (manual exclusion/re-inclusion) against a specific resource (PCA outlier samples or named peaks), and qualifies the operation as reversible and non-destructive up front. An agent understands immediately this is a curated edit to analysis exclusions, not a data mutation.

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

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

Explicitly states the prerequisite (run arf_parser first) and where the exclusion propagates (re-runs of arf_parser / arf_preprocess → arf_pca_preprocessed / arf_differential). It does not name an alternative tool for the same job, so it stops short of full when-to-use-vs-alternative guidance.

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

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

Far exceeds the annotations (which only say idempotent, non-destructive, non-read-only): it explains what apply_curation removes (wrong-marked spots treated as unidentified), that meta rows declare '# curation = ...', the exact success payload fields {state, wrong_excluded, suspect, orphaned} plus assigned/redundant_excluded, and that unreadable flag lines cause an error rather than silent loss. This is rich, specific behavioral disclosure.

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

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

Front-loads purpose and prerequisites well, but the curation paragraph is dense and trails into payload-field enumeration that could be tightened. Most sentences earn their place, though the structure is not maximally lean.

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

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

With no output schema, the description compensates by documenting the return payload and warning behavior. Combined with prerequisite and join semantics, an agent has everything needed to call it correctly.

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

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

Schema coverage is 0%, so the description must carry parameter meaning; it does this thoroughly for apply_curation (default true, exclusion behavior, no-op when no flags, assign/redundant handling). output_path is left uncharacterized (overwrite behavior, directory creation) but is self-evident from its name and required status.

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

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

States a specific verb and resource: writes differential results into a single file with InChIKey (spec §6.1), and clarifies it emits all rows with InChIKey, not only significant ones. It does not name distinguishing alternatives such as arf_export_evidence_bundle or dataset_export_differential, so an agent must infer the choice.

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

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

Explicitly states the prerequisite ordering: run arf_preprocess → arf_differential first, and that identification data is joined from the sibling .arf2 via MasterAlignmentID. No exclusions or comparison against sibling export tools are given, so it stops short of full when/when-not guidance.

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

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

Annotations already declare write (readOnly=false), idempotent, and non-destructive; the description's 'v1 is not modified' reinforces non-destructiveness but adds little new. It does not say whether an existing v2 bundle is overwritten, nor what apply_curation does or why it defaults to true, leaving curation behavior opaque.

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

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

Two short sentences with the purpose front-loaded and no filler. Efficient, though the second sentence is a behavioral caveat rather than actionable guidance.

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

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

For a write/export tool with two undocumented parameters, no output schema, and a curation toggle that changes results, the description is too thin. It omits parameter semantics, overwrite behavior, and when to prefer this export over its near-identical sibling.

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

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

Schema description coverage is 0%, so the description must compensate for both parameters. It never mentions output_dir or apply_curation, leaving the meaning and effect of the curation flag entirely undocumented.

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

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

States a specific verb (出力する/export) and resource (全特徴量と出典別候補を massbank-context 用 v2 バンドル). It partially distinguishes itself by naming the v2 bundle format and noting v1 is untouched, but it does not explicitly differentiate from the very similar sibling dataset_export_evidence_bundle.

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

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

The only guidance is 'existing v1 is not modified', which describes behavior, not when to choose this tool over dataset_export_evidence_bundle or arf_export_differential. There is no when-to-use or when-not-to-use statement.

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

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

With readOnlyHint=true already covering the safety profile, the description adds real value: the vocabulary is returned even when `.mddata` is absent, and it warns that token positions shift when a value splits into two tokens (G_uralensis) so positions must not be used for specification. That is a non-obvious behavioral caveat an agent would otherwise get wrong.

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

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

Purpose is front-loaded in the first line, followed by discovery usage, return structure, and a caveat, in that order. Every sentence carries information; the token-position warning is dense but necessary rather than padding.

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

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

There is no output schema, so the description carries the burden of explaining returns, and it does so by naming the sample_token_vocabulary.tokens fields. Combined with the offline-availability note and the positional caveat, an agent has enough to call it correctly; only concrete field types/shape detail is left implicit.

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

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

Zero parameters, so the baseline is 4. The description goes further by describing the shape of entries under sample_token_vocabulary.tokens (occurrence count, role breakdown, position within sample names), which tells the agent how to interpret the returned vocabulary it will feed into other tools' parameters.

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

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

The first sentence states a specific verb and resource: returns factor tokens usable for filtering/grouping, covering both Class IDs and sample names. Siblings like arf_list_tags and arf_list_sample_roles list different vocabularies, and this description's scoping to filtering/grouping factors makes the distinction clear without opening the schema.

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

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

It explicitly positions itself as the entry point for discovering what can be written into class_ids / group_levels / group_factors / group_a / group_b, which is concrete when-to-use guidance. It does not name a when-not condition or an alternative sibling, keeping it just 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.

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

Beyond the readOnlyHint annotation, it discloses the return format (TSV), the exact column set, and an important data-quality caveat: `batch` is inferred from an 8-digit date in the filename because MS-DIAL lacks a dedicated field, with `batch_source` hoisted into the header row. That caveat is exactly the kind of context annotations cannot carry; it only lacks notes on failure modes (e.g., no ARF loaded).

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

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

Purpose and the pre-processing-check framing are front-loaded in the first sentence, with column and derivation details following. Slightly dense but every sentence carries information an agent would otherwise have to discover by running the tool.

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

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

No output schema exists, so the description must describe returns — and it does, listing all six columns and the header-level `batch_source`. Complete enough to call and interpret; only preconditions (a loaded ARF must exist) are left implicit.

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

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

Zero parameters, so the baseline is 4. The description still adds value by explaining the default semantics of the emitted `group` column (full Class ID when group_levels is unspecified), which preempts confusion about output rather than input.

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

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

States a specific verb and resource: classify samples of a loaded ARF into sample/qc/blank and return a TSV table, with the columns enumerated. An agent can tell this is a read-only role-listing tool rather than an analysis tool like arf_pca_preprocessed, though it never names the sibling listers (arf_list_tags, arf_list_classes) it sits beside.

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

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

「前処理の適用前確認」 gives a clear trigger condition — run this to confirm sample roles before applying preprocessing. There is no explicit when-not guidance or named alternative for other listing needs, 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.

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

readOnlyHint=true already declares the safety profile, so the description only needs added context. It contributes the scope limitation (only the currently loaded dataset), but says nothing about what happens with no dataset loaded or what a 'tag' record contains.

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

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

A single sentence with no filler, and the scope constraint is front-loaded. Nothing to trim and nothing important buried.

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

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

For a zero-param read-only list tool this is close to adequate, but with no output schema the return shape (what fields a 'tag' has, whether an empty list is possible) is entirely undocumented, and the description doesn't compensate.

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

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

The tool takes zero parameters, so the baseline is 4 and no parameter explanation is required. The description correctly signals the only input-state dependency: which dataset is 'currently loaded'.

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

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

The description names a specific verb and resource ('List MS-DIAL tags') and scopes it to 'the currently loaded ARF dataset'. The resource qualifier distinguishes it from siblings like arf_list_classes and arf_list_sample_roles, though it never names them explicitly.

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

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

'For the currently loaded ARF dataset' implies the prerequisite that a dataset must already be loaded (e.g., via arf_parser), but neither the condition nor any alternative among the many arf_* siblings is stated. Usage is only inferable.

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

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

Annotations only declare readOnlyHint=true, and the description adds real behavior beyond that: session-level file caching (no re-parse), the interaction with manual exclusions, the shape of the return value (Markdown summary with top positive/negative loadings plus JSON for score plots), and the caveat that subset selections break global normalization. That is a lot of genuine context for a read-only tool.

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

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

Purpose and the key alternative come first, then a parameter inventory; length is proportional to 20 arguments and no bullet is pure filler. It is dense rather than padded, though the class_ids/group_factors examples and the TIC caveat could be tightened slightly.

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

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

For a read-only, 20-parameter analysis tool with no output schema, the description covers inputs, caching, exclusion interaction, return contents, and downstream implications (re-running preprocessing after spot selection changes). An agent has what it needs to call this correctly.

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

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

Schema coverage is 0% and there are 20 parameters, so the description must carry the load — and it does, documenting defaults and edge semantics for nearly every argument: annotation_keyword vs ontologies (PC matching LPC), class_ids token AND/OR resolution across Class ID and sample name, group_factors vs group_levels precedence, and include_roles defaulting to sample-only. This is well beyond a restatement of the schema.

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

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

States a concrete verb chain (load .arf, apply filters, run PCA) and declares itself the single entry point for PCA on the raw spot matrix. It also explicitly separates itself from arf_pca_preprocessed, which handles the preprocessed matrix, so an agent can route between the two without opening schemas.

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

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

Gives explicit when-to-use rules: re-call with different arguments to redo PCA (noting the file is session-cached), and use arf_preprocess → arf_pca_preprocessed for normalized/QC'd matrices. It also notes arf_exclude changes are applied before PCA and warns about TIC normalization on subsets.

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

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

Annotations already declare readOnlyHint=true, and nothing in the description contradicts that (it is a computation over an existing matrix). Beyond annotations it adds real behavioral context: preprocessing is not repeated on re-execution when only grouping or log transform changes. It stops short of describing return contents or component defaults.

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

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

Front-loads the core purpose and the sibling distinction before the detail, which is the right ordering. Some sentences (the group_factors explanation) are dense and line-wrapped, but each carries information rather than filler.

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

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

Covers the workflow position, the alternative path, and the grouping mechanics thoroughly, which is the main complexity for this tool. However, with no output schema and no annotation coverage beyond readOnlyHint, an agent still lacks guidance on what components does, what top_features (default 10) controls, or what the call returns — meaningful gaps for a 5-parameter analysis tool.

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

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

Schema coverage is 0% and there are 5 parameters, so the description must compensate. It does well on grouping — group_levels is one factor, group_factors is a product of factor axes with a concrete example ([['control','ILG'],['0h','6h']] → 'control|0h') and a note that tokens resolve from both Class ID and sample name — but components and top_features are never mentioned, leaving two parameters undocumented anywhere.

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

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

States a specific verb+resource (PCA on the matrix produced by arf_preprocess) and explicitly frames itself as the entry point of the preprocessed route. It also names the distinct sibling path (arf_parser) that re-filters raw spots, so an agent can tell the two apart without reading either schema.

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

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

Gives the exact call order (arf_preprocess → this tool) and the condition that selects the alternative arf_parser (PCA that refilters raw spots). It also states when NOT to redo preprocessing — if only group_levels coloring or log transform changes, just re-run this tool.

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

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

Goes well beyond readOnlyHint=true: it discloses that low_reliability_samples are excluded from the fit and only projected (rendered hollow), the exact normalization and log10(x+1) + autoscale pipeline, dropping of zero-variance species, the orient_by sign convention, that loadings are persisted to the session for plot_pca_loadings(source="species") and figures saved via save_figure(kind="pca", source="species"), plus the error envelope {"status": "error", "message": ...} for fewer than 3 usable samples.

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

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

The lead sentence states the action and return, then bullets front-load the sample-set and preprocessing semantics before the persistence/output notes. Dense but each bullet carries decision-relevant information; the parenthetical normalization explanation is the only slightly verbose stretch.

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

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

For a 12-parameter tool with no output schema and no schema descriptions, the description covers the computation pipeline, figure/payload return modes, cross-tool side effects, and the error shape. The remaining gap is the handful of boolean filter parameters (require_msms, apply_curation, exclude_auto_likely_wrong) whose effect on the input sample/feature set is never stated.

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

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

Schema description coverage is 0% across 12 parameters, so the description must carry the load. It explains the non-obvious ones well (normalize, log_transform, orient_by, low_reliability_samples, output), but require_msms, apply_curation, exclude_auto_likely_wrong, standard_samples and title are left entirely undocumented in both schema and description.

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

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

States a specific verb+resource: run PCA on the selected molecular species (item specification/exclusion identical to arf_plot_species) and return a score plot. It anchors the item-selection convention to a named sibling, which makes the input intent unambiguous. It does not, however, distinguish itself from the other PCA siblings (arf_pca_preprocessed, dataset_pca).

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

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

Usage is implied rather than routed: the description explains that items/groups follow the same convention as arf_plot_species and gives a conditional for normalize="total" (when comparing composition after removing sample-amount differences). There is no explicit statement of when to prefer this over arf_pca_preprocessed or dataset_pca, nor any exclusion guidance.

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

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

Annotations only declare readOnlyHint, but the description discloses the real behavior: curation defaults (apply_curation, exclude_auto_likely_wrong), that class totals drop (d7)-labeled internal standards and standard_samples-only species, that arf_exclude removals propagate, the log10 common axis and mean±SD computation, and that a failed call discards the previous figure. Error semantics ({"status": "error", "message": ...}) are stated too. This is a lot of value beyond the annotation.

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

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

The purpose sentence leads, followed by per-parameter bullets, so the doc is front-loaded and easy to scan. It is dense and mixes in edge cases like error strings and prior-figure invalidation, which are useful but slightly bloat the end of the list.

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

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

Given 10 parameters, no output schema and only a readOnly annotation, the description covers inputs, computation, exclusion rules, output mode ("image" vs the lipidmix.group_intensity.v1 payload) and failure behavior. That is sufficient for an agent to invoke it correctly without guessing.

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

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

Schema coverage is 0% and there are 10 params, so the description must carry the load, and it mostly does: items gets matching rules, '|' candidate handling, '+' summing, the 1–30 limit and N.D. fallback; groups gets the token rule with the qc/blank caveat; output, apply_curation, exclude_auto_likely_wrong, detection_limit and low_reliability_samples are all defined. title is never mentioned and ncols is only referenced via its validation constraint, leaving two params under-specified.

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

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

States a specific verb and resource: it lays out per-sample intensities of sample groups for each selected class or molecular species, one item per panel (default PNG). It also explicitly contrasts itself with arf_differential (no statistical testing) and save_figure (for getting a PNG file), so an agent can place it among the plotting siblings without opening a schema.

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

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

Gives explicit routing: '検定はしない（`arf_differential` を使う）' and 'PNG ファイルが要るときは save_figure(kind="group_intensity")', plus a clear rule that QC/blanks are only included when requested. It never differentiates itself from the nearest sibling, arf_plot_species, which is the one remaining gap.

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

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.

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.

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.

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.

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.

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.

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

Goes well beyond readOnlyHint=true: declares that it writes no file, describes server-side rendering and the image-block-plus-caption return shape, the alternative JSON payload contract (lipidmix.volcano.v1), the LIPIDMIX_PLOT_OUTPUT env override, and a token-cost warning. It also discloses the thinning rule and that counts are reported in `selection`, which is exactly the kind of behavioral caveat annotations cannot express.

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

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

Front-loaded with the core action and the prerequisite, then structured mode-by-mode. Dense but nearly every clause carries decision-relevant information; the payload-mode paragraph is long and the parenthetical "Use-LLLM's Plotly view" is incidental, keeping it just short of fully economical.

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

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 covers return shapes for both modes, the prerequisite step, the cost tradeoff, the disk-write alternative, and the deployment-level default. For a plot tool with three params and no annotations beyond read-only, nothing an agent needs in order to call it correctly or choose a mode is missing.

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

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

Schema coverage is 0%, so the description must carry the parameters, and it does explain `output` ("image" vs "payload" plus default and env override) and `max_points` (only ns points are thinned; up/down always kept; image always draws every feature). The third parameter, `title`, is never mentioned, leaving one small gap.

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

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

States a specific verb and resource ("Show the latest two-group volcano"), names the default rendering medium (PNG image), and implicitly distinguishes itself from arf_plot_species and the separate save_figure writer. An agent can tell what it produces and in what form without opening the schema.

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

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

Explicitly states the prerequisite ("Run arf_differential (two-group) first"), states a preference ("Prefer the image"), gives a rationale, and routes the disk-writing case to save_figure(kind="volcano"). When-to-use and when-to-use-something-else are both spelled out.

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

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

The description does disclose valuable behavior beyond the schema: it mutates the session and writes the result to session_state.session.feature_matrix, which downstream steps read. However, that stated session update sits in tension with the annotation readOnlyHint=true, so the agent receives conflicting signals about side effects. It also says a 'report' is returned without describing its content.

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

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

Two short sentences with no filler, and the core action is front-loaded before the downstream-dependency note. It is efficiently written, though the terseness is partly a symptom of the missing parameter and return-value detail.

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

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

For a six-parameter preprocessing tool with no output schema and no documented parameters, the description covers only the high-level purpose and the session dependency. It does not explain the recipe options, defaults, valid ranges, or what the returned report contains, leaving most of what an agent needs to call it correctly undocumented.

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

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

Six parameters exist with 0% schema description coverage and no enums, and the description mentions none of them – not props, impute, normalize, max_qc_rsd, drift_correct, or blank_min_fold. With the schema carrying no semantics and the description adding nothing, an agent cannot tell what a 'recipe' consists of or what values are legal.

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

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

The description states a specific verb and resource – applying a preprocessing recipe to an already-loaded ARF matrix – and adds the concrete effect of updating the session. It is distinguishable from siblings like arf_pca_preprocessed or dataset_preprocess by naming the preprocessing step itself, though it never explicitly differentiates itself from those near-neighbours.

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

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

Usage is only implied: the second sentence says downstream PCA/differential analyses consume session_state.session.feature_matrix after preprocessing, which hints this runs before those steps. There is no explicit 'use this when...', no statement of prerequisites (which matrix must already be loaded), and no named alternative such as dataset_preprocess.

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

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

Beyond the annotations (destructiveHint=true, idempotentHint=true, readOnlyHint=false), it discloses the crucial safety design: deletion is driven only by the analysis-job.json manifest, never by timestamp guessing, raw data such as .wiff is untouched, and jobs without a record are refused. It also explains the post-delete side effect that the job status becomes `cleaned` and why that matters to dataset_load.

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

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

The default behavior and the deletion scope are front-loaded, and the bold emphasis on exactly what gets deleted is well placed. The background paragraph on MS-DIAL Console is slightly verbose but justifies why the tool exists.

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

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

For a default-no-op destructive mutation tool with no output schema, it covers scope, refusal behavior, and status transition adequately. The remaining gap is the unresolved job_path semantics and what the returned listing actually contains.

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

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 parameter burden. It fully explains dry_run (default True = list only, False = actually delete) but says nothing about job_path, which is the key selector parameter and defaults to null, leaving the agent to infer its format and meaning.

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

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

The opening line gives a specific verb pair (list/delete) with an explicit scope: only files generated by one job, defaulting to listing. The follow-up explains the exact domain problem (MS-DIAL Console piling up timestamped alignment sets in the raw-data folder), so an agent can tell this is the targeted cleanup tool rather than a generic file remover.

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

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

It clearly states the triggering situation (repeated runs leave mixed batches and you can no longer tell which result is current) and the guardrail that only artifacts recorded in analysis-job.json are touched, with NO_JOB_OUTPUT returned for unrecorded jobs. It does not, however, point to specific sibling alternatives (e.g. job_list / console_status) for inspecting before cleaning.

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

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

Annotations already declare read-only/idempotent/non-destructive, and the description adds genuinely non-obvious behavior: the search silently expands to sibling folders and past runs, search_dirs is non-recursive, and key_params is omitted when more than 10 candidates exist to avoid bloat. These are exactly the surprises an agent needs warned about.

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

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

Front-loaded with purpose and the console_plan relationship, then a clean per-parameter block. Slightly verbose in the MS-DIAL background paragraph, but every sentence contributes context.

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

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

With no output schema, the description still names the return fields (usable, needs_polarity_conversion, key_params) and their conditional presence, which is what an agent needs to interpret results. It stops short of describing the candidate entry shape (path, filename, detection parameters), which is the remaining gap.

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

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

Schema coverage is 0%, so the description carries the full burden — and it does: dataset_root, polarity string values plus its effect on the output and on needs_polarity_conversion, omics default of 'lipidomics' with None meaning no filtering, and search_dirs' non-recursive semantics. All four parameters gain meaning beyond the bare schema.

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

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

States a specific verb and resource ('列挙します' of usable method-file candidates) and immediately scopes it against the sibling workflow ('console_plan が失敗する前に呼べます'). The explanation of where MS-DIAL param files come from makes the tool's role unmistakable versus console_method_template and console_plan.

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

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

Gives clear timing context (call before console_plan fails) and routes mismatched-polarity entries to console_method_template via the needs_polarity_conversion flag. No explicit 'do not use when' statement, but the routing guidance is actionable.

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

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

Annotations already mark it as non-destructive, idempotent, and not read-only, and the description goes well beyond that: it states that detection/alignment conditions are inherited unchanged, that the empty `Lbm file path` is always resolved, that ambiguous candidates halt with `METHOD_FILE_CHOICE_REQUIRED` rather than silently picking the newest, and how `library_mode=msp_only` rewrites library paths. That is exactly the operational context annotations cannot carry.

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

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

The critical guidance (try console_plan first) is front-loaded before any parameter detail, and each paragraph maps to a decision the caller must make. It is on the long side with heavy bold emphasis, but for a 7-parameter tool with zero schema descriptions every sentence does real work; only minor tightening is possible.

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

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

For a 7-parameter mutation tool with no output schema, the description covers purpose, prerequisites, exact mutation surface, stop conditions, and mode behavior. Remaining gaps are small: what the call returns (a path? a confirmation?) is not stated, and the `omics` parameter is undocumented.

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

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

With 0% schema description coverage the description carries the full burden, and it does so for six of seven parameters: `polarity` values ('positive'/'negative'), `based_on` being polarity-agnostic, `dataset_root` search scope, `library_mode` values and their effect, and `msp_file` usage. The `omics` parameter (default 'lipidomics') is never mentioned, leaving one gap in an otherwise thorough mapping.

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

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

The description opens with a specific verb and resource (creates a method/parameter file for the opposite polarity from existing parameters) and immediately distinguishes this from the sibling tool console_plan by framing itself as a last resort. It also scopes the change precisely (only `Ion mode` and `Searched adduct ions` are swapped), which tells an agent exactly what artifact it produces.

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

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

It gives an explicit when-not ('まず console_plan の method_file 省略を試してください') with the reason (the GUI auto-saves `<project>_param_<終了時刻>.txt` on every run), and an explicit when ('その極性で一度も処理していない場合だけ'). The alternative and the decision rule that selects it are both named, so no inference is required.

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

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

Annotations declare readOnlyHint=false, idempotentHint=false, destructiveHint=false, and the description adds real context beyond them: it writes analysis-job.json and run_dir/effective-method.txt, hardlinks into a new <folder>_<ext> directory while leaving the original untouched, and sets session.current_job_path on success. However, it never confirms or explains the non-idempotent framing (the hardlink step is described as incremental/top-up, which an agent could read as repeat-safe), leaving a mild tension with idempotentHint=false.

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

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

Front-loaded one-sentence purpose followed by a scannable per-parameter block, with no filler sentences. It is very long, but for 11 undocumented parameters at 0% schema coverage most of the length is load-bearing; a few passages (e.g. the LBM resolution chain detail) go deeper than an agent likely needs to select and call the tool.

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

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

For a non-read-only tool with no output schema and 11 undocumented parameters, the description covers prerequisites, failure codes, side effects, and the success outcome (session.current_job_path). What is thin is the shape of the returned plan object beyond the job path and the enumerated error identifiers, so an agent knows the exit paths but not the full payload.

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

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 full load, and it does: all 11 parameters are explained with defaults, accepted values, mutual exclusions (lbm_file vs library_mode='msp_only'), precedence rules, and the error each violation produces. It adds semantics the bare schema cannot, e.g. that .mdproject/.mddata are unusable and that missing LBM resolution silently yields zero identifications.

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

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

Opening line states a specific verb and artifact: builds an MS-DIAL Console execution plan and generates analysis-job.json. It is clearly distinguishable from console_run (executes) and console_method_candidates (only lists candidates), both of which are named in the body.

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

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

Extensive when-to-use guidance: method_file omission behavior with METHOD_FILE_CHOICE_REQUIRED, keep_extension handling with MIXED_RAW_FORMATS and the instruction to re-call with a choice, measure='peak_area_above_zero' stopping with UNSUPPORTED_AREA_CONSOLE, and explicit routing to console_method_candidates and console_run. Alternatives and failure exits are spelled out rather than implied.

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

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

Rich disclosure beyond the annotations: hard links instead of copies, copies only when the volumes differ, the source folder is never modified (consistent with destructiveHint=false), and MS-DIAL outputs land in the new folder. It also explains that for .d/.raw-style formats the directory tree is recreated and only inner files are linked, which an agent could not infer from any structured field.

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

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

The purpose and the motivating failure mode are front-loaded, followed by behavior and then a parameter glossary, which is a sensible order. It is on the long side with some explanatory redundancy about the wiff/wiff2 distinction, but every block is functional.

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

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

For a two-hint, no-output-schema tool the description is nearly complete: it covers behavior, safety, defaults, and valid inputs. The one gap is the return value (the created path / summary) and idempotency behavior on re-run with an existing out_dir, which is not spelled out.

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

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 all parameter meaning — and it does: dataset_root is the raw folder, keep_extension defaults to "wiff" and enumerates the 12 MS-DIAL-readable extensions, and out_dir defaults to the sibling <source>_<extension>. This is exactly the value the schema lacks.

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

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

It pairs a concrete verb (create a folder holding one measurement format) with the exact problem state it resolves (MS-DIAL's MIXED_RAW_FORMATS prompt / SCIEX .wiff vs .wiff2). No sibling tool addresses this remediation step, so the purpose is distinguishable without opening the schema.

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

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

It states the trigger condition clearly — a raw folder that would otherwise raise MIXED_RAW_FORMATS and prompt interactively — and describes handling of folder-as-sample formats (.d, .raw). It does not name exclusions or an alternative tool (e.g. console_cleanup / console_plan) when this is not the right step, 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.

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

Goes far beyond the annotations: it discloses that detach returns immediately with a worker pid (not the Console pid), that the worker also collects artifacts and finalizes the job, that execution-result.json is always written to run_dir, and that exit code 0 alone does not mean completed (partial/failed criteria are named). It also notes session.current_job_path persists after the run.

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

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

The lead sentence is front-loaded and the content is dense and necessary, but the detach section is verbose with bold emphasis and the pid/worker explanation is extended. Nearly every sentence earns its place, though the layout could be tighter.

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

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

No output schema exists, so the description must cover return semantics — it explains the returned pid, the run_dir execution-result.json artifact, the completion criteria (unique main mzTab-M, finite values in the quantification matrix, all planned inputs mapped to assays), and where to read results. Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 0%, so description carries the full burden — and it does. job_path is defined as the path to analysis-job.json with a stated default (session.current_job_path), and detach is defined behaviorally (detached worker, no wait, pid semantics) rather than just as a boolean.

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

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

States a specific verb and resource ('MS-DIAL Console を実行します') and immediately anchors it in the workflow by requiring console_plan beforehand. This makes it clearly distinguishable from console_plan, console_status, and console_cleanup.

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

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

Explicitly says console_plan must be run first, gives a concrete rule for choosing detach=True (60 samples ≈ 44 min, sync calls can be interrupted and lose artifacts), and directs to console_status or dataset_load to check results. The when/when-not conditions are spelled out.

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

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

Annotations already declare readOnlyHint=true, but the description adds substantial context beyond that: no completion or side effects occur, results are finalized independently of this call, and — critically — the default output can bury 'warnings / error' under 300+ artifact lines (5 per sample × 60 samples). That is exactly the kind of output-volume and data-shape behavior an agent cannot infer from structured fields.

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

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

Purpose and the read-only/no-finalization caveat are front-loaded, then each parameter gets a compact block. Nothing is padding — even the numeric detail (5 artifacts per sample, 60 samples) exists to justify the default, so an agent can decide correctly rather than guess.

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

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

With no output schema and zero schema coverage, the description covers the two parameters and hints at return fields (artifact_count, artifacts_by_role, warnings, error). It never enumerates the status values or the remaining top-level response fields, so an agent still has some uncertainty about what 'current status' actually contains, but nothing needed to invoke it correctly is missing.

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

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

Schema description coverage is 0%, so the description carries the full burden and does: job_path is defined as a path to analysis-job.json with a stated default (session.current_job_path), and include_artifacts gets its default, its effect (full TSV listing), the reason it is off by default (300+ rows swamping warnings/error), and the specific situation that justifies True (locating missing paths).

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

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

States a specific verb and resource ('returns the current status of a job') and immediately defines the negative scope — it only reads persisted state and does not perform completion processing. It also names the actor that does the finishing work (the detached worker started by console_run), which cleanly separates it from the sibling console_run.

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

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

It says explicitly that calling this tool is not required for results to be finalized, which prevents an agent from polling it as a necessary step, and it implies its monitoring role. It does not, however, compare itself with the other status/enumeration siblings (job_list, pipeline_status, dataset_status) or state when the agent should prefer one over another.

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

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

The readOnlyHint annotation already establishes safety, but the description adds useful behavioral detail beyond annotations: output is TSV, only the latest row per spot is included, and cleared items are excluded. It does not mention size limits, pagination, or authorization requirements, but the key filtering behavior is disclosed.

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

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

The description is two compact sentences. The key return format and filtering rule are front-loaded, followed by the column list, with no wasted text.

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

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

Because there is no output schema, the description appropriately documents the TSV columns and filtering behavior. However, it leaves the sole optional parameter unexplained and gives no routing guidance among the many curation-related siblings, so it is only minimally complete for correct invocation.

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

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

There is one optional parameter, file_path, with 0% schema description coverage, and the description never mentions it. Since schema coverage is low, the description should compensate by explaining what file_path controls, but it does not.

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

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

The description clearly states the tool returns currently valid curation decisions as TSV, with specific scope: latest row per spot and excluding cleared entries. It also names the exact columns, making the resource and output concrete. It does not explicitly distinguish itself from related siblings such as curation_view_data or curation_review, so it falls short of a 5.

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

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

The description explains what is returned but gives no explicit guidance on when to use this tool versus curation_view_data, curation_review, curation_suggest, or curation_submit. Usage is only implied by the read-only nature of the output.

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

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

Beyond the annotations (readOnly=false, idempotent=false, destructive=false) it discloses real behavior: outputs are limited to suspect-or-worse spots, capped by max_rows (default 100) with total-vs-shown counts in named fields, unknown file_ids raise an error, and EIC series/spectra are deliberately not returned. It also explains that the HTML viewer performs the Submit and writes _tags.xml. The only gap is that it never says what files/artifacts are written on disk by this call itself (e.g., the HTML path's lifecycle).

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

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

Bold section markers (prerequisite, target/scope, return values, judgment taxonomy) make it well front-loaded and skimmable. It is long, and the exhaustive enumeration of likely_wrong/suspect codes (polarity_mismatch, precursor_unmatched, dmz_out, class_rule_rejected, adduct_isomer_of, etc.) is denser than strictly needed to invoke the tool, but each item is substantive rather than filler.

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

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

There is no output schema, so the description carries the return contract—and it does: TSV of suspect+ spots, ordering, named count fields (n_table_rows_total, n_table_rows_shown), per-class trend summary contents (scores, R², outlier counts), and the html_path. Combined with the workflow hand-off to curation_flags and curation_submit, an agent has everything needed to call it and interpret the result.

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

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

Schema description coverage is 0%, so the prose must carry all semantics; it explains file_ids (only IDs present as .arf rows, else error), max_rows (default 100, heavy-first ordering), ontology ("PG" class filter), name_contains (partial name match), and thresholds (with concrete defaults ppm_pass=5, ppm_borderline=10, drt_pass=0.5). However file_path and max_traces are never mentioned, leaving two of seven parameters undocumented anywhere.

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

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

The opening sentence names a specific action and artifact: it builds a review table of annotated spots containing EIC, mirror plot, Δppm, ΔRT, RT–m/z trend and machine discrimination. It also clearly separates this from curation_suggest/curation_submit/curation_flags by describing the review-and-submit workflow, so an agent can identify the tool without opening the schema.

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

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

It states the prerequisite explicitly ('先に library_load', recommending the *_Loaded.msp2.dbs), explains the default scope versus the ontology/name_contains filters, and gives the exact fallback condition for hitting curation_submit (pasted Copy text / submit.via == "copy"). It also says where to verify submitted results (curation_flags), so the when/how of use is fully prescribed.

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

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

The description goes well beyond the annotations by explaining append-only recording, atomic validation, review lookup order, backup behavior, post-recording _tags.xml reflection, and failure semantics. It also warns that an open MS-DIAL project can overwrite changes and tells the caller to relay tags_xml.note to the user. This is fully consistent with destructiveHint=true and readOnlyHint=false.

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

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

The description is front-loaded with the core action and every section appears to earn its place. It is dense and long, but that length is largely justified by the tool's complexity; minor improvements in formatting could make it easier to scan.

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

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

Given five parameters, 0% schema descriptions, no output schema, and a destructive mutation, the description is complete: it covers input forms, validation, review lookup, persistence, tags_xml output fields, and the MS-DIAL overwrite caveat. An agent has enough information to call it correctly and warn the user appropriately.

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

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 burden, and it does: it defines the flags structure, allowed flag values, candidate fields, source values ('user' vs 'llm'), and the roles of review_id, file_path, and submission_text. It adds substantial meaning well beyond the bare schema.

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

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

The description clearly states that this tool records curation flags in an append-only manner, including the two submission modes (pasted text vs. direct flags). The purpose is highly specific, though it does not explicitly distinguish itself from sibling curation tools such as curation_flags or curation_suggest.

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

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

It provides strong usage context: pass the pasted 'CURATION_SUBMIT' text directly, use review_id and flags for direct submission, and use separate flag schemas for candidate assignment. It also explicitly says not to call without user consent and explains atomic error behavior, but it does not name alternative tools or explain when to prefer them.

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

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

注釈は readOnlyHint=false 等を提供するが、説明はそれを超えて候補の生成元（MS-DIAL 下位候補・緩和再検索・同位体/アダクト説明）、極性矛盾や |Δm/z|≥10 mDa の除外、非典型アダクト等の順位低下、脂質規則未評価の注意、戻り値形式（TSV・件数・html_path）と送信フローまで開示している。

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

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

長めだが「対象」「候補」「戻り値」と段落が分かれ、前提条件が冒頭に置かれている。太字で重要制約（先に library_load と curation_review、同意なき submit 禁止）が目立つ。やや情報量は多いが無駄な文は少ない。

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

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

出力スキーマはないが、戻り値の形（1 スポット 1 行 TSV・件数・html_path）とビューア送信という後続フロー、脂質規則未評価の注意まで説明されており、複雑な 11 パラメータツールとして必要な情報はほぼ揃う。

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

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

schema の description カバレッジが 0% で 11 パラメータあるうち、wrong・unannotated・include_decided・review_id・max_rows については説明が意味を補っている。一方 top_n・file_path・rt_window・thresholds・relation_min_r・relation_mz_tol は説明も schema も沈黙しており、補完は不十分。

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

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

「間違いになったスポットと未注釈スポットに注釈候補を並べる」と動詞＋対象を具体的に述べ、curation_review や curation_submit との役割の違いも文脈から明確。何をするツールか一目で分かる。

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

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

「先に library_load と curation_review」という前提条件、wrong/unannotated の使い分け、判断済みスポットの扱い、ビューア送信と curation_submit への引き渡し条件、同意なき submit 禁止まで明示されており、いつ使うか・どう進めるかが具体的。

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

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

readOnlyHint=true is consistent with a return-only tool. Beyond the annotations, the description discloses two non-obvious behaviors: results are paginated ('ページ単位') and the tool is restricted to the MCP Apps viewer context. It doesn't describe the shape of the returned spots or paging limits.

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

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

Three short sentences, no waste. The viewer-only restriction is front-loaded before the functional description, so the most important constraint is seen first.

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

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

For a viewer-facing data feed with two simple parameters, no output schema, and a readOnly annotation, the description covers role, exclusion, and pagination. The one remaining gap is what a spot record contains and any page-size limits, which is minor given the tool isn't meant for LLM invocation.

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

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

Schema description coverage is 0%, so the description must compensate. 'ページ単位で返す' conveys the meaning of the page parameter, but review_id is only implied by '保存済みレビュー' with no format or scoping detail. Partial compensation, so it is only adequate.

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

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

The description gives a specific verb and resource: it returns ('返す') saved review spots ('保存済みレビューのスポット') page by page. It clearly frames the tool as the data provider for the MCP Apps viewer. It stops short of naming a sibling, but the viewer-only framing already does the differentiating work.

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

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

It states an explicit exclusion: viewer-only, and 'LLM は呼ばない' (the LLM must not call this). That is a clear, actionable negative guideline far beyond what most definitions offer. It doesn't say what an agent should call instead for review data, which keeps it from a 5.

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

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

Annotations only supply readOnlyHint, so the description carries most of the burden and does so well: it discloses that validation rules are shared with the pipeline, that a missing feature-to-internal-standard mapping aborts with `missing_state` rather than producing a fake ratio matrix, and that `filter.min_detection_rate` silently no-ops with `not_evaluable` recorded in `history`. It also states values are held in session rather than returned. Not a full 5 because repeat-call/overwrite behavior for an existing `recipe_id` is unstated.

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

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

The artifact and its source are front-loaded in the first sentence, then parameters, then failure modes are grouped into labeled blocks, which reads efficiently. The bulleted caveats each carry distinct information, though the recipe paragraph is denser than necessary.

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

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

With no output schema, the description correctly covers the return contract (values stay in session, only `matrix_id` is handed off to `dataset_statistic`) and both known failure paths. What an agent needs to call it correctly is essentially present; only the shape of the returned object and idempotency of re-calling with the same `recipe_id` are missing.

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

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

Schema coverage is 0% and `recipe` is an untyped object with additionalProperties, so the description must compensate, and it does: it enumerates the five recipe keys and states that under- or over-specified recipes are rejected outright. It also clarifies the subtle `recipe_id` versus derived `matrix_id` distinction. It does not document the value domains of the individual recipe keys, keeping it below 5.

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

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

The first line gives a specific verb and resource: build exactly one v2 analysis matrix (analysis-matrix.v1) from the session's DatasetState. It also distinguishes the artifact from pipeline-produced matrices by noting the deterministic matrix_id allows cross-matching. It stops short of naming a sibling to use instead, so it is clear but not fully differentiated.

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

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

It states the recipe must match one element of the profile's `matrix_recipes` (five keys, extra/missing rejected), which implies the context of use, and it routes the agent onward by saying to pass `matrix_id` to `dataset_statistic`. However, it never says explicitly when to use this standalone tool versus `pipeline_run` or `dataset_preprocess`, leaving the choice to inference.

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

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

Despite annotations only providing readOnlyHint=true, the description discloses critical non-obvious behavior: full results and volcano points are NOT returned but stored in session.dataset.last_differential, with export handled by dataset_export_differential. It also notes that samples missing from the preprocessed matrix or flagged as QC/blank are excluded and named in a caveat, which is essential behavioral context for interpreting results.

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

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

The description is front-loaded with the core action, then follows with parameter meanings and a bolded directionality note. It is appropriately detailed for a 7-parameter tool but slightly dense; every sentence earns its place, though the structure could be marginally tighter by grouping the label parameters.

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

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

With no output schema, 0% schema coverage, and 7 parameters, the description does a strong job covering the essential execution context, parameter semantics, session storage behavior, and export routing. The only gap is the undocumented group_a_label/group_b_label parameters, which are minor but leave a small incompleteness for a tool of this complexity.

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

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

Schema description coverage is 0%, so the description carries the full burden. It explains the defaults and semantics of q_threshold (BH-FDR significance level, default 0.05), log2fc_threshold (absolute value threshold for significance, default 1.0), and log_transform (log2(x+1) space, with rationale that MS intensities are near log-normal). It also critically clarifies the directionality: positive log2FC means group_b is higher, with group_a as baseline. However, group_a_label and group_b_label (2 of 7 parameters) are not mentioned at all.

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

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

The description opens with a specific verb and resource: 'Execute differential analysis (Welch t-test + BH-FDR) on 2 groups using a preprocessed DatasetState'. This clearly distinguishes the tool from siblings like dataset_export_differential (export) and dataset_status (inspection). An agent can immediately understand the purpose without opening the schema.

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

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

The description states a clear prerequisite (preprocessed DatasetState) and explicitly tells the agent how to find valid sample names ('check usable names and roles in dataset_status's `samples` TSV'). It also names the alternative for exporting results (dataset_export_differential). However, it does not explicitly state when NOT to use this tool versus siblings like arf_differential or dataset_statistic.

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

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.

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.

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.

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.

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.

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.

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

Annotations already declare this as a non-read-only, idempotent, non-destructive write operation. The description adds useful behavior about retaining name-only candidates in the bundle, but it does not explain overwrite behavior, where files land, or how apply_curation affects the output.

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

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

The description is two compact sentences with the main action front-loaded. It is appropriately terse, though that terseness contributes to missing operational details.

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

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

For a three-parameter export tool with no output schema and no parameter descriptions, the definition is too sparse. It omits output structure, curation behavior, and how this export relates to sibling export tools.

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

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

Schema description coverage is 0%, so the description must compensate, but it only indirectly implies result_id via 'specified two-group results'. It says nothing about output_dir or apply_curation, leaving two of three parameters unexplained.

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

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

The description names a specific verb and resource: exporting all features and candidates from specified two-group results into a v2 evidence bundle. It is clear what the tool does, but it does not explicitly distinguish itself from closely related siblings such as arf_export_evidence_bundle or dataset_export_differential.

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

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

It does not state when to use this tool instead of dataset_export_differential or the arf-prefixed evidence-bundle export. There are no exclusions, prerequisites, or alternative-selection guidance beyond the implied export context.

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

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

readOnlyHint already covers the safety profile, but the description adds substantial behavioral detail beyond it: qualification ordering (adduct tiers, sme_match → sml_match → unannotated), the rule that exactly one qualified candidate is required and that intensity/ppm/RT proximity are NOT used for selection, polarity resolution order with rule.polarity_source, and the rule_hash normalization caveat. Recording these in the description rather than annotations means non-DB-reading agents cannot rely on them, and the two modes' error/omission behavior (notes, missing_state) is fully described, so 4 rather than higher.

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

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

It is long, but the length buys real information: purpose first, then the two modes under bold headings, then parameter notes. A few clauses (recomputing rule_hash, display-rounding of theoretical m/z) are dense but justified because they prevent a specific misuse; nothing is pure filler.

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

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

There is no output schema, yet the description specifies return shapes in detail: features TSV columns with the evidence enum, targets/candidates/rule with rule_hash, and stats TSV columns with status semantics (not_in_matrix/not_testable are not 'no difference'), detected_* definition, and results containing bh_population plus caveat. It even points to a docs resource for field meanings, which is all an agent needs to call and interpret this tool.

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

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

Schema coverage is 0%, so the description carries the whole burden and does: it defines feature_ids as SMF_ID exact match (with empty-list semantics), min/max mz and rt as inclusive AND bounds, max_results default 20 with truncation in notes, result_ids as differential groups with defaults and staleness handling, and the nested `targets` object field-by-field including required fields, inchikey 14-char prefix matching, ppm default 10 and rt_tol_min default 0.3.

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

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

States a specific verb and resource (search features in DatasetState, rule-based judgment against target compounds) and immediately declares the read-only nature. The two operating modes are named and separated, so an agent can tell it apart from siblings like dataset_statistic or library_match_feature without opening the schema.

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

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

Explicitly states that mode selection is driven by the presence of `targets`, that combining modes yields DATASET_BAD_REQUEST, and describes each mode's own preconditions (empty query → FEATURE_SEARCH_EMPTY_QUERY, >50 targets, polarity conflicts → FEATURE_TARGET_INVALID). It also says what happens when result_ids are missing or stale (missing_state).

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

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

Beyond the annotations (readOnly=false, idempotent=true), it discloses the error on exclusive parameters, the `INCOMPLETE_ANALYSIS_JOB` rejection by default, and the downstream consequence that incomplete loads are exploration-only and block `dataset_differential` and differential export. It also documents state effects (DatasetState written to session.dataset, existing arf/arf2/pai2/eic untouched) and that pipeline results are returned only when data/group fingerprints match.

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

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

The purpose is front-loaded and the parameter modes are formatted as a scannable list, so length is justified by density of real information. A few rationalizing asides (why no matrix-only entry point, why result_id is fingerprinted) could be trimmed without losing the operational instruction.

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

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

For a four-parameter state-building tool with no output schema, the description closes the important gaps: return behavior is covered by naming session.dataset and pointing to `dataset_status` for inspection, and the side-effect footprint on other session objects is stated. An agent has what it needs to call this correctly and interpret the outcome.

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

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

Schema coverage is 0% and every parameter has only a bare title, so the description must carry the load — and it does, defining what each path type points at, what `job_path` resolves via polarity/measure, and that `pipeline_path` accepts a file or its parent directory. `allow_incomplete` is given its default, the run states it accepts, and its downstream restriction.

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

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

The opening line states a specific verb and resource: read an mzTab-M 2.0 file and build the canonical DatasetState. It does not, however, distinguish itself from the very similarly named sibling `load_dataset`, leaving the agent to guess which loader to pick.

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

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

It spells out three mutually exclusive input modes, recommends `job_path` after `console_run`, and explains that `pipeline_path` is the only way to bring in matrices because mixing runs would silently misalign groups. It also states that omitting all three or passing two or more is an error, and gives explicit when-not guidance for `allow_incomplete`. The only missing routing advice is versus the `load_dataset` sibling.

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

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

Beyond readOnlyHint=true, the description discloses a real behavioral trait: full loadings are not returned but persisted in session.dataset.last_pca. It also bounds n_components by min(samples, features). The implicit session-state write alongside readOnlyHint is worth noting but is not a hard contradiction of the annotation.

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

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

Front-loaded with the action, then prerequisite, then per-parameter notes, then return-value caveat. Each line adds distinct information with no filler.

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

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

With no output schema, the description usefully explains that loadings live in session.dataset.last_pca, but it is ambiguous about what the return value itself actually contains (scores, explained variance, partial loadings). Everything needed to invoke the tool correctly is present.

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

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

Schema coverage is 0%, so the description carries the full burden, and it does: n_components gets a default and an upper bound (min of samples/features), and log_transform is defined as a log10 transform applied before standardization, which is semantics the schema cannot express.

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

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

States a specific verb and resource: run PCA on the preprocessed DatasetState. The purpose is unambiguous and the prerequisite (dataset_preprocess) anchors it in the pipeline. It does not, however, distinguish itself from similar siblings such as arf_pca_preprocessed, arf_pca_species, or plot_pca_loadings.

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

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

'dataset_preprocess を先に実行しておくこと' gives an explicit precondition, which is the key usage signal for this tool. There is no statement of when not to use it or which sibling PCA tool applies to which input format, so the guidance is clear but not complete.

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

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

The description adds substantial behavior beyond the annotations: it discloses that success writes the matrix to session.dataset.pp_matrix, that drift_correct silently degrades to a reported caveat when the mzTab-M lacks injection-sequence labels, and that min_detection_rate > 0 without imported .arf detection data raises an argument error rather than silently passing. The only tension is that this documented session-state write sits awkwardly with readOnlyHint=true, though it is disclosed rather than hidden.

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

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

Purpose is front-loaded in one sentence, followed by a compact per-parameter block and a closing statement of the side effect. Dense but every block earns its place; the parameter list is lengthy, which is justified by the 0% schema coverage.

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

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

With no output schema, the description still tells the agent where the result lands (session.dataset.pp_matrix) and which tools consume it, plus the error semantics of the riskiest parameter. It stops short of describing the tool's immediate return payload or the interplay with dataset_status's detection field beyond a pointer.

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

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

Schema description coverage is 0% and the schema exposes no enums, yet the description documents every one of the six parameters with allowed values and defaults (normalize: none/tic/median/pqn; impute: half_min/knn/column_mean/none), the meaning of blank_min_fold, the 0.0-1.0 range of min_detection_rate, and the failure mode when its prerequisite is absent. It fully compensates for the empty schema.

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

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

The opening line names a specific verb and resource: applying a preprocessing recipe to the DatasetState quantitative matrix, which is clearly distinct from the ARF/ARF2 tool families. It also names the downstream consumers (dataset_pca / dataset_differential) that read the produced matrix. Sibling differentiation is present but partly implicit — it says the arguments are identical to arf_preprocess without stating the rule that selects one over the other.

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

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

Usage is implied rather than stated: the note that dataset_pca / dataset_differential consume the preprocessed matrix tells the agent this is an upstream step, and the drift_correct paragraph explains when that option is unavailable. There is no explicit 'use this instead of arf_preprocess when …' rule and no stated prerequisites such as needing dataset_load first.

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

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

Goes well beyond the annotations by disclosing all-or-nothing validation ('no partial application'), that errors leave session.dataset untouched and can be safely resent, and the precise invalidation cascade (preprocessing-input changes kill matrices/PCA/differential; group-only changes kill only differential and preserve PCA). This is exactly the mutation-safety context an agent needs.

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

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

The core purpose is front-loaded and each substantive sentence (validation atomicity, invalidation rules, changed_fields) adds new information. The closing paragraph on resolve_comparison/run_comparison is somewhat tangential but still connects to the sibling relationship.

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

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

For a single-parameter mutation tool, the description covers validation behavior, failure semantics, invalidation consequences, and idempotency-relevant resend safety. The only gap is relying on an external spec for column meanings, which is acceptable given the tool's scope.

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

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

Only one parameter (manifest_path) with 0% schema coverage, so the description must carry the meaning. It does so by naming the manifest format (sample-manifest.v1) and the columns it expects (role/batch/injection_order/qc_pool/include/sample_id/source_file), though it defers exact type/format to an external spec doc.

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

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

States a specific verb chain (read → validate → bulk-apply) on a specific resource (sample-manifest.v1 into DatasetState), and explicitly positions itself against the dataset_differential path. An agent can tell exactly what it does and what it is not.

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

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

Explains the primary use case (correcting group/batch/injection_order/qc_pool mistakes without re-running the upstream Console) and contrasts it with calling dataset_differential directly. It gives clear context but does not enumerate explicit 'do not use when' exclusions.

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

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

Annotations only declare readOnlyHint=true; the description adds the important trait beyond that: per-feature full results are not returned but retained in the session. It also discloses numeric-contract behavior (effect size = log2 of pre-transform arithmetic mean ratio, no pseudocount, BH population limited to testable features). It does not say how the session-held results are later retrieved, nor how long they persist.

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

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

Front-loaded with the core action, then the two parameters, then the differentiators. Dense but every block earns its place; the v1 comparison paragraph is long but is the main disambiguation content. Minor redundancy with the indentation/line-break formatting that adds lines without adding meaning.

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

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

For a read-only, no-output-schema, two-parameter tool with an untyped nested object, this covers what an agent needs: what runs, which matrix it runs on, why the matrix must be explicit, how the numbers differ from v1, and where the full results go. The only residual gap is retrieval of the session-stored results, which is arguably another tool's concern.

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

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

Schema description coverage is 0% and the nested `specification` object is an open additionalProperties object, so the description carries the full burden — and it does: it names the shared keys (statistic_id / kind / transform / feature_scope) and the kind-specific keys (reference_group+test_group, groups+alpha, scaling+n_components), and ties `matrix_result_id` to `analysis-matrix.v1` artifacts produced by pipeline preprocess / qc_processed.

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

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

States a specific verb and resource with the exact statistic families enumerated (welch / anova_tukey / pca) and the scope constraint that it runs against an explicitly named analysis matrix. It also explicitly contrasts itself with the sibling dataset_differential, so an agent can pick between them without opening a schema.

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

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

Gives a concrete usage rule — never implicitly reuse the most recent preprocessing, always name the matrix_result_id, because two matrices from different recipes may coexist. It explains how this differs numerically from v1's dataset_differential, but stops short of an explicit 'use this when X, use dataset_differential when Y' routing statement.

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

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

readOnlyHint=true already tells the agent this is a safe read. The description adds non-obvious behavior beyond the annotation: the prerequisite ordering and the missing_state envelope returned on misuse, which is exactly the kind of context annotations can't convey. It stops short of describing the full DatasetState overview payload, so a 4 rather than 5.

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

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

Four short lines, each earning its place: purpose, output key, downstream consumer, and prerequisite. The prerequisite is placed where an agent will see it before calling.

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

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

There is no output schema, so the description bears return-value disclosure. It covers the `samples` field and the missing_state envelope, which is the operationally critical part, but leaves the rest of the 'overview' fields unnamed. Adequate for a zero-parameter status tool, with a small gap.

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

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

Zero parameters, so there is nothing to disambiguate and baseline is 4. The description correctly spends no words on parameters and instead documents the output shape (`samples` TSV of name/role).

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

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

States a specific verb and resource ('現在の DatasetState の概要を返す') and links to a sibling (dataset_differential) that consumes its output. It doesn't explicitly negate other sibling tools like dataset_statistic or dataset_build_matrix, but the resource (DatasetState) is distinctive enough to separate it from the cluster.

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

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

Explicit prerequisite: 'dataset_load を先に実行しておくこと', plus the failure mode (missing_state envelope) when the prerequisite is unmet. It also tells the agent exactly how to use the output in dataset_differential (group_a/group_b take names as-is). This is close to ideal when/when-not guidance.

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

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

Annotations already declare readOnlyHint=true, so safety is covered. The description adds one genuinely useful behavioral fact: no hits yield `status="not_found"`. It says nothing about which `.dcl` is used when file_path is null, nor about the shape of a successful result — and with no output schema that gap matters.

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

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

Four short sentences with the lookup target front-loaded, followed by use case, RT semantics, and the not-found sentinel. Little waste; the structure is easy to scan.

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

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

For a six-parameter tool with no schema descriptions and no output schema, the description leaves too much unspecified: tolerance parameters, the default file resolution behavior for file_path, and the successful return shape are all unaddressed.

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

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

Schema coverage is 0%: parameters carry only titles and defaults. The description explains precursor_mz and rt, but mz_tol, rt_tol, file_path, and top_n_peaks are undocumented in both schema and description — four of six parameters unexplained, so the description fails to compensate for the coverage gap.

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

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

States a specific verb+resource: look up MS/MS spectra matching a precursor m/z (optionally RT) from a `.dcl` file. This is clearly distinct from sibling dcl_parser (which parses the file) or library_match_feature, though no sibling is named explicitly.

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

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

Gives a concrete use case — verifying annotations by checking whether expected fragments actually appear — and explains that supplying RT disambiguates co-eluting peaks at the same m/z. It offers no when-not condition and never names an alternative tool such as verify_peak_annotation or pai2_inspect_peak.

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

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

With readOnlyHint=true already covering safety, the description adds real context: one `.dcl` per measurement file, `dcl_index` matches peak order in the same-named `.pai2`, and what the summary contains (acquisition rate, peak-count distribution, precursor m/z and RT ranges). It doesn't discuss file-size limits or failure behavior, so it stops short of 5.

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

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

The opening sentence states purpose and return value up front, then context, routing, and a bulleted parameter list. Dense and mostly waste-free, though the parameter bullets and the prose overlap slightly.

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

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

No output schema exists, so the description correctly describes the return shape (summary statistics + preview entries). The main omission is how `file_path` is resolved when it is null, which matters for a file-taking tool.

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

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

Schema coverage is 0%, so the description must carry the parameters, and it explains two of them well: `top_n_peaks` (default 10, 0 = keep all) and `preview` (number of MSDecResults appended to the summary). `file_path`, which is nullable, is not explained at all, leaving one gap.

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

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

States a specific verb and resource: parses a single `.dcl` (MSDecResult) and returns an MS/MS inventory summary plus the first few entries. It also names the sibling (`pai2_parser`) used for a different purpose, so an agent can tell the two apart without opening schemas.

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

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

Explicitly routes the agent: for per-peak identification confidence, use `pai2_parser` → `verify_peak_annotation`. That gives a clear alternative and condition. It lacks an explicit 'do not use this when…' statement, but the positive routing is strong.

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

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

The annotations already declare readOnlyHint=true, so the agent knows this is a safe read. The description adds that the output is a text summary, which matters because no output schema exists. However, it does not disclose file size limits, error behavior for malformed files, or what the summary contains.

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

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

Two short sentences, with the file-type scope stated first and no filler. The phrase 解析用関数 (parsing function) is slightly redundant with the tool name, but it costs little.

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

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

For a one-parameter read-only parser with no output schema, stating that the output is a text summary covers the main gap. The undefined semantics of an optional file_path defaulting to null, and the absence of any expectations about the file, remain unresolved.

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

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

Schema description coverage is 0% for the single file_path parameter, so the description must supply that meaning. It only implies that a file is involved; it does not say whether the path must be absolute or relative, or what happens when the optional, null-defaulting file_path is omitted.

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

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

The description names a specific verb (parse) and a specific resource (.EIC.aef files), and adds that the result is a text summary. That separates it from sibling plotting tools such as eic_plot_chromatograms and eic_plot_compounds, although the description does not name those alternatives explicitly.

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

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

The description says nothing about when to call this tool rather than eic_plot_chromatograms, eic_search, or the other parsers (pai2_parser, dcl_parser, arf_parser). The intended use is only implied by the file extension.

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

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

The description adds useful behavior beyond readOnlyHint=true: it returns only structured lipidmix.eic.v1 JSON, does not render images or write files, and is client-neutral. It also states a 12-trace limit for file_ids. It does not fully explain the returned JSON shape or several parameters.

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

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

The description is front-loaded with the purpose and then adds constraints in a compact, readable way. Every sentence contributes useful routing or behavioral information without unnecessary repetition.

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

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

For a read-only plotting-data tool with no output schema and low parameter description coverage, the description does well to explain output format and file behavior. However, it omits meaning for title, file_path, and especially normalize, and does not describe the structured JSON content enough for an agent to fully anticipate the response.

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

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 parameter meaning. It explains spot_id as exact and sourced from search tools, and file_ids as selecting at most 12 traces, but it does not explain title, file_path, or normalize, leaving three of five parameters undocumented.

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

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

The description states a specific verb and resource: return client-neutral plot data for selected EIC chromatograms. It clearly distinguishes this from image rendering and save_figure, but does not explicitly differentiate it from the sibling eic_plot_compounds tool.

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

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

It gives explicit usage guidance: use for structured EIC plot data, do not use for rendering or writing files, and call save_figure(kind="eic") only after an explicit PNG request. It also says spot_id normally comes from existing m/z or RT search tools and explains file_ids selection behavior.

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

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

Goes well past the readOnlyHint annotation by disclosing that no file is written, that output can be flipped deployment-wide via LIPIDMIX_PLOT_OUTPUT, and that the coordinate payload costs tens of thousands of tokens. It also exposes verification semantics (spot_id checked against RT and m/z), the pre-2023-11-20 m/z=-1 fallback with a caveat, and the dropped-with-reason list.

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

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

Front-loaded with the one-line what-it-does and the read-only guarantee, then grouped into output-format, per-sample, selection, and verification paragraphs. Dense but each paragraph carries distinct information; a few clauses (e.g. the token-cost justification) run longer than strictly necessary.

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

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

Given no output schema, the description does describe the return shape (image block plus one-line caption, or the lipidmix.eic.multi.v1 JSON) and the selection.dropped side channel. The remaining gap is the four undocumented optional parameters (title, normalize, arf2_path, file_path), which matter for an agent trying to steer the plot or point it at alternative inputs.

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

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

With 0% schema description coverage the description must carry all 9 parameters, and it explains only the load-bearing ones: file_id, names (ARF2 Name substring, case-insensitive), ontologies (exact match, unioned with names), top_n (default 8), and output (image vs payload). title, arf2_path, file_path, and normalize are left completely undocumented in both schema and description.

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

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

States a specific verb and resource ('Overlay several identified compounds' EIC traces') with a hard scope constraint ('for ONE sample'), and declares the default rendering explicitly. This distinguishes it from eic_plot_chromatograms and from cross-sample comparison work without the agent needing to open a schema.

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

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

Gives explicit routing rules: use output=image by default, use output=payload only for a client that draws its own chart, and call the tool once per sample to compare samples side by side. It also states the selection prerequisite ('At least one of them is required') and instructs the agent to read selection.dropped before concluding a compound is absent.

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

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

readOnlyHint is already declared; the description adds meaningful context beyond it — the TSV row layout, provenance of name/ontology/adduct (from .arf2) and n_msms (from .dcl), that '-' means missing or precursor mismatch rather than zero, and that out-of-range spot IDs are listed in notes. Silent on truncation behavior from max_results, which is a gap for a mutation-free but potentially large result set.

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

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

Front-loads purpose and filter semantics before diving into output columns. The column list and provenance notes are dense but justified since no output schema exists; minor density is the only knock.

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

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

Without an output schema, the description thoroughly specifies the returned row shape and the meaning of sentinel values, and provides a follow-up workflow for unannotated rows. The unexplained file_path and max_results/truncation semantics keep it short of fully complete for an 8-parameter tool.

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

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

With 0% schema coverage, the description carries the burden well: it defines broad scope and semantics for spot_ids, sort (max_intensity vs default spot_id ascending), min/max m/z, and min/max RT with boundary handling. However, file_path and max_results (a default of 20 implying truncation) are never explained, leaving 2 of 8 params undocumented in both schema and description.

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

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

States a specific verb (search), resource (EIC spots), filtering dimensions (spot ID, m/z range, RT range) and output format (TSV). An agent can immediately distinguish it from eic_parser and eic_plot_chromatograms.

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

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

Explains AND semantics, that no filters means all records, boundary-inclusive behavior, and exact-match semantics for spot_ids. Also routes unannotated but n_msms-bearing rows to library_match_feature → library_plot_mirror as a follow-up. No explicit exclusion of siblings, but context is clear.

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

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

links 指定時に本文末尾へ [[link]] を追記するという副作用を開示しており、注釈を超えた付加価値がある。ただし destructiveHint=true にもかかわらず、元ノートが _inbox から削除されるのか、既存の knowledge/ ファイルを上書きするのか、操作が取り消せるのかが述べられていない。

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

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

核心的な目的を先頭に置き、続けて claim_strength と links の補足を続ける構成で、無駄な文がない。やや簡潔すぎて、破壊的挙動に関する情報が不足している。

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

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

出力スキーマがなく破壊的変更を伴うツールであり、スキーマ側のパラメータ説明も皆無である。パラメータの意味はかなり補えているが、昇格後の状態や戻り値、上書きや削除の挙動が不明なままで、破壊的ツールとしては説明が不足している。

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

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

スキーマの説明カバレッジが 0% で enum も定義されていない中、claim_strength の取り得る値（established / suggested / speculative）と links の追記挙動を記述しており、スキーマ以上の意味を補っている。ただし必須の slug については説明がない。

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

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

「_inbox の保留ノートを knowledge/ へ昇格する」と具体的な動詞とリソースを明示し、「信頼知識化の唯一の経路」と述べて ingest_stage / ingest_reject との役割の違いを暗黙に区別している。エージェントはこの記述だけで他ツールと切り分けられる。

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

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

claim_strength の値や links を渡したときの挙動には触れているが、いつ使うべきか、代わりに ingest_stage や ingest_reject を使うのはどんな場合かは明示されていない。用途は推測できるが、除外条件や前提条件の記述はない。

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is known; the description adds which subset is affected (pending notes in _inbox). It does not say whether the note is deleted from disk or merely flagged as rejected, nor whether the action is recoverable, which matters for a destructive tool.

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

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

One short, front-loaded sentence with no filler. It is efficient rather than verbose, though the terseness leaves the under-specification problems noted in other dimensions.

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

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

For a destructive, one-parameter tool with no output schema and no parameter documentation, the description omits outcome, irreversibility, and slug provenance. An agent could invoke it but cannot predict what it will do to the note.

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

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

Schema description coverage is 0% for the single required parameter 'slug', and the description never explains what the slug identifies or where it comes from (presumably an inbox note identifier). With the schema contributing nothing, the description should have compensated but does not.

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

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

States a specific verb (破棄する / discard) and a specific resource (_inbox の保留ノート / pending notes in _inbox), so an agent knows exactly what operation it performs. It does not, however, differentiate itself from siblings like ingest_promote or ingest_review_queue, which address the same inbox objects.

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

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

There is no guidance on when to reject versus promote, stage, or send to the review queue, and no prerequisites or exclusions are stated. The agent must infer the workflow position entirely from the word 'reject'.

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

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

readOnlyHint=true already conveys safety, so the description only needs to add context. It does say the result is pending notes grouped by analysis_id×Qi, but says nothing about ordering, pagination, whether all pending notes are included, or what a group contains.

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

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

One compact sentence with the resource and grouping key front-loaded; nothing is wasted. It is slightly too terse and jargon-dense ('_inbox', 'analysis_id×Qi') for an agent unfamiliar with the domain.

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

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

No output schema exists, so explaining the return shape matters, yet the description only says 'grouped' without describing group structure or ordering. For a no-arg read tool this is minimally adequate but leaves the agent guessing at what it will receive.

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

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

Zero parameters, so the baseline of 4 applies. There are no parameter semantics to explain or compensate for.

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

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

States a specific action ('グルーピングして返す') on a specific resource ('_inbox の保留中ノート') and names the grouping key (analysis_id×Qi). An agent can tell this is a read-only pending-queue listing, distinct from mutation siblings like ingest_stage/ingest_promote/ingest_reject, though the term 'note' and composite key are not elaborated.

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

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

No guidance on when to call this versus curation_review, ingest_stage, ingest_promote, or ingest_reject. The pending-inbox context implies it precedes staging/promotion, but that workflow is left for the agent to infer.

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

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

Annotations already declare readOnlyHint=false and idempotentHint=false, so the write and non-idempotent nature is covered structurally. The description does add real behavioral context beyond them: everything lands in knowledge/_inbox as 'speculative' (i.e., isolated, not curated) and a call without a citable source is rejected. It stays silent on what happens to duplicates or whether the item then appears in ingest_review_queue.

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

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

Very short and front-loaded, with the core action in the first clause. The '出典必須' parenthetical is redundant with the later '出典なしは拒否' sentence, costing a little space for no added information.

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

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

For a 7-parameter write tool with zero schema coverage and no output schema, the description should say more: what staging produces, how it relates to ingest_promote/ingest_reject/ingest_review_queue, and how duplicate DOIs are handled (relevant given idempotentHint=false). Only the source-required rule and found_for format are covered.

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

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

Schema description coverage is 0% across 7 parameters, so the description must carry the burden. It clarifies only two: found_for is documented as '<analysis_id>/<Qi>' format and source as a citable bibliography that is rejected when absent. The remaining five (title, abstract, query, doi, relevance_score) get no semantic help at all.

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

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

The description states a specific verb and destination: quarantine candidates judged relevant into knowledge/_inbox as speculative. That distinguishes it from a general write, though it never names its close siblings ingest_promote or ingest_reject to clarify the staging stage of the workflow.

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

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

'関連と判断した候補' implies the trigger (after a relevance decision), but there is no explicit when/when-not, no mention of the alternative exit paths (ingest_promote, ingest_reject), and no statement of prerequisites beyond the mandatory source.

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

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

readOnlyHint=true already tells the agent this is a safe read. The description adds useful behavior beyond that: results are scoped to dataset_root/runs/ and sorted newest-first. It does not say what happens when no jobs exist or whether results are truncated, so the addition is real but partial.

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

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

Two short lines with the core behavior front-loaded and the parameter note second. No filler; the only quibble is that the parameter gloss could have been folded into the first sentence rather than a separate line.

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

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

This is a simple one-parameter read tool with no output schema, so the agent needs some idea of what a job entry looks like (id, status, timestamp) and whether the list is bounded. Neither is covered, leaving a modest but real gap for a listing tool.

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

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

Schema coverage is 0%, so the description must carry the parameter, and it does: dataset_root is defined as the raw-data folder path and tied to the value used in console_plan. That removes the main ambiguity for the single required parameter, though it gives no format example or path syntax.

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

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

States a specific verb and resource: returns the list of jobs under dataset_root/runs/, in newest-first order. The scope and ordering are unambiguous, though it does not name a sibling (e.g. console_status) to distinguish when this list is the right source of job information.

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

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

There is no explicit when-to-use or when-not-to-use guidance, and no mention of alternatives such as console_status or pipeline_status, which also expose job state. The only hint is that dataset_root matches what console_plan took, which implies the tool is used within a console workflow but doesn't state it.

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

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

The readOnly annotation covers safety, and the description adds meaningful behavior beyond it: deterministic baseline using character bigrams plus lipid-class vocabulary, mandatory verification of COVERED notes, and automatic-search eligibility for GAPs only. It still does not describe the return payload in detail.

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

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

The description is short, front-loaded with the core classification purpose, and each sentence adds operational information. The parenthetical method note is compact and does not distract from the main instruction.

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