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

Annotations already establish read-only, idempotent, non-destructive behavior, so the bar is lower, and the description still adds non-obvious behavior: the `options` object is kind-discriminated and an option the kind does not take raises an error naming the valid ones. That is a genuine failure-mode disclosure not present in the annotations. It does not mention size limits, path-resolution expectations, or other runtime constraints.

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

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

Three short sentences with no filler; the purpose statement is front-loaded and the batch alternative is deferred appropriately. It is tightly written, though the opening sentence is abstract enough that it reads more as a framing statement than a definition.

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 described, and the annotations carry the safety profile, so the description's remaining job is the kind/options contract, which it covers well along with the multi-file alternative. The only gap is that the resource and result nature are left entirely 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 coverage is 100%, so baseline would be 3, but the description adds real meaning: it explains that `options` is a discriminated union where only the selected kind's settings are valid, which resolves the confusing `anyOf`-over-all-kinds shape in the schema. It does not clarify the `strict` or `file` semantics, which the schema already handles.

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 says it produces 'an analysis with a documented method, picked by kind', which is a clear action but never names the resource being analyzed (instrument files) or what the analyses actually produce. The real specifics of purpose live in the `kind` enum, not the description, so an agent must open the schema to know what this tool is for. It does route to a sibling, which keeps it above pure vagueness.

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

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

It explicitly names the alternative and the condition that selects it: 'openreadout_batch runs the same kinds and options over many files', implying this tool is for a single file. That is a real when-to-use-ex-batch signal. It stops short of an explicit 'use this when X' statement or any exclusions beyond the batch 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 declare destructiveHint=true and idempotentHint=true; the description adds genuine behavioral context beyond them — a failing file becomes a row with error, results are capped by limit/offset, output writes the full table to a file, and joins are reported in joins[] with unmatched rows. This meaningfully lowers the need to inspect the schema for error/pagination 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?

The purpose is front-loaded, but the body is a single dense run-on paragraph with nested parentheticals that is hard to parse. Most content earns its place for a 22-param tool, yet the structure could be broken into clearer segments.

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 22-parameter, nested-object tool with an output schema, the description covers the overall workflow, join behavior, pagination/limit semantics, error-row handling, and the summarize mode. Output-schema presence excuses it from explaining return values, and the remaining gaps are 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 coverage is 100%, so the schema already documents all 22 parameters thoroughly (including join keys, by, measure enum, and options). The description restates the input model (files, directories, globs, index query) and join-key selection, but adds little syntax or format detail beyond the schema. 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+scope: 'One measure over many files as one tidy table,' which cleanly distinguishes the batch tool from single-dataset siblings like openreadout_table, openreadout_stats, and openreadout_analyze. An agent can identify this as the many-files aggregator 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?

Establishes the batch context ('one measure over many files') and routes options to openreadout_analyze ('Analyses take the same options as openreadout_analyze'), plus notes measure=summarize regroups a prior output. It lacks an explicit when-not-to-use or a direct 'prefer X over Y' statement, but the context is clear.

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

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

Annotations give readOnlyHint=false/destructiveHint=false/idempotent, and the description usefully explains the write behavior behind that (report writes a bundle to `output`, default only returns it) plus refusal semantics (strict → error with exit_code 6 and a hint). It also discloses the privacy model (no data values; free text only with include_text). Missing: any note on cost/runtime for large plates.

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 purpose, which is good, but the rest is a single run-on paragraph of semicolon-joined clauses mixing three modes. Every clause carries information, yet the mode boundaries are hard to parse on a first read.

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 all three operating modes, privacy handling, and the refusal path. Adequate for an 11-parameter tool; only the sibling-tool boundary is left implicit.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it groups parameters by mode (plain check vs `against` vs `report`), explains what `against` compares (metadata, geometry, channels, per-plane hashes or max |difference| within tolerance), and clarifies `strict` and `include_text` behavior beyond the schema text.

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 ('Integrity check: ok plus findings ... for truncation, missing planes or parts, bad blocks') and explicitly names the two alternate modes (against-comparison, report bundle). An agent can distinguish it from openreadout_info/export/analyze without opening the schema.

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

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

