pipedrive_update_deal_field

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

Annotations already indicate this is a write operation (readOnlyHint=false), idempotent (idempotentHint=true), and non-destructive (destructiveHint=false). The description adds a valuable constraint about immutable fields (field_type and field_code). However, it doesn't disclose other behavioral traits like permission requirements or side effects beyond the schema.

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 a single, well-structured sentence that states the action, target, and key constraint upfront. There is no unnecessary verbiage, and the most critical information (immutability of field_type and field_code) is included.

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?

While the schema covers parameter details, the description lacks broader context: no mention of when to use this over other field tools, no expected outcomes, and no mention of prerequisites (e.g., needing a prior field create/list response). For a mutation tool with nested objects and 6 parameters, it is functionally adequate but not comprehensive.

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 100%, and each parameter (field_code, field_name, description, ui_visibility, required_fields, important_fields) has a detailed schema description. The tool description adds no extra parameter semantics beyond what the schema already provides, which keeps this at the baseline 3.

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 clearly states the action (update) and the resource (deal custom field) with a specific identifier (field_code). It also defines a precise scope by noting that field_type and field_code cannot be changed, which distinguishes it from create and option-update sibling tools.

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 implies its purpose but provides no explicit guidance on when to use this tool versus alternatives like pipedrive_create_deal_field or pipedrive_update_deal_field_options. The phrase 'by field_code' and the immutability note hint at usage, but no direct exclusions or alternative routing is given.

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