neuron_session_checkpoint

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

With no annotations, the description carries the full behavioral disclosure burden, and it delivers: it precisely discloses the two state mutations (cursor increment and item relocation to completed) and characterizes the call as 'quick' and hot-path. It omits idempotency and failure-mode details, but the core side effects are transparently communicated.

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 with zero waste: the first front-loads the core state transition, the second adds high-value workflow positioning with concrete examples. Every phrase earns its place.

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 low-complexity tool (2 required params, no nesting, no output schema), the description covers what it does, the exact state changes, and when to call it. Missing only return-value or failure-behavior notes, which are minor given the tool's simplicity and the strong schema coverage.

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% so the baseline is 3, but the description adds meaning beyond the schema by revealing that completed_item originates from working_set and by tying session_id to the active per-action recipe context. This enriches the agent's mental model of both parameters without repeating the schema text.

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 names concrete operations ('increment cursor,' 'move an item from working_set to completed') on a specific resource (session checkpoint), making the tool's function unmistakable. It also differentiates itself from the large sibling family by framing itself as the per-action progress update rather than a session save, recipe completion, or diagnostic call.

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 description explicitly states when to use it — 'the hot-path call that recipes use after each action' — with concrete examples (after scraping one profile, sending one message). This gives clear timing context, though it stops short of naming alternatives or stating when-not-to-use cases (e.g., vs neuron_recipe_complete or neuron_session_save).

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