The 'instead' framing tells the agent when to switch modes: pass `against` to compare two files, pass `report=true` for a refused/failed file. It also notes acquisition_in_progress for in-progress writes. It does not, however, explicitly contrast with sibling tools like openreadout_info or openreadout_export, which the comparison mode overlaps with.

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 destructiveHint=true and readOnlyHint=false, and the description reconciles this correctly: 'the source is never touched' while overwrite is parameter-controlled, and the output is 'read back and verified'. It also discloses progressToken progress reporting, adding real context beyond the annotations. It stops short of describing error/refusal behavior beyond what the schema's `strict` note already covers.

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 guarantee (new file, source untouched) is front-loaded, then formats, then attachment, then progress. Dense but every clause carries information for an 18-parameter tool. Slightly list-heavy, but not 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?

For an 18-parameter, no-output-schema export tool, the description covers the main modes (format conversion, attachment extraction, progress) and the safety guarantee. It doesn't need to explain return values since none are declared, though it could say more about failure/verification outcomes.

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 format menu and adds a couple of nuances not in the schema (pyramidal output mirroring the source, plates as OME-NGFF HCS), but most parameter meaning is already carried by 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: 'Convert to an open format: a new file, read back and verified; the source is never touched.' This clearly frames it as a file-export tool and the format enumeration reinforces scope. It does not explicitly contrast itself with siblings like openreadout_preview or openreadout_analyze, so a 4 rather than 5.

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

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

The description implies when to use it (when you need a converted, verified copy on disk, or a stored attachment via `attachment`), but there is no explicit 'use this instead of X' routing against the many siblings. Usage is implied by the format/attachment modes rather than stated as 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, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds genuine content about what the listing reports (per-format read/write capability, confidence, undecoded gaps), but adds nothing about freshness or scope of the format registry.

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 parenthetical defining 'known gaps' is the only elaboration. It is dense but every clause carries information.

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

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

An output schema exists, so return-value shape need not be explained, and the tool is parameterless and read-only. The description covers the content of the payload adequately; only the sibling routing question remains open.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. No parameter-level confusion is possible.

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 (supported formats) and enumerates what the listing contains: read/write support, confidence, and known gaps. It is far more concrete than a tautology, but it does not distinguish itself from the similarly named sibling openreadout_info, leaving the agent to guess which discovery tool to call.

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 statement of when to call this versus alternatives, nor any prerequisite or trigger condition. With an ambiguous sibling like openreadout_info in the toolset, the absence of routing guidance is a real gap.

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

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

Annotations declare readOnlyHint=false, idempotentHint=true, destructiveHint=false, and the description adds genuinely useful behavior: headers-only pass, resumable with complete=false, restart/full_rescan semantics, and PII discovery. This goes beyond the annotation flags, though it does not describe write location constraints beyond 'never inside a root' (which is in the schema) or failure behavior.

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

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

Front-loaded with the core action and output shape, then the resumption contract, then the sibling handoff. Dense but every clause carries information; the long parenthetical field list is the only slightly heavy element, and it is arguably warranted given no output schema is described in prose.

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, and the description covers the operation, resumption model, and downstream tool. For a 10-parameter mutation tool it is nearly complete, missing only explicit guidance on choosing between resuming and restart/full_rescan and any notion of cost or duration.

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 earns above that by explaining the cross-parameter interaction semantics of max_files/max_seconds ('a call stops ... and the same call again continues'), which the schema fields describe only individually.

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 ('Catalog every data set under roots into index_dir') and immediately characterizes the artifact produced (Parquet, one row per data set with listed fields). It also names the sibling that consumes the result (openreadout_search), so an agent can place it 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?

