arf2_annotate_identities

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

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

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

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

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

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

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

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

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It thoroughly explains max_rows pagination and ordering semantics, but says nothing about file_path beyond the schema's type, leaving one of two parameters unexplained.

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

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

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

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

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

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

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