pipedrive_create_deal_field

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

Annotations declare readOnlyHint=false and openWorldHint=true, indicating an unconstrained mutation. The description adds genuinely useful behavioral context: it reveals the return payload shape (response.data.field_code) and instructs the agent to retain that 40-char hash for later updates/deletes. This anticipates a real workflow need beyond what annotations provide. No contradiction with annotations found.

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 dense sentences with zero filler. The core purpose is front-loaded, followed immediately by the most important parameter constraints. The field_code guidance gives a forward-looking note without bloat. Slightly more detail on the field_code implications could be added, but the current text is efficiently structured.

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?

With no output schema present, the description correctly carries the return-value burden by documenting the field_code that must be preserved. It covers required parameters and the conditional options requirement. It doesn't detail auth/error handling, but for a field-creation tool where annotations signal an open-world, non-destructive operation, the essential call-time context is present.

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?

The schema has 100% coverage of all 7 parameters, but the description adds value by surfacing the conditional dependency between options and enum/set field types, and by re-emphasizing the two required parameters. Since the schema already documents each parameter, the description's reinforcement of the options-required-for-enum/set rule is meaningful added guidance rather than repetition.

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 'Create a deal custom field' — a specific verb + resource combination that clearly states the operation. The 'deal' qualifier distinguishes it from siblings like pipedrive_create_person_field, pipedrive_create_organization_field, and pipedrive_create_product_field. An agent can immediately tell this is the right tool for creating a custom field on deal records.

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 parameter usage guidance — field_name and field_type are required, and options is required for enum/set types — which helps the agent assemble a valid request. However, it doesn't explicitly address when to use this tool versus its siblings (create_person_field, create_organization_field, etc.) or mention any exclusions. The differentiation relies on the name itself rather than the description.

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