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

With no annotations, the description carries the full behavioral burden and does so well. It discloses atomicity, ownership constraints, takeover rules, lease renewal, lease clamping, and that expiry is checked during tool calls without background timers.

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 front-loaded with the core action and then adds compact lifecycle details. Every sentence provides useful behavioral context without redundant restatement of the tool name.

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?

The description is strong for a concurrency-sensitive claim operation, especially given the output schema covers return values. Minor gaps remain around explicit sibling-tool selection and message_id parameter semantics.

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 should compensate. It explains lease_seconds meaningfully through renewal and clamping behavior, but message_id is only implied by 'unread message' and lacks explicit semantics or 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 verb and resource: atomically claiming an unread message for this MCP server process. The scope is clear, but it does not explicitly distinguish itself from siblings such as release_message, mark_read, or receive_messages.

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 explains claim lifecycle rules, including active-claim restrictions, renewal behavior, and expired-claim takeover. However, it does not explicitly say when to choose this tool over alternatives like receive_messages or mark_read.

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?

With no annotations, the description carries the full burden and does so unusually well: it discloses that status never returns goal or message text (no payload, no secrets), that cancel does not roll back already-produced side effects, that repeating the current state is an idempotent no-op, and that a conflicting terminal state is rejected so the two agents cannot fight over the outcome. Those are exactly the side-effect, idempotency, and failure-mode facts an agent needs before mutating.

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 purpose sentence followed by one dense clause per action, so the agent can jump straight to the relevant mode. The 'never the goal text, never message text (no payload, no secrets)' line is slightly redundant, and the unexplained 'outcome a'/'outcome c' shorthand spends words without transferring meaning.

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?

An output schema exists, yet the description still usefully previews what status returns (state, turn_count/max_turns, expiry, recent transitions, in-flight message), and terminal-state semantics are fully covered. Remaining gaps are the undefined outcome taxonomy and the absence of any note on identity/auth requirements or invalid-conversation_id behavior for a tool whose whole premise is agent-scoped access.

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% and the action parameter has no enum, so the description is the only place the valid action values and their meanings appear — the four 'status/cancel/complete/needs_human' labels plus per-action state constraints. conversation_id gets only indirect semantics ('a conversation only its two agents belong to'), and the list is never explicitly declared exhaustive, so it nearly but does not fully compensate.

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 concrete verb pair ('Inspect or steer') and resource ('a conversation'), then enumerates four distinct operations (status, cancel, complete, needs_human) with their effects. The scope constraint 'only its two agents belong to' signals the ownership boundary. It never names a sibling tool, so differentiation from send_message/start_conversation is left to inference rather than stated.

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?

Each action carries its own applicability condition: cancel is 'allowed from active/blocked/needs_human', complete and needs_human are 'only from active'. That is genuine when-to-use guidance. It stops short of naming alternatives or saying when not to call this at all, and the '(the review worker's outcome a)' / '(outcome c)' references point at an undefined taxonomy the agent cannot resolve.

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?

