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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered without the description. The description adds the analysis-scoping rule but says nothing about error behavior, layout-resolution conflicts, or what happens when required layout/standards are missing — context the schema only partially carries (e.g. strict/exit_code 6).

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 analysis taxonomy is dense and useful, and the scoping sentence earns its place. But the opening fragment is confusingly terse (it states no action), and the whole enumeration duplicates the `analysis` parameter's enum description, so a meaningful portion is redundant for an agent that has the schema.

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 an output schema present the description need not explain return values, and annotations cover safety, so what remains — orienting the agent on the six analysis families and the argument-scoping rule — is largely delivered. It falls short only on modality routing versus siblings and on failure/precondition behavior for a 22-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?

Schema description coverage is 100%, so the schema already documents all 22 parameters with enums, defaults and formulas. The description's analysis enumeration largely restates the `analysis` enum text (LLOQ/ULOQ, IC50/EC50, Z′/S/B/S/N/SSMD) rather than adding new meaning, so the baseline of 3 is correct.

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 the resource (plate-reader exports) and enumerates the six analysis modes the tool computes, so an agent can tell it is the plate-reader assay analysis tool rather than the qPCR, chromatogram, or ephys siblings. However, the opening 'Plate-reader exports, with the layout the file stores or `layout`' is a verbless fragment that never states the action ('analyse/compute') outright, and no sibling is named for contrast.

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?

'An argument that names analyses applies to those only' gives real applicability guidance, telling the agent that e.g. `curve` or `plot` are scoped to the analyses named in `analysis`, and the analysis enumeration implies which mode to pick. But there is no when-to-use/when-not guidance and no naming of alternatives like `openreadout_stats`, `openreadout_extract` or `openreadout_summarize` that an agent might otherwise reach for.

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 the safety profile (destructiveHint=true, idempotentHint=true), and the description adds real behavior beyond that: a failing file becomes a row with error rather than aborting, limit defaults to 20/max 500 with offset paging, output writes all rows and never overwrites without overwrite, and the join key is chosen from the data and reported in joins[] with unmatched rows.

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?

Dense and front-loaded: the core purpose, then joins/summarization, then inputs, then paging/output semantics. Every clause carries information, though the heavy parenthetical stacking (measure lists, option lists) makes it read as one long run-on rather than clearly separable statements.

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?

An output schema exists, so return values need not be described, and the description still covers the non-obvious output contract (rows written to file vs returned, per-file errors as rows, joins[] reporting). For a 22-parameter tool with nested `options` this is nearly complete, missing only explicit prerequisites/permissions for writing output files.

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 100%, so the schema already documents all 22 parameters in detail, including the per-measure semantics of `measure`. The description reinforces how `options` maps to sibling tools and how joins are keyed, but adds little syntax beyond what the schema provides — the baseline 3 for full coverage applies.

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+scope: 'One measure over many files as one tidy table', then names the optional join and group-summarization behaviors. It explicitly distinguishes itself from the sibling openreadout_summarize, which only regroups a previously written table, so an agent can route 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 clear input-mode guidance ('files, directories, globs or an index query') and explains that analyses (peaks, chromatogram, nmr-peaks, ...) are invoked by passing their tool arguments as options. It also names openreadout_summarize as the follow-up alternative, but never states the when-not condition versus the singular openreadout_stats/table/trace tools.

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 cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower, and the description adds real behavioral detail: the shape of findings (severity, code, message), the plate-folder per-well reporting mode, and the acquisition_in_progress special case. It does not explain the strict/exit_code 6 behavior that only the schema hints at.

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 dense sentence that front-loads the outcome (ok plus findings) before enumerating detection categories. No filler, though the semicolon-chained clauses make it slightly harder to parse than it needs to be.

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?

An output schema exists, so return values need not be explained, yet the description still usefully summarizes the finding structure and the folder-mode behavior. Complete enough to call correctly; the only gap is sibling differentiation and strict-mode behavior.

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 100%, so all three parameters are already documented, making 3 the baseline. The description adds only slight context (a directory argument triggers per-well reporting) and does not elaborate on strict or headers_only semantics beyond 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 specific action (integrity check) on a specific resource (file/data-set directory) and enumerates what it detects: truncation, missing planes or parts, bad blocks. An agent can tell it is a damage check, but the description never distinguishes it from the similarly-scoped sibling openreadout_health.

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 by the content: the tool is for verifying file/folder integrity. There is no explicit when-to-use statement, no when-not-to, and no routing to alternatives such as openreadout_info or openreadout_health.

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, idempotentHint, destructiveHint=false and a closed world, so the safety profile is fully covered. The description adds that output arrays are thinned while the apex/integral summary covers every point, which is useful behavioral context, but it discloses nothing about cost, streaming, or parameter interaction beyond what the schema's own parameter text already states.

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 dense sentences, front-loaded with the supported chromatogram modes before the per-chromatogram output and the use-case question. Nothing is padded, though the mode enumeration and output summary run long for a single sentence, which keeps it just under a 5.

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 a 23-parameter tool with an output schema and full annotation coverage, the description supplies the missing high-level framing: which chromatogram types exist and what each result contains. It does not explain how the many mode selectors (tic/bpc/mz/transitions/traces) interact or which combinations are mutually exclusive, which is the main residual gap for a tool this complex.

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 100%, so every one of the 23 parameters is already documented in the schema, including tolerances, defaults, and the max_points thinning rule. The description only restates a handful of these (mz with ppm or da, transitions, traces) at a conceptual level without adding syntax or interaction semantics, so the baseline 3 applies.

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 the resource (chromatograms) and enumerates the specific modes it extracts — TIC, BPC, extracted-ion with ppm/da tolerance, SRM/MRM transitions, stored/detector traces — which lets an agent recognize the tool against siblings like openreadout_spectrum or openreadout_trace. The verb is only implied in the text (it lives in the annotation title 'Extract chromatograms'), and no sibling is named for contrast, so it stops 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?

