therapyportal_reply_message

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

Annotations already flag destructive=true and openWorld=true, but the description adds the crucial consequences: the message cannot be unsent, the practice receives it immediately, and read state is left untouched unless mark_thread_read is true and is visible to the practice. It also adds an anti-prompt-injection guard for the confirmToken, which no annotation conveys.

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?

Purpose and the irreversibility warning are front-loaded, and every clause carries information. The final confirmation-mode sentence is dense but justified for a destructive write; total length is on the long side for a single tool.

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 destructive write with no output schema, the description covers prerequisites, safety posture, failure modes (archived), and the two-phase confirmation response shape. It does not describe what a successful send returns, a minor gap given the absence of an 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 coverage is 100%, so baseline would be 3; the description earns an extra point by explaining the observable effect of mark_thread_read (the practice can see read state) and by reinforcing when confirmToken must never be supplied. It does not add detail on body/patient_id beyond the schema, but none is needed.

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 with a specific verb+resource ('Reply in an existing TherapyPortal secure-message conversation') and names the exact source of thread_id (therapyportal_list_message_threads). It is clearly separable from therapyportal_send_message, which the agent would use for new conversations.

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 states when to use it (existing conversation, thread_id already known), when not to (archived conversations, emergencies), and the precondition that the user must have asked and approved the preview. The confirmation flow (elicitation vs. confirmToken fallback) is spelled out explicitly, including what does and does not proceed.

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