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

ghl-mcp-server-v2

by zackscriven

ghl_social_attach_oauth_accounts

Connects a selected OAuth social account to a GoHighLevel location as the final OAuth step, enabling the account for social media posting.

Instructions

Connect Account (Step 3 of 3)

OAuth Connection Flow - Step 3: Connect the Account

This is the final step in the OAuth flow. After retrieving available accounts (Step 2), use this endpoint to connect the selected account to your location.

OAuth Flow Summary

  1. Start OAuth → User authenticates with platform

  2. Get Accounts → Retrieved available pages/channels

  3. Attach Account (this endpoint) → Connect the selected account

Request Body

The accepted fields depend on the platform path parameter — pick the matching schema in the request body below. Most platforms take the originId, name and optional avatar of the account you selected in Step 2; Google Business Profile takes the full location and account objects.

tiktok-business accounts are connected through the TikTok Business flow, not this endpoint.

After Connection

Once connected, the account will appear in your location's connected accounts and can be used for social media posting. Endpoint: POST /social-media-posting/oauth/{locationId}/{platform}/accounts/{accountId} (Version header: v3; source: v3/social-planner-v3.json) Requires a Sub-Account (location) token. OAuth scopes: socialplanner/oauth.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": {
      "platform": "<platform>",
      "locationId": "<locationId>",
      "accountId": "<accountId>",
      "body": "<body>"
    },
    "name": "ghl_social_attach_oauth_accounts"
  }
}

Input Schema

