update_lead

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

Annotations already declare readOnly=false, idempotent=true, destructive=false, so the safety profile is covered structurally. The description adds the meaningful patch semantics ("only provided fields change") plus the auth scope, but stays silent on what happens with an unknown `id`, and critically on whether the `notes` array is replaced or appended.

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 tight sentences with zero filler, and the partial-update behavior is front-loaded before the permission requirement. It is efficient, though the extreme brevity is partly the cause of the gaps flagged elsewhere.

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 12-parameter mutation with nested objects, no output schema, and a sibling `upsert_lead` that overlaps functionally, the description is too thin. An agent still cannot tell how `notes` entries merge, how to clear a nullable field, or what the call returns.

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 12 parameters and only 17% schema description coverage (only `value` and `externalId` are annotated), the description carries the compensation burden and supplies nothing — no field-level meaning, no note on null-clearing versus omission, and no explanation of the nested `notes`/`metadata` structures.

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?

Specific verb+resource ("Update a lead") with a parenthetical that defines the semantics as a partial/patch update, which is genuinely useful. It does not distinguish the tool from the closely related `upsert_lead` sibling, so the agent must infer when PATCH-update is preferable to upsert.

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` is a real prerequisite an agent must satisfy before calling. Beyond that there is no guidance on when to use this versus `upsert_lead` (which the schema itself says POST-upserts on `externalId`), leaving the main routing decision unaddressed.

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