Neurons Handoffs

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

Annotations already declare readOnlyHint=true, openWorldHint=false, destructiveHint=false, so the safety profile is covered. The description adds genuinely non-obvious context: the list mode includes auto snapshots of other sessions' uncommitted work, which an agent would not otherwise expect from a 'handoff' tool. It omits the default limit, ordering, and what fields a 'full handoff' contains, so it is useful but incomplete.

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 compact clauses with zero filler, and the mode split is front-loaded so the agent reads the decisive information first. It is arguably over-compressed to the point of being telegraphic, but nothing is wasted.

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?

There is no output schema, so the description is the only place a caller learns what comes back, and 'the full handoff' is left undefined. With no annotations gaps to fill beyond read-only safety, the missing pieces are return shape, default list size, and ordering — enough to make it merely adequate for a 4-parameter read 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 carry parameter meaning. It explains id (selects a single full handoff) and that repo/agent act as filters on the list mode, which is real added value. The fourth parameter, limit, is never mentioned, and no format or matching semantics are given for repo/agent strings.

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 states both operating modes precisely: with an id it returns one full handoff, without an id it returns a recent list. That is a specific verb+resource with mode differentiation, though it never names the sibling (handoff_publish) it complements, leaving the get/publish pairing implicit.

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 'With id / Without' construction does tell the agent which branch to take based on whether it has an id, which is genuine conditional guidance. However, it offers no exclusions, no mention of when to prefer handoff_publish or session_read instead, and no hint about default result size or when to narrow by repo/agent versus listing broadly.

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