Create a broadcast: a one-off message to a list or audience on a single channel. It starts as a draft with no content; add content with put_broadcast_content, then send_broadcast or schedule_broadcast.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Human-readable name | |
| channel | Yes | The single delivery channel for this broadcast |
Changes observed during successful MCP inspections.
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark this as read-write and non-destructive. The description adds useful behavioral context beyond annotations: the created broadcast 'starts as a draft with no content'. It also outlines the expected sequence, which helps the agent understand the object's state after creation. Idempotency is not elaborated, but idempotentHint=false already covers that.
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 two sentences with zero filler. The core purpose is front-loaded ('Create a broadcast'), and the workflow is stated compactly in the second sentence. Every clause earns its place.
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 simple create tool with two scalar parameters and no output schema, the description is complete enough. It states the draft state and the next steps. It does not cover edge cases like name collisions or channel mutability, but given the annotations and schema, these are minor omissions.
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 coverage is 100%, so both parameters (name, channel) are already fully described in the schema. The description adds only that the broadcast is a draft with no content, which implies the channel is set at creation but does not add semantics for the parameters themselves. Baseline 3 is appropriate for high 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 uses a specific verb-resource pair ('Create a broadcast') and clarifies the scope: a one-off message to a list or audience on a single channel. It also notes the draft state, distinguishing it from content-loading (put_broadcast_content) and sending (send_broadcast/schedule_broadcast) 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?
It explicitly describes the intended workflow: create the broadcast first, then add content with put_broadcast_content, then send or schedule. This tells the agent when to use this tool and names the follow-up alternatives. No exclusions are given, but the lifecycle guidance is clear and actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add one secure layer between your agents and this server.