Gives clear context: build an index first, then query it via openreadout_search, and explains the resumable calling pattern (stop at max_files/max_seconds, call again to continue). It does not explicitly state when not to use it (e.g., vs. openreadout_watch or openreadout_check on an already-indexed share), but the intended flow is unambiguous.

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 still adds real behavior: header-only reads are fast even on huge files, thumbnails are skipped with a note when decoding would be too costly, vendor trees can be megabytes, and strict mode refuses unvalidated values. Return-shape details are largely deferred to the output 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?

Three dense sentences, front-loaded with the resource and the cost characteristic ('fast on huge files'), then the payload inventory, then the view=summary and ask modifiers. Slightly packed but no sentence 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 an 8-parameter tool with a full output schema, the description supplies enough orientation: what the header report contains, the cost profile, and the two notable modifiers. It need not explain return values, though it could say more about when to reach for it versus 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% and the per-parameter docs are already detailed, so baseline 3 applies. The description restates view=summary thumbnail behavior and that ask implies view=explain, which mirrors rather than extends 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 names the specific resource (an instrument file or data-set directory) and enumerates exactly what it reports: format, images, tables, traces, spectra, plate, experiment, assurance. It distinguishes itself from generic siblings like openreadout_stats or openreadout_preview by scoping to header-derived metadata, but it never names an alternative tool 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 rather than stated: 'fast on huge files' hints that this is the cheap first-look tool, and the view/ask semantics suggest follow-up queries. There is no explicit when-to-use or when-to-prefer-a-sibling guidance against the 15 other openreadout_* 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), and the description adds real output-behavior context: every link carries evidence and a confidence, and links below min_confidence are diverted to weak_links rather than grouped. This tells the agent how results are partitioned, which is 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?

One sentence, front-loaded with the core action and its criteria, and it ends with the confidence/weak_links rule. The long parenthetical of linkage criteria makes it dense but every element carries meaning, so little 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?

An output schema exists, so return structure need not be explained; the description covers grouping semantics, confidence levels, and weak-link handling. The only gap is the absence of when-to-use guidance relative to the many sibling query 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 schema already documents all six parameters. The description reinforces min_confidence semantics (below-threshold links go to weak_links), which the schema also states, so it adds little beyond the structured data. 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 ('Groups') and resource ('files that measured the same sample'), then enumerates the exact linkage criteria (sample id, barcode, plate well + plate, conversion source, same acquisition/spectra). An agent can distinguish this from siblings like search, index, or table without opening a schema.

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

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

Usage is implied: the tool reads headers and groups files by sample identity, which suggests when it applies. However, it never states when to prefer this over openreadout_search or openreadout_index, nor any exclusions or prerequisites (e.g., requires readable headers).

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 safety is covered. The description still adds real behavioral context: image pictures carry rulers in full-resolution pixels plus a µm scale bar, and a region read only touches the tiles needed, which tells the agent the operation is cheap and how coordinates relate to what is drawn.

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 effectively two sentences: an enumerated list of preview kinds followed by a note on rulers and zoom. The purpose is front-loaded and nothing is obviously padded, though the first sentence is a dense run-on enumeration rather than crisp structure.

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 full parameter documentation, the description need not explain return values, and it does orient the agent across the tool's several preview modes. It stops short of tying each mode to its required parameter cluster (trace/sweep/spectrum/table) or explaining the strict/contrast/lut behaviors, but the schema fills those gaps.

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 23 parameters and the baseline is 3. The description reinforces a few pieces (default channel 0, middle z, mip=z, region in full-resolution pixels) but adds little syntax or interaction detail beyond what the schema states.

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 concrete verb and resource: it renders a picture of the data (image plane, composite, mip, region, trace/spectrum plot, plate heat map). That gives an agent a clear sense of what openreadout_preview produces, though it never explicitly contrasts itself with visual-adjacent siblings like openreadout_export or openreadout_trace.

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: 'a region read off the rulers zooms in' hints at an iterative look-then-zoom workflow, and the modes named map implicitly to parameter sets. There is no explicit when-to-use, when-not-to-use, or pointer to an alternative tool (e.g. export vs preview), so an agent must infer 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 readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely useful behavior: the distinction that `total` counts every match while `results` is capped by `limit` (default 50), and that `fields=['all']` expands the columns. This clarifies truncation semantics that a naive caller could misread.

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 with examples front-loaded and return semantics last; nothing is padded. The example list is long but each example illustrates a distinct operator, so it earns its space.

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 full parameter coverage, the description needn't explain return fields in detail, yet it does clarify the total-vs-returned cap. Combined with the index prerequisite, this is complete enough to invoke the tool correctly, though sibling routing remains 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 query syntax, limit, sort, fields, and index_dir exhaustively. The description's example query strings largely duplicate schema-documented syntax, so it meets but does not exceed the baseline of 3 for high-coverage schemas.

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 uses a clear verb ('Query') plus resource ('an index from openreadout_index') and immediately grounds it with concrete query examples. It does not, however, differentiate this tool from siblings like openreadout_table or openreadout_stats, which also read from the index.

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: 'an index from openreadout_index' signals that an index must exist first, but there is no explicit when-to-use guidance or when-not to use this versus the other index-reading siblings. An 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 readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuinely useful behavior: the list mode returns headers 'without decoding peaks' (a cost/perf hint), that every match is counted even when paged, and that the detail mode returns mz[]/intensity[] with metadata.

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 resource then the mode split, with no filler. Slightly long clauses but every element (header fields, paging, counts vs mz[]/intensity[]) 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?

