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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: it uses real contacts from the segment, returns per-contact rendered previews, and explicitly states the failure signal (unmapped_placeholders or blank/wrong values). It does not contradict annotations. A small gap is that it doesn't mention the limit parameter's effect on preview count, but the schema 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 dense but every sentence earns its place: the core action, the usage context, the return shape, and the error-remediation workflow. It is front-loaded with the most important instruction ('Call this before send_broadcast') and avoids fluff.

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 read-only preview tool with no output schema, the description fully specifies the return value shape, the success/failure signals, and the follow-up action. The sibling list includes send_broadcast and set_template_variables, and the description explicitly ties into both. Nothing an agent needs to invoke it correctly is missing.

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 only 33% (limit has a description; segment_id and template_id only have format: uuid). The description compensates by explaining that segment_id selects the real contacts and template_id is the template to render, and it clarifies the limit's role implicitly through 'per-contact rendered message' and the schema's 'How many sample contacts to render'. It doesn't spell out the parameter names, but the context makes the mapping clear enough.

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 states a specific verb ('Render exactly what a broadcast would send'), a clear resource (broadcast preview using real contacts from the segment), and explicitly distinguishes it from send_broadcast. It also explains the practical purpose (catching personalisation errors like 'Hi Alex' instead of the real name), which makes the tool's role unmistakable.

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 explicitly says to call this BEFORE send_broadcast, tells the agent to show the result to the user for confirmation, and gives a concrete remediation path: if unmapped_placeholders is non-empty or a preview shows a wrong value, fix with set_template_variables and preview again. This is explicit when-to-use guidance with a named alternative and follow-up action.

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