Updates an existing GoHighLevel note by ID, allowing changes to title, body, color, or pinned status.
Update Note Endpoint: PUT /notes/{id} (Version header: v3; source: v3/objects-v3.json) OAuth scopes: notes.write
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Note Id | |
| body | Yes | Request body (schema carried verbatim from the official OpenAPI spec). | |
| locationId | Yes | Location Id |
Changes observed during successful MCP inspections.
v2.1.0Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly=false, idempotent=true and destructive=false, so safety is covered; the description adds a genuinely useful detail not in structured fields, the required notes.write OAuth scope and the v3 version header. It does not explain update semantics — whether omitted fields in the body object (color, title, pinned) are preserved or cleared — which matters for a mutation tool.
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?
Three compact lines, front-loaded with the action, then endpoint and auth. No filler. It is short to the point of under-specification rather than bloated, but nothing in it is wasted.
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 three-parameter mutation with a nested DTO and no output schema, the safety profile and parameter docs are covered by annotations and schema respectively. The remaining gap is behavioral: partial-vs-replace semantics on the nested body, and whether the note must belong to the given locationId.
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%, so id, locationId and every nested body property (body, color, title, pinned) are already documented in the schema. The description adds no syntax, format, or constraint detail beyond it, so the baseline 3 applies.
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?
"Update Note" plus the endpoint line (PUT /notes/{id}, v3) identifies the verb and resource, so an agent knows it mutates an existing note. But there are several note-update siblings (ghl_contact_update_note, ghl_object_update_note_relations, ghl_object_update_note_attachments, ghl_calendar_appointment_note_update) and nothing distinguishes this one from them. Without the endpoint string the first line alone would be a name restatement.
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?
No statement of when to use this over ghl_contact_update_note or the attachments/relations variants, and no preconditions (does the note need to exist, is it scoped by locationId?). The only guidance is the OAuth scope, which is an auth requirement rather than usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.