Send SMS

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

Annotations already declare openWorld=true and idempotentHint=false, and the description adds real-account consequences (message counts against plan quota), automatic device/account selection, silent SIM id failure, and non-retry advice. It falls slightly short of explaining the strict return/error shape on failure, but on the whole the description adds meaningful context beyond the annotations.

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?

Three dense but well-structured paragraphs grouped by concern — send/cost, device selection rule, recipients, scheduled send, SIM fallback. Every sentence carries operational value; no filler or repetition despite the length.

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?

Covers a surprising amount of edge cases: plan limits, max recipients, quota-capped segments, queue-enabled scheduling, a specific source device, account defaulting, a boolean for queue failure in get_messages, and a full sibling handoff. The only missing piece is what the success response looks like — but the omission is defensible because get_messages is assigned for delivery status.

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?

The schema covers 100% of parameters, and the prose substantially raises the bar: E.164 validation, recipients counted as one each, long messages over 1600 chars segmented and each segment counted, omit device_id by default and source it from list_devices, sched_at requires future+queuing, sim_subscription_id silently ignored. This is much more than a restated 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?

Clear verb–object pairing: “Send an SMS” through the user's own textbee account/Android phone. Scope is sharply delimited from siblings: unlike list_devices/get_messages, this sends. Distinctive constraints are stated (E.164 recipients, auto-selected phone, explicit device_id only when the user names a device).

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?

Explicit operational rules: omit device_id in almost every case; pass it only when the user asks for a specific phone; do not speculative-send, do not retry a send that may have succeeded; use sched_at only with queuing, and route batch status to get_messages. No ambiguity about when to use the tool or its siblings.

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