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

Beyond annotations, it discloses two substantive behaviors: values are stored verbatim with no unit conversion, and duplicate equivalent readings are merged with the surviving id returned. That dedup/merge behavior is genuinely useful context an agent cannot get elsewhere. One tension worth noting: dedup means a repeat call has no additional effect, which sits awkwardly with idempotentHint=false, though the merge is conditional on equivalence so it is not a clean contradiction; error modes and auth are still unaddressed.

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 sentences, front-loaded with what is recorded, then the storage and dedup semantics. No restated title, no filler, and the most surprising behavior (deduped success) is called out where an agent will see it.

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 5 params at 0% schema coverage and no output schema, the description covers the core write and the dedup response shape but leaves gaps: the notes and unit fields go unmentioned, observedAt format is unspecified, and failure behavior is absent. Adequate to call correctly in the happy path, thin for a multi-field mutation 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 0%, so the description must compensate for all 5 params. It does add real meaning for three of them: biomarker is free-form text, value is a string stored as-is, unit exists but triggers no conversion, and observedAt is implied by 'at a point in time'. It says nothing about notes, and no formats (e.g., accepted timestamp syntax) are given, so the compensation is partial.

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: records a generic measured value / tracked metric, distinguishing it as free-form (arbitrary biomarker name, string value) rather than a curated metric. An agent can tell it is a write into the observations store, though it never names the sibling it differs from (vora_add_biomarker, still_add_biomarker_reading), so the differentiation is inferred rather than stated.

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: 'generic' and 'free-form biomarker name' suggest this is the fallback when no typed add-tool fits, but the description never says when to prefer it over vora_add_biomarker or vora_add_symptom. There are no exclusions, prerequisites, or named alternatives, leaving routing between the many vora_* add tools to inference.

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