Usage is implied through one concrete question it answers, "when does m/z X elute," which points at extracted-ion work, and through the mode list that hints which parameters select which behavior. There is no explicit when-to-use versus openreadout_spectrum/openreadout_trace/openreadout_peaks, and no stated exclusions or prerequisites.

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 readOnly, idempotent and non-destructive, so the safety profile is covered. The description adds behavior beyond that: it discloses the default equality rule (bit-identical xxh3-128 planes unless tolerance is set), that strict mode refuses unvalidated values with exit_code 6, and what the 'identical' flag reports. It does not describe output shape or performance characteristics, but the output schema exists to carry that.

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 dense sentence with the core action front-loaded and the compared aspects following. Every clause carries information, though the enumerated list plus the trailing 'identical says...' sentence makes it slightly cramped rather than maximally scannable.

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 9-parameter comparison tool, the definition plus a 100%-covered schema, an output schema, and safe-read annotations leave nothing an agent needs missing: purpose, what is compared, the equality default, and the return signal ('identical') are all 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 description coverage is 100%, so every one of the 9 parameters is already documented in the schema, including tolerance's xxh3-128 default and the ignore JSON-pointer syntax. The description only echoes these at a high level ('per-plane hashes or the largest difference within tolerance') without adding format or interaction details, so baseline 3 applies.

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 ('Compare two files') and enumerates exactly what dimensions are compared: metadata, geometry, channel names, physical sizes, per-plane hashes. That is far more specific than the title alone. It stops short of naming a sibling, so an agent cannot infer from the text alone why it would pick this over openreadout_check or openreadout_info.

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 parenthetical 'e.g. a raw file and its export' gives a concrete usage scenario and the required params reinforce it ('an OME-TIFF export of `file`'). There is no explicit when-not guidance and no naming of the alternative tools (openreadout_check, openreadout_info) whose output feeds the `ignore` pointers.

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, idempotentHint and non-destructive, so the safety profile is covered. The description adds no behavioral context beyond the domain split of current vs voltage clamp: nothing about required file/assurance preconditions, what happens when features cannot be computed, or how strict mode affects 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?

A single front-loaded sentence with no filler; the topic leads and the clamp-mode distinction follows. It is efficient, though the semicolon-heavy feature list reads more like an output inventory than 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?

An output schema exists, so return values need not be explained — yet the description spends its length restating those outputs instead of covering the gaps: required input format, the meaning of strict/exit_code 6, and how it relates to openreadout_spikes. Adequate but with clear omissions for a 9-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?

Schema description coverage is 100% and every parameter carries its own default and semantics, so the baseline of 3 applies. The description's enumerated quantities describe outputs rather than clarifying any parameter, adding no interpretive value for inputs like sweeps, channel or the spike-detection thresholds.

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 the resource (patch-clamp features) and enumerates the specific quantities computed, so an agent can tell this is an ephys feature-extraction tool. However, there is no explicit verb and no differentiation from neighbours like openreadout_spikes or openreadout_trace, which also operate on traces.

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 when-to-use guidance, no prerequisite statement (e.g. what file kinds qualify), and no mention of alternatives such as openreadout_spikes for raw spike events. The agent must infer selection context entirely from the feature list.

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 flag a non-read-only, destructive, idempotent write confined to the local world. The description adds real value on top: the source is never touched, output is read back and verified, overwrite replaces an existing file or directory, strict mode can fail with exit_code 6, and progress is reported via progressToken. Minor gap: no mention of permissions or what is returned on success.

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 in the first clause, which is good. But the remainder is a single dense run-on that dumps the entire format list already present in the schema's format parameter, so a large fraction of the text duplicates structured data instead of earning its place. Structure suffers from being one unbroken block.

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 23-parameter, no-required, nested-object tool with no output schema, the description covers conversion targets, figure saving, verification, overwrite and progress well. The main gap is the return value for the data-export path (only figures are said to come back), which with no output schema is left unstated.

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 100%, so every one of the 23 parameters is already documented inline, including the format enum-like list. The description largely restates the format options rather than adding interpretation, and the default-selection rule (extension of output decides unless format is given) is already in the schema. Baseline 3 is appropriate.

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 clause gives a specific verb and resource: convert data to an open format or save a figure, written as a new file that is read back and verified, leaving the source untouched. This is clearly distinguishable from display-oriented siblings like openreadout_plot and openreadout_preview, whose arguments this tool reuses. An agent knows exactly what this tool 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?

