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

Annotations already declare that this mutates state (readOnlyHint=false) but is not destructive and is closed-world. The description adds meaningful context with 'advisory', signaling the locks are cooperative rather than enforced. It does not disclose lock expiry/TTL behavior, conflict handling, or the effect of the force flag, which are the behaviors an agent most needs.

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 short, front-loaded sentences with no filler; the purpose comes first and the action enumeration second. It is efficient, though the action list is a bit telegraphic.

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 six-parameter mutation tool with no output schema and no annotation detail on conflicts or expiry, the description is thin. It says nothing about lock duration, what a failed claim returns, what force overrides, or what list returns, leaving significant gaps an agent would need to call it correctly.

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 0%, so the description carries the full burden, yet it only mentions paths and the 'all' shorthand for release. Four of six parameters (repo, force, reason, ttl_minutes) are never explained, so the agent must guess at force semantics and TTL defaults from the name alone.

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 first sentence names a specific mechanism (advisory edit locks) and the concrete problem it solves (two sessions editing the same files). The second sentence enumerates the three actions, so the agent knows this is a lock-management tool. It does not need sibling differentiation since the siblings are unrelated collaboration tools.

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 rationale sentence implies when to use it (before editing shared files), and the action list hints at the lifecycle. However, there is no explicit when-to-use/when-not guidance, no mention of what happens on a conflicting claim, and no statement of which action applies in which situation beyond the parenthetical hints.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=false, so the safety profile is available. The description adds useful context that 'all' is a valid target and that omitting arguments disconnects the caller's only line, but it does not describe the effect of disconnecting or what happens afterward.

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?

The description is short and front-loaded, with no wasted sentences. The phrasing 'No arguments: your only line' is slightly compressed and awkward, but overall it remains efficient.

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 simple one-parameter disconnect tool with annotations and no output schema, the description is mostly complete: it covers the action, accepted target values, and default behavior. The main remaining gap is lack of guidance on when to choose this over related communication tools.

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 does explain that the optional target can be a handle, an agent, or 'all', and that omission targets the caller's only line, but it does not clarify handle formatting or any other constraints.

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 a specific action, 'hang up your line', and identifies possible targets: a handle, an agent, or 'all'. It is clear enough to distinguish from unrelated siblings, but it does not explicitly differentiate this tool from related communication tools such as send or reply.

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 implies that this is how you end a line, but it gives no explicit when-to-use guidance relative to siblings and no when-not-to-use conditions. The phrase 'No arguments: your only line' explains a default behavior more than it explains tool selection.

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

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

The description states that passing model/task/label 'tells peers what you are doing', i.e. broadcasting your activity to other users — a side effect that modifies shared state. This conflicts with the annotation readOnlyHint=true, which declares the tool does not modify its environment.

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 terse sentences with no filler, and the return-value summary is front-loaded. The first sentence is a cryptic noun list rather than a clean action statement, which slightly hurts readability.

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 read tool with annotations but no output schema, the description covers the key returns (online peers, lines, inbox count) and the optional broadcast params. It leaves 'lines' undefined and does not clarify the inbox-count overlap with the inbox sibling, so it is adequate but incomplete.

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 0% schema coverage, the description must carry parameter meaning, and it does add value by framing all three params (model/task/label) as activity advertisement to peers. However it never distinguishes the three fields or gives format/length context, so it only partially compensates.

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 enumerates what the tool surfaces (who is online, your lines, inbox count) but never states the action as a verb, leaving the agent to infer 'discover peers/status'. It also overlaps with the sibling 'inbox' tool by claiming to return 'your inbox count', muddying differentiation.

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 only guidance is 'Pass model/task/label to tell peers what you are doing', which explains parameter usage but not when to choose this tool over siblings like inbox or send. No when-not-to-use or alternative routing is given.

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

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.

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

Annotations already state this is a non-read-only, non-destructive, closed-world write, so the description is not on the hook for the safety profile. It does add one genuinely useful behavior — `to` notifies a running agent — but it says nothing about where the handoff lands, whether it persists or is overwritten, what happens with an absent/invalid `to`, or what is returned after publishing.

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?

Extremely compact and front-loaded: the core action leads, the field inventory follows, and the `to` side-effect is placed last. It earns its brevity, though the compression contributes to gaps elsewhere.

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?

A 12-parameter write tool with no output schema and 0% schema coverage needs the description to explain destination, persistence, notification behavior, and every parameter. This description omits the sole required parameter (title), two other fields, and all behavioral detail about what publishing actually does beyond notification.

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 the parameter burden across 12 parameters. It lists goal, done, decisions, next_steps, open_questions, gotchas, files, commits and `to`, but omits the required `title` entirely, plus `repo` and `summary`, and gives no format guidance (e.g. commit hash vs message, path expectations for files) beyond 'decisions (with reasons)'.

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 opens with a clear verb phrase, 'Hand work over', and enumerates the handoff payload, so an agent can tell this is a write/publish tool that produces a handoff record. It never names the sibling handoff_get or explains the publish-vs-retrieve split explicitly, so differentiation is only implied.

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?

