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

Annotations already establish that this is a read-only, non-destructive, closed-world calculation. The description adds meaningful behavioral context beyond that: it reports both monoisotopic and average mass, supports m/z at multiple charge states, validates against pyteomics, and treats ProForma modifications monoisotopically. It does not contradict 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 description is front-loaded with the main calculation and then adds the sequence-format distinctions that matter for correct invocation. It is dense but not wasteful; the ProForma examples earn their space by clarifying valid input syntax.

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 and parameter descriptions are complete, so the description does not need to explain return values or every nested parameter. It covers the non-obvious input modes and modification syntax well. The main remaining gap is the absence of explicit guidance about related tools and when this one is preferred.

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 usefully adds semantic detail beyond the schema: charge states, ion types for plain sequences, and concrete ProForma modification examples as masses or Unimod identifiers. Nested record-reference parameters such as _subject and _files are left largely to 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 states a specific calculation over a specific resource: monoisotopic and average peptide mass plus m/z at each charge state. It also distinguishes plain one-letter sequences from ProForma peptidoforms with modifications. It does not explicitly name or rule out close siblings such as fragment_ions or isotope_envelope, so it stops short of full sibling differentiation.

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 intended use is clearly implied: calculate peptide mass/m/z, use ionType for plain sequences, and use ProForma syntax for modified peptidoforms. However, there is no explicit when-to-use guidance, no when-not-to-use guidance, and no named alternatives among the many related sibling tools.

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