Usage is implied rather than stated: it lists per-source default formats and notes that plot/preview arguments are reused for figures, which hints at the boundary with those siblings. However, it never explicitly says when to choose export over plot/preview, nor states any prerequisites or exclusions. Guidance is present but 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 already declare destructiveHint=true, idempotentHint=true, readOnlyHint=false and openWorldHint=false, so the safety profile is covered structurally. The description adds a genuine behavioral note with 'as stored, verified' (bytes are written unmodified and checked), but says nothing about what overwriting destroys, permissions, or failure behavior when the attachment is absent.

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 padding; the action and its scope are front-loaded and the pointer to openreadout_info view=structure comes second as a discovery hint. Every clause earns its place.

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 annotations covering the destructive/idempotent profile and an output schema present, the description need not explain return values; it correctly focuses on which attachment to pull and where listing lives. It is slightly thin on interaction between `output` and `overwrite` (what happens when the target already exists), which keeps it from a 5.

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 100%, so all four parameters (file, output, overwrite, attachment) are already documented, including the `#<index>` form. The description only echoes the attachment concept and adds no syntax, default, or interaction detail beyond the schema, so the baseline of 3 applies.

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 (extract/write) and resource (an embedded attachment such as a slide label, thumbnail, preview image, or time stamps) and gives concrete examples of the attachment types, which separates it from generic siblings like openreadout_export. It lacks explicit verb+resource naming tied to other tools' scopes, but the purpose is 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?

Points the agent at openreadout_info view=structure as the way to discover valid attachment values, which is useful context, but never states when to use this tool versus alternatives like openreadout_export or openreadout_preview, nor any prerequisites or exclusions. Usage is implied rather than 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 readOnly, idempotent and non-destructive, so the safety profile is covered. The description adds real behavioral context beyond that: the fallback interpretation of `file` when both gating inputs are omitted, and the specific report contents per population. It does not mention failure modes such as the strict/exit_code 6 path (that only appears in the schema).

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 dense sentences, front-loaded with the core action and outputs. The second sentence's fallback rule is a little packed with clauses, but every clause carries actionable information and nothing is repeated from the schema.

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 8 parameters, an output schema present, and full schema coverage, the description supplies what the structured fields cannot: the operating-mode logic and the fallback behaviour. Minor gaps remain around error/strict handling and how `populations` and `medians` interact, but nothing essential for a correct call 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 100%, so the baseline is 3, but the description goes further by describing cross-parameter coupling: `workspace` makes `file` the FCS file to count in, `gatingml` is an alternative to `workspace`, and the absence of both redefines `file`. That role-switching is not obvious from the schema alone.

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 — flow-cytometry gating — and names the two input modes (FlowJo workspace, Gating-ML 2.0) plus the exact outputs (event count, percentage, medians per population). No sibling tool overlaps this domain, so an agent can select it unambiguously.

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 gives clear mode-selection guidance: pass `workspace` or `gatingml` to compute gated counts, and if neither is supplied, `file` acts as the gating file and the answer degrades to a sample/gate-tree description. It does not point to any alternative tool for other flow-cytometry tasks, so exclusions are 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?

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds that duplicate confirmation reads file content unless no_hash is set, hinting at I/O cost, but it does not state how expensive a full hash pass is, whether progress is reported, or how sections behave on a partially indexed share.

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 front-loaded sentence that leads with the resource ('Storage health of a share indexed by openreadout_index') and then lists findings; the enumeration is dense but every item conveys a distinct output category. Slightly list-heavy but free of 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 a full output schema and complete annotation coverage, the description only needs to convey purpose and scope, and it does so, including the results categories. The only gap is workflow guidance relative to sibling diagnostics, which is minor given the rich structured metadata.

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 100% and each parameter already carries a description, so the schema does the heavy lifting. The description only gestures at no_hash via 'unless no_hash' and says nothing extra about max_list or index_dir beyond the schema, which is an appropriate baseline-3 case.

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?

Names a specific resource and scope — storage health of a share produced by openreadout_index — and enumerates the concrete findings it reports (truncated/corrupt files, duplicates, files at risk, totals). This separates it from openreadout_stats, openreadout_info and openreadout_check well enough for selection, though the phrasing is a noun phrase rather than an explicit verb.

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 tie to openreadout_index implies 'run after indexing', but there is no explicit when-to-use, when-not-to-use, or named alternative (e.g. openreadout_check vs openreadout_stats). The agent must infer the workflow position and the choice between this and sibling inspection tools.

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 it discloses the substantive behavioral traits: headers-only scanning, resumability via max_files/max_seconds with complete=false, and the same call resuming an interrupted crawl. This resumption contract is not derivable from the annotations or schema and is exactly what the agent needs. It is consistent with idempotentHint=true and readOnlyHint=false (it writes an index).

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 mechanics, then sibling routing; every sentence carries weight. The parenthetical column list is dense but informative. Slightly long, but 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 an output schema present, return values need not be explained, yet the description still outlines the index contents. Combined with annotations covering safety and idempotency, an agent has everything needed to invoke 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 100%, so the baseline is 3, but the description adds meaning: it enumerates the per-row fields produced and clarifies the stop-and-continue semantics of max_files/max_seconds. It also implies the roots/index_dir distinction ('never inside a root' contrast). Modest extra value over 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?

