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

ghl-mcp-server-v2

by zackscriven

ghl_agent_studio_execute_deprecated

Execute a GoHighLevel agent via the deprecated Agent Studio endpoint and return its complete JSON response; migrate to the documented execute endpoint.

Instructions

Deprecated per official spec — use ghl_agent_studio_execute (POST /agent-studio/agent/{agentId}/execute) instead. [DEPRECATED per official docs — prefer the documented replacement if one exists.] Execute Agent (Deprecated) Deprecated endpoint - use POST /agent/:agentId/execute instead.

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. Endpoint: POST /agent-studio/public-api/agents/{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_deprecated"
  }
}

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)
agentIdYesManaged Agent ID

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed5 schema fields changedv2.1.0
    • addedInput schema / properties / agentId / description
      Added value: +"Managed Agent ID"
    • 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.6/5.0
Behavior4/5

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

Annotations already declare non-readOnly, open-world, non-idempotent, non-destructive; the description adds prerequisites the annotations cannot express: the agent must be active and belong to the location, a Sub-Account token is required, the scope is agent-studio.write, and executionId carries session state across calls. That is substantive schema-independent context, though it omits error behavior and what happens on an inactive agent.

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

Conciseness2/5

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

The deprecation warning appears four separate times before any functional content ('Deprecated per official spec', the bracketed DEPRECATED line, the title line, and the bolded 'Deprecated endpoint' sentence), and two different URL paths are quoted for the replacement. Redundancy and front-loading of a single repeated fact push the useful content down and dilute it.

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?

Given three parameters with a nested body object and no output schema, the description supplies auth requirements, agent status prerequisites, the session continuation protocol, and the response shape ('non-streaming JSON ... complete agent output'), which is enough to invoke it correctly. Only error and version-header behavior details are thin.

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 description coverage is 100%, so the baseline is 3. The description restates the locationId-in-body requirement and explains the executionId omit-on-first-message / echo-on-subsequent-message protocol, which is helpful workflow guidance but largely duplicates what the executionId property description already says.

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 returns a non-streaming JSON response with the complete agent output') and names the sibling it supersedes, ghl_agent_studio_execute. The purpose is recognizable, but the repeated deprecation banners bury the actual functional sentence several lines down.

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?

Explicitly routes the agent to ghl_agent_studio_execute (POST /agent-studio/agent/{agentId}/execute) as the preferred alternative, which is the key decision an agent faces here. It does not explain any situation in which this deprecated tool is still the correct choice, leaving that inference to the caller.

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