Skip to main content
Glama

list_posts

Read-onlyIdempotent

Posts in your workspaces, teammates' too, per your role there (brand-locked seats only see their assigned brands). If workspace_id is omitted, this searches every workspace you belong to. view=list (default): posts filtered by status, platform, account_id, workspace_id, brand_id, group_id, release_id, approval_status, approval_waiting_on, and a scheduled date range: scheduled_from (inclusive) and scheduled_to (a plain date includes that whole day), read in timezone (IANA, default UTC; also the zone times are shown in). Returns limit posts (default 20, max 200) starting at offset; with a date range the order defaults to oldest first (order=asc|desc). The output always says whether every matching post was shown. If it says more are available, call again with the offset it gives and keep paging until all are shown before drawing any conclusion about totals, gaps, or how busy a client is. view=counts (scheduled_from and scheduled_to required, up to 366 days): exact totals per day, status, account, and brand for the same filters (limit, offset, and order are ignored); use it for "how many" or "is this month full" questions. Each post includes approval.pending_client_approval.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "list_posts"
  }
}

Input Schema

NameRequiredDescriptionDefault
viewNolist (default): the posts. counts: totals (needs scheduled_from and scheduled_to).list
limitNoPosts per page (default 20, max 200). Ignored by view=counts.
orderNoasc (oldest first) or desc (newest first). Default asc with a date range, otherwise desc. Ignored by view=counts.
offsetNoMatching posts to skip; use the offset the previous page gives. Ignored by view=counts.
statusNoStored post status, or missed. paused_due_to_token is a reconnect pause and paused_due_to_billing is a billing pause. missed is a filter, not a stored status: a scheduled post that is still scheduled 10 minutes after its time (the publish sweep runs every 5 minutes, plus the same wait for a late sweep). A reaper reset or an auto-retry requeue keeps a row off this list for those same 10 minutes. A fresh edit does not. Also an awaiting_manual story whose time has been reached, or a workspace or brand publishing pause whose scheduled time has been reached. Each row keeps its stored status and has missed true or false. Failed is its own status. Queued is not missed.
brand_idNoFilter to posts assigned to a specific brand/client (the id from list_brands).
group_idNoCaller group id. Matches api_group_id, group_id, post_group_id.
platformNo
timezoneNoIANA time zone such as Europe/London for reading plain dates and showing times. Default UTC.
account_idNo
release_idNoCaller release id. Matches release_id only.
scheduled_toNoEnd of the scheduled range: a plain date (2026-10-31) includes that whole day; an ISO date-time is exclusive.
workspace_idNo
scheduled_fromNoStart of the scheduled range, inclusive: a date (2026-10-01) or an ISO date-time. Plain dates and times without an offset are read in timezone.
approval_statusNoFilter by client review approval status. pending_client means the post is waiting on the client.
approval_waiting_onNoclient: approval_status pending_client. team: changes_requested or rejected. Conflicts with a non-overlapping approval_status.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedInput schema / properties / status / description
      Previous value: -"Stored post status, or missed. paused_due_to_token is a reconnect pause and paused_due_to_billing is a billing pause. missed: failed, still scheduled after the scheduled time, or held by a publishing pause past it."New value: +"Stored post status, or missed. paused_due_to_token is a reconnect pause and paused_due_to_billing is a billing pause. missed is a filter, not a stored status: a scheduled post that is still scheduled 10 minutes after its time (the publish sweep runs every 5 minutes, plus the same wait for a late sweep). A reaper reset or an auto-retry requeue keeps a row off this list for those same 10 minutes. A fresh edit does not. Also an awaiting_manual story whose time has been reached, or a workspace or brand publishing pause whose scheduled time has been reached. Each row keeps its stored status and has missed true or false. Failed is its own status. Queued is not missed."
  2. Changed4 schema fields changed
    • addedInput schema / properties / group_id
      Added value: +{
      +  "description": "Caller group id. Matches api_group_id, group_id, post_group_id.",
      +  "type": "string"
      +}
    • addedInput schema / properties / release_id
      Added value: +{
      +  "description": "Caller release id. Matches release_id only.",
      +  "type": "string"
      +}
    • addedInput schema / properties / status / description
      Added value: +"Stored post status, or missed. paused_due_to_token is a reconnect pause and paused_due_to_billing is a billing pause. missed: failed, still scheduled after the scheduled time, or held by a publishing pause past it."
    • changedInput schema / properties / status / enum
      Previous value: -[
      -  "scheduled",
      -  "published",
      -  "failed",
      -  "draft"
      -]New value: +[
      +  "draft",
      +  "scheduled",
      +  "publishing",
      +  "processing",
      +  "awaiting_tiktok_publish",
      +  "awaiting_manual",
      +  "published",
      +  "failed",
      +  "paused",
      +  "paused_due_to_token",
      +  "paused_due_to_billing",
      +  "missed"
      +]
  3. Changed2 schema fields changed
    • changedInput schema / properties / offset / description
      Previous value: -"How many matching posts to skip. Use the offset the previous page gives to get the next page. Ignored by view=counts."New value: +"Matching posts to skip; use the offset the previous page gives. Ignored by view=counts."
    • changedInput schema / properties / view / description
      Previous value: -"list (default): the posts themselves, one page at a time. counts: exact totals per day, status, account, and brand (needs scheduled_from and scheduled_to)."New value: +"list (default): the posts. counts: totals (needs scheduled_from and scheduled_to)."
  4. First observed

TDQS

A4.3/5.0
Behavior5/5

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

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses access scoping (teammates' posts, brand-locked seats limited to assigned brands, all workspaces when workspace_id is omitted), default ordering that flips when a date range is present, the 20/200 paging envelope, and the 366-day cap on counts. It also tells the agent that the output always reports whether all matching posts were shown and that each post carries approval.pending_client_approval — behavior an agent could not infer from annotations or schema alone.

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

Conciseness3/5

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

The scope constraint and the list-vs-counts split are front-loaded, which is good. However, it is a single dense paragraph that spends several clauses repeating parameter facts already present in the schema, making it longer than the genuinely new information warrants.

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?

This is a 16-parameter tool with no output schema, and the description still tells the agent what the response contains (a completeness signal and approval.pending_client_approval per post) and how to continue paging. For its complexity, nothing essential to a correct call is missing.

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 81%, so the schema already carries most parameter meaning, and the description largely restates it (limit/offset/order ignored in counts, plain dates read in timezone, scheduled_to inclusive-day vs exclusive date-time). It adds a modest amount by synthesizing cross-parameter interactions, but does not go meaningfully beyond the schema on individual filters.

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?

The description establishes what the tool returns (posts across your workspaces, plus a counts mode) and scopes visibility by role and brand-locked seats. It is a clear resource statement, though it opens with a noun phrase rather than a verb and does not name a sibling it replaces (e.g. list_brands for brand ids), so it falls just short of full differentiation.

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 routes between the two modes: view=counts is prescribed for "how many" or "is this month full" questions and marked as requiring both dates, while list is the default. It also states the behavior when workspace_id is omitted and gives a concrete paging protocol (call again with the returned offset, keep paging before concluding anything about totals or client workload).

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources