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

The annotations only provide readOnly=false and destructive=false, so the description carries the full behavioral disclosure burden. It clearly reveals patch semantics ('never a replacement'), strict status validation ('rejected by the database, not silently ignored'), and nuanced contact linkage behavior including multiple leads pointing to one contact and null detaching. This is far more transparent than the annotations alone.

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 description is four sentences, each carrying a distinct behavioral fact with no filler. It front-loads the core purpose, then adds patch semantics, status validation, and contact relationship nuances in a logical order.

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?

Despite having 10 parameters, no output schema, and sparse annotations, the description provides all critical invocation knowledge: partial update behavior, validation rejection, the duplicate-contact workflow, and null detachment. The only minor omission is return-value details, which are less essential for a mutation tool and are not required by the context signals.

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 10% schema description coverage, the description compensates well for the key parameters: the general patch rule applies to every passed field, and status and contact_id get detailed semantics including null handling. The remaining params like email, phone, company, and full_name are self-explanatory from their names, but owner_id and value receive no additional context, so the compensation is strong 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 description opens with 'Update fields on a lead,' naming a specific verb and resource, and immediately differentiates this from a full replacement by explaining it is a patch. This clearly distinguishes it from sibling tools like crm_update_contact or crm_update_deal by specifying the resource as 'lead.'

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 description gives explicit usage context for the contact_id parameter: use it when crm_get_leads reports a possible duplicate, and link the existing contact instead of creating a second record. It also warns that status must be a valid pipeline stage. However, it does not explicitly name alternatives for the general update case or state when not to use this tool, so it falls just short of exhaustive routing guidance.

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