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

Annotations only say readOnlyHint=false, idempotentHint=false, and destructiveHint=false. The description goes further by disclosing that the signature is the authentication, that queue ownership is enforced by construction, that expired acts are skipped, and that past-delivery acts dead-letter. It stops short of explaining whether a successful drain durably removes acts from the broker or what happens if the client fails after receiving them, which matters for a drain operation.

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 purpose stated first and each sentence carrying meaningful security or behavioral detail. However, the misplaced and inaccurate example at the end weakens the structure: it is presented as an invocation template while being impossible given the required parameters, and it should be corrected or removed.

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 mutating, non-idempotent tool with no output schema, the description covers identity, auth, queue scoping, expiry/dead-letter behavior, and the response shape. Gaps remain around error-code semantics, whether acts are removed atomically on collection, and redelivery behavior if the caller never succeeds, plus the incorrect empty-arguments example undermines the completeness of the calling guidance.

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 a baseline of 3 is warranted, and the description does add useful context by explaining that node_id is an authenticated identity rather than a filter and that signature covers a canonical envelope. However, the final example, 'call federation_node_drain_queue with arguments {}', directly contradicts the five required parameters in the schema. This is actively misleading: an agent following the description would omit node_id, nonce, timestamp, signature, and alg.

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 sentence names a specific operation and resource: collect brokered acts queued for your node. It then sharpens the scope with a construction-level guarantee that a node drains only its own queue, which distinguishes it from other federation node tools without needing to inspect a 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?

The description explicitly frames the tool as poll-shaped and notes that the node collects on its own initiative. It also states the authentication precondition ('No operator token; the signature is the auth'). It does not name an alternative to use instead, but it references report-in as a comparable signing pattern and gives enough context for when this call is appropriate.

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