contact_leads

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

Annotations declare non-read-only, open-world, non-idempotent, non-destructive, so the safety profile is already carried by structured fields; the description adds real value on top with 'real calls / real SMS, billed' (cost/side-effect disclosure), the 500-lead cap, the message-required-unless-sendMode=agent rule, and the audience-confirmation requirement. It does not describe what happens on partial failure or what the response contains, which keeps it short of a 5.

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 audience/cost framing is front-loaded, and the destructive-scale warning (500 cap, confirm with user) sits before the alternative-tool pointer. It is a dense single paragraph, but each clause carries distinct information; only minor formatting (splitting the channel branches) would improve scannability.

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 high-blast-radius, 10-parameter, nested-object tool with no output schema, the description covers the essentials an agent needs to invoke safely: source of leads, per-channel requirements, cost, cap, and confirmation. Gaps are the undocumented options/campaignId parameters and the absence of any return-value expectation, which is a modest hole given there is no output schema.

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?

With 10 parameters at 50% schema coverage, the description carries meaningful extra semantics: it explains channel's two modes and their side effects, that message is required unless sendMode=agent, and that leads must be objects carrying a phone field. options, campaignId, and the interaction between from and contactMethodsPriority remain undocumented in both places.

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?

States a specific verb (call or text) applied to a specific resource (a list of leads from leads_read) and immediately distinguishes itself from campaigns_write for scheduled/throttled dialing. The channel=call vs channel=sms behavioral split is spelled out, so an agent can tell it apart from send_sms, start_outbound_call, and campaigns_write without opening the schema.

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?

Explicit guidance on when to use it (bulk one-shot dialing), when not to (scheduled/throttled → use a campaign), prerequisites (leads must come from leads_read and carry a phone like userPhone), and a hard constraint (max 500 per call) plus an operational rule (confirm the audience with the user first). Nothing is left to inference.

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