Skip to main content
Glama
ghl-mcp-server-v2

ghl-mcp-server-v2

by zackscriven

ghl_location_create_custom_field

Create a custom field for a GoHighLevel location, defining its name, data type, and options so contacts or opportunities capture the data you need.

Instructions

Create Custom Field Endpoint: POST /locations/{locationId}/customFields (Version header: v3; source: v3/locations-v3.json) OAuth scopes: locations/customFields.write

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "locationId": "<locationId>",
      "body": "<body>"
    },
    "name": "ghl_location_create_custom_field"
  }
}

Input Schema

NameRequiredDescriptionDefault
bodyYesRequest body (schema carried verbatim from the official OpenAPI spec).
locationIdYesLocation Id

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed8 schema fields changedv2.1.0
    • addedInput schema / properties / body / properties / dataType / description
      Added value: +"Data type of the custom field.\n\nURL, USER, TIME, DATE_TIME and RICH_TEXT are Labs-only for now."
    • addedInput schema / properties / body / properties / dataType / enum
      Added value: +[
      +  "TEXT",
      +  "LARGE_TEXT",
      +  "NUMERICAL",
      +  "PHONE",
      +  "MONETORY",
      +  "CHECKBOX",
      +  "SINGLE_OPTIONS",
      +  "MULTIPLE_OPTIONS",
      +  "FLOAT",
      +  "TIME",
      +  "DATE",
      +  "TEXTBOX_LIST",
      +  "FILE_UPLOAD",
      +  "SIGNATURE",
      +  "RADIO",
      +  "URL",
      +  "DATE_TIME",
      +  "USER",
      +  "RICH_TEXT"
      +]
    • addedInput schema / properties / body / properties / dateTimeValidation
      Added value: +{
      +  "allOf": [
      +    {
      +      "properties": {
      +        "bufferDays": {
      +          "description": "For future_only: minimum days from today before a date is selectable",
      +          "example": 2,
      +          "type": "number"
      +        },
      +        "daysAllowed": {
      +          "description": "Days of week 0=Sunday..6=Saturday. Works alongside future_only, past_only, or range modes.",
      +          "example": [
      +            1,
      +            2,
      +            3,
      +            4,
      +            5
      +          ],
      +          "items": {
      +            "type": "number"
      +          },
      +          "type": "array"
      +        },
      +        "inputType": {
      +          "description": "For DATE_TIME fields: collect date only, time only, or both (defaults per product if omitted).",
      +          "enum": [
      +            "date_only",
      +            "time_only",
      +            "date_and_time"
      +          ],
      +          "example": "date_and_time",
      +          "type": "string"
      +        },
      +        "mode": {
      +          "description": "any: no restriction. future_only: value must be in future. past_only: value must be in past. range: value within rangeMin-rangeMax.",
      +          "enum": [
      +            "any",
      +            "future_only",
      +            "past_only",
      +            "range"
      +          ],
      +          "example": "any",
      +          "type": "string"
      +        },
      +        "rangeMax": {
      +          "description": "Required when mode is range. ISO date or datetime string",
      +          "example": "2026-12-31",
      +          "type": "string"
      +        },
      +        "rangeMin": {
      +          "description": "Required when mode is range. ISO date or datetime string",
      +          "example": "2026-01-01",
      +          "type": "string"
      +        },
      +        "rollingDays": {
      +          "description": "For future_only: rolling window in days from today (e.g. 30 = next 30 days). Mutually exclusive with bufferDays.",
      +          "example": 30,
      +          "type": "number"
      +        }
      +      },
      +      "title": "DateTimeValidationDto",
      +      "type": "object"
      +    }
      +  ],
      +  "description": "Date/time validation. Required for TIME and DATE_TIME; optional for DATE when using validation rules.",
      +  "example": {
      +    "mode": "range",
      +    "rangeMax": "2026-12-31",
      +    "rangeMin": "2026-01-01"
      +  }
      +}
    • addedInput schema / properties / body / properties / optionDisplayType
      Added value: +{
      +  "description": "Option rendering mode for RADIO / CHECKBOX. One of TEXT_ONLY, TEXT_WITH_ICON, TEXT_WITH_IMAGE. Defaults to TEXT_ONLY.",
      +  "enum": [
      +    "TEXT_ONLY",
      +    "TEXT_WITH_ICON",
      +    "TEXT_WITH_IMAGE"
      +  ],
      +  "example": "TEXT_WITH_IMAGE",
      +  "type": "string"
      +}
    • changedInput schema / properties / body / properties / textBoxListOptions / items / anyOf
      Previous value: -[
      -  {
      -    "properties": {
      -      "label": {
      -        "example": "First",
      -        "type": "string"
      -      },
      -      "prefillValue": {
      -        "example": "",
      -        "type": "string"
      -      }
      -    },
      -    "type": "object"
      -  },
      -  {
      -    "properties": {
      -      "label": {
      -        "example": "First",
      -        "type": "string"
      -      },
      -      "prefillValue": {
      -        "example": "",
      -        "type": "string"
      -      }
      -    },
      -    "type": "object"
      -  }
      -]New value: +[
      +  {
      +    "properties": {
      +      "label": {
      +        "example": "First",
      +        "type": "string"
      +      },
      +      "prefillValue": {
      +        "example": "",
      +        "type": "string"
      +      }
      +    },
      +    "title": "textBoxListOptionsSchema",
      +    "type": "object"
      +  },
      +  {
      +    "properties": {
      +      "label": {
      +        "example": "First",
      +        "type": "string"
      +      },
      +      "prefillValue": {
      +        "example": "",
      +        "type": "string"
      +      }
      +    },
      +    "title": "textBoxListOptionsSchema",
      +    "type": "object"
      +  }
      +]
    • addedInput schema / properties / body / properties / urlValidation
      Added value: +{
      +  "allOf": [
      +    {
      +      "properties": {
      +        "allowedDomains": {
      +          "description": "Domains accepted when mode is allow_only",
      +          "example": [
      +            "example.com"
      +          ],
      +          "items": {
      +            "type": "string"
      +          },
      +          "type": "array"
      +        },
      +        "blockedDomains": {
      +          "description": "Domains rejected when mode is block",
      +          "example": [],
      +          "items": {
      +            "type": "string"
      +          },
      +          "type": "array"
      +        },
      +        "mode": {
      +          "description": "allow_all: any url. allow_only: only allowedDomains. block: anything but blockedDomains.",
      +          "enum": [
      +            "allow_all",
      +            "allow_only",
      +            "block"
      +          ],
      +          "example": "allow_all",
      +          "type": "string"
      +        }
      +      },
      +      "title": "UrlValidationDto",
      +      "type": "object"
      +    }
      +  ],
      +  "description": "URL validation rules. Required when dataType is URL.",
      +  "example": {
      +    "allowedDomains": [
      +      "example.com"
      +    ],
      +    "mode": "allow_only"
      +  }
      +}
    • addedInput schema / properties / body / properties / userFieldConfig
      Added value: +{
      +  "allOf": [
      +    {
      +      "properties": {
      +        "multiSelect": {
      +          "description": "Single or multi-select; cannot change after create",
      +          "example": false,
      +          "type": "boolean"
      +        }
      +      },
      +      "title": "UserFieldConfigDto",
      +      "type": "object"
      +    }
      +  ],
      +  "description": "User field options. Required when dataType is USER. multiSelect cannot be changed after create.",
      +  "example": {
      +    "multiSelect": false
      +  }
      +}
    • addedInput schema / properties / body / title
      Added value: +"CreateCustomFieldsDTO"
  2. First observedv2.0.0