Publishing a handoff at the end of a work segment is implied by 'Hand work over' and by the `to` notification clause, which hints at coordinating with a running agent. There is no explicit when-to-use / when-not-to-use guidance relative to send, memory_save, or reply, so the agent must infer the routing.

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

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

Annotations declare readOnlyHint=false, implying a side effect, and the presence of peek/include_read strongly suggests fetching can mutate read state — yet the description says nothing about this. The only behavioral detail given is that wait_seconds blocks until something arrives; the caps (limit 50, wait 120s) and any side effects are undisclosed.

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 tight sentences with zero waste, and the resource enumeration is front-loaded ahead of the blocking-wait note. Nothing is repeated from structured fields.

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 should say roughly what an inbox item looks like and which IDs it exposes for follow-up calls (reply, review_submit, handoff_get). It also leaves the read-state side effect unexplained. The wait_seconds behavior is at least covered, keeping this from being inadequate.

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% across 4 parameters, so the description bears full responsibility, and it explains only wait_seconds. peek, limit, and include_read get no meaning at all — an agent cannot tell that peek likely means 'read without marking as read' or what limit defaults to.

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 a concrete resource and enumerates its contents (unread questions, replies, reviews, handoffs), so the agent knows this is an aggregate inbox feed rather than a single-item fetch. However, there is no verb, and it never distinguishes itself from siblings like review_get, handoff_get, or recall, which an agent could reasonably choose instead.

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: 'for you' suggests a personal feed and wait_seconds hints at long-polling, but there is no explicit when-to-use, no exclusions, and no guidance to prefer review_get/handoff_get for a single known item. The agent must infer the polling vs. blocking-wait choice from a single clause.

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

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

Annotations already declare the mutation and non-destructive profile, and the description adds real policy the annotations can't convey: no secrets should be stored, and peer facts require declared source plus recorded evidence. It leaves unclear whether an update via id overwrites body wholesale or what confirm_new does.

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?

Three short sentences, no filler, with the mode-to-parameter mapping front-loaded. The phrasing is telegraphic to the point of being slightly cryptic ('Facts from a peer need source=peer and evidence of what you verified').

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 an 11-parameter mutation tool with no output schema and no per-parameter documentation, the description covers the operating modes but not enough of the surface for confident invocation. The undefined confirm_new parameter is the clearest completeness hole.

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% across 11 parameters, so the description carries the burden and only explains id, archive, source and evidence. The remaining parameters, notably confirm_new, plus the roles of title vs body, tags, scope, type and repo, are left for the agent to guess.

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?

Names a specific verb set (save/update/archive) and resource (a note in YOUR Neurons memory), and even maps each mode to its controlling parameter (id, id + archive). It does not contrast itself with siblings such as recall or recall_get, so an agent must infer the boundary between writing and reading.

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?

Mode selection is spelled out explicitly via parameters: no id = create, id = update, id + archive = archive. It also gives a conditional rule for peer-sourced facts (source=peer plus evidence). It stops short of naming when to prefer this over sibling tools or when not to save at all.

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

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

Annotations already declare readOnlyHint, destructiveHint=false and openWorldHint=false, so the safety profile is free. The description adds meaningful behavior beyond that: it enumerates the four corpora searched and makes clear the return is a list of "hits" requiring a second call to retrieve content — a non-obvious two-step interaction. It omits result ordering and the default of the limit parameter.

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?

Three short sentences, no filler: capability first, the use case second, the required follow-up last. Every sentence changes how the agent would call the tool.

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 no output schema and 0% schema description coverage, the description should work harder. It covers the search scope and the retrieval handoff, but an agent still cannot tell what limit defaults to or caps at, what repo_path does (and whether it is required when sources includes repo), or how hits are shaped.

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, and it only partly does: the four named corpora map one-to-one onto the sources enum (neurons, memory, sessions, repo), which is genuinely useful since the enum values are otherwise opaque. However, limit and repo_path get no mention at all, leaving half the parameters undocumented anywhere.

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 ("Search") and a precisely scoped resource set ("your memory files, past chats, Neurons notes and the repo"), with "YOUR OWN knowledge" drawing the boundary against external search tools like discover. The sentence "Open hits with recall_get" separates this search tool from its retrieval sibling without the agent needing to open either schema.

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?

Gives an explicit use case ("Use it to answer a peer's question") and an explicit follow-up step ("Open hits with recall_get"), which is clear routing guidance. It does not state when *not* to use it or name a competing search tool, so it stops short of full when/when-not coverage.

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

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