With no annotations provided, the description carries the full burden and does: it discloses idempotency guarantees (exclusive flock, no duplicate sessions), the supervision semantics of disable (finishes the current worker, then exits), and a safety boundary ('No PID is ever killed from here'). It also scopes the returned data ('never task payload'), which preempts a plausible agent assumption.

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 with identity and scope, then segmented by action, with zero filler sentences. The register is telegraphic ('removes the disabled marker', 'writes the marker'), which compresses well but occasionally forces the reader to reconstruct grammar rather than read meaning directly.

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 single-parameter tool with an output schema and no annotations, this covers the operations, their side effects, idempotency, and the safety boundary. What is left unsaid is failure behavior (e.g., what status reports when no listener is running, or what happens on enable when already enabled) and any auth requirement beyond the AGENT_ID scope.

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% and the single 'action' parameter has no enum, so the description must supply the value domain — and it does, defining status/enable/disable with the exact behavior of each. It falls short of 5 because the values are only implied by colon-prefixed labels rather than stated as a closed set, leaving open whether other actions exist.

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 opening line names a specific resource (this agent's own background listener) and a hard scope limit (AGENT_ID only), and the three sub-operations status/enable/disable define exactly what 'manage' covers. It is clearly distinct from the messaging siblings, though the generic verb 'Manage' does the least work in the sentence and 'listener' is only defined indirectly via the task/worker/flock details.

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?

Each action is given a use condition: status to inspect, enable to clear the disabled marker, disable to stop taking new work gracefully. The closing line 'Dispatch itself stays governed by systemd/config.json auto.<agent>' is an explicit exclusion telling the agent not to reach for this tool to change dispatch, though no sibling or alternative tool is named as the route for that.

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?

With no annotations, the description carries the behavioral burden and discloses important traits: recipient-only authorization and silent skipping of already-acknowledged, foreign, and actively claimed ids. It also notes compatibility for free messages and expired claims, though it could say more about the acknowledgement side effect and return 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?

The description is front-loaded and appropriately short for a one-parameter tool. Most sentences earn their place by covering authorization and skip behavior, though the final compatibility sentence is somewhat dense.

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?

An output schema exists, so return values need not be described. For a simple one-parameter tool, the description covers the key invocation constraints and edge cases, with the main remaining gap being explicit guidance relative to sibling message-handling 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 compensate for the undocumented message_ids parameter. It clarifies that ids refer to messages and are subject to recipient-only acknowledgement, but it does not explain array/batch behavior, duplicate handling, or empty-input semantics.

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 verb and resource: acknowledge messages by id. It also clarifies the recipient-only scope. It does not explicitly distinguish mark_read from siblings such as claim_message or receive_messages.

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 gives clear context that only the recipient can acknowledge and that some ids are skipped silently. However, it does not explicitly say when to use mark_read instead of claim_message, release_message, or receive_messages.

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?

With no annotations, the description carries the full burden and does a solid job: it discloses claim-hiding, the wait cap of MAX_WAIT_SECONDS (30), non-destructive read semantics (stays unread until mark_read), and per-message metadata fields. However, it omits auth/AGENT_ID resolution, empty-result behavior, and any error or timeout semantics.

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 short sentences, front-loaded with the core action, which is good. But the trailing "cursor is the last returned id, or None" sentence does not fit an input-side description and is partly redundant given the tool has an output schema, so it does not fully earn 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 two-parameter, no-annotation polling tool, the description covers the essential pull semantics: claimed messages are hidden, the wait cap, and unread persistence. The output shape is already covered by the output schema, and the only meaningful gap is the undocumented limit parameter.

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. It explains wait_seconds including the hard cap, but says nothing about limit, its default of 20, or what happens if limit is exceeded; "cursor is the last returned id" refers to an output field, not a parameter, so it does not help parameter use.

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 with scope: "Return available unread messages addressed to AGENT_ID, oldest first." The unread/address-to-this-agent scope and the oldest-first ordering distinguish it from siblings like claim_message and mark_read, though no sibling is named explicitly.

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 implied rather than stated: messages claimed by another process are hidden, and "messages stay unread until mark_read" hints at the follow-up tool. There is no explicit statement of when to choose this over listener or claim_message, 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?

No annotations are provided, so the description carries the full behavioral burden. It discloses the central effect—releasing the active claim without acknowledging the message—but does not clarify edge cases, required permissions, idempotency, or behavior when no active claim exists.

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 definition is a single front-loaded sentence with no filler. Every phrase contributes to specifying the operation and its contrast with acknowledgement.

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?

An output schema exists, so return-value detail is not required, and the operation is simple with one parameter. However, the absence of annotations and the lack of usage or parameter guidance leave meaningful gaps for correct invocation.

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% and the single parameter, message_id, is undocumented in the schema. The description does not mention the parameter or explain its role, so it fails to compensate for the missing schema semantics.

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 uses a specific verb, 'Release', and names the concrete resource, 'this process's active claim', making the operation identifiable. The phrase 'without acknowledging the message' also distinguishes it from acknowledgement-oriented siblings such as mark_read.

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 when this tool applies by contrasting it with acknowledging the message, but it does not explicitly state when to choose it over siblings like mark_read or claim_message. Usage is inferable but not fully guided.

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?

With no annotations, the description carries the full burden and does so well: it discloses that response_timeout_seconds is pure metadata with nothing timed, deleted, or resent, that duplicate (sender, dedup_key) inserts return the existing message with duplicate=true, and that conversation sends are validated atomically with an in-flight limit and turn limits that reject and move to needs_human. These are non-obvious side effects an agent could not infer.

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 with the one-line purpose, then organized by topic (reply/timeout, dedup, conversation semantics). It is long, but nearly every clause carries operational detail; the parenthetical 'e.g. a task id' is the only clearly disposable fragment.

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 7-parameter mutation tool with no annotations and an output schema present, the description covers side effects, idempotency, validation failure modes, and parameter interactions. Nothing an agent needs to call it safely is missing, and return values are correctly delegated to the output 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% across 7 parameters, so the description must compensate and does: it defines reply_to, dedup_key semantics, conversation_id inheritance from reply_to, the clamp range and default persistence for response_timeout_seconds, and the three kind values with their differing wake behavior. Only recipient and text are left implicit, which is reasonable given their names.

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 ('Send a message to another agent') and pins down the implicit sender identity ('this process's AGENT_ID'), which the agent could not know otherwise. It is immediately distinguishable from the receiving-side siblings (receive_messages, claim_message, release_message).

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 concrete conditional guidance: use reply_to to answer requests, use dedup_key for idempotent retries, pass conversation_id/kind for dialogue sends, and omit kind for a plain message. It also directs behavior after a deadline ('report it and wait for human direction'). It stops short of explicitly stating when to prefer start_conversation over a plain send, which is the main missing routing cue.

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?

With no annotations, the description carries the full burden and does so richly: it discloses the conversational state machine, the auto-posted root task as turn 1, the turn accounting rule ('counts every automatic worker turn, result reviews included'), clamping ranges, the needs_human escalation path, and dedup idempotency returning duplicate=true. This is exactly the behavioral context an agent cannot infer from the schema.

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 with purpose then behavior, and nearly every clause adds operational information. It is somewhat dense and the parenthetical '(goal, initiator = AGENT_ID, recipient, state active)' plus the mid-sentence line break cost a little readability, but there is little true waste.

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 state-creating tool with an output schema and no annotations, the description covers lifecycle, limits, escalation, idempotency, and the sibling distinction. An agent has everything needed to invoke it correctly; only response_timeout_seconds is left to the 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 compensate, and it does for five of six parameters: max_turns (clamped 2..20, hard cap 20, counts all worker turns), expires_in_seconds (60..86400 s window), dedup_key (idempotent restart semantics), recipient (listener picks up), goal (posted as root task/turn 1). response_timeout_seconds is never mentioned, leaving one parameter's meaning entirely undocumented.

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 states a specific verb and resource — 'Start a bounded autonomous conversation with another agent' — and the closing sentence explicitly contrasts it with the sibling send_message ('An ordinary send_message never creates a conversation'). An agent can distinguish it from conversation, listener, and send_message without opening the 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?

It gives clear triggering context ('so the recipient's listener picks it up without any manual phrase'), names the alternative that does NOT apply (send_message), and specifies when the conversation ends (completed, needs_human, turn limit, expiry, cancellation). No explicit 'prefer X when Y' for the other siblings like claim_message, so it falls short of a 5.

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