TDQS

C2.9/5.0
Behavior3/5

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

Annotations already declare readOnlyHint=false, idempotentHint=false, destructiveHint=false, openWorldHint=true, so the safety profile is covered. The description adds genuinely useful context not in annotations: the exact POST endpoint, API version header (v3), and the required OAuth scope `locations/customFields.write`. It does not mention that creating a field mutates the location's schema going forward or whether names must be unique, which would have been valuable for a create operation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short lines, front-loaded with the action, then endpoint and scope — no filler. It is arguably too sparse rather than too long, but nothing is wasted.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the rich nested schema and existing annotations, the description covers the essentials for invocation (endpoint, scope). It still leaves the sibling-disambiguation gap and says nothing about post-creation behavior or whether the created field is immediately usable, which matters for a schema-mutating create in a crowded tool family.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the nested body schema is extremely detailed, so the schema carries the parameter burden. The description adds only the OAuth scope requirement, nothing about `locationId` meaning or `body` composition beyond what the schema already documents.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource ("Create Custom Field") plus the endpoint path, so the basic action is clear. However, it never distinguishes this from the highly similar siblings `ghl_custom_field_create` and `ghl_location_update_custom_field`, so an agent cannot tell from prose alone why it should pick the location-scoped variant.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus the near-identical custom-field siblings, and no prerequisites stated beyond the API path. The agent must infer the location-scoping rationale from the parameter names.

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

Deploy Server

Other Tools