Skip to main content
Glama
Sign In

HelpCenter.io

by io.helpcenter
OverviewDiscussionsAdmin

List HelpCenter Comments

helpcenter_list_comments
Read-onlyIdempotent

List reader comments across the whole connected HelpCenter.io help center.

Read-only, flat and filterable — this is both the moderation queue (status: 'pending') and the "what are readers asking about?" feed (status: 'all'). Each comment carries the article it sits on, so the output is readable without a second lookup.

PRIVACY — read before reporting on this data:

  • Commenter email addresses are REDACTED by default. An absent 'email' field means it was withheld, NOT that the reader had no address. Pass include_email: true (write-scoped key only) if the task genuinely needs to contact someone.

  • Commenter IP addresses are NEVER returned, at any scope, with any parameter.

  • Internal team notes (the private editorial threads written in the article editor) are excluded from this tool entirely. An article whose comments look purely external may still have staff discussion you cannot see here.

Comment bodies are returned as PLAIN TEXT — no HTML, no escape sequences — so they can be quoted and summarised directly.

Args:

  • status ('pending' | 'published' | 'unpublished' | 'deleted' | 'all', optional): default 'all', which excludes deleted.

  • article_id (number, optional): restrict to one article. An id from another help center is a 404, not an empty list.

  • lang (string, optional): language code enabled on the site.

  • search (string, optional): substring match on the comment body.

  • order ('asc' | 'desc', optional): by creation time, default 'desc'.

  • limit (number, optional): 1-100, default 25. page (number, optional): default 1.

  • include_email (boolean, optional): see PRIVACY above.

  • response_format ('markdown' | 'json'): default 'markdown'.

Returns: { total, count, page, per_page, total_pages, has_more, status_counts, next, items } where status_counts is the queue depth for the WHOLE help center — use it to decide whether to keep paging.

Paging: every response carries next: { page, limit } — the exact arguments that fetch the first item it did not return — or null when nothing is left. Follow next, with the same filters, instead of computing page + 1 yourself. A response is capped at 25000 characters, in its text and in its structured data alike, and 5.0 MB in all: when a page does not fit, only its first items are returned (truncated: true, count says how many) and next points at the rest, usually with a smaller limit and a later page number. Requesting page + 1 with your original limit would skip them.

Errors: 403 if include_email is set on a read-scoped key (the rest of the listing still works without it); 404 if article_id belongs to another help center.

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": "helpcenter_list_comments"
  }
}

Input Schema

NameRequiredDescriptionDefault
langNoLanguage code to filter by (must be enabled on the site).
pageNoPage number for pagination (default 1).
limitNoMaximum comments to return per page (1-100, default 25).
orderNoSort by creation time: 'desc' (default, newest first) or 'asc'.
searchNoSubstring match against the comment body.
statusNoModeration state to filter by: 'pending' (awaiting approval — the queue), 'published' (visible to readers), 'unpublished' (rejected), 'deleted' (soft-deleted, excluded otherwise), or 'all' (default, everything except deleted).
site_idNoWhich help center to act on: an id from helpcenter_list_sites. Needed when this connection reaches more than one help center; omit it when it reaches one. Applies to this call only — pass it on every call of a task, and ask the user which help center they mean if their request does not say.
article_idNoRestrict to one article. An id from another help center is a 404, not an empty list.
include_emailNoInclude the commenter's email address. Off by default and deliberately so: these are readers' personal addresses, not the help center's data. Requires a WRITE-scoped key — a read-scoped key asking for it gets 403. Leave this off unless the task actually needs to contact someone.
response_formatNoOutput format: 'markdown' for a human-readable summary or 'json' for the full structured payload.markdown

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.6/5.0
Behavior5/5

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

Annotations already declare readOnly/idempotent/non-destructive, and the description still adds substantial non-redundant behavior: email redaction semantics, IPs never returned, exclusion of internal team notes, plain-text bodies, the 25k-character/5MB truncation rule, and 403/404 error conditions.

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-loaded purpose sentence, then clearly labeled PRIVACY, Args, Returns, Paging and Errors sections. It is long, but nearly every line carries information an agent would otherwise have to guess; the PRIVACY block is the only mildly repetitive part.

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?

With 10 optional params and no output schema, the description does the work the schema cannot: it describes the return payload field-by-field, explains how to follow next rather than incrementing page, and warns about truncation. The only gap is not restating site_id, which the schema documents thoroughly.

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 is 3, but the description adds real meaning beyond it: status 'all' excluding deleted, article_id from another help center yielding 404 rather than an empty list, include_email requiring write scope, and the meaning of status_counts. It omits site_id from its Args list, leaving that one parameter entirely to the schema.

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?

States a specific verb and resource ('List reader comments across the whole connected HelpCenter.io help center') and implicitly distinguishes itself from the per-article sibling helpcenter_get_article_comments by emphasizing cross-site scope and flat/filterable output.

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?

Names two concrete use cases (moderation queue via status 'pending', reader-feedback feed via status 'all') and gives explicit conditional guidance for include_email. It stops short of naming the sibling tools it replaces (get_article_comments, moderate_comment), so the routing is implied rather than stated.

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

All HelpCenter.io toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources