Add support for new property Documentation fields (Data entry instructions + per-option descriptions)

[chad-hohn-radai]

Summary

HubSpot recently shipped a new Documentation tab on the property editor UI (Apr 2026, currently rolling out; not yet in public KB docs as of this writing). It introduces three fields:

1. Property description — the same field as the legacy description on the v3 properties endpoint. Round-trips through this MCP server correctly.
2. Data entry instructions (new) — per-property text explaining how users and Breeze agents should populate the property.
3. Option descriptions (new) — per-option text on enumeration properties explaining when each option should be selected. Feeds Breeze agents.

Neither of the two new fields is exposed by this MCP server today, and testing shows the new "Option descriptions" feature is stored separately from the legacy options[].description field in the v3 API.

Reproduction

Tested on a Deal enumeration property (rfx_procurement_vehicle) in an Enterprise portal.

1. Data entry instructions — not in API at all

Setting this field via the UI does not cause it to appear in hubspot-get-property. The response contains no dataEntryInstructions (or similarly named) key at any level.

2. Option descriptions — separate storage from options[].description

Using hubspot-update-property to write options[].description on all four enum values:

{
  "options": [
    { "label": "RFP", "value": "rfp", "description": "Request for Proposal. ..." },
    { "label": "RFI", "value": "rfi", "description": "Request for Information. ..." },
    { "label": "RFQ", "value": "rfq", "description": "Request for Quote. ..." },
    { "label": "Sole Source", "value": "sole_source", "description": "Non-competitive procurement. ..." }
  ]
}

• hubspot-update-property response echoes the descriptions back.
• A subsequent hubspot-get-property returns all four descriptions cleanly, and updatedAt bumps.
• However, opening the property in the HubSpot UI and navigating to Documentation > Option descriptions shows only the description that was set via the UI earlier. All four options show "No option description added" for the text written via the MCP, even though the API GET just returned those values.

This indicates that the new Documentation > Option descriptions UI writes to a distinct backing store, and the legacy options[].description field the MCP exposes is a different (orphaned?) field that is not surfaced anywhere in the new UI.

3. updatedAt behavior confirms separate storage

Editing the new Documentation fields in the UI does NOT bump the property's updatedAt in the v3 API response, whereas editing options[].description via the API DOES bump it. Two different persistence paths.

Requested behavior

Once HubSpot's CRM team exposes these fields on the v3 properties endpoint (or through whatever Breeze-documentation endpoint they're living on today), please:

1. Return a dataEntryInstructions (or equivalent) field on hubspot-get-property.
2. Return the new per-option descriptions inside the options[] array on hubspot-get-property, with a clearly distinct key if they have to coexist with the legacy options[].description.
3. Accept writes for both fields on hubspot-create-property and hubspot-update-property.

Why this matters

The new Documentation feature is explicitly designed to improve Breeze agent results ("Documentation improves the quality of results from Breeze agents"). First-class MCP support is especially valuable for anyone bulk-configuring enumeration properties that Breeze agents will populate — which is a common RevOps pattern.

Environment

• @hubspot/mcp-server via npx
• HubSpot Enterprise portal
• Observed: April 2026

[ross-makeacompany]

Great repro — the "API GET returns the value cleanly but the UI doesn't show it" detail (your point 2) is exactly the kind of bug that only catches you because you actually exercised both ends. Saves the next person a week.

Adding our use case as a data point on prioritization: we're building AI assistants over HubSpot for athlete-program customers, and option-descriptions-for-Breeze is the kind of thing that materially improves agent behavior when present (because the LLM stops guessing what each enum value means). So even though we're not on Enterprise yet, this is the kind of metadata we'd want to push into HubSpot from our own tooling once it has an API surface.

Would also help us interpret the schema in our wrapper service (we currently reimplement only the tools we need against HubSpot's REST — see #1 and #7 for context on why).

[m13v]

the seam here isn't that the MCP is missing two fields, it's that the v3 properties endpoint and the Breeze Documentation store are two different write paths that don't reconcile. options[].description round-trips through the API (echoes on write, returns on GET) but never lands in the Documentation > Option descriptions store the agents actually read, so a client thinks it set the guidance while the UI shows 'none added'. and since editing the new fields doesn't bump updatedAt, there's no change signal to sync against. anything writing options[].description today is feeding an orphaned field.