Change a CRM field

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the mutation nature is given; the description adds real value by clarifying that the existing value is overwritten rather than appended, and by disclosing the asymmetric set-only restriction on DO_NOT_CALL/DO_NOT_EMAIL. It does not cover error behavior for invalid field names or what is returned, but against destructiveHint annotations this is meaningful supplementary context.

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?

Three short sentences, front-loaded with the operation and scope, then the overwrite semantics, then the single hard constraint. No filler, no redundant restatement of the title.

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 destructive single-field mutation with no output schema, the definition covers what changes and one important restriction, which is the minimum an agent needs. It omits the neighboring tool relationship (crm_add_or_update) and any indication of failure modes or confirmation expectations for an overwrite, leaving the definition adequate but thin.

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 coverage is 100%, so a 3 is the baseline, and the description earns a bump by adding semantics the schema lacks: that `field` values include DO_NOT_CALL/DO_NOT_EMAIL and that setting them to 'no' will not work, which is non-obvious parameter behavior. It still says nothing about record disambiguation behavior (email/phone duplicates vs record_id) beyond what the schema already documents.

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+resource combination: changing exactly one field of a customer, organization, or potential record, with the record types enumerated to match the schema enum. It implicitly contrasts with wholesale update tools by emphasizing 'one field' and 'replaces the current value', though it never names a sibling alternative explicitly.

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 offers no when-to-use guidance and does not distinguish this tool from crm_add_or_update, which an agent could reasonably choose instead for the same record. The only rule-like sentence (DO_NOT_CALL/DO_NOT_EMAIL set-only) is a value constraint, not usage routing.

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