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

Adds rich context well beyond annotations: append-only semantics ('never edits or removes saved versions or the user's notes'), host confirmation, version_conflict reconciliation, and the exact consequences of outcome=unchanged. It also discloses prose sanitization and refusal rules (no 'price target', 'hold rating', advisory phrasing) and that brief prose/excerpts are untrusted data, none of which annotations 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?

Every sentence carries a distinct rule, so little is wasted, but the content is delivered as a single dense paragraph mixing validation rules, outcome semantics, and sanitization guidance. It would be easier to apply if the third-party-content and formatting rules were separated from the core save semantics.

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 10-param mutation tool with nested content objects and no output schema, the description covers content requirements, outcome branches, conflict recovery, and error-prevention rules, which is substantial. Gaps remain on version/idempotency parameter semantics, but nothing critical to invoking the tool correctly 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?

With only 30% schema description coverage across 10 parameters, the description carries most of the load: it declares required content (thesis, five lens statuses, per-lens verdict and summary, findings with evidence_ids, counterarguments, uncertainties, reconsider_when), the conditional requirement that updated versions need header/short_description/summary, plain-text formatting constraints, and change_reason restrictions (initial_research first version only; no_material_change for unchanged only). It leaves run_id, expected_version and idempotency_key semantics largely 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: 'Save a completed research run as a new brief version'. The scope constraint (research:write permission, adds-only versioning) distinguishes it from read-side siblings like get_research and from begin_research_run.

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 about when to call it (after completing research, with outcome=updated vs unchanged) and what happens with unchanged ('Helmbeam saves nothing, this run expires, ... you tell the user in your reply'). It handles version_conflict recovery but never explicitly names alternatives such as begin_research_run or get_company_research as the route for other tasks.

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