The description opens with a specific verb and resource ('Catalog every data set under roots into index_dir') and details the output shape (Parquet, one row per data set). It distinguishes itself from siblings by naming openreadout_search as the query path and openreadout_batch as the alternative for single folders.

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 routes the agent explicitly: openreadout_search queries the index, and openreadout_batch should be used for one folder of files instead. It does not state when *not* to index or prerequisites (e.g. permission to write index_dir), but the alternative-tool guidance is clear and 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 cover the safety profile (readOnlyHint, idempotentHint, non-destructive), so the bar is lower, and the description still adds real behavior: header-only reads are fast on huge files, view=summary attaches a ~384 px thumbnail with pixel rulers, and it reports the 'assurance' field. It could go further on rate limits or how the server behaves on unsupported formats.

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 in the first clause, but the rest is a dense, parenthetical run-on enumerating return fields (images[], tables[], traces[], spectra[], plate, experiment) that partly duplicates the output schema. Given 11 parameters and 5 view modes, some length is justified, but it is not tightly structured.

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, multi-view inspection tool with full schema coverage, annotations, and an output schema, the description supplies the core mental model: header-derived content, view modes, thumbnail behavior, and cheap format detection. Nothing essential for calling it correctly is missing, though the relationship to sibling inspection tools 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?

Schema description coverage is 100% and an output schema exists, so the schema carries the parameter burden and 3 is the baseline. The description only lightly adds meaning — roughly that view=summary governs the thumbnail and that ask returns answers with the fields used — while most of the parameter detail lives in 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?

The opening clause names a specific resource and action: reading what an instrument file or data-set directory holds from its headers. It conveys the 'inspect metadata' role clearly, but it never distinguishes itself from close siblings such as openreadout_check, openreadout_summarize, or openreadout_preview, which an agent must route between.

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 context is implied rather than stated: 'fast on huge files' and 'works on damaged files' hint at when this tool is the right choice, and the view list implies mode selection. However, there is no explicit when-to-use vs when-not, and no routing to any of the many sibling tools.

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 establish the safe-read profile (readOnlyHint, idempotentHint, non-destructive), so the bar is lower, and the description still adds real behavior: each link carries evidence and a confidence rating, and below-threshold links are diverted into a weak_links list rather than grouped. That threshold-diversion behavior is not derivable from the annotations and is exactly the kind of operational detail 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, but the whole definition is a single semicolon-joined run-on sentence with a long parenthetical of matching criteria, which is dense and slows parsing. Every clause is substantive, so nothing is padding, but the structure could be cleaner and shorter.

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 an output schema present, return values need not be explained, and the description does cover the grouping logic and confidence handling adequately. However, for a six-parameter cross-file correlation tool with no required parameters and no stated usage context, the absence of any when-to-use or scoping guidance leaves a real 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 description coverage is 100%, so all six parameters are already documented in the schema, and several of those descriptions are themselves truncated ('… and the query', 'the index directory …'). The description only reinforces min_confidence's weak_links consequence, which the schema already states, so it adds little beyond the baseline.

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 ('groups') and resource ('files that measured the same sample'), then enumerates the actual matching heuristics (sample id, barcode, plate well + plate, conversion source, shared acquisition/spectra). This makes the tool's function unmistakable and hard to confuse with the many read/plot/query siblings, though no sibling is named explicitly for contrast.

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 choose this tool over alternatives such as openreadout_search, openreadout_index, or openreadout_compare, despite a crowded sibling set. The description explains what the tool computes but never states the scenario that should trigger it or any exclusion conditions.

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, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: the FID processing chain it will apply (group delay, apodization, zero filling, FT, phase, baseline) and the fact that a stored spectrum is used as-is unless processing is requested. It stops short of stating permissions or failure behavior, but this is solid added context.

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 dense sentence with the primary output (peak list) front-loaded and the processing options parenthesized after. No wasted words, though the nested parentheses make it harder to parse at a glance than a two-sentence split would.

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 an output schema present and 100% schema coverage, the description need not explain return values or parameter details; it correctly focuses on scope and the processing modes. The one gap is the absence of any differentiation from the sibling openreadout_peaks, which an agent needs for correct tool selection.

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 100%, so the schema already documents all 18 parameters, including defaults and enumerated string values. The description echoes only two of them (from=fid, auto_integrate) without adding syntax or constraints beyond the schema, so the baseline 3 applies.

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 resource (NMR peak list plus integrals) and enumerates the returned quantities (ppm, height, width, S/N), so an agent knows exactly what it gets. However, it never distinguishes itself from the closely named sibling openreadout_peaks (or openreadout_spectrum), leaving ambiguity about which tool to pick for generic vs NMR-specific peak extraction.

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 implies usage contexts via 'from the vendor's processed spectrum or a spectrum processed from the FID (from=fid ...)' and 'integrals of given regions or of every multiplet (auto_integrate)', which hints at the two operating modes. But it gives no explicit when-to-use/when-not guidance and never names an alternative tool, so the agent must infer the routing.

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, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description adds genuine scope context (which instruments/domains it applies to and that signal selection mirrors openreadout_chromatogram), but much of the rest is a recitation of returned quantities that the output schema already carries, and it says nothing about errors, caveats, or cost for a 35-parameter call.

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?

