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

ghl-mcp-server-v2

by zackscriven

ghl_conversation_ai_create_action

Create and attach a new action to an AI agent to define tasks such as appointment booking, follow-ups, or external API calls. Configure specific behaviors and triggers.

Instructions

Attach Action to Agent Creates and attach a new action for an AI agent. Actions define specific tasks or behaviors that the agent can perform, such as booking appointments, sending follow-ups, collecting information, or making an external API call via the customApi ("API Call") type. For customApi, put the config in details (details.apiConfig is required) and a per-agent limit (up to 5) applies. Endpoint: POST /conversation-ai/agents/{agentId}/actions (Version header: v3; source: v3/conversation-ai-v3.json) OAuth scopes: conversation-ai.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": {
      "agentId": "<agentId>",
      "body": "<body>"
    },
    "name": "ghl_conversation_ai_create_action"
  }
}

Input Schema

NameRequiredDescriptionDefault
bodyYesRequest body (schema carried verbatim from the official OpenAPI spec).
agentIdYesThe unique identifier of the AI agent

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed9 schema fields changedv2.1.0
    • addedInput schema / properties / agentId / description
      Added value: +"The unique identifier of the AI agent"
    • addedInput schema / properties / agentId / example
      Added value: +"ve9EPM428h8vShlRW1KT"
    • changedInput schema / properties / body / properties / details / description
      Previous value: -"Action-specific details. The structure depends on the action type. For TRIGGER_WORKFLOW use triggerWorkflowDto, for UPDATE_CONTACT_FIELD use updateContactFieldDto, for APPOINTMENT_BOOKING use appointmentBookingDto, for STOP_BOT use stopBotDto, for HUMAN_HAND_OVER use humanHandOverDto, for ADVANCED_FOLLOWUP use advancedFollowupDto, and for TRANSFER_BOT use transferBotDto."New value: +"Action-specific details. The structure depends on the action type. For TRIGGER_WORKFLOW use triggerWorkflowDto, for UPDATE_CONTACT_FIELD use updateContactFieldDto, for APPOINTMENT_BOOKING use appointmentBookingDto, for STOP_BOT use stopBotDto, for HUMAN_HAND_OVER use humanHandOverDto, for ADVANCED_FOLLOWUP use advancedFollowupDto, for TRANSFER_BOT use transferBotDto, and for CUSTOM_API use CustomApiDetailsDTO (the API Call config)."
    • addedInput schema / properties / body / properties / details / example
      Added value: +{
      +  "triggerCondition": "When user requests appointment",
      +  "workflowIds": [
      +    "workflow123"
      +  ]
      +}
    • changedInput schema / properties / body / properties / details / oneOf
      Previous value: -[
      -  {
      -    "properties": {
      -      "triggerCondition": {
      -        "description": "Condition that triggers the workflow",
      -        "example": "When user requests appointment",
      -        "type": "string"
      -      },
      -      "triggerMessage": {
      -        "description": "Optional message to send when triggering the workflow",
      -        "example": "Workflow triggered successfully",
      -        "type": "string"
      -      },
      -      "workflowIds": {
      -        "description": "Array of workflow IDs to trigger",
      -        "example": [
      -          "workflow123",
      -          "workflow456"
      -        ],
      -        "items": {
      -          "type": "string"
      -        },
      -        "type": "array"
      -      }
      -    },
      -    "required": [
      -      "workflowIds",
      -      "triggerCondition"
      -    ],
      -    "type": "object"
      -  },
      -  {
      -    "properties": {
      -      "contactFieldId": {
      -        "description": "ID of the contact field in Contacts Table",
      -        "example": "123",
      -        "type": "string"
      -      },
      -      "contactUpdateExamples": {
      -        "default": [],
      -        "description": "Contact update examples in Contacts Table. Not required when using standard fields, Monetory or Date Custom fields.",
      -        "example": [
      -          "Example 1"
      -        ],
      -        "items": {
      -          "type": "string"
      -        },
      -        "type": "array"
      -      },
      -      "description": {
      -        "description": "Description of the contact field in Contacts Table",
      -        "example": "Business Name",
      -        "type": "string"
      -      }
      -    },
      -    "required": [
      -      "contactFieldId",
      -      "description"
      -    ],
      -    "type": "object"
      -  },
      -  {
      -    "properties": {
      -      "actionId": {
      -        "description": "Optional action ID reference",
      -        "example": "action123",
      -        "type": "string"
      -      },
      -      "calendarId": {
      -        "description": "Calendar ID for appointment booking",
      -        "example": "calendar123",
      -        "type": "string"
      -      },
      -      "cancelEnabled": {
      -        "default": false,
      -        "description": "Whether to allow appointment cancellation (cannot be true when onlySendLink is true)",
      -        "example": true,
      -        "type": "boolean"
      -      },
      -      "onlySendLink": {
      -        "description": "If true, only sends the appointment link without booking",
      -        "example": false,
      -        "type": "boolean"
      -      },
      -      "rescheduleEnabled": {
      -        "default": false,
      -        "description": "Whether to allow appointment rescheduling (cannot be true when onlySendLink is true)",
      -        "example": true,
      -        "type": "boolean"
      -      },
      -      "sleepAfterBooking": {
      -        "description": "Whether to put the agent to sleep after booking (cannot be true when onlySendLink is true)",
      -        "example": true,
      -        "type": "boolean"
      -      },
      -      "sleepTime": {
      -        "description": "Sleep duration (required when sleepAfterBooking is true)",
      -        "example": 24,
      -        "type": "number"
      -      },
      -      "sleepTimeUnit": {
      -        "description": "Unit for sleep time (required when sleepAfterBooking is true)",
      -        "enum": [
      -          "days",
      -          "hours",
      -          "minutes"
      -        ],
      -        "example": "hours",
      -        "type": "string"
      -      },
      -      "transferAgent": {
      -        "description": "Agent ID to transfer to (required when transferBot is true)",
      -        "example": "employee456",
      -        "type": "string"
      -      },
      -      "transferBot": {
      -        "description": "Whether to transfer to another agent after booking (cannot be true when onlySendLink is true)",
      -        "example": false,
      -        "type": "boolean"
      -      },
      -      "triggerWorkflow": {
      -        "description": "Whether to trigger a workflow after booking (cannot be true when onlySendLink is true)",
      -        "example": true,
      -        "type": "boolean"
      -      },
      -      "workflowIds": {
      -        "description": "Workflow IDs to trigger after booking (required when triggerWorkflow is true)",
      -        "example": [
      -          "workflow123"
      -        ],
      -        "items": {
      -          "type": "string"
      -        },
      -        "type": "array"
      -      }
      -    },
      -    "required": [
      -      "calendarId",
      -      "onlySendLink",
      -      "triggerWorkflow",
      -      "sleepAfterBooking",
      -      "transferBot",
      -      "rescheduleEnabled",
      -      "cancelEnabled"
      -    ],
      -    "type": "object"
      -  },
      -  {
      -    "properties": {
      -      "enabled": {
      -        "description": "Whether this action is enabled for the agent",
      -        "example": true,
      -        "type": "boolean"
      -      },
      -      "finalMessage": {
      -        "description": "Final message sent when stopping the bot",
      -        "example": "Thank you for contacting us. Have a great day!",
      -        "type": "string"
      -      },
      -      "reactivateEnabled": {
      -        "description": "Whether the bot can be reactivated after being stopped",
      -        "example": true,
      -        "type": "boolean"
      -      },
      -      "sleepTime": {
      -        "description": "Time duration before reactivation (required when reactivateEnabled is true)",
      -        "example": 24,
      -        "type": "number"
      -      },
      -      "sleepTimeUnit": {
      -        "description": "Time unit for reactivation delay (required when reactivateEnabled is true)",
      -        "enum": [
      -          "days",
      -          "hours",
      -          "minutes"
      -        ],
      -        "example": "hours",
      -        "type": "string"
      -      },
      -      "stopBotDetectionType": {
      -        "description": "Type of stop bot detection - Goodbye or Custom",
      -        "enum": [
      -          "Goodbye",
      -          "Custom"
      -        ],
      -        "example": "Custom",
      -        "type": "string"
      -      },
      -      "stopBotExamples": {
      -        "description": "Example phrases that trigger stop bot action (minimum 2 required)",
      -        "example": [
      -          "goodbye",
      -          "thank you",
      -          "no more questions"
      -        ],
      -        "items": {
      -          "type": "string"
      -        },
      -        "type": "array"
      -      },
      -      "stopBotTriggerCondition": {
      -        "description": "Condition that triggers stopping the bot",
      -        "example": "When the user says they no longer need assistance or want to end the conversation",
      -        "type": "string"
      -      },
      -      "tags": {
      -        "description": "Tags to apply when stopping the bot",
      -        "example": [
      -          "resolved",
      -          "no-response"
      -        ],
      -        "items": {
      -          "type": "string"
      -        },
      -        "type": "array"
      -      }
      -    },
      -    "required": [
      -      "stopBotDetectionType",
      -      "stopBotTriggerCondition",
      -      "reactivateEnabled",
      -      "enabled",
      -      "stopBotExamples",
      -      "finalMessage"
      -    ],
      -    "type": "object"
      -  },
      -  {
      -    "properties": {
      -      "assignToUserId": {
      -        "description": "ID of the user to assign the conversation to",
      -        "example": "user123",
      -        "type": "string"
      -      },
      -      "createTask": {
      -        "description": "Whether to create a task when handing over",
      -        "example": true,
      -        "type": "boolean"
      -      },
      -      "enabled": {
      -        "description": "Whether human handover action is enabled",
      -        "example": true,
      -        "type": "boolean"
      -      },
      -      "examples": {
      -        "description": "Example phrases that trigger human handover (required when handoverType is custom or contactRequest)",
      -        "example": [
      -          "speak to human",
      -          "talk to agent",
      -          "need help from person"
      -        ],
      -        "items": {
      -          "type": "string"
      -        },
      -        "type": "array"
      -      },
      -      "finalMessage": {
      -        "description": "Final message sent when handing over to human",
      -        "example": "I am transferring you to a human agent who will assist you shortly.",
      -        "type": "string"
      -      },
      -      "handoverType": {
      -        "description": "Type of human handover detection",
      -        "enum": [
      -          "contactRequest",
      -          "lackOfInformation",
      -          "failedToResolveIssue",
      -          "custom"
      -        ],
      -        "example": "contactRequest",
      -        "type": "string"
      -      },
      -      "reactivateEnabled": {
      -        "description": "Whether the agent can be reactivated after handover",
      -        "example": true,
      -        "type": "boolean"
      -      },
      -      "skipAssignToUser": {
      -        "description": "Whether to skip assigning to a specific user",
      -        "example": false,
      -        "type": "boolean"
      -      },
      -      "sleepTime": {
      -        "description": "Time duration before reactivation (required when reactivateEnabled is true)",
      -        "example": 24,
      -        "type": "number"
      -      },
      -      "sleepTimeUnit": {
      -        "description": "Time unit for reactivation delay (required when reactivateEnabled is true)",
      -        "enum": [
      -          "days",
      -          "hours",
      -          "minutes"
      -        ],
      -        "example": "hours",
      -        "type": "string"
      -      },
      -      "tags": {
      -        "description": "Tags to apply during handover",
      -        "example": [
      -          "escalated",
      -          "human-requested"
      -        ],
      -        "items": {
      -          "type": "string"
      -        },
      -        "type": "array"
      -      },
      -      "triggerCondition": {
      -        "description": "Condition that triggers human handover",
      -        "example": "When the user requests to speak with a human agent or expresses frustration",
      -        "type": "string"
      -      }
      -    },
      -    "required": [
      -      "enabled",
      -      "triggerCondition",
      -      "reactivateEnabled",
      -      "finalMessage",
      -      "handoverType"
      -    ],
      -    "type": "object"
      -  },
      -  {
      -    "properties": {
      -      "enabled": {
      -        "description": "Whether advanced followup is enabled",
      -        "example": true,
      -        "type": "boolean"
      -      },
      -      "followupSequence": {
      -        "description": "Sequence of followup actions to perform",
      -        "items": {
      -          "properties": {
      -            "aiEnabledMessage": {
      -              "default": true,
      -              "description": "Whether to use AI to generate the followup message",
      -              "example": true,
      -              "type": "boolean"
      -            },
      -            "contactRequested": {
      -              "description": "Whether contact was requested in this followup",
      -              "example": false,
      -              "type": "boolean"
      -            },
      -            "customMessage": {
      -              "description": "Custom message to send (when aiEnabledMessage is false)",
      -              "example": "Hi! Just following up on our previous conversation. Do you have any questions?",
      -              "type": "string"
      -            },
      -            "followupTime": {
      -              "description": "Time duration before followup (max: 60 minutes, 24 hours, or 180 days depending on unit)",
      -              "example": 2,
      -              "type": "number"
      -            },
      -            "followupTimeUnit": {
      -              "description": "Time unit for followup delay",
      -              "enum": [
      -                "days",
      -                "hours",
      -                "minutes"
      -              ],
      -              "example": "hours",
      -              "type": "string"
      -            },
      -            "id": {
      -              "description": "Unique identifier for this followup step",
      -              "example": 1,
      -              "type": "number"
      -            },
      -            "triggerWorkflow": {
      -              "default": false,
      -              "description": "Whether to trigger a workflow during this followup",
      -              "example": false,
      -              "type": "boolean"
      -            },
      -            "workflowId": {
      -              "description": "Workflow ID to trigger (when triggerWorkflow is true)",
      -              "example": "workflow789",
      -              "type": "string"
      -            }
      -          },
      -          "required": [
      -            "id",
      -            "followupTimeUnit",
      -            "followupTime"
      -          ],
      -          "type": "object"
      -        },
      -        "type": "array"
      -      },
      -      "followupSettings": {
      -        "allOf": [
      -          {
      -            "properties": {
      -              "dynamicChannelSwitching": {
      -                "default": true,
      -                "description": "Whether to dynamically switch channels for followups",
      -                "example": true,
      -                "type": "boolean"
      -              },
      -              "followUpHours": {
      -                "description": "Whether to respect working hours for followups",
      -                "example": true,
      -                "type": "boolean"
      -              },
      -              "timezoneToUse": {
      -                "description": "Timezone to use for followups, contact or location",
      -                "enum": [
      -                  "contact",
      -                  "business"
      -                ],
      -                "type": "string"
      -              },
      -              "workingHours": {
      -                "description": "Working hours configuration for followups",
      -                "items": {
      -                  "properties": {
      -                    "dayOfTheWeek": {
      -                      "description": "Day of the week (0=Sunday, 1=Monday, etc.)",
      -                      "example": 1,
      -                      "type": "number"
      -                    },
      -                    "intervals": {
      -                      "description": "Time intervals for this day",
      -                      "items": {
      -                        "properties": {
      -                          "endHour": {
      -                            "description": "End hour (24-hour format)",
      -                            "example": 17,
      -                            "type": "number"
      -                          },
      -                          "endMinute": {
      -                            "description": "End minute",
      -                            "example": 30,
      -                            "type": "number"
      -                          },
      -                          "startHour": {
      -                            "description": "Start hour (24-hour format)",
      -                            "example": 9,
      -                            "type": "number"
      -                          },
      -                          "startMinute": {
      -                            "description": "Start minute",
      -                            "example": 0,
      -                            "type": "number"
      -                          }
      -                        },
      -                        "required": [
      -                          "startHour",
      -                          "startMinute",
      -                          "endHour",
      -                          "endMinute"
      -                        ],
      -                        "type": "object"
      -                      },
      -                      "type": "array"
      -                    }
      -                  },
      -                  "required": [
      -                    "dayOfTheWeek"
      -                  ],
      -                  "type": "object"
      -                },
      -                "type": "array"
      -              }
      -            },
      -            "required": [
      -              "dynamicChannelSwitching"
      -            ],
      -            "type": "object"
      -          }
      -        ],
      -        "description": "Additional settings for followup behavior"
      -      },
      -      "scenarioId": {
      -        "description": "ID of the followup scenario",
      -        "enum": [
      -          "contactStoppedReplying",
      -          "contactIsBusy",
      -          "contactRequested"
      -        ],
      -        "example": "contactIsBusy",
      -        "type": "string"
      -      }
      -    },
      -    "required": [
      -      "enabled",
      -      "scenarioId",
      -      "followupSequence"
      -    ],
      -    "type": "object"
      -  },
      -  {
      -    "properties": {
      -      "enabled": {
      -        "description": "Whether this transfer action is enabled",
      -        "example": true,
      -        "type": "boolean"
      -      },
      -      "transferBotExamples": {
      -        "description": "Example phrases that trigger transfer (required for Custom type, minimum 2)",
      -        "example": [
      -          "talk to sales",
      -          "pricing information",
      -          "speak to specialist"
      -        ],
      -        "items": {
      -          "type": "string"
      -        },
      -        "type": "array"
      -      },
      -      "transferBotTriggerCondition": {
      -        "description": "Condition that triggers the transfer (required for Custom type)",
      -        "example": "When the user asks to speak with sales or needs pricing information",
      -        "type": "string"
      -      },
      -      "transferBotType": {
      -        "description": "Type of transfer - Default or Custom",
      -        "enum": [
      -          "Default",
      -          "Custom"
      -        ],
      -        "example": "Custom",
      -        "type": "string"
      -      },
      -      "transferToBot": {
      -        "description": "ID of the bot/agent to transfer to",
      -        "example": "employee789",
      -        "type": "string"
      -      }
      -    },
      -    "required": [
      -      "transferBotType",
      -      "transferToBot",
      -      "enabled"
      -    ],
      -    "type": "object"
      -  }
      -]New value: +[
      +  {
      +    "properties": {
      +      "triggerCondition": {
      +        "description": "Condition that triggers the workflow",
      +        "example": "When user requests appointment",
      +        "type": "string"
      +      },
      +      "triggerMessage": {
      +        "description": "Optional message to send when triggering the workflow",
      +        "example": "Workflow triggered successfully",
      +        "type": "string"
      +      },
      +      "workflowIds": {
      +        "description": "Array of workflow IDs to trigger",
      +        "example": [
      +          "workflow123",
      +          "workflow456"
      +        ],
      +        "items": {
      +          "type": "string"
      +        },
      +        "type": "array"
      +      }
      +    },
      +    "required": [
      +      "workflowIds",
      +      "triggerCondition"
      +    ],
      +    "title": "triggerWorkflowDto",
      +    "type": "object"
      +  },
      +  {
      +    "properties": {
      +      "contactFieldId": {
      +        "description": "ID of the contact field in Contacts Table",
      +        "example": "123",
      +        "type": "string"
      +      },
      +      "contactUpdateExamples": {
      +        "default": [],
      +        "description": "Contact update examples in Contacts Table. Not required when using standard fields, Monetory or Date Custom fields.",
      +        "example": [
      +          "Example 1"
      +        ],
      +        "items": {
      +          "type": "string"
      +        },
      +        "type": "array"
      +      },
      +      "description": {
      +        "description": "Description of the contact field in Contacts Table",
      +        "example": "Business Name",
      +        "type": "string"
      +      }
      +    },
      +    "required": [
      +      "contactFieldId",
      +      "description"
      +    ],
      +    "title": "updateContactFieldDto",
      +    "type": "object"
      +  },
      +  {
      +    "properties": {
      +      "actionId": {
      +        "description": "Optional action ID reference",
      +        "example": "action123",
      +        "type": "string"
      +      },
      +      "calendarId": {
      +        "description": "Calendar ID for appointment booking",
      +        "example": "calendar123",
      +        "type": "string"
      +      },
      +      "cancelEnabled": {
      +        "default": false,
      +        "description": "Whether to allow appointment cancellation (cannot be true when onlySendLink is true)",
      +        "example": true,
      +        "type": "boolean"
      +      },
      +      "onlySendLink": {
      +        "description": "If true, only sends the appointment link without booking",
      +        "example": false,
      +        "type": "boolean"
      +      },
      +      "rescheduleEnabled": {
      +        "default": false,
      +        "description": "Whether to allow appointment rescheduling (cannot be true when onlySendLink is true)",
      +        "example": true,
      +        "type": "boolean"
      +      },
      +      "sleepAfterBooking": {
      +        "description": "Whether to put the agent to sleep after booking (cannot be true when onlySendLink is true)",
      +        "example": true,
      +        "type": "boolean"
      +      },
      +      "sleepTime": {
      +        "description": "Sleep duration (required when sleepAfterBooking is true)",
      +        "example": 24,
      +        "type": "number"
      +      },
      +      "sleepTimeUnit": {
      +        "description": "Unit for sleep time (required when sleepAfterBooking is true)",
      +        "enum": [
      +          "days",
      +          "hours",
      +          "minutes"
      +        ],
      +        "example": "hours",
      +        "type": "string"
      +      },
      +      "transferAgent": {
      +        "description": "Agent ID to transfer to (required when transferBot is true)",
      +        "example": "employee456",
      +        "type": "string"
      +      },
      +      "transferBot": {
      +        "description": "Whether to transfer to another agent after booking (cannot be true when onlySendLink is true)",
      +        "example": false,
      +        "type": "boolean"
      +      },
      +      "triggerWorkflow": {
      +        "description": "Whether to trigger a workflow after booking (cannot be true when onlySendLink is true)",
      +        "example": true,
      +        "type": "boolean"
      +      },
      +      "workflowIds": {
      +        "description": "Workflow IDs to trigger after booking (required when triggerWorkflow is true)",
      +        "example": [
      +          "workflow123"
      +        ],
      +        "items": {
      +          "type": "string"
      +        },
      +        "type": "array"
      +      }
      +    },
      +    "required": [
      +      "calendarId",
      +      "onlySendLink",
      +      "triggerWorkflow",
      +      "sleepAfterBooking",
      +      "transferBot",
      +      "rescheduleEnabled",
      +      "cancelEnabled"
      +    ],
      +    "title": "appointmentBookingDto",
      +    "type": "object"
      +  },
      +  {
      +    "properties": {
      +      "enabled": {
      +        "description": "Whether this action is enabled for the agent",
      +        "example": true,
      +        "type": "boolean"
      +      },
      +      "finalMessage": {
      +        "description": "Final message sent when stopping the bot",
      +        "example": "Thank you for contacting us. Have a great day!",
      +        "type": "string"
      +      },
      +      "reactivateEnabled": {
      +        "description": "Whether the bot can be reactivated after being stopped",
      +        "example": true,
      +        "type": "boolean"
      +      },
      +      "sleepTime": {
      +        "description": "Time duration before reactivation (required when reactivateEnabled is true)",
      +        "example": 24,
      +        "type": "number"
      +      },
      +      "sleepTimeUnit": {
      +        "description": "Time unit for reactivation delay (required when reactivateEnabled is true)",
      +        "enum": [
      +          "days",
      +          "hours",
      +          "minutes"
      +        ],
      +        "example": "hours",
      +        "type": "string"
      +      },
      +      "stopBotDetectionType": {
      +        "description": "Type of stop bot detection - Goodbye or Custom",
      +        "enum": [
      +          "Goodbye",
      +          "Custom"
      +        ],
      +        "example": "Custom",
      +        "type": "string"
      +      },
      +      "stopBotExamples": {
      +        "description": "Example phrases that trigger stop bot action (minimum 2 required)",
      +        "example": [
      +          "goodbye",
      +          "thank you",
      +          "no more questions"
      +        ],
      +        "items": {
      +          "type": "string"
      +        },
      +        "type": "array"
      +      },
      +      "stopBotTriggerCondition": {
      +        "description": "Condition that triggers stopping the bot",
      +        "example": "When the user says they no longer need assistance or want to end the conversation",
      +        "type": "string"
      +      },
      +      "tags": {
      +        "description": "Tags to apply when stopping the bot",
      +        "example": [
      +          "resolved",
      +          "no-response"
      +        ],
      +        "items": {
      +          "type": "string"
      +        },
      +        "type": "array"
      +      }
      +    },
      +    "required": [
      +      "stopBotDetectionType",
      +      "stopBotTriggerCondition",
      +      "reactivateEnabled",
      +      "enabled",
      +      "stopBotExamples",
      +      "finalMessage"
      +    ],
      +    "title": "stopBotDto",
      +    "type": "object"
      +  },
      +  {
      +    "properties": {
      +      "assignToUserId": {
      +        "description": "ID of the user to assign the conversation to",
      +        "example": "user123",
      +        "type": "string"
      +      },
      +      "createTask": {
      +        "description": "Whether to create a task when handing over",
      +        "example": true,
      +        "type": "boolean"
      +      },
      +      "enabled": {
      +        "description": "Whether human handover action is enabled",
      +        "example": true,
      +        "type": "boolean"
      +      },
      +      "examples": {
      +        "description": "Example phrases that trigger human handover (required when handoverType is custom or contactRequest)",
      +        "example": [
      +          "speak to human",
      +          "talk to agent",
      +          "need help from person"
      +        ],
      +        "items": {
      +          "type": "string"
      +        },
      +        "type": "array"
      +      },
      +      "finalMessage": {
      +        "description": "Final message sent when handing over to human",
      +        "example": "I am transferring you to a human agent who will assist you shortly.",
      +        "type": "string"
      +      },
      +      "handoverType": {
      +        "description": "Type of human handover detection",
      +        "enum": [
      +          "contactRequest",
      +          "lackOfInformation",
      +          "failedToResolveIssue",
      +          "custom"
      +        ],
      +        "example": "contactRequest",
      +        "type": "string"
      +      },
      +      "reactivateEnabled": {
      +        "description": "Whether the agent can be reactivated after handover",
      +        "example": true,
      +        "type": "boolean"
      +      },
      +      "skipAssignToUser": {
      +        "description": "Whether to skip assigning to a specific user",
      +        "example": false,
      +        "type": "boolean"
      +      },
      +      "sleepTime": {
      +        "description": "Time duration before reactivation (required when reactivateEnabled is true)",
      +        "example": 24,
      +        "type": "number"
      +      },
      +      "sleepTimeUnit": {
      +        "description": "Time unit for reactivation delay (required when reactivateEnabled is true)",
      +        "enum": [
      +          "days",
      +          "hours",
      +          "minutes"
      +        ],
      +        "example": "hours",
      +        "type": "string"
      +      },
      +      "tags": {
      +        "description": "Tags to apply during handover",
      +        "example": [
      +          "escalated",
      +          "human-requested"
      +        ],
      +        "items": {
      +          "type": "string"
      +        },
      +        "type": "array"
      +      },
      +      "triggerCondition": {
      +        "description": "Condition that triggers human handover",
      +        "example": "When the user requests to speak with a human agent or expresses frustration",
      +        "type": "string"
      +      }
      +    },
      +    "required": [
      +      "enabled",
      +      "triggerCondition",
      +      "reactivateEnabled",
      +      "finalMessage",
      +      "handoverType"
      +    ],
      +    "title": "humanHandOverDto",
      +    "type": "object"
      +  },
      +  {
      +    "properties": {
      +      "enabled": {
      +        "description": "Whether advanced followup is enabled",
      +        "example": true,
      +        "type": "boolean"
      +      },
      +      "followupSequence": {
      +        "description": "Sequence of followup actions to perform",
      +        "example": [
      +          {
      +            "aiEnabledMessage": true,
      +            "followupTime": 2,
      +            "followupTimeUnit": "hours",
      +            "id": 1
      +          }
      +        ],
      +        "items": {
      +          "properties": {
      +            "aiEnabledMessage": {
      +              "default": true,
      +              "description": "Whether to use AI to generate the followup message",
      +              "example": true,
      +              "type": "boolean"
      +            },
      +            "contactRequested": {
      +              "description": "Whether contact was requested in this followup",
      +              "example": false,
      +              "type": "boolean"
      +            },
      +            "customMessage": {
      +              "description": "Custom message to send (when aiEnabledMessage is false)",
      +              "example": "Hi! Just following up on our previous conversation. Do you have any questions?",
      +              "type": "string"
      +            },
      +            "followupTime": {
      +              "description": "Time duration before followup (max: 60 minutes, 24 hours, or 180 days depending on unit)",
      +              "example": 2,
      +              "type": "number"
      +            },
      +            "followupTimeUnit": {
      +              "description": "Time unit for followup delay",
      +              "enum": [
      +                "days",
      +                "hours",
      +                "minutes"
      +              ],
      +              "example": "hours",
      +              "type": "string"
      +            },
      +            "id": {
      +              "description": "Unique identifier for this followup step",
      +              "example": 1,
      +              "type": "number"
      +            },
      +            "triggerWorkflow": {
      +              "default": false,
      +              "description": "Whether to trigger a workflow during this followup",
      +              "example": false,
      +              "type": "boolean"
      +            },
      +            "workflowId": {
      +              "description": "Workflow ID to trigger (when triggerWorkflow is true)",
      +              "example": "workflow789",
      +              "type": "string"
      +            }
      +          },
      +          "required": [
      +            "id",
      +            "followupTimeUnit",
      +            "followupTime"
      +          ],
      +          "title": "FollowupSequence",
      +          "type": "object"
      +        },
      +        "type": "array"
      +      },
      +      "followupSettings": {
      +        "allOf": [
      +          {
      +            "properties": {
      +              "dynamicChannelSwitching": {
      +                "default": true,
      +                "description": "Whether to dynamically switch channels for followups",
      +                "example": true,
      +                "type": "boolean"
      +              },
      +              "followUpHours": {
      +                "description": "Whether to respect working hours for followups",
      +                "example": true,
      +                "type": "boolean"
      +              },
      +              "timezoneToUse": {
      +                "description": "Timezone to use for followups, contact or location",
      +                "enum": [
      +                  "contact",
      +                  "business"
      +                ],
      +                "example": "contact",
      +                "type": "string"
      +              },
      +              "workingHours": {
      +                "description": "Working hours configuration for followups",
      +                "example": [
      +                  {
      +                    "dayOfTheWeek": 1,
      +                    "intervals": [
      +                      {
      +                        "endHour": 17,
      +                        "endMinute": 0,
      +                        "startHour": 9,
      +                        "startMinute": 0
      +                      }
      +                    ]
      +                  }
      +                ],
      +                "items": {
      +                  "properties": {
      +                    "dayOfTheWeek": {
      +                      "description": "Day of the week (0=Sunday, 1=Monday, etc.)",
      +                      "example": 1,
      +                      "type": "number"
      +                    },
      +                    "intervals": {
      +                      "description": "Time intervals for this day",
      +                      "example": [
      +                        {
      +                          "endHour": 17,
      +                          "endMinute": 0,
      +                          "startHour": 9,
      +                          "startMinute": 0
      +                        }
      +                      ],
      +                      "items": {
      +                        "properties": {
      +                          "endHour": {
      +                            "description": "End hour (24-hour format)",
      +                            "example": 17,
      +                            "type": "number"
      +                          },
      +                          "endMinute": {
      +                            "description": "End minute",
      +                            "example": 30,
      +                            "type": "number"
      +                          },
      +                          "startHour": {
      +                            "description": "Start hour (24-hour format)",
      +                            "example": 9,
      +                            "type": "number"
      +                          },
      +                          "startMinute": {
      +                            "description": "Start minute",
      +                            "example": 0,
      +                            "type": "number"
      +                          }
      +                        },
      +                        "required": [
      +                          "startHour",
      +                          "startMinute",
      +                          "endHour",
      +                          "endMinute"
      +                        ],
      +                        "title": "Interval",
      +                        "type": "object"
      +                      },
      +                      "type": "array"
      +                    }
      +                  },
      +                  "required": [
      +                    "dayOfTheWeek"
      +                  ],
      +                  "title": "WorkingHours",
      +                  "type": "object"
      +                },
      +                "type": "array"
      +              }
      +            },
      +            "required": [
      +              "dynamicChannelSwitching"
      +            ],
      +            "title": "FollowupSettings",
      +            "type": "object"
      +          }
      +        ],
      +        "description": "Additional settings for followup behavior",
      +        "example": {
      +          "dynamicChannelSwitching": true,
      +          "followUpHours": false,
      +          "timezoneToUse": "contact"
      +        }
      +      },
      +      "scenarioId": {
      +        "description": "ID of the followup scenario",
      +        "enum": [
      +          "contactStoppedReplying",
      +          "contactIsBusy",
      +          "contactRequested"
      +        ],
      +        "example": "contactIsBusy",
      +        "type": "string"
      +      }
      +    },
      +    "required": [
      +      "enabled",
      +      "scenarioId",
      +      "followupSequence"
      +    ],
      +    "title": "advancedFollowupDto",
      +    "type": "object"
      +  },
      +  {
      +    "properties": {
      +      "enabled": {
      +        "description": "Whether this transfer action is enabled",
      +        "example": true,
      +        "type": "boolean"
      +      },
      +      "transferBotExamples": {
      +        "description": "Example phrases that trigger transfer (required for Custom type, minimum 2)",
      +        "example": [
      +          "talk to sales",
      +          "pricing information",
      +          "speak to specialist"
      +        ],
      +        "items": {
      +          "type": "string"
      +        },
      +        "type": "array"
      +      },
      +      "transferBotTriggerCondition": {
      +        "description": "Condition that triggers the transfer (required for Custom type)",
      +        "example": "When the user asks to speak with sales or needs pricing information",
      +        "type": "string"
      +      },
      +      "transferBotType": {
      +        "description": "Type of transfer - Default or Custom",
      +        "enum": [
      +          "Default",
      +          "Custom"
      +        ],
      +        "example": "Custom",
      +        "type": "string"
      +      },
      +      "transferToBot": {
      +        "description": "ID of the bot/agent to transfer to",
      +        "example": "employee789",
      +        "type": "string"
      +      }
      +    },
      +    "required": [
      +      "transferBotType",
      +      "transferToBot",
      +      "enabled"
      +    ],
      +    "title": "transferBotDto",
      +    "type": "object"
      +  },
      +  {
      +    "properties": {
      +      "apiConfig": {
      +        "allOf": [
      +          {
      +            "properties": {
      +              "authentication": {
      +                "description": "Auth config; secrets stored per-instance, write-only",
      +                "example": {
      +                  "token": "••••••••",
      +                  "type": "bearer"
      +                },
      +                "type": "object"
      +              },
      +              "bodyTemplate": {
      +                "description": "Request body template — object or raw JSON string. Supports {{variable}} placeholders.",
      +                "example": {
      +                  "email": "{{contact.email}}",
      +                  "orderId": "{{parameters.orderId}}"
      +                },
      +                "type": "object"
      +              },
      +              "headers": {
      +                "additionalProperties": {
      +                  "type": "string"
      +                },
      +                "description": "Static HTTP headers sent with every call. Secrets belong in `authentication`, not here. On update this object REPLACES the stored headers — send them all, not just the changed one.",
      +                "example": {
      +                  "Content-Type": "application/json",
      +                  "X-Source": "conversation-ai"
      +                },
      +                "type": "object"
      +              },
      +              "method": {
      +                "description": "HTTP method used for the call. REQUIRED on create. Optional on update — omit it to keep the stored method.",
      +                "enum": [
      +                  "GET",
      +                  "POST",
      +                  "PUT",
      +                  "PATCH",
      +                  "DELETE"
      +                ],
      +                "example": "GET",
      +                "type": "string"
      +              },
      +              "outputFields": {
      +                "description": "Dot-paths of the response fields handed back to the agent. Omit to return the whole body; use [] notation for arrays, e.g. `result[].id`.",
      +                "example": [
      +                  "data.id",
      +                  "data.status"
      +                ],
      +                "items": {
      +                  "type": "string"
      +                },
      +                "type": "array"
      +              },
      +              "parameters": {
      +                "additionalProperties": true,
      +                "description": "JSON Schema of LLM-supplied params",
      +                "example": {
      +                  "properties": {
      +                    "orderId": {
      +                      "description": "The order number the caller gave",
      +                      "type": "string"
      +                    }
      +                  },
      +                  "required": [
      +                    "orderId"
      +                  ],
      +                  "type": "object"
      +                },
      +                "type": "object"
      +              },
      +              "queryParams": {
      +                "additionalProperties": {
      +                  "type": "string"
      +                },
      +                "description": "Static query-string parameters appended to the URL.",
      +                "example": {
      +                  "limit": "10",
      +                  "status": "active"
      +                },
      +                "type": "object"
      +              },
      +              "retryOnFailure": {
      +                "description": "Retry the call once on a network error or a 5xx. 4xx is never retried.",
      +                "example": false,
      +                "type": "boolean"
      +              },
      +              "sampleResponse": {
      +                "additionalProperties": true,
      +                "description": "Trimmed sample of a real response (editor Test tab). Prompt-only — inlined so the agent knows the response shape; never executed. Secrets are masked on read.",
      +                "type": "object"
      +              },
      +              "timeoutMs": {
      +                "description": "Per-request timeout in milliseconds (max 60000).",
      +                "example": 15000,
      +                "type": "number"
      +              },
      +              "url": {
      +                "description": "HTTPS endpoint; supports {{var}}. REQUIRED on create. Optional on update — omit it to keep the stored url (apiConfig merges by top-level key).",
      +                "example": "https://api.example.com/orders/{{orderId}}",
      +                "type": "string"
      +              },
      +              "useSimpleRequestBody": {
      +                "description": "Send the body template verbatim as raw JSON instead of building it from the parameter schema.",
      +                "example": false,
      +                "type": "boolean"
      +              }
      +            },
      +            "title": "ApiCallConfigDTO",
      +            "type": "object"
      +          }
      +        ],
      +        "description": "The self-contained HTTP definition. Required on CREATE (enforced in the handler). OPTIONAL on UPDATE — omit it to edit just name/description/triggerCondition. When sent on update it is merged ONE LEVEL DEEP over the stored config: top-level keys present replace the stored value, keys absent are kept, and nested objects/arrays (headers, queryParams, bodyTemplate, parameters, outputFields) are replaced whole — send the complete value, not just the entry that changed. Secrets are redacted on read; see `authentication` for how they round-trip."
      +      },
      +      "description": {
      +        "description": "Optional description of the API Call action",
      +        "example": "Looks up an order in the fulfilment system and returns its status and delivery date.",
      +        "maxLength": 2000,
      +        "type": "string"
      +      },
      +      "postActionPrompt": {
      +        "description": "Guidance the agent follows AFTER the call returns (e.g. how to phrase the reply, what not to reveal). REQUIRED on CREATE (enforced in the handler) to match the builder; on UPDATE it may be OMITTED to leave it unchanged (partial merge), but sending it blank is rejected.",
      +        "maxLength": 300,
      +        "type": "string"
      +      },
      +      "triggerCondition": {
      +        "description": "\"use this when…\" rule shown to the agent. REQUIRED on CREATE (enforced in the handler) to match the builder; on UPDATE it may be OMITTED to leave it unchanged, but sending it blank is rejected.",
      +        "example": "When the customer asks where their order is or for a delivery date.",
      +        "maxLength": 500,
      +        "type": "string"
      +      }
      +    },
      +    "title": "CustomApiDetailsDTO",
      +    "type": "object"
      +  }
      +]
    • addedInput schema / properties / body / properties / name / description
      Added value: +"Name of the action (3-50 characters)"
    • addedInput schema / properties / body / properties / type / description
      Added value: +"Type of action to perform"
    • changedInput schema / properties / body / properties / type / enum
      Previous value: -[
      -  "triggerWorkflow",
      -  "updateContactField",
      -  "appointmentBooking",
      -  "stopBot",
      -  "humanHandOver",
      -  "advancedFollowup",
      -  "transferBot"
      -]New value: +[
      +  "triggerWorkflow",
      +  "updateContactField",
      +  "appointmentBooking",
      +  "stopBot",
      +  "humanHandOver",
      +  "advancedFollowup",
      +  "transferBot",
      +  "customApi"
      +]
    • addedInput schema / properties / body / title
      Added value: +"CreateActionDTO"
  2. First observedv2.0.0

