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

The description adds considerable behavior beyond the annotations: expired acts are skipped, past-delivery acts dead-letter, the operation is poll-shaped, the node signs the canonical envelope, and the auth is the signature rather than an operator token. This meaningfully enriches the sparse annotation set and gives an agent accurate expectations about side effects and security boundaries.

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 dense and front-loaded, with the core purpose in the first sentence and supporting behavioral details following logically. It is longer than minimal, but the extra sentences about expiry, dead-lettering, polling shape, auth, and return shape all carry meaningful information. The style is slightly run-on, but the content 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?

The tool is a mutating queue-drain operation with no output schema and modest annotations, so the description must carry the full context. It does: auth model, node isolation, expiry/dead-letter behavior, polling semantics, and the response shape. Even error shape is disclosed. This is complete enough for an agent to invoke the tool 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 100%, so the baseline is 3. The description adds value by explaining how node_id, nonce, timestamp, and signature relate to the signed canonical envelope and authentication, and it clarifies that the drain is keyed by the authenticated node id, not by any supplied filter. This goes beyond the individual schema descriptions, though it does not exhaustively map each parameter.

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 by naming the exact verb and resource: 'Collect brokered acts queued for your node.' It further distinguishes itself from related node operations by emphasizing that a node drains only its own queue and that the drain is keyed by authenticated node id, not a supplied filter.

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 clearly frames when to use the tool: a node should poll to collect its own queued acts, and no operator token is involved because signature-based auth suffices. It gives solid context and a clear exclusion ('one node can never collect another's acts'), though it does not explicitly name alternative tools or spell out when not to use it.

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