For an 18-parameter tool with an output schema present, the description covers the critical behavioral fork (list vs single spectrum) and the counting/paging semantics. Return-value detail is delegated to the output schema, which is appropriate, leaving only minor gaps around error/paging edge cases.

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 per-parameter descriptions are already detailed (nth semantics, ppm vs 0.01 m/z, limit cap of 5000, strict exit_code 6). The description adds little parameter-level meaning beyond restating which params select the detail mode, 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 (mass spectra of an MS run) and defines two distinct retrieval modes by parameter combination, so an agent knows exactly what this tool yields. It does not explicitly contrast itself with siblings like openreadout_preview or openreadout_search, which keeps it short of a 5.

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

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

It states the trigger conditions clearly: omitting scan/index/nth gives paged scan headers, while supplying scan, index, or ms_level+nth returns a single decoded spectrum. That is explicit conditional routing, though it offers no guidance on when to prefer this tool over sibling tools such as openreadout_preview.

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. The description still adds genuine behavioral context beyond that: saturated fractions are computed at the detector's 2^bits−1 only 'when recorded', and it discloses what the aggregates cover. No permissions or performance limits are mentioned, but the conditional-recording caveat is real added value.

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

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

The description is front-loaded with the core output metrics and then branches into the per/mip/whole-slide cases. It is dense and telegraphic with heavy semicolon use, but every clause carries information and there is no filler.

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

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

With 11 parameters, a rich output schema, and full annotations, the description covers the main operational branches (per modes, mip, region/level for slides) adequately. Return-value format is delegated to the output schema, which is appropriate, and nothing critical for correct invocation appears 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 thoroughly. The description largely restates the per and mip semantics that the schema already spells out, adding little parameter meaning beyond the baseline. A 3 is appropriate when the schema carries the semantic load.

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 operation (compute pixel statistics) on a specific resource (per channel and image) and enumerates the metrics returned (count, min, max, mean, std, percentiles, zero/saturated fractions, histogram). It is clearly distinguishable from sibling tools like openreadout_spectra or openreadout_table, though it never names them explicitly.

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

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

It gives conditional usage for options (per=plane adds every plane; per=well/field for screening plates; mip='z' for projections; coarser level/region for whole slides), which is helpful routing within the tool. However, it offers no guidance on when to choose this tool over alternatives such as openreadout_spectra or openreadout_table, leaving cross-tool selection 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 readOnly/idempotent/non-destructive/closed-world, so the safety profile is covered; the description adds genuine behavioral context beyond that: values are returned raw, compensation and transforms are optional and workspace/Gating-ML driven, and counts can substitute for rows. It stops short of noting truncation handling or paging limits in prose, which the schema covers.

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?

