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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is carried structurally. The description adds real behavioral context beyond that: it is workspace-scoped, and the returned record includes run history ('what it has sent and heard back') and scheduling state ('when it runs next and last'). It stops short of describing pagination or result volume.

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 sentences, front-loaded with the resource definition followed by the returned fields, and the alternative tools named last. The phrase 'a list texted in touches on a schedule' is slightly compressed but still parseable. No filler sentences.

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?

With no input parameters and no output schema, the description must carry the return-value burden, and it does by enumerating the fields each wave carries. An agent knows what it gets back and what to call next. Minor gap: no indication of result ordering or whether all waves are always returned.

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 tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a no-param tool applies. The description instead spends its words on the return shape, which the empty schema cannot convey.

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?

Defines the resource concretely: 'The workspace's text waves: a list texted in touches on a schedule,' which tells an agent both the domain concept and its nature (scheduled multi-touch texting). It also enumerates what each item carries (id, on/off, recipients, touches, next/last run, sends and replies), which is more specific than the bare name. It does not contrast itself against look-alike siblings such as list_lists or list_events, keeping it short of a 5.

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 points forward in the workflow by naming preview_wave and run_wave for execution, which is useful next-step routing. However, it never states when an agent should call this vs. other listing tools, or any precondition (e.g., discover waves before previewing one). Guidance is implied rather than explicit.

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