3Dsellers

get-helpdesk-tickets

Read-only

List Helpdesk tickets — the buyer conversations, returns, inquiries, cancellations and cases the Helpdesk inbox shows, each with its status, buyer, linked order and tags. Filters map to the inbox folders, so filtering by status returns the same set (and the same metadata.total) the app shows. Message bodies are not included — call get-helpdesk-ticket-messages for a thread. Authenticated via bearer token.

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": "get-helpdesk-tickets"
  }
}

Input Schema

Name	Required	Description
`page`	No
`limit`	No
`isRead`	No	Filter by read state
`search`	No	Match subject, buyer name, buyer username or last message
`sortBy`	No	Sort key; lastMessageDate matches the inbox order
`source`	No	Where the thread came from. "regular" is a buyer message; "system" is a marketplace notification email — exclude it to match the inbox. The ebay_* sources (ebay_return, ebay_inquiry for Item Not Received, ebay_cancel, ebay_case) are marketplace threads and are ALREADY included by default — set this only to narrow to them. Their eBay detail is on the ticket as caseDetail.
`status`	No	Only tickets in these statuses: a built-in value or the exact label of one of the company's custom statuses (see get-helpdesk-custom-statuses), matched exactly as the ticket carries it. A value that is neither a custom status nor a label any ticket carries is an error that lists the statuses that exist. "new_ticket" is the Helpdesk's "New Ticket" folder.
`buyerId`	No	Only tickets from this buyer's marketplace username
`channel`	No	Only tickets on this channel
`orderId`	No	Only tickets attached to this marketplace order ID
`sellerId`	No	Only tickets on this marketplace account
`isReplied`	No	false is the "newest buyer message unanswered" queue
`isStarred`	No	Filter by starred state
`sortOrder`	No
`ticketType`	No	Only these ticket types
`updatedAfter`	No	Only tickets written to at or after this ISO 8601 moment — the field to poll for an incremental mirror
`assignedUserId`	No	Only tickets assigned to this teammate
`customStatusId`	No	Only tickets in these custom statuses, by id (from get-helpdesk-custom-statuses) — the surest way to address a label with emoji or punctuation; an unknown id is an error that lists the statuses that exist. Combines with status as OR.
`lastMessageAfter`	No	Only tickets whose newest message is at or after this ISO 8601 moment

Schema Changelog

Changes observed during successful MCP inspections.

Changed5 schema fields changedNov 3, 2026

addedInput schema / properties / customStatusId

Added value: +{
+  "description": "Only tickets in these custom statuses, by id (from get-helpdesk-custom-statuses) — the surest way to address a label with emoji or punctuation; an unknown id is an error that lists the statuses that exist. Combines with status as OR.",
+  "items": {
+    "maximum": 2147483647,
+    "minimum": 1,
+    "type": "integer"
+  },
+  "type": "array"
+}

changedInput schema / properties / status / description

Previous value: -"Only tickets in these statuses. \"new_ticket\" is the Helpdesk's \"New Ticket\" folder."New value: +"Only tickets in these statuses: a built-in value or the exact label of one of the company's custom statuses (see get-helpdesk-custom-statuses), matched exactly as the ticket carries it. A value that is neither a custom status nor a label any ticket carries is an error that lists the statuses that exist. \"new_ticket\" is the Helpdesk's \"New Ticket\" folder."

addedInput schema / properties / status / items / anyOf

Added value: +[
+  {
+    "enum": [
+      "new_ticket",
+      "to_do",
+      "waiting_for_reply",
+      "snoozed",
+      "resolved",
+      "archived",
+      "system"
+    ],
+    "type": "string"
+  },
+  {
+    "maxLength": 255,
+    "minLength": 1,
+    "type": "string"
+  }
+]

removedInput schema / properties / status / items / enum

Removed value: -[
-  "new_ticket",
-  "to_do",
-  "waiting_for_reply",
-  "snoozed",
-  "resolved",
-  "archived",
-  "system"
-]

removedInput schema / properties / status / items / type
```
Removed value: -"string"
```

First observedOct 26, 2026

TDQS

A4.1/5.0

Behavior3/5

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds real context beyond that: message bodies are excluded, metadata.total mirrors the app's inbox count, and authentication is via bearer token. It does not describe pagination behavior or result ordering defaults, which matters for a paged list.

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?

Four dense sentences, front-loaded with purpose before caveats and the alternative tool. No filler, though the sentence chain packs several distinct claims (scope, folder parity, exclusions, auth) without visual separation, which slightly slows scanning.

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 19-parameter, zero-required listing tool with no output schema, the description covers scope, exclusions, count fidelity, and auth. The only notable gap is return shape beyond metadata.total and pagination behavior, which an agent must infer for a paged endpoint.

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 description coverage is high (84%), so the baseline is 3, but the description adds meaning the schema does not: filters map to inbox folders so counts match the app, and it points to customStatusId as the reliable way to address custom labels (which the schema hints at but the description frames as the strategy). The source/staging semantics for ebay_* sources are mostly carried by the schema itself.

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?

Names a specific verb and resource ('List Helpdesk tickets') and immediately enumerates the domain (buyer conversations, returns, inquiries, cancellations, cases) plus the fields returned (status, buyer, linked order, tags). It also distinguishes itself from get-helpdesk-ticket-messages, so an agent can route between the list and the thread view without opening either schema.

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 directs the agent to get-helpdesk-ticket-messages when message bodies are needed, and explains that status filters reproduce the app's inbox folders so results are directly comparable. It does not contrast with get-helpdesk-ticket-counts or get-helpdesk-ticket for single-ticket lookups, leaving some sibling routing to inference.

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

All 3Dsellers tools Inspect

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.