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

ghl-mcp-server-v2

by zackscriven

ghl_agent_studio_execute

Executes a GoHighLevel Agent Studio agent to return complete JSON output; continue multi-turn conversations by passing executionId from prior responses.

Instructions

Execute Agent Executes the specified agent and returns a non-streaming JSON response with the complete agent output. The agent must be in active status and belong to the specified location. locationId is required in the request body.

Session Management:

  • For the first message in a new session, do not include the executionId in the request payload.

  • The API will return an executionId along with the agent response, which uniquely identifies this conversation session.

  • To continue the conversation within the same session, include the executionId from the previous response in subsequent requests. This allows the agent to maintain conversation context and history across multiple interactions. Endpoint: POST /agent-studio/agent/{agentId}/execute (Version header: v3; source: v3/agent-studio-v3.json) Requires a Sub-Account (location) token. OAuth scopes: agent-studio.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_agent_studio_execute"
  }
}

Input Schema

NameRequiredDescriptionDefault
bodyYesRequest body (schema carried verbatim from the official OpenAPI spec).
sourceNoOrigin channel attributed to this execution for auditing (e.g. public_api, internal)
agentIdYesAgent ID to execute (must be in active status and belong to the location)

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed5 schema fields changedv2.1.0
    • addedInput schema / properties / agentId / description
      Added value: +"Agent ID to execute (must be in active status and belong to the location)"
    • addedInput schema / properties / body / properties / attachments / example
      Added value: +[
      +  {
      +    "mimeType": "image/png",
      +    "type": "image",
      +    "url": "https://example.com/image.png"
      +  }
      +]
    • addedInput schema / properties / body / properties / attachments / items / title
      Added value: +"PublicAttachmentSchema"
    • addedInput schema / properties / body / title
      Added value: +"ExecutePublicAgentDTO"
    • addedInput schema / properties / source / description
      Added value: +"Origin channel attributed to this execution for auditing (e.g. public_api, internal)"
  2. First observedv2.0.0

TDQS

A3.9/5.0
Behavior4/5

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

Annotations already declare readOnly=false, idempotent=false, openWorld=true, destructive=false, so the safety profile is covered. The description adds meaningful context beyond that: a Sub-Account (location) token is required, the OAuth scope agent-studio.write is needed, responses are non-streaming JSON, and the call establishes server-side session state keyed by the returned executionId.

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-loads the core verb and response type, then uses a labeled Session Management block for the multi-turn rule. Slightly verbose with endpoint/version/source metadata that is of marginal use to an invoking agent, but nothing is truly wasted.

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 stateful, non-idempotent execution call with no output schema, the description covers auth requirements, endpoint, session lifecycle, and required fields. It leaves the response shape at 'complete agent output' and says nothing about failure modes such as an inactive agent or an unknown executionId, which would have been worth a sentence.

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%, so the schema already documents all parameters including the executionId lifecycle and inputVariables semantics. The description restates the locationId requirement and the session pattern but adds no syntax or format detail the schema does not already carry; baseline 3 applies.

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

Purpose4/5

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

States a specific verb and resource ('Executes the specified agent') and adds the important qualifier that the response is a non-streaming JSON payload containing the complete agent output. It does not, however, distinguish itself from the closely related siblings ghl_agent_studio_execute_managed and ghl_agent_studio_execute_deprecated, which an agent must choose between.

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 real preconditions: the agent must be active and belong to the supplied location, locationId is required, and the first-message vs. continuation-message rule for executionId is spelled out explicitly. Missing is any routing guidance to or away from the managed/deprecated execute variants.

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