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

ghl-mcp-server-v2

by zackscriven

ghl_media_list_files

Read-onlyIdempotent

Retrieves paginated files and folders from media storage for a location, supporting query, parent folder, sorting, and offset/limit paging.

Instructions

Regression check (old connector 422'd here because it had no way to pass the required type param): VERIFIED FIXED — type, altType, altId, sortBy, sortOrder are all present and required in this tool's input schema, matching the spec. Get List of Files/Folders Fetches list of files and folders from the media storage Endpoint: GET /medias/files (Version header: v3; source: v3/medias-v3.json) Requires a Sub-Account (location) token. OAuth scopes: medias.readonly Pagination params: offset, limit — pass them to page through full result sets.

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": {
      "sortBy": "<sortBy>",
      "sortOrder": "<sortOrder>",
      "type": "<type>",
      "altType": "<altType>",
      "altId": "<altId>"
    },
    "name": "ghl_media_list_files"
  }
}

Input Schema

NameRequiredDescriptionDefault
typeYesType
altIdYeslocation Id
limitNoNumber of files to show in the listing
queryNoQuery text
offsetNoNumber of files to skip in listing
sortByYesField to sorting the file listing by (e.g. updatedAt, name)
altTypeYesAltType
fetchAllNoFetch all files or folders
parentIdNoparent id or folder id
sortOrderYesDirection in which file needs to be sorted

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv2.1.0
    • changedInput schema / properties / sortBy / description
      Previous value: -"Field to sorting the file listing by"New value: +"Field to sorting the file listing by (e.g. updatedAt, name)"
  2. First observedv2.0.0

TDQS

A3.5/5.0
Behavior4/5

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds genuinely new context beyond them: the required location-token auth, the OAuth scope, the API version header, and pagination behavior. The opening regression-note sentence is internal QA chatter that does not help an agent and slightly muddies the read.

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 very first sentence is an internal regression/QA changelog ('VERIFIED FIXED — type, altType, altId... are all present') that is front-loaded ahead of the actual purpose, forcing the agent to read past noise. The remainder is terse and useful, but the structure wastes the most valuable position.

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 10-parameter read tool with no output schema, the description covers auth requirement, scope, endpoint/version, and pagination expectations — enough to invoke it correctly. It omits what sortBy/sortOrder do together and what fetchAll toggles, which the schema handles only thinly.

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 schema already documents every parameter; a baseline 3 applies. The description only restates that `type` is required and that offset/limit drive paging, adding no syntax or value guidance (e.g. valid `type` values, sortBy/sortOrder interaction, meaning of fetchAll).

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: 'Get List of Files/Folders ... Fetches list of files and folders from the media storage', plus the concrete endpoint GET /medias/files. It does not distinguish itself from media siblings like ghl_media_create_folder or ghl_media_update_file, so it falls short of a 5.

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

Usage Guidelines3/5

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

Gives the operational precondition (requires a Sub-Account/location token, scope medias.readonly) and tells the agent to use offset/limit to page through full result sets. It never says when to choose this over related media tools or when a folder-scoped call (parentId) is appropriate, so guidance is implied rather than 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