Import or update up to 100 leads in one call, matching records by externalId. Omitted fields are cleared on update, so send complete lead data to avoid data loss.
Import up to 100 leads (upsert on externalId; omitted fields are cleared on update).
Requires scope leads:write.
| Name | Required | Description | Default |
|---|---|---|---|
| leads | Yes |
Changes observed during successful MCP inspections.
v0.1.1Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), and the description adds two things they do not convey: the required auth scope and the critical gotcha that omitted fields are cleared on update. That clearing behavior materially changes how an agent must construct payloads and is exactly the kind of context the annotations undersell.
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?
Two short sentences, both front-loaded with the highest-value information (the batch limit and the destructive update semantic) before the auth requirement. Nothing is redundant with the tool name or padding.
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 write tool with a deeply nested single-param schema and no output schema, the definition covers batch limit, upsert key, update-clearing semantics and auth scope. It leaves two gaps: nothing about what the call returns (no output schema to fall back on) and nothing about partial-failure behavior when some leads in the batch fail.
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 only one parameter and 0% schema description coverage, the description must carry the semantic load, and it does: it names externalId as the upsert key and warns that unspecified fields are nulled on update. It stops short of describing the nested lead object's fields (value in cents, notes structure), though the schema documents several of those itself.
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 (import), resource (leads), batch ceiling (up to 100) and the upsert key (externalId), which cleanly separates it from the single-record sibling upsert_lead. It never names that sibling explicitly, so the differentiation is inferred from 'batch/up to 100' rather than stated.
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 scope requirement (`leads:write`) tells an agent the preconditions for calling it, and 'Import' implies bulk-loading use. However, there is no explicit when-to-use/when-not guidance and no named alternative (e.g. use upsert_lead for a single record), so routing between the two upsert tools 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.