Appropriately sized for a 35-parameter tool and front-loaded with the core verb phrase, but it is a single run-on sentence stitched together with semicolons and nested parentheses, which makes the modality-by-modality enumeration hard to parse.

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 an output schema documenting returns, 100% schema coverage, and annotations carrying the safety profile, the description is nearly sufficient: it establishes scope across chromatography, spectroscopy and electrophoresis. The main remaining gap is sibling disambiguation (openreadout_nmr_peaks, openreadout_chromatogram) that an agent needs in order to pick the right 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 description coverage is 100% across 35 parameters, so the baseline is 3 and the schema does the heavy lifting. The description only names a handful of parameters (x_range, integrate, rt) and cross-references openreadout_chromatogram for signal selection; it adds no tolerance, unit, or default semantics beyond what is already in 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?

Opens with a specific verb+resource ('Detect and integrate peaks') and then enumerates the exact data types handled (detector traces, TIC, XIC, SRM, IR/Raman/UV-Vis/NMR bands, electropherogram peaks in bp) plus the reported quantities. This is well beyond a tautology. It does not, however, differentiate itself from the close sibling openreadout_nmr_peaks, which plausibly overlaps the NMR/spectral case.

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 enumeration of applicable modalities tells the agent what kinds of inputs qualify, and 'Takes the openreadout_chromatogram arguments to choose the signal' links it to a sibling for signal selection. There is no explicit when-to-use / when-not-to-use statement and no routing away from openreadout_nmr_peaks or openreadout_chromatogram.

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 readOnly/idempotent/non-destructive, so the safety profile is covered; the description adds real workflow context: the tool returns image content plus a record of what was drawn, and it will not persist anything (export is needed to save). The 'never paste numbers' rule is extra behavioral guidance beyond the annotations.

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 well front-loaded, but the middle is one very long run-on sentence listing every drawable data type with semicolons, which is hard to scan. Each clause carries information, yet the structure could be split or bulletted for the same content.

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 19-parameter tool with full schema coverage, annotations, and an output schema, the description covers the capability envelope, the draw-vs-save boundary, faceting/panels, and annotation support. Minor schema-level details (size caps, strict mode) are left entirely to the schema, which is acceptable.

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 100%, so the baseline is 3, but the description adds a conceptual map of the selector space (file+selector by data family) and the important rule that values must be referenced by file/selector rather than pasted, which is semantic guidance the schema does not state outright.

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 ('a finished figure from lab files in one call') and enumerates exactly the data families it can draw (traces, chromatograms, plates, FCS, dose-response, tables). It explicitly routes the agent apart from siblings by naming what it does not do ('Draws only; openreadout_export saves the figure') and by relating itself to openreadout_preview.

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 selection rule ('Name data by file and selector, never by pasting numbers' with inline values as the exception) and names the alternative tool for a related task (openreadout_export for saving). It does not, however, explicitly state when to choose this over openreadout_preview, which also draws.

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 readOnly/idempotent/destructive=false, so the safety profile is covered. The description adds real behavioral context beyond that: images carry rulers in full-resolution pixels plus a µm scale bar, a region read off the rulers zooms in, and annotations are 'drawn on top and reported back with their pixel positions.' That the tool only draws (never writes files) is also usefully 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 core purpose is buried in a single enormous run-on sentence that enumerates every picture modality; nothing is front-loaded, and several clauses ('region ... only the tiles needed are read', 'x_range zooms') simply repeat structured schema content. It is information-dense but structurally weak, so it is neither wasteful enough for a 2 nor clean enough for a 4.

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 33-parameter, multi-modal tool with an output schema and annotations already present, the description covers the modality space, the drawing-only scope, and coordinate conventions well. Return-value detail is rightly left to the output schema, so the remaining gap is minor.

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 100%, so the baseline is 3; the description still adds cross-parameter meaning beyond the schema — the default plane ('channel 0, middle z'), that mip=z is a max projection, that marks=spikes marks action potentials, that x_range zooms the axis, and that a region taken from the rulers zooms in. Much of this is restated from the schema, keeping it out of the top band.

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+resource (draws a picture of the data as image content) and enumerates the exact picture types it produces across modalities. It also explicitly distinguishes itself from a sibling: 'Draws only; openreadout_export saves the picture,' so an agent can tell preview from export without opening 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?

It names the alternative that matters most (openreadout_export for saving) and gives the selecting condition ('Draws only'). It also frames the use case ('annotations ... to show the user what you found'), but never differentiates itself from other rendering-adjacent siblings such as openreadout_plot or openreadout_chromatogram, so guidance is clear but not exhaustive.

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, idempotentHint=true, destructiveHint=false and a closed world, so the safety profile is fully covered without the description. The description adds output-format context (one record per well and target; 2^-ΔΔCq; per-target efficiency) but says nothing about permissions, rate limits, or failure behavior beyond what annotations give.

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 dense sentence, front-loaded with the assay type and file formats, then the record structure and the three mode flags. Nothing is wasted, though the mode list is crammed into one clause that would read better as a short enumeration.

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?

