import_leads

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

With no annotations, the description carries the full burden and does well: it discloses dedup, suppressed-skip, invalid-count behavior, background ESP detection/verification triggered by the final chunk, and the 5,000-row cap. It stops short of permissions requirements, error behavior on partial failure, or whether an import can be rolled back.

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?

Roughly four sentences, front-loaded with the resource and the protocol, then the side effects. Every sentence adds an operational fact; nothing is a restatement of the name or schema.

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 9-parameter, no-output-schema, no-annotation mutation tool, the description covers the call protocol and post-import processing well, and noting that the first call returns an id substitutes for a missing output schema. Missing only error/partial-failure behavior and permission needs.

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 only 56%, so the description must compensate, and it does for the most consequential parameters: the importId/final interplay is spelled out as cross-parameter sequencing that the individual schema descriptions don't convey. It leaves list, existing, verify, fileName, and the client* counters to the schema, so coverage is good but not complete.

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 opening line states a specific verb and resource ('Import leads in chunks') and immediately adds the defining constraint of the tool: the chunked, multi-call protocol. An agent can distinguish this from sibling add_leads_to_campaign without opening the schema, since the chunking/final semantics are unique to this tool.

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 gives explicit procedural guidance: 5,000 rows per call, omit importId on the first call, pass the returned id on subsequent chunks, and set final:true on the last. What it does not do is contrast this with the sibling add_leads_to_campaign, so the when/when-not routing 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.