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

Beyond annotations, it discloses side effects (advances the node's liveness clock separately from operator standing), failure behavior (fails closed on bad/absent/replayed signature or stale timestamp), and the auth model (signature is the auth). No contradiction with readOnlyHint=false or idempotentHint=false.

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 but logically organized: purpose, auth, payload, effect, failure mode, and return format. The example 'call federation_node_report_in with arguments {}' is misleading given five required parameters, and 'CO 486' adds jargon. Still, each sentence carries unique information.

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, the description fully specifies return values: { ok: true, last_report_in, report_in_count } or { error, code }. It also covers auth requirements, failure cases, and side effects, making it complete for a complex node-reporting operation.

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 baseline is 3. The description adds meaning by explaining the signed envelope { node_id, nonce, timestamp, route } and that the signature is verified against the bound key, tying parameters together. However, it mentions 'route' which is not in the schema, and other parameter details largely restate the schema.

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: a self-hosted node reports in to the hub on its own initiative, carrying version, catalog digest, and journal head. It clearly differentiates from sibling federation tools by emphasizing node-signed, node-initiated semantics and the mothership link role.

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 explicitly establishes when this tool is for node-initiated reporting and that the hub never calls the node, and clarifies that no operator token is required. It does not name sibling alternatives or state when not to use it, but the node/operator auth distinction provides clear routing context.

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