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

Annotations already declare destructiveHint=true and readOnlyHint=false, but the description goes well beyond them: it discloses the two-phase confirmation protocol (status='confirmation_required', action_id, plan_token, then confirm_action), that a change touching stored values reports affected-lead counts, and that values which cannot be kept require explicit opt-in. This is exactly the behavioral context an agent needs before invoking a destructive write.

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?

Front-loads the create-vs-change split, then terse colon-delimited lists of arguments, then impact/dry_run semantics, then the confirmation protocol — a sensible information hierarchy. Some sentences are dense run-ons with parenthetical fragments, but nearly every clause carries operational meaning.

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 14-parameter destructive mutation with no output schema, the description covers the confirmation lifecycle, impact reporting, and workspace limits, which are the highest-risk unknowns. The remaining gap is minor parameter coverage (label_en) and return-shape detail, though the confirmation response fields are named.

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%, so the description must carry the load, and it mostly does: it explains key format and length rules, label_uk, type, options for enum/multi_enum, the label/filterable/indexed/required/order mutations, add_options/remove_options, archived, drop_unconvertible, and dry_run. It omits label_en entirely, and does not enumerate the nine permitted type values that the schema only implies via enum.

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?

Opens with a specific verb+resource: "Create or change one of the workspace's lead fields," and immediately splits into "New field" and "Existing field" modes so an agent knows which parameter set applies. It does not explicitly distinguish itself from neighboring CRM tools (e.g., crm_list_fields or crm_pipeline_define), which keeps it 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?

Gives explicit conditional guidance: which arguments to supply for a new field versus an existing one, which mutations affect stored values, when 'drop_unconvertible' is required, and when to use dry_run=true to preview impact. It also states the hard limits (50 fields, 10 indexed) that constrain when this call can succeed, and routes the agent to confirm_action for execution.

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