upsert_lead

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

Adds real value beyond annotations by disclosing the required scope `leads:write`. However, it omits the critical upsert behaviors: whether omitted fields are nulled or preserved on update, and whether `name` is required even when updating an existing lead. There is also an unresolved tension with idempotentHint=false, since keying updates on externalId reads as idempotent.

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, the upsert condition is front-loaded, and the scope requirement is stated tersely. Zero wasted words for the amount of text present.

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 an 11-parameter mutation with a nested notes array, no output schema, and thin schema descriptions, the description is far too thin. An agent cannot tell what the call returns, how partial updates are handled, or what happens to notes arrays on a repeat call.

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 18% across 11 parameters, with nested objects (notes) and enums-free nullable fields that need explanation. The description explains none of them — fields like stage, value (cents), and metadata semantics, plus merge behavior on update, are left entirely to an under-documented schema.

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 action and resource with the key insight that it is an upsert keyed on externalId ('Create a lead, or update the one with the same externalId'), which lets an agent distinguish it from a plain create. It does not explicitly contrast with siblings update_lead / batch_upsert_leads, so it falls short of a 5.

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 externalId keying implies when this tool is appropriate (records that have a CRM id), but there is no explicit when-to-use vs update_lead, and no guidance on behavior when externalId is omitted or null. Usage must be inferred from the upsert semantics.

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