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

With no annotations, the description carries the full behavioral burden. It discloses that the tool only relays caller-built artifacts, that prepare returns the current head, and that stale seq/prevHash triggers chain_conflict. It does not explicitly describe the submit response or state that the append is permanent, but the core behavior is clearly conveyed.

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 dense sentences front-load the operation and endpoint, then organize the two modes and their sequence. Every clause earns its place, including the failure-mode warning and the relay-only clarification, with no filler.

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, two-mode tool with nested objects, no annotations, and no output schema, the description covers the essential workflow, auth requirements, and error condition. The main gaps are the lack of a submit response format and the unexplained notary vs relay-mode distinction that appears only in 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 only 57%, so the description adds necessary meaning by explaining mode semantics, the auth requirements for prepare vs submit, and that envelope/hash/signature/payload must be constructed by the caller. The schema already documents many fields, and the description fills the critical workflow gaps rather than repeating schema text.

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: 'Append a signed, hash-chained message to an active session' and provides the exact endpoint. This clearly differentiates send_message from lifecycle siblings like start_session and close_session, despite the title being more abstract.

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 explicit mode-level guidance: always run prepare first unless certain of the head, because a stale head is rejected with chain_conflict. It also explains what each mode is for and the sequence between them, leaving no ambiguity about how to invoke the tool correctly.

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