Compute Topological Fingerprint (TDA)

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

Goes well past the annotations (readOnly/idempotent/closed-world) by disclosing H0/H1 at a 15-Å Vietoris-Rips 2-skeleton, that H2 is NOT computed, the 4-Å fallback behavior, and that the result flags which method ran. It also covers external dependency (fetching the AlphaFold model) and the no-structure case, which is exactly the kind of behavioral context structured fields can't convey.

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 function is front-loaded in the first sentence and the caveat stack follows in a sensible order. There is some redundancy — the GUDHI-vs-fallback story is stated twice (once mid-paragraph, again in the 'Full persistent homology needs the optional [tda] extra' sentence) — which could be collapsed.

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

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

For a single-parameter tool an agent could trivially misuse as a general structural-biology answer, the description supplies the failure modes (no AlphaFold model), the degraded-mode flag, the dimensionality, and the scientific limits. Return values are already covered by the output schema, so nothing an agent needs before calling 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?

Only one parameter, and the schema itself fully documents it with a format description and a strict accession/isoform regex, so the description's baseline of 3 is appropriate. The description merely echoes 'uniprot_id' in backticks without adding resolution, isoform, or lookup-failure 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 verb and resource ('Compute a rotation-invariant topological fingerprint of a protein's fold') and pins down the concrete output (an exploratory 64-dimensional geometric/topological feature vector from Cα coordinates), so the agent knows exactly what it gets. It never names the obvious close sibling 'compare_proteins_topologically' (or 'get_protein_structure'), so the pairwise-vs-single-protein distinction 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?

Clear context for use: the agent is told the full homology path requires the optional [tda]/gudhi extra, that a coarse fallback runs otherwise, and that the tool is explicitly NOT a substitute for sequence alignment, RMSD, or functional-homology assessment. That rules out several misuses, but it stops short of naming the sibling tool to choose instead when a comparative topological analysis is actually wanted.

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