An output schema exists, so return values need no explanation, and annotations carry the safety profile. For an 18-parameter tool the description still conveys the core analysis modes and record shape; the only real gap is that it does not say when to prefer ddcq versus standard_curve or when compute_cq should be enabled.

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 100%, so the schema already documents all 18 parameters (including the cq_method enum values and every analysis flag). The description restates compute_cq, ddcq and standard_curve at a high level but adds no syntax or semantics beyond the schema, so the baseline of 3 applies.

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 domain (real-time PCR), the supported file formats (RDML, .eds, .rex), and the output granularity (one record per well and target with sample, task, Cq and Tm). That is clear enough to distinguish it from the other domain-specific siblings, but it never explicitly names an alternative or positions itself relative to them.

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 the three analysis modes do (compute_cq recomputes Cq, ddcq gives 2^-ΔΔCq fold changes, standard_curve fits efficiency), which implicitly tells the agent when each flag is relevant. However it gives no explicit when-to-use guidance, no prerequisites, and no routing away from sibling tools.

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 (readOnlyHint=false, openWorldHint=false, idempotentHint=true, destructiveHint=false), the description discloses meaningful behavior: 'Nothing is sent; the user files it' confirms no network transmission, 'privacy-reviewed' signals a sanitization step, 'no data values' states the data-minimization posture, and the include_text mention ties free-text retention to consent. These add real context an agent would not infer from annotations alone.

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 a single compact sentence, which is good, but the structure is a run-on with multiple colons and an ambiguous clause ('for a new-variant issue: no data values, free text only with include_text') that forces re-reading. Front-loading the bundle concept is fine; the rest is dense rather than efficient.

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 an output schema present, return values need no explanation, and the description covers the operative context for this tool: the trigger condition, the privacy/consent behavior, and the fact that nothing is transmitted. An agent could call it correctly; only the missing verb and confusing 'new-variant issue' phrasing leave minor ambiguity.

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 100%, so the schema already documents file, output and include_text with descriptions, making the baseline 3. The description only restates the include_text consent rule and references 'the issue_url to file it at' (an output field, not a parameter), adding no parameter syntax or format detail.

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 the deliverable (a 'privacy-reviewed diagnostic bundle') and its trigger ('a file that is refused, fails or is not validated'), so the resource is identifiable, but it never states a verb like 'produce' or 'write' and the colon-laden phrasing ('for a new-variant issue: no data values, free text only...') muddies what the tool actually does. No sibling is named or differentiated, though the purpose is distinctive enough to stand apart.

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 usable trigger condition — use it when a file is refused, fails validation, or is a 'new-variant issue' — which is better than nothing. However, it names no alternative sibling (e.g. openreadout_check or openreadout_info) and gives no 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 readOnly, idempotent and non-destructive, so the safety profile is covered. The description adds useful behavior beyond that: it lists the exact fields returned, notes that results are filtered/paged, and discloses that every match is counted (matched, ms_level_counts) even when paging. No auth or rate-limit context, hence not 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?

A single dense sentence with semicolons, front-loaded with the resource and field list before the routing note. Every clause carries information (fields, filtering/paging, counting, sibling routing), though the field enumeration makes it heavier 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?

An output schema exists, so return-value explanation is not required, and the annotations carry the safety profile. For a 15-parameter filtered-list tool, the description supplies the resource scope, the returned fields, and sibling routing, leaving only minor gaps like prerequisites or run semantics that the schema covers.

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 100%, so the schema already documents all 15 parameters thoroughly (rt_range, precursor_tol, strict, count, limit, etc.). The description only summarizes 'filtered and paged' and the counting behavior; it adds no parameter syntax or format detail beyond the schema. Baseline 3 applies when the schema does the heavy lifting.

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 ('scans of a mass-spectrometry run') and immediately scopes it with 'without decoding peaks', enumerating the fields it returns. It also distinguishes itself from openreadout_trace by naming the modalities (IR, Raman, UV-Vis, NMR) that belong to the sibling, so an agent can tell the two apart without opening 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?

Clear routing: this tool is for MS scans, and the final sentence directs the agent to openreadout_trace for IR/Raman/UV-Vis/NMR. 'Without decoding peaks' implies openreadout_peaks is the alternative for peak data. There is no explicit when-not statement, but the alternative is named, which is strong 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, idempotentHint, non-destructive, and openWorldHint=false, so the safety profile is covered. The description adds that total is the full match count while results is capped by limit (default 50) — real behavioral value — but an output schema already exists, so this partially duplicates structured data rather than breaking new ground.

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 front-loaded paragraph: purpose first, then concrete query exemplars, then the return envelope. It is dense and every clause is relevant, though the query examples overlap heavily with the already-complete schema and slightly dilute the opening.

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 search tool with full schema coverage, an output schema, and a rich annotation set, the definition covers the essentials. It omits only secondary concerns — index_dir validity requirements and how sort interacts with the limit cap — which are minor given the structured fields carry them.

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 100% and the query grammar, sort semantics, limit bounds, and field aliases are all documented in the schema. The description's query exemplars ('rate>=20kHz', 'status=truncated|corrupt') restate that syntax rather than adding units or edge cases the schema omits, so the baseline 3 applies.

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?

Opens with a specific verb+resource ('Query an index from openreadout_index'), naming the sibling that produces the input and thereby signaling the precondition. However, it never contrasts itself with search-adjacent siblings like openreadout_table, openreadout_info, or openreadout_scans, so an agent must infer the boundary from names alone.

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 phrase 'an index from openreadout_index' implies the index must exist first, which is useful routing context. But there is no explicit when-to-use/when-not, no statement of what to do when the index is missing, and no pointer to a sibling for viewing or exporting the results.

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, idempotentHint=true, openWorldHint=false and destructiveHint=false, so the safety profile is fully covered. The description adds little beyond structured fields: the 'nearest scan' rt behavior and the peak/charge/neutral-mass output details are already in the schema and output schema respectively. No mention of errors, cost, or the strict/exit_code 6 refusal 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?