NameRequiredDescriptionDefault
bodyYesThe account to connect. The accepted fields depend on the `platform` path parameter.
platformYesSocial media platform. Must match the platform used in the preceding steps of the OAuth flow.
accountIdYesThe OAuth Account ID received from Step 1 (Start OAuth) via the window message event
locationIdYesThe Location ID where you want to connect this social account

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed9 schema fields changedv2.1.0
    • changedInput schema / properties / accountId / description
      Previous value: -"The OAuth Account ID received from Step 1 (same as used in Step 2)"New value: +"The OAuth Account ID received from Step 1 (Start OAuth) via the window message event"
    • addedInput schema / properties / accountId / example
      Added value: +"w37swmmLbA02zgqKPpxITe"
    • changedInput schema / properties / body / description
      Previous value: -"Account details to connect. The structure varies by platform - see description above for examples."New value: +"The account to connect. The accepted fields depend on the `platform` path parameter."
    • changedInput schema / properties / body / oneOf
      Previous value: -[
      -  {
      -    "properties": {
      -      "avatar": {
      -        "description": "Avatar or profile picture URL",
      -        "example": "https://storage.googleapis.com/2ad21ebc23/test",
      -        "type": "string"
      -      },
      -      "name": {
      -        "description": "Name of the Facebook page or account",
      -        "example": "JOHN_DEO",
      -        "type": "string"
      -      },
      -      "originId": {
      -        "description": "Original Facebook platform identifier",
      -        "example": "244405****11687",
      -        "type": "string"
      -      },
      -      "type": {
      -        "description": "Type of Facebook account (must be page)",
      -        "enum": [
      -          "page"
      -        ],
      -        "example": "page",
      -        "type": "string"
      -      }
      -    },
      -    "required": [
      -      "type",
      -      "originId",
      -      "name",
      -      "avatar"
      -    ],
      -    "title": "Facebook",
      -    "type": "object"
      -  },
      -  {
      -    "properties": {
      -      "avatar": {
      -        "description": "Avatar or profile picture URL",
      -        "example": "https://storage.googleapis.com/2ad21ebc23/test",
      -        "type": "string"
      -      },
      -      "name": {
      -        "description": "Display name of the account",
      -        "example": "JOHN_DEO",
      -        "type": "string"
      -      },
      -      "originId": {
      -        "description": "Original platform-specific account identifier",
      -        "example": "244405****11687",
      -        "type": "string"
      -      },
      -      "pageId": {
      -        "description": "Facebook page ID associated with the Instagram account",
      -        "example": "234234234242sd",
      -        "type": "string"
      -      }
      -    },
      -    "required": [
      -      "pageId"
      -    ],
      -    "title": "Instagram",
      -    "type": "object"
      -  },
      -  {
      -    "properties": {
      -      "account": {
      -        "allOf": [
      -          {
      -            "properties": {
      -              "accountName": {
      -                "description": "Display name of the account",
      -                "type": "string"
      -              },
      -              "name": {
      -                "description": "Account name identifier",
      -                "type": "string"
      -              },
      -              "type": {
      -                "description": "Type of the account",
      -                "type": "string"
      -              },
      -              "verificationState": {
      -                "description": "State of account verification",
      -                "type": "string"
      -              },
      -              "vettedState": {
      -                "description": "Vetting state of the account",
      -                "type": "string"
      -              }
      -            },
      -            "required": [
      -              "name",
      -              "accountName",
      -              "type",
      -              "verificationState",
      -              "vettedState"
      -            ],
      -            "type": "object"
      -          }
      -        ],
      -        "type": "object"
      -      },
      -      "location": {
      -        "allOf": [
      -          {
      -            "properties": {
      -              "isConnected": {
      -                "description": "Whether the location is connected",
      -                "type": "boolean"
      -              },
      -              "isVerified": {
      -                "description": "Whether the location is verified",
      -                "type": "boolean"
      -              },
      -              "maxLocation": {
      -                "description": "Whether this is a max location",
      -                "type": "boolean"
      -              },
      -              "metadata": {
      -                "description": "Additional metadata",
      -                "type": "object"
      -              },
      -              "name": {
      -                "description": "Location name",
      -                "type": "string"
      -              },
      -              "storeCode": {
      -                "description": "Store code",
      -                "type": "string"
      -              },
      -              "storefrontAddress": {
      -                "description": "Storefront address details",
      -                "type": "object"
      -              },
      -              "title": {
      -                "description": "Location title",
      -                "type": "string"
      -              }
      -            },
      -            "required": [
      -              "name",
      -              "title"
      -            ],
      -            "type": "object"
      -          }
      -        ],
      -        "type": "object"
      -      }
      -    },
      -    "required": [
      -      "location",
      -      "account"
      -    ],
      -    "title": "Google Business Account",
      -    "type": "object"
      -  },
      -  {
      -    "properties": {
      -      "avatar": {
      -        "description": "Avatar URL",
      -        "type": "string"
      -      },
      -      "companyId": {
      -        "description": "Company ID",
      -        "example": "companyId",
      -        "type": "string"
      -      },
      -      "name": {
      -        "description": "Name",
      -        "example": "Ayush",
      -        "type": "string"
      -      },
      -      "originAccountType": {
      -        "description": "Origin account type",
      -        "type": "string"
      -      },
      -      "originId": {
      -        "description": "Origin ID",
      -        "example": "244405****11687",
      -        "type": "string"
      -      },
      -      "type": {
      -        "description": "Account type must be one of the following values: profile",
      -        "enum": [
      -          "profile"
      -        ],
      -        "type": "string"
      -      },
      -      "username": {
      -        "description": "Username",
      -        "example": "@ayush",
      -        "type": "string"
      -      },
      -      "verified": {
      -        "description": "Verification status",
      -        "example": true,
      -        "type": "boolean"
      -      },
      -      "websiteUrl": {
      -        "description": "Website URL",
      -        "example": "https://www.website.com",
      -        "type": "string"
      -      }
      -    },
      -    "required": [
      -      "originId"
      -    ],
      -    "title": "Pinterest",
      -    "type": "object"
      -  },
      -  {
      -    "properties": {
      -      "avatar": {
      -        "description": "Avatar or profile picture URL",
      -        "example": "https://example.com/avatar.jpg",
      -        "type": "string"
      -      },
      -      "name": {
      -        "description": "Display name of the account",
      -        "example": "JOHN_DEO",
      -        "type": "string"
      -      },
      -      "originId": {
      -        "description": "Original platform-specific account identifier",
      -        "example": "244405****11687",
      -        "type": "string"
      -      },
      -      "type": {
      -        "description": "Type of TikTok account",
      -        "enum": [
      -          "page",
      -          "group",
      -          "profile",
      -          "location",
      -          "business"
      -        ],
      -        "example": "profile",
      -        "type": "string"
      -      },
      -      "username": {
      -        "description": "Username or handle of the TikTok account",
      -        "example": "JOHN_DEO",
      -        "type": "string"
      -      },
      -      "verified": {
      -        "description": "Indicates if the TikTok account is verified",
      -        "example": true,
      -        "type": "boolean"
      -      }
      -    },
      -    "required": [
      -      "type",
      -      "originId",
      -      "name",
      -      "avatar"
      -    ],
      -    "title": "Tiktok",
      -    "type": "object"
      -  },
      -  {
      -    "properties": {
      -      "avatar": {
      -        "description": "Avatar URL",
      -        "type": "string"
      -      },
      -      "name": {
      -        "description": "Name",
      -        "example": "Ayush",
      -        "type": "string"
      -      },
      -      "originId": {
      -        "description": "Origin ID",
      -        "example": "244405****11687",
      -        "type": "string"
      -      },
      -      "type": {
      -        "description": "Account type",
      -        "enum": [
      -          "profile"
      -        ],
      -        "type": "string"
      -      },
      -      "username": {
      -        "description": "Username",
      -        "example": "@ayush",
      -        "type": "string"
      -      },
      -      "verified": {
      -        "description": "Verification status",
      -        "example": true,
      -        "type": "boolean"
      -      }
      -    },
      -    "required": [
      -      "type",
      -      "originId",
      -      "name",
      -      "avatar"
      -    ],
      -    "title": "YouTube",
      -    "type": "object"
      -  },
      -  {
      -    "properties": {
      -      "avatar": {
      -        "description": "Avatar or profile picture URL",
      -        "example": "https://storage.googleapis.com/2ad21ebc23/test",
      -        "type": "string"
      -      },
      -      "name": {
      -        "description": "Name of the LinkedIn page or profile",
      -        "example": "JOHN_DEO",
      -        "type": "string"
      -      },
      -      "originId": {
      -        "description": "Original LinkedIn platform identifier",
      -        "example": "244405****11687",
      -        "type": "string"
      -      },
      -      "type": {
      -        "description": "Type of LinkedIn account (must be one of: page, profile)",
      -        "enum": [
      -          "page",
      -          "group",
      -          "profile",
      -          "location",
      -          "business"
      -        ],
      -        "example": "page",
      -        "type": "string"
      -      },
      -      "urn": {
      -        "description": "LinkedIn URN (Uniform Resource Name) identifier",
      -        "example": "urn:li:organization:80847980",
      -        "type": "string"
      -      }
      -    },
      -    "required": [
      -      "type",
      -      "originId",
      -      "name",
      -      "avatar",
      -      "urn"
      -    ],
      -    "title": "Linkedin",
      -    "type": "object"
      -  },
      -  {
      -    "properties": {
      -      "avatar": {
      -        "description": "Avatar URL",
      -        "example": "https://storage.googleapis.com/2ad21ebc23/test",
      -        "type": "string"
      -      },
      -      "name": {
      -        "description": "Account name",
      -        "example": "JOHN_DEO",
      -        "type": "string"
      -      },
      -      "originId": {
      -        "description": "Origin ID",
      -        "example": "244405****11687",
      -        "type": "string"
      -      },
      -      "type": {
      -        "description": "Account type",
      -        "enum": [
      -          "profile"
      -        ],
      -        "example": "profile",
      -        "type": "string"
      -      }
      -    },
      -    "required": [
      -      "type",
      -      "originId",
      -      "name",
      -      "avatar"
      -    ],
      -    "title": "Threads",
      -    "type": "object"
      -  }
      -]New value: +[
      +  {
      +    "properties": {
      +      "avatar": {
      +        "description": "Avatar or profile picture URL",
      +        "example": "https://storage.googleapis.com/2ad21ebc23/test",
      +        "type": "string"
      +      },
      +      "name": {
      +        "description": "Name of the Facebook page or account",
      +        "example": "JOHN_DEO",
      +        "type": "string"
      +      },
      +      "originId": {
      +        "description": "Original Facebook platform identifier",
      +        "example": "244405****11687",
      +        "type": "string"
      +      },
      +      "type": {
      +        "description": "Type of Facebook account (must be page)",
      +        "enum": [
      +          "page",
      +          "group",
      +          "profile",
      +          "location",
      +          "business"
      +        ],
      +        "example": "page",
      +        "type": "string"
      +      }
      +    },
      +    "title": "Facebook",
      +    "type": "object"
      +  },
      +  {
      +    "properties": {
      +      "avatar": {
      +        "description": "Avatar or profile picture URL",
      +        "example": "https://storage.googleapis.com/2ad21ebc23/test",
      +        "type": "string"
      +      },
      +      "name": {
      +        "description": "Display name of the account",
      +        "example": "JOHN_DEO",
      +        "type": "string"
      +      },
      +      "originId": {
      +        "description": "Original platform-specific account identifier",
      +        "example": "244405****11687",
      +        "type": "string"
      +      },
      +      "pageId": {
      +        "description": "Facebook page ID associated with the Instagram account",
      +        "example": "234234234242sd",
      +        "type": "string"
      +      }
      +    },
      +    "required": [
      +      "pageId"
      +    ],
      +    "title": "Instagram",
      +    "type": "object"
      +  },
      +  {
      +    "properties": {
      +      "avatar": {
      +        "description": "Avatar or profile picture URL",
      +        "example": "https://storage.googleapis.com/2ad21ebc23/test",
      +        "type": "string"
      +      },
      +      "name": {
      +        "description": "Name of the LinkedIn page or profile",
      +        "example": "JOHN_DEO",
      +        "type": "string"
      +      },
      +      "originId": {
      +        "description": "Original LinkedIn platform identifier",
      +        "example": "244405****11687",
      +        "type": "string"
      +      },
      +      "type": {
      +        "description": "Type of LinkedIn account (must be one of: page, profile)",
      +        "enum": [
      +          "page",
      +          "profile"
      +        ],
      +        "example": "page",
      +        "type": "string"
      +      },
      +      "urn": {
      +        "description": "LinkedIn URN (Uniform Resource Name) identifier",
      +        "example": "urn:li:organization:80847980",
      +        "type": "string"
      +      }
      +    },
      +    "title": "Linkedin",
      +    "type": "object"
      +  },
      +  {
      +    "properties": {
      +      "account": {
      +        "allOf": [
      +          {
      +            "properties": {
      +              "accountName": {
      +                "description": "Display name of the account",
      +                "example": "My Business Account",
      +                "type": "string"
      +              },
      +              "name": {
      +                "description": "Account name identifier",
      +                "example": "accounts/114659701071209971352",
      +                "type": "string"
      +              },
      +              "type": {
      +                "description": "Type of the account",
      +                "example": "PERSONAL",
      +                "type": "string"
      +              },
      +              "verificationState": {
      +                "description": "State of account verification",
      +                "example": "VERIFIED",
      +                "type": "string"
      +              },
      +              "vettedState": {
      +                "description": "Vetting state of the account",
      +                "example": "NOT_VETTED",
      +                "type": "string"
      +              }
      +            },
      +            "required": [
      +              "name",
      +              "accountName",
      +              "type",
      +              "verificationState",
      +              "vettedState"
      +            ],
      +            "title": "AttachGMBLocationAccountDTO",
      +            "type": "object"
      +          }
      +        ],
      +        "description": "Google My Business account details",
      +        "example": {
      +          "accountName": "My Business Account",
      +          "name": "accounts/12345",
      +          "type": "LOCATION_GROUP",
      +          "verificationState": "VERIFIED",
      +          "vettedState": "VETTED"
      +        }
      +      },
      +      "location": {
      +        "allOf": [
      +          {
      +            "properties": {
      +              "isConnected": {
      +                "description": "Whether the location is connected",
      +                "example": false,
      +                "type": "boolean"
      +              },
      +              "isVerified": {
      +                "description": "Google Place ID indicating verification, or \"false\" if unverified",
      +                "example": "ChIJsZQpj1qbXjkRQNDUG4UUx6k",
      +                "type": "string"
      +              },
      +              "maxLocation": {
      +                "description": "Whether this is a max location",
      +                "example": false,
      +                "type": "boolean"
      +              },
      +              "metadata": {
      +                "description": "Additional location metadata, passed through from the Google Business Profile location",
      +                "example": {
      +                  "canHaveFoodMenus": false,
      +                  "canOperateLocalPost": true,
      +                  "hasVoiceOfMerchant": true
      +                },
      +                "type": "object"
      +              },
      +              "name": {
      +                "description": "Location name",
      +                "example": "accounts/114659701071209971352/locations/17909648580344584627",
      +                "type": "string"
      +              },
      +              "storeCode": {
      +                "description": "Store code",
      +                "example": "STORE-001",
      +                "type": "string"
      +              },
      +              "storefrontAddress": {
      +                "description": "Storefront address details, passed through from the Google Business Profile location",
      +                "example": {
      +                  "addressLines": [
      +                    "1600 Amphitheatre Pkwy"
      +                  ],
      +                  "administrativeArea": "CA",
      +                  "languageCode": "en",
      +                  "locality": "Mountain View",
      +                  "postalCode": "94043",
      +                  "regionCode": "US"
      +                },
      +                "type": "object"
      +              },
      +              "title": {
      +                "description": "Location title",
      +                "example": "My Business Location",
      +                "type": "string"
      +              }
      +            },
      +            "required": [
      +              "name",
      +              "title"
      +            ],
      +            "title": "AttachGMBLocationLocationDTO",
      +            "type": "object"
      +          }
      +        ],
      +        "description": "Google My Business location details to attach",
      +        "example": {
      +          "isConnected": true,
      +          "isVerified": "ChIJsZQpj1qbXjkRQNDUG4UUx6k",
      +          "name": "locations/12345",
      +          "storeCode": "STORE123",
      +          "title": "My Business Location"
      +        }
      +      }
      +    },
      +    "title": "Google Business Account",
      +    "type": "object"
      +  },
      +  {
      +    "properties": {
      +      "avatar": {
      +        "description": "Avatar URL",
      +        "example": "https://i.pinimg.com/example-avatar.jpg",
      +        "type": "string"
      +      },
      +      "name": {
      +        "description": "Pinterest account display name",
      +        "example": "Ayush",
      +        "type": "string"
      +      },
      +      "originAccountType": {
      +        "description": "Origin account type",
      +        "example": "business",
      +        "type": "string"
      +      },
      +      "originId": {
      +        "description": "Pinterest origin account id",
      +        "example": "244405****11687",
      +        "type": "string"
      +      },
      +      "type": {
      +        "description": "Account type must be one of the following values: profile",
      +        "enum": [
      +          "profile"
      +        ],
      +        "example": "profile",
      +        "type": "string"
      +      },
      +      "username": {
      +        "description": "Username",
      +        "example": "@ayush",
      +        "type": "string"
      +      },
      +      "verified": {
      +        "description": "Verification status",
      +        "example": true,
      +        "type": "boolean"
      +      },
      +      "websiteUrl": {
      +        "description": "Website URL",
      +        "example": "https://www.website.com",
      +        "type": "string"
      +      }
      +    },
      +    "required": [
      +      "originId",
      +      "name",
      +      "verified",
      +      "username",
      +      "websiteUrl"
      +    ],
      +    "title": "Pinterest",
      +    "type": "object"
      +  },
      +  {
      +    "properties": {
      +      "avatar": {
      +        "description": "Profile avatar URL",
      +        "example": "https://storage.googleapis.com/2ad21ebc23/test",
      +        "type": "string"
      +      },
      +      "name": {
      +        "description": "Display name of the profile to connect",
      +        "example": "JOHN_DEO",
      +        "type": "string"
      +      },
      +      "originId": {
      +        "description": "Threads profile ID to connect, taken from Get Accounts.",
      +        "example": "244405****11687",
      +        "type": "string"
      +      },
      +      "type": {
      +        "description": "Account type. Threads accounts always connect as `profile`.",
      +        "enum": [
      +          "profile"
      +        ],
      +        "example": "profile",
      +        "type": "string"
      +      }
      +    },
      +    "title": "Threads",
      +    "type": "object"
      +  },
      +  {
      +    "properties": {
      +      "avatar": {
      +        "description": "Profile avatar URL",
      +        "example": "https://example.com/avatar.jpg",
      +        "type": "string"
      +      },
      +      "handle": {
      +        "description": "Bluesky handle of the profile",
      +        "example": "handle.bsky.social",
      +        "type": "string"
      +      },
      +      "name": {
      +        "description": "Display name of the profile to connect",
      +        "example": "John Doe",
      +        "type": "string"
      +      },
      +      "originId": {
      +        "description": "Bluesky DID (decentralized identifier) of the profile to connect, taken from Get Accounts.",
      +        "example": "did:plc:abc123",
      +        "type": "string"
      +      },
      +      "type": {
      +        "description": "Account type. Bluesky accounts always connect as `profile`.",
      +        "enum": [
      +          "profile"
      +        ],
      +        "example": "profile",
      +        "type": "string"
      +      }
      +    },
      +    "title": "Bluesky",
      +    "type": "object"
      +  },
      +  {
      +    "properties": {
      +      "avatar": {
      +        "description": "Avatar or profile picture URL",
      +        "example": "https://storage.googleapis.com/2ad21ebc23/test",
      +        "type": "string"
      +      },
      +      "connectionSource": {
      +        "description": "Source that connected the TikTok account",
      +        "enum": [
      +          "integration",
      +          "social_media_posting"
      +        ],
      +        "example": "social_media_posting",
      +        "type": "string"
      +      },
      +      "name": {
      +        "description": "Display name of the account",
      +        "example": "JOHN_DEO",
      +        "type": "string"
      +      },
      +      "originId": {
      +        "description": "Original platform-specific account identifier",
      +        "example": "244405****11687",
      +        "type": "string"
      +      },
      +      "type": {
      +        "default": "business",
      +        "description": "Type of TikTok account (defaults to business)",
      +        "enum": [
      +          "profile",
      +          "business"
      +        ],
      +        "example": "business",
      +        "type": "string"
      +      },
      +      "username": {
      +        "description": "Username or handle of the TikTok account",
      +        "example": "JOHN_DEO",
      +        "type": "string"
      +      },
      +      "verified": {
      +        "description": "Indicates if the TikTok account is verified",
      +        "example": true,
      +        "type": "boolean"
      +      }
      +    },
      +    "title": "Tiktok",
      +    "type": "object"
      +  },
      +  {
      +    "properties": {
      +      "avatar": {
      +        "description": "Avatar URL",
      +        "example": "https://yt3.ggpht.com/example-avatar",
      +        "type": "string"
      +      },
      +      "name": {
      +        "description": "Name",
      +        "example": "Ayush",
      +        "type": "string"
      +      },
      +      "originId": {
      +        "description": "Origin ID",
      +        "example": "244405****11687",
      +        "type": "string"
      +      },
      +      "type": {
      +        "description": "Account type",
      +        "enum": [
      +          "profile"
      +        ],
      +        "example": "profile",
      +        "type": "string"
      +      },
      +      "username": {
      +        "description": "YouTube channel handle",
      +        "example": "@ayush",
      +        "type": "string"
      +      },
      +      "verified": {
      +        "description": "Whether the YouTube channel is verified",
      +        "example": true,
      +        "type": "boolean"
      +      }
      +    },
      +    "title": "YouTube",
      +    "type": "object"
      +  }
      +]
    • addedInput schema / properties / locationId / example
      Added value: +"w37swmmLbA02zgqKPpxITe2"
    • changedInput schema / properties / platform / description
      Previous value: -"Social media platform (must match the platform used in Steps 1 and 2)"New value: +"Social media platform. Must match the platform used in the preceding steps of the OAuth flow."
    • changedInput schema / properties / platform / enum
      Previous value: -[
      -  "google",
      -  "facebook",
      -  "instagram",
      -  "linkedin",
      -  "tiktok",
      -  "youtube",
      -  "pinterest",
      -  "threads",
      -  "bluesky"
      -]New value: +[
      +  "google",
      +  "facebook",
      +  "instagram",
      +  "threads",
      +  "bluesky",
      +  "linkedin",
      +  "tiktok",
      +  "tiktok-business",
      +  "youtube",
      +  "pinterest"
      +]
    • addedInput schema / properties / platform / example
      Added value: +"facebook"
    • changedInput schema / required
      Previous value: -[
      -  "locationId",
      -  "platform",
      -  "accountId",
      -  "body"
      -]New value: +[
      +  "platform",
      +  "locationId",
      +  "accountId",
      +  "body"
      +]
  2. First observedv2.0.0