TDQS

A4.3/5.0
Behavior4/5

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false and openWorldHint=true. The description adds real value beyond them: the 5-action-per-agent limit, the customApi configuration requirement, and the required OAuth scope `conversation-ai.write`. It stops short of describing the response or rollback behavior.

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?

Front-loaded with the purpose, then the type examples, then the customApi caveat, then endpoint and scopes. Every sentence carries information; the only redundancy is the title line echoing the tool name.

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

Completeness4/5

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

For a mutation tool with a deeply nested polymorphic body and no output schema, the description supplies endpoint, version header, OAuth scope, and the key limit/customApi constraints. It could say more about how agentId is sourced or what the created action returns, but nothing critical is missing.

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

Parameters4/5

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema does not foreground: that `details` must contain `apiConfig` for the customApi type and that a per-agent limit applies. The polymorphism of `details` is explained in the schema description, so the marginal gain is modest.

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

Purpose5/5

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

States a specific verb and resource ('Creates and attach a new action for an AI agent') and enumerates concrete action categories (booking, follow-ups, custom API). The agent can distinguish this creation tool from siblings like ghl_conversation_ai_update_action or ghl_conversation_ai_create_agent without opening the schema.

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

Usage Guidelines4/5

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

Gives actionable routing guidance for the non-obvious case: for `customApi`, put config in `details`, with `details.apiConfig` required and a per-agent cap of 5. It does not explicitly contrast with `update_action` or `create_agent`, so it stops short of full when/when-not framing.

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