Reply to a Messenger / Instagram DM

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

The description delivers far more than the sparse annotations (readOnlyHint:false, openWorldHint:true) require. It discloses the real-person consequence with a mandatory confirmation gate, the 24-hour window check behavior with and without conversationId, the outbound 'refuses with the real reason' behavior, the platform-specific ID scoping, and 'ACCEPTED IS NOT DELIVERED.' It also flags the 0-credit cost. No contradiction exists with the annotations — the write nature aligns with readOnlyHint: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?

Information is densely packed and the critical safety warning is front-loaded ('THIS REACHES A REAL PERSON... get a yes, then send'). Every sentence carries weight. The heavy ALL-CAPS emphasis ('HERMOSO SENDS REPLIES ONLY', 'ACCEPTED IS NOT DELIVERED') is stylistically noisy and the recipientId guidance is duplicated between the schema and description, so it could be tightened despite being well ordered.

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 safety-critical, platform-variant tool with no output schema, the description covers everything an agent needs: the confirmation gate, the 24-hour window rule and its failure mode, per-platform ID scoping with provenance, the response-only boundary, delivery semantics, and credit cost. Nothing required for a correct call is missing.

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?

With 60% schema coverage the description compensates substantively: it explains that recipientId is a page-scoped (Messenger) vs Instagram-scoped ID that cannot be derived from a username/handle, and it attaches concrete behavioral consequences to conversationId (enables pre-send window check vs. disclosed 'could not be checked'). The platform property's scoping impact is clarified. However, pageId remains undocumented in both the schema and description, so it is not a 5.

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 first sentence states a specific verb and resource: 'Send a text reply to someone who has messaged the brand.' It immediately distinguishes itself from sibling reply tools (reply_to_meta_comment, reply_to_thread, send_whatsapp_message) by scoping to Messenger/Instagram DMs. The platform scope and reply-only boundary make the purpose unambiguous.

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 it — replying to someone who has messaged the brand — and states hard boundaries: proactive messages and message tags are deliberately not offered, messaging_type is always RESPONSE. It routes the agent to read_meta_conversation for the replyTo ID. However, it never names a sibling tool as an explicit alternative (e.g., for when a user wants to start a new conversation rather than reply), which keeps it a 4.

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