TDQS

A4.7/5.0
Behavior4/5

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

The annotations already declare this is a non-read-only, non-destructive, open-world, non-idempotent operation. The description adds valuable context beyond that: it requires a Sub-Account token, needs the `socialplanner/oauth.write` scope, and explains that the connected account will appear in the location's connected accounts for posting. It does not cover edge cases like reconnecting an existing account, but the key behavioral context is present.

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

Conciseness5/5

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

The description is structured with clear headings, a short flow summary, request-body guidance, and an after-connection note. It is somewhat long, but the length is justified by the ten platform-specific body schemas and the need to frame this as the final OAuth step.

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

Completeness5/5

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

For a complex OAuth account-connection mutation with a large platform-dependent oneOf schema and no output schema, the description supplies the missing operational context: step sequencing, token and scope requirements, platform-body selection, and the effect of a successful connection.

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 would be 3. The description adds meaningful guidance beyond the schema by explaining that the body fields depend on the `platform` path parameter and by summarizing which platforms use originId/name/avatar versus Google Business Profile's full location/account objects. This helps an agent choose the correct oneOf branch.

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?

The description states a specific verb and resource: connect/attach a selected OAuth social account to a location as the final step of a defined flow. It clearly distinguishes this from the preceding retrieval step and from other social-account attachment tools by naming the OAuth step sequence and noting TikTok Business is not handled here.

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

Usage Guidelines5/5

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

It explicitly places the tool as Step 3 of 3, says to use it after retrieving available accounts in Step 2, and warns that `tiktok-business` accounts are connected through a different flow rather than this endpoint. The when-to-use context is unusually explicit.

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