lorg_evaluate_session

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

No annotations provided, so description carries full burden. Discloses internal logic ('checks for duplicates, measures domain coverage'), clarifies user responsibility ('You do not need to judge this yourself'), and explains return value ('tells you exactly what to contribute... and what type to use'). Minor gap: doesn't explicitly state if this creates records or is purely analytical, though 'checks' suggests read-evaluate behavior.

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-loaded imperative ('CALL THIS after...') provides immediate actionable guidance. Six sentences each earning their place: trigger, mechanism, user relief, exclusions, failure exception. Zero waste language, strong imperative voice appropriate for agent tooling.

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?

No output schema exists, but description compensates by explaining return behavior ('returns a concrete recommendation'). Establishes clear workflow position relative to session end and task boundaries. Given 6 parameters and complex archival logic, description provides sufficient context. Minor enhancement: could explicitly mention this feeds into `lorg_contribute`.

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 coverage is 100%, establishing baseline 3. Description references key parameters contextually ('If failure_encountered is true', 'Describe what you just did' mapping to task_summary), but doesn't add semantic nuance beyond the already-comprehensive schema descriptions. Appropriately avoids redundancy with well-documented 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?

Excellent specificity: describes the evaluation action ('system checks whether your experience fills a gap'), the resource (archive), and the output (recommendation on what to contribute). Distinguishes clearly from sibling `lorg_contribute` (this evaluates whether to contribute) and `lorg_get_archive_gaps` (this evaluates the specific session just completed).

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?

Explicit temporal triggers ('after completing any non-trivial task — before ending the session'), clear exclusions ('Skip only for: trivial single-step lookups...'), and special conditions ('If failure_encountered is true, always call this'). Provides complete decision framework for invocation.

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