Annotations already declare readOnlyHint, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds one genuinely new constraint — "Your own data only" — but says nothing about what happens with an invalid or expired ref, or what the returned payload looks like.

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 short sentences with the action front-loaded and the scope caveat placed last; the parenthetical examples are dense but each carries distinct information. No filler sentences.

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 one parameter and no output schema, the description should clarify what a successful "open" produces and how errors on stale refs behave. It covers input shape adequately but leaves the return contract entirely implicit for a detail-fetching 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 carries the burden, and it does supply the main semantic content: an enumeration of ref shapes (`#12`, `memory:…`, `session:<id>@<line>`, `repo:<path>:<line>`). The grammar remains partial (the `memory:…` form is elided), keeping it below a 5.

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 ("Open a ref from recall") and backs it with four concrete ref-format examples, which makes it distinguishable from the sibling `recall` that produces those refs. It stops short of saying what "opening" yields, so it is clear but not fully differentiating.

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?

Sequencing is only implied by "a ref from recall" — the agent must infer this is the follow-up call after a `recall` listing. No explicit when-not guidance, and the description does not address overlap with siblings like `session_read` even though one accepted ref form is `session:<id>@<line>`.

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

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

Annotations already cover the safety profile (writable, non-destructive, closed-world). The description adds genuinely useful behavioral semantics beyond that: 'accepted' grants a permission request and 'rejected' denies it, which tells the agent that the status field triggers a real side effect. It stops short of saying whether that action is reversible or what the sender sees.

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?

Four very short sentences, purpose front-loaded, no filler. The telegraphic fragments ('Proposals: status accepted or rejected.') are efficient but slightly cryptic, which keeps it from a 5.

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 4-parameter write tool with no parameter descriptions and no output schema, the description covers purpose and the status decision, but leaves the default status, the nature of refs, and any confirmation of what happens after a reply or an accept noticeably under-specified.

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 0%, so the description carries the burden. It does explain the meaning of 'accepted'/'rejected' in context and 'with sources' hints at the refs array, but the 'answered' enum value and the refs format (up to 30 strings) are never clarified, and body length limits are only implied by 'short'.

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 (Answer) and a specific resource (a message addressed to you), which implicitly differentiates it from the sibling 'send' for new messages. It doesn't explicitly name the alternative, so it falls short of a 5.

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?

'Only what was asked, short, with sources' gives content/style guidance, and the proposal/permission-request sentences tell the agent which status to pick in two situations. However, there is no explicit when-to-use-this-vs-'send' or 'review_submit' guidance, and the default 'answered' case is left unstated.

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

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

The parenthetical "(and claim)" usefully discloses that this is not a pure read despite the "get" name, which is consistent with readOnlyHint=false and destructiveHint=false. But it does not say what claiming does to other users, whether claiming an already-claimed review fails, whether claiming is idempotent, or that the no-id listing path is read-only — meaningful gaps for a tool that mixes read and mutation.

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 clauses, front-loaded on the mode distinction, with nothing wasted. The telegraphic phrasing ("With id: ... Without: ...") is efficient but borders on cryptic, costing a point.

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?

A five-parameter, dual-mode tool with no output schema, no parameter descriptions, and mixed read/mutate behavior demands more than one sentence. Missing: the repo parameter's role, defaults for status/mine/claim, the claim-id dependency, and any hint of what the listing or claim result looks like.

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 0% schema description coverage the description does the heavy lifting, and it explains id as the mode switch and names status and mine as list filters. It never mentions the repo parameter at all, gives no defaults (what happens with zero arguments?), and the claim parameter is only hinted at with "(and claim)" — the id+claim interaction an agent most needs is left unstated.

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 the two modes concretely: with an id it retrieves (and optionally claims) a specific review, without an id it lists reviews. That dual-mode framing plus the named filters (status, mine) tells an agent what the tool does and roughly how it differs from siblings like review_request and review_submit. Minus one point because "open" is ambiguous (retrieve? create?) and the resource being operated on is only implied by the title.

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 keyed entirely to the presence of the id parameter, which is genuinely actionable guidance for choosing the mode. However, there is no mention of when to prefer this over review_request/review_submit/claims, and no prerequisites or exclusions are stated; usage is implied rather than spelled out.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds real context beyond that: the work is delegated to a 'running' agent and results are delivered asynchronously to the inbox rather than returned inline. It omits what happens if no agent is available and any cost/timeout behavior, so it stops short of full transparency.

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?

Three short clauses with the core action front-loaded and the input-mode hint immediately after; no filler. It is arguably too terse for an 8-parameter tool, which costs it the top score.

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 an 8-param, no-output-schema tool the description covers what an agent needs to call it correctly: what it does, the two input shapes, that the response is asynchronous (findings arrive in the inbox, so review_get is implied), and the secrets constraint. Remaining gaps are parameter naming rather than missing task-critical information.

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 the parameter burden. It explains the important ambiguity — diff vs base/head + files are alternative ways to specify the change — but leaves `to`, `repo`, `focus` (up to 4000 chars) and `title` entirely undefined, so half the parameters remain opaque.

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 a specific verb and resource: ask a running agent to review a change, with the two supported input shapes (diff text, or base/head + files). It is clear what the tool does, though it never names the sibling review_get/review_submit tools that an agent would use to retrieve or supply the result, so differentiation is only implicit via 'findings come back to your inbox'.

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?

It does state the two mutually exclusive invocation modes and a hard constraint ('No secrets in the diff'), which is genuine usage guidance. However, it never says when to choose this over review_get or review_submit, nor what prerequisite state is needed (an agent actually being 'running'), so the agent must infer the surrounding workflow.

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

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

Annotations establish the safety profile (mutation, non-destructive, closed-world). The description usefully adds the side effect that the requester receives the result in their inbox, which the annotations do not convey. It says nothing about resubmission/idempotency, whether finishing closes the review permanently, or whether verdict=approve triggers downstream effects.

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 short sentences, front-loaded with the action and the required payload, with no filler. It is, however, terse to the point of under-specification given a four-parameter schema with a nested array.

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?

A mutation tool with a rich nested findings schema, zero schema description coverage, and no output schema. The description should explain the id, the findings structure, and what happens on submit, but it leaves an agent to reverse-engineer the payload from the raw schema.

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 the load. It names three of four parameters but adds no meaning: it never explains that id is the review identifier, what each verdict value implies for the requester, or how the nested findings objects (file/line/severity/title/detail/suggestion) should be populated.

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 ("Finish a claimed review") and enumerates the payload (verdict, summary, findings), which distinguishes it from review_request and review_get. It doesn't carve out the boundary against reply/send, but the action is unambiguous.

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?

"Claimed review" implies a prerequisite (the review must already be claimed, presumably via claims), but the description never says so explicitly or names the alternatives for unclaimed/other review operations. Usage is inferable rather than stated.

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

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

Beyond the annotations, the description discloses two high-value traits: a hard failure precondition (messages only travel over lines the user connected in the Neurons dashboard; without one this fails) and blocking semantics (`wait_seconds` blocks for the reply, up to the schema's 120s cap). It does not explain what a `proposal` triggers downstream or what happens when the wait expires without a reply.

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?

Dense and front-loaded: the routing targets come first, then fallback behavior, then the blocking caveat, with no filler sentences. The heavy inline quoting makes it slightly harder to scan than it needs to be.

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 an 8-parameter tool with no output schema and only three boolean annotations, the description covers routing, failure, and blocking well but leaves a third of the parameters undocumented and never says what the reply actually looks like or what happens on timeout. Adequate, with clear gaps.

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% across 8 parameters, so the description must carry the load. It explains `to`, `kind`, `local_first`, and `wait_seconds` well, but `refs`, `repo`, and `subject` receive no mention at all, and "keep it short" is vague next to the body's 8000-character maxLength.

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 gives specific verbs (ask/tell/suggest) mapped to the three message kinds and enumerates valid targets ("codex", "claude", a handle, "all", "local"). It does not explicitly distinguish this from the sibling `reply` tool, so an agent must infer that `send` starts a conversation while `reply` continues one.

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?

It states when to pick each kind (question/note/proposal) and when to use "all" (for a second opinion) and "local"/"local_first" (free local model). What is missing is a when-not-to-use clause, particularly versus `reply` and `handoff_publish`.

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

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

The annotations already establish this as a safe, read-only, non-destructive operation, and the description adds useful disclosure that returned session content is redacted and includes text and tool names. However, it says nothing about pagination, defaults, limits, or how the optional parameters affect 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?

Two short sentences with the main behavioral distinction front-loaded and no wasted verbiage. The terse style is appropriate, even though it contributes to the semantic gaps captured elsewhere.

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 tool with seven optional parameters, no output schema, and no schema descriptions, the description is too thin. It explains the central list/read distinction but omits how pagination, tail, limits, and location scoping (here) alter results.

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, but it only explains handle/native_id and their absence/presence effect. It leaves here, tail, limit, offset, and max_chars completely undocumented, which is a significant gap for seven parameters.

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 clearly states two modes: listing the agent's own past sessions when no identifier is supplied, and reading a specific session when handle/native_id is supplied. The verb and resource are identifiable, though it does not explicitly differentiate itself from siblings like recall or discover.

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?

It gives explicit conditional guidance: omit handle/native_id to list sessions, include one to read a session. It does not mention alternatives among sibling tools, but the mode-selection condition is clear enough for invocation.

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