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

Annotations already indicate a write and destructive operation, but the description goes far beyond by explaining the exact effect on scheduled broadcasts (unschedule/update/reschedule), the recovery behavior if the schedule cannot be restored, and the mandatory reporting to the user. It also mentions the workspace-change effect and the need to retry after reading current resource state, providing rich behavioral context not available in structured fields.

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?

The description is longer than ideal, but every sentence carries critical procedural information about handling scheduled broadcasts and failure recovery. It is front-loaded with the core purpose and then logically flows into constraints and detailed workflow. The only minor drawback is the density of instructions in a single paragraph, which could be slightly restructured for readability, but it is still appropriately sized for the tool's complexity.

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?

Given the tool's complex behavior around updating drafts and rescheduling, the description is remarkably complete. It covers all relevant edge cases: which states are disallowed, how to handle scheduled broadcasts, what to do on failure, and the user reporting requirement. The existence of an output schema means return values need not be described, and the description even includes permission and API reference links, making it self-sufficient.

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%, meaning broadcast_id and body both have descriptions (e.g., 'The broadcast identifier' and 'The exact JSON request body defined by the Mailrith public API contract'). The tool description adds some usage context around broadcast_id (e.g., read by ID for scheduled broadcasts) but does not elaborate on the body fields, leaving that to the nested schema. This is adequate but does not exceed the baseline.

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 'Updates an existing Broadcast draft,' clearly stating the action and target. It distinguishes this tool from siblings by explicitly listing which broadcast states cannot be changed here (scheduled, running, completed, failed), making it stand apart from broadcasts_create, broadcasts_schedule, and similar 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 provides explicit when-to-use guidance: it is for drafts only, and for scheduled broadcasts it prescribes a specific unschedule-update-reschedule workflow, including reading the broadcast by ID first and asking the user for a new time if the saved time is unsafe. It also tells the user what to do if the update fails after unscheduling, effectively covering alternatives and exclusions.

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