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

Annotations already declare readOnlyHint=false, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so safety and repeat-call behavior is largely covered. The description's one real contribution is the patch contract implied by "Give only the fields to change", i.e. unsupplied fields are preserved. It says nothing about whether array fields like tags are replaced or merged, nor what happens if leadId is unknown.

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 with the core action front-loaded and no filler. It is efficient, though the brevity is achieved partly by omitting content that the other dimensions penalize.

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 tool with undocumented parameters and no output schema, the description is too thin. An agent learns the resource and the patch convention but not the identity requirement, field semantics, or result shape, leaving meaningful gaps before a safe 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 0% across 11 parameters, so the description must carry the burden and does not. It clarifies only that status is updatable and that omitted fields should be left alone; it adds no meaning for leadId (required), tags (replace vs append?), notes, or the enum-valued source field. The enum values themselves come from the schema, not the description.

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?

"Update a lead, e.g. its status" names a specific verb and resource, and the example field makes the operation concrete. It does not distinguish itself from siblings like qualify_lead or convert_lead, which also mutate a lead's status, so an agent cannot rule those out from this text alone.

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?

"Give only the fields to change" is a partial-update instruction, not tool-selection guidance. There is no statement of when to prefer this over qualify_lead, convert_lead, update_contact, or upsert_deal, and no prerequisites (e.g. needing a valid leadId) are mentioned.

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