Return shape is front-loaded, followed by supported table types and then the FCS processing and filter-count behavior. Dense but efficient, with parenthetical enumerations rather than filler; the mixed phrasing ('event, spike or peak tables') is slightly loose but not wasteful.

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 names the envelope fields and the table categories. For a 14-parameter, FCS-heavy tool the coverage of raw-vs-processed values and the count path is adequate, though it could say more about paging/truncation 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% across 14 parameters, so the schema carries the semantics and 3 is the baseline. The description does add conceptual linkage between compensate/transform/workspace/gatingml and mentions the count=true counting behavior, but most parameter-level detail is already in the schema descriptions.

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

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

States a concrete resource and return shape ('Rows of a table {columns, labels, rows, total_rows, truncated}') and enumerates the table types it serves (FCS events, plate reads, event/spike/peak tables), so an agent knows what it gets back. It does not explicitly differentiate itself from siblings like openreadout_preview or openreadout_export, which keeps it 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 rather than stated: the description notes that filtering plus count=true yields event counts, which hints at a counting use case, and it explains that FCS data can be compensated/transformed/population-annotated. There is no explicit when-to-use-this-vs-alternatives guidance, e.g. versus preview or export.

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 the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description adds the windowing behavior and the process=true transformation semantics, but does not disclose anything about pagination limits, error behavior, or the assurance/strict interaction beyond what the schema already says.

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 statement is front-loaded, which is good, but the first sentence is an extremely long enumerated list of instrument domains and the per-channel return explanation is a separate dense clause. It is informative but bloated; several domain examples are redundant for an agent that already knows this reads generic instrument traces.

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, yet it spends most of its length on them anyway. For a 10-parameter tool it is reasonably complete on domain applicability but leaves the agent without routing guidance among the many sibling readers, so it is adequate rather than fully complete.

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 semantics the schema states (process turns an FID into a spectrum; the axis units for argmax_axis_value and x_range) and clarifies that 'each spectrum of a map is a sweep', but adds little that the parameter descriptions do not already contain.

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 ('one window of one sweep of a sampled signal or 1-D spectrum in physical units') and the extensive domain list (electrophysiology, chromatography, NMR, ITC, SPR, etc.) tells an agent exactly what kinds of files it operates on. It is clear about what is read, though it never explicitly contrasts itself with siblings like openreadout_spectra or openreadout_stats.

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

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

Usage is implied rather than stated: the domain enumeration and the process=true note give context for when the tool applies, but there is no explicit when-to-use vs when-not, and no routing to alternatives such as openreadout_stats or openreadout_table for the same signal data.

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=true, destructiveHint=false, idempotentHint=false), and the description usefully adds that each call is a one-shot look rather than a live stream, that polling uses the returned cursor, and that files are never locked. That is meaningful behavioral context beyond the annotations, though it omits rate/backpressure details.

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 with no filler, front-loading the core purpose and then the polling/event semantics. The event enumeration is long but informative and 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?

An output schema exists, so return-value explanation is unnecessary, and the description covers the essential polling model and non-locking guarantee. Combined with the rich schema, an agent has enough to call it correctly, though it could mention how to stop watching or cursor reset 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 description coverage is 100%, so the schema already documents every parameter (qc, dirs, limit, since, cursor, stall_after_s) in detail. The description only restates the cursor-polling pattern and the qc=true behavior, which the schema already provides, 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?

The description states a specific verb (follow/watch) and resource (directories an instrument writes to) and enumerates the event types emitted, so an agent knows exactly what this tool does. It doesn't explicitly contrast itself with siblings like openreadout_index or openreadout_search, but the streaming/polling nature is distinctive enough that confusion is unlikely.

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 clear operational guidance for continued use ("Poll with the returned cursor") and a safety note ("files are never locked"), but says nothing about when to prefer this tool over alternatives such as openreadout_index or openreadout_check, and no explicit when-not conditions.

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