A single dense sentence, front-loaded with the resource and the selection keys before listing outputs. It is run-on and packs three selectors plus output shape into one clause, but every element earns its place and nothing is padded.

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 an output schema present, the description need not explain return values, and with 100% schema coverage the parameters are covered. It adequately frames the selection keys and the shape of the result for a read-only single-record tool; only alternative-routing guidance 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 100%, so the schema already documents all 11 parameters in detail (rt, run, scan, spectrum, ms_level, top_peaks, max_points, etc.). The description restates only rt, scan and spectrum and adds no format or default semantics beyond what the schema provides, so the baseline 3 applies.

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 resource ('One mass spectrum') and the three mutually exclusive selectors (retention time, scan number, zero-based spectrum index), which is enough to distinguish it from siblings like openreadout_chromatogram, openreadout_scans and openreadout_peaks. An agent can tell what it retrieves and how to address the target 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?

Usage is implied: read a single spectrum when you can name it by rt, scan or index. There is no explicit when-to-use / when-not-to-use guidance and no routing to alternatives such as openreadout_scans (enumerate scans) or openreadout_peaks (peak lists), so the agent must infer the boundaries.

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 readOnly, idempotent and non-destructive behavior, so the bar is low; the description still adds real value by disclosing the processing pipeline (band-pass, K x MAD thresholding) and the outputs produced (counts, rates, times). It does not mention cost, data-size limits, or failure modes.

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 front-loaded sentence that names the domain first and then enumerates the pipeline stages and outputs. No filler, no restatement of the title or name.

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 a full output schema and complete annotation set, the description only needs to frame the computation, which it does. The main residual gap is the absence of any statement about prerequisites (e.g. broadband trace selection, assurance/strict validation) that an agent would need before calling it.

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 100% with 10 well-documented parameters, so the schema already carries parameter meaning. The description echoes band-pass, threshold and time outputs but adds no syntax, units or default information beyond what the schema provides, so the baseline 3 applies.

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 ('Extracellular spike detection per channel') plus the algorithm used, so an agent knows exactly what computation is performed. It contrasts implicitly with generic siblings like openreadout_peaks by naming the extracellular-spike domain, but never names an alternative 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?

Usage is implied by the domain phrase 'extracellular spike detection per channel' plus the mention of picking a broadband stream, which tells the agent the expected input. There is no explicit when-to-use/when-not guidance and no routing to sibling tools such as openreadout_peaks or openreadout_ephys_features.

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 the read-only/idempotent/non-destructive profile, so the bar is lower, and the description still adds real behavior: 'strict ... refuses values the file's assurance does not validate (exit_code 6)', that 'the counts cover all' objects while only max_objects are listed, and that with a ladder 'bands then get sizes'. No rate limits, cost, or failure modes beyond exit_code 6 are described.

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 a single very long run-on passage with semicolon-separated clauses and no structure, so the key 'what it computes' idea competes with a dense feature dump. Nothing is truly wasted, but it is not front-loaded by importance and is hard to scan, which weakens selection speed.

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 16-parameter tool this is a thorough description: it covers the output statistics, every measurement mode, projection and pyramid handling, plate/slide scoping, and selection semantics. With annotations and an existing output schema carrying the safety and return-shape burden, almost nothing an agent needs in order to call it 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 100%, so the schema already documents all 16 parameters, and the description largely mirrors that content (mip, per, line, polygon, objects, lanes are all restated rather than extended). It does tie modes together usefully ('preview marks=objects shows them'), but adds little semantic detail the schema lacks, so the baseline 3 is right.

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+resource (pixel statistics per channel/image) and immediately enumerates the measurement families it covers (count, min/max/mean/std, percentiles, histogram), so an agent knows exactly what the tool produces. It does not, however, name or contrast itself with any sibling such as openreadout_preview or openreadout_extract, leaving the boundary to inference.

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?

Embedded conditional guidance is present: 'per=plane adds every plane; per=well or field gives rows per well of a screening plate', 'mip=z measures the maximum-intensity projection', and 'Measurements on one plane: line..., polygon..., objects..., lanes...'. This tells the agent when each mode applies, but there are no explicit exclusions or pointer to an alternative 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?

Annotations declare a non-read-only, destructive, idempotent operation, and the description is consistent with that by noting the `output` write target and the ability to overwrite an existing output file. It also adds genuinely useful context beyond the annotations, such as accepted input formats and that replicates can be averaged before summarization. It does not discuss failure modes or what happens to prior results beyond the overwrite flag.

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 (group statistics of a table) and the enumerated outputs, followed by the optional behaviors. It is a single dense sentence with nested parentheticals, which makes it slightly run-on but still economical with no wasted clauses.

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 ten-parameter statistical tool with an output schema (so return values need no explanation) and annotations covering the safety profile, the description supplies enough to call it correctly: input formats, the grouping key, and the optional replicate/control behaviors. It is close to complete, with only minor gaps around filtering and value-column selection.

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 100%, so all ten parameters are already documented in the schema and this is the baseline case. The description reinforces `by` grouping, replicate averaging, and control testing, but says nothing about `where`, `exact_by`, or `values`, adding little meaning beyond 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?

The description gives a specific verb+resource (group summary statistics of a table) and enumerates exactly what is computed (n, mean, sd, sem, median, min, max, CV%), plus the accepted input sources. It does not explicitly differentiate itself from potentially overlapping siblings such as openreadout_stats or openreadout_compare, so it stops 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?

Usage is only implied: an agent can infer it should call this when it wants per-group descriptive statistics, optionally with replicate averaging or a control comparison. No when-not-to-use conditions, prerequisites, or alternative tools are named, and the relationship to openreadout_stats is 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 already carry readOnly/idempotent/no-destructive, but the description adds real behavior: values are raw unless compensate/transform/workspace/populations are applied, FCS scaling ($PnE, $PnG, $TIMESTEP) is applied first, and strict can refuse values (exit_code 6). Those are substantive traits beyond the annotation 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?

Two dense sentences that front-load the return shape and table kinds, with no filler. The colon-separated noun lists are terse to the point of being hard to parse, but nothing is wasted.

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 14-parameter tool the description covers the important axes — table selection, raw vs compensated/transformed values, workspace/Gating-ML population columns, and filter/count behavior — and an output schema exists so return format need not be repeated. Only the interaction between first_row/max_rows paging and filtering is left to the schema.

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 100%, so the baseline is 3. The description restates the filter semantics ('tested on the values returned after compensate/transform', matched_rows counting) that the schema already documents, and adds little independent meaning for the other 13 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 description names the resource precisely (rows of a table) and enumerates the concrete table kinds it returns — FCS events, plate reads, event/spike/peak tables — plus the return shape {columns, labels, rows, total_rows, truncated}. That is a clear specific operation, though it never explicitly contrasts itself with preview/export/extract siblings, only deferring to openreadout_info for table indices.

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: it points to openreadout_info → tables[] for choosing a table index and notes that filter+count=true yields counts. There is no explicit 'use this when you need actual row values, use openreadout_preview/summarize otherwise' routing, so an agent must infer the boundary from siblings.

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, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered by structured data. The description's remaining behavioral contribution is the NMR process=true transform, which is notable, but the return contents it lists (min/max/mean/std/argmax) are already covered by the output schema. Error behavior (strict/exit_code 6) is left entirely to the schema.

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 definition is front-loaded, but the first sentence is a very long catalogue of ~14 instrument domains whose tail entries add little for an agent that already knows its data type. The second sentence stacks output fields and axis-unit clarifications into a single run-on. Information-dense, but not tightly edited.

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 an output schema present and 100% parameter description coverage, the description does not need to explain return values; it still usefully frames what a window/sweep/spectrum means, which the schema alone would not convey. The main gap is the absence of any when-to-use or alternative-tool guidance given 27 sibling 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 100%, so the baseline is 3. The description reinforces the units used by argmax_axis_value and by x_range (retention time, ppm, cm⁻¹, °2θ) and clarifies that a map's each spectrum counts as a sweep, but it adds no syntax or default information beyond what the parameter descriptions already state.

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 precise definition of the resource: 'one window of one sweep of a sampled signal or 1-D spectrum in physical units', and enumerates the data domains it covers (electrophysiology, chromatography, NMR, ITC, SPR, qPCR, etc.). It is clear the tool reads a sub-window of a series, but it never explicitly names the sibling it replaces or differs from (e.g. openreadout_spectrum, openreadout_scans, openreadout_stats), so sibling differentiation must be inferred.

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 by the domain enumeration — the agent can infer this is the general-purpose trace/sweep reader for any sampled signal. There is no explicit when-to-use statement, no exclusions, and no routing to alternatives such as openreadout_spectrum or openreadout_scans. The 'process=true turns an FID into a spectrum' note is the closest thing to a mode-selection hint.

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 cover the safety profile (readOnly, non-destructive, not idempotent), and the description adds genuinely useful behavior beyond that: each call is a single non-blocking look, continuation is by cursor, and watching never locks files. It does not explain backpressure or what happens when a watched directory disappears.

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 tight sentences, with the core purpose front-loaded before the event-type parenthetical. The embedded enumeration of event names is dense but earns its place by telling the agent what to expect to parse.

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?

An output schema exists, so return-value detail is not required, yet the description still names the event vocabulary the agent will need for routing. Combined with the polling/cursor guidance, an agent has enough to invoke and loop correctly; only edge behavior (missing dirs, error recovery) 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?

Schema coverage is 100%, so the schema already documents all seven parameters including the first-call-only nature of qc/since/stall_after/follow_symlinks. The description adds only the cursor/polling linkage, which the schema's cursor description already carries, so baseline 3 is appropriate.

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 ('Follow directories an instrument writes to') plus the operational model ('each call looks once and returns events since cursor'), and enumerates the returned event types. It is clearly distinguishable from read-once siblings like openreadout_scans or openreadout_check.

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 operational context: poll repeatedly using the returned cursor, and 'files are never locked' signals it is safe to call alongside a running acquisition. It does not name an alternative sibling or state an explicit when-not-to-use, 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.