schedule_message

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It meaningfully reveals that delivery is not immediate or guaranteed at the exact timestamp, but depends on a background service or manual invocation, and that the tool returns a job ID useful for cancellation.

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 short sentences, each serving a purpose: the action, the delivery behavior, and the return value with cancellation path. No filler or repetition of schema details.

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?

The description covers the tool's core purpose, the asynchronous delivery model, the returned job ID, and how to cancel. While there is no output schema, the return value is described adequately. It does not cover edge cases like past send_at values, but these are not critical for basic invocation.

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 100%, so the schema already documents all parameters including the ISO datetime format and group/recipient mutual exclusivity. The description adds no extra parameter-level meaning, matching the baseline for full schema coverage.

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 clearly states the tool schedules a message for a future time, using a specific verb and resource. It distinguishes itself from immediate-send siblings like send_message and from the related cancel_scheduled_message and run_scheduled_messages tools.

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 explains when delivery will occur: when the background service runs or when run_scheduled_messages is called manually. It also directs cancellation to cancel_scheduled_message, though it does not explicitly contrast with immediate sending via send_message.

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