What can you do with this server?

This server is an extended, production-grade Model Context Protocol (MCP) server for Zendesk, enabling secure, multi-tenant interactions via AI applications. It provides comprehensive tools for ticket, user, group, knowledge base, and attachment management, deployable locally (stdio for Claude Desktop) or remotely (HTTP with TLS). Read Operations (tickets:read scope): * get_ticket – retrieve a specific ticket by ID * get_tickets – list tickets with cursor pagination and sort options * get_ticket_comments – fetch paginated comments including attachment metadata * search_tickets – search using Zendesk query syntax * get_ticket_attachment – download image attachments as base64 * get_user – resolve user ID to details * search_users – search users by name/email * list_groups – list agent groups/teams * list_ticket_fields – list all ticket fields with IDs, types, and options Knowledge Base (kb:read scope): * search_articles – search Help Center articles (also available as a resource zendesk://knowledge-base) Write Operations (tickets:write scope): * create_ticket – create a ticket with custom fields, tags, assignee, priority, etc. * update_ticket – update status, priority, assignee, tags, due date, custom fields * create_ticket_comment – add public/internal comment with optional attachments (public comments may trigger human-in-the-loop confirmation) * upload_attachment – upload a file (base64, ≤10 MB) and get a token for attaching to comments Prompts: analyze-ticket and draft-ticket-response for assisted workflows. Security & Access Control: OAuth 2.1 and scoped API keys (zmk_ prefix) with fine-grained permissions (tool-specific scopes: tickets:read, tickets:write, kb:read, *); tool-list filtering; optional human-in-the-loop confirmation for destructive actions; dual Zendesk identity (restricted user for reads, full agent for writes). Multi-Tenancy: Route requests to different Zendesk accounts per API key or OAuth claim, with per-tenant credentials. Deployment: Local stdio for Claude Desktop; remote Streamable HTTP with TLS, health checks; Docker, Docker Compose with Caddy, Terraform for AWS EC2/ECS Fargate with ALB. Admin Console: Separate web interface for managing tenants, API keys, and Zendesk connection settings, plus a zendesk-keys CLI. Additional Features: Cursor-based pagination to avoid context blowout; structured tool annotations; backward compatibility with the original reminia/zendesk-mcp-server.

Which integrations are available for this server?

Provides tools for managing Zendesk tickets (create, update, comment, search), users, groups, ticket fields, knowledge base articles, and attachments.

How do I use Zendesk MCP Server (Extended)?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Zendesk MCP Server (Extended) show me open tickets about billing" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

Zendesk MCP Server (Extended)

by srinivas-86

Overview Schema Source Related Servers Score Discussions Admin

Python

Hybrid

This server is an extended, production-grade Model Context Protocol (MCP) server for Zendesk, enabling secure, multi-tenant interactions via AI applications. It provides comprehensive tools for ticket, user, group, knowledge base, and attachment management, deployable locally (stdio for Claude Desktop) or remotely (HTTP with TLS).

Read Operations (tickets:read scope):

get_ticket – retrieve a specific ticket by ID
get_tickets – list tickets with cursor pagination and sort options
get_ticket_comments – fetch paginated comments including attachment metadata
search_tickets – search using Zendesk query syntax
get_ticket_attachment – download image attachments as base64
get_user – resolve user ID to details
search_users – search users by name/email
list_groups – list agent groups/teams
list_ticket_fields – list all ticket fields with IDs, types, and options

Knowledge Base (kb:read scope):

search_articles – search Help Center articles (also available as a resource zendesk://knowledge-base)

Write Operations (tickets:write scope):

create_ticket – create a ticket with custom fields, tags, assignee, priority, etc.
update_ticket – update status, priority, assignee, tags, due date, custom fields
create_ticket_comment – add public/internal comment with optional attachments (public comments may trigger human-in-the-loop confirmation)
upload_attachment – upload a file (base64, ≤10 MB) and get a token for attaching to comments

Prompts: analyze-ticket and draft-ticket-response for assisted workflows.

Security & Access Control: OAuth 2.1 and scoped API keys (zmk_ prefix) with fine-grained permissions (tool-specific scopes: tickets:read, tickets:write, kb:read, *); tool-list filtering; optional human-in-the-loop confirmation for destructive actions; dual Zendesk identity (restricted user for reads, full agent for writes).

Multi-Tenancy: Route requests to different Zendesk accounts per API key or OAuth claim, with per-tenant credentials.

Deployment: Local stdio for Claude Desktop; remote Streamable HTTP with TLS, health checks; Docker, Docker Compose with Caddy, Terraform for AWS EC2/ECS Fargate with ALB.

Admin Console: Separate web interface for managing tenants, API keys, and Zendesk connection settings, plus a zendesk-keys CLI.

Additional Features: Cursor-based pagination to avoid context blowout; structured tool annotations; backward compatibility with the original reminia/zendesk-mcp-server.

Zendesk MCP Server (Extended Edition)

License version

A production-grade Model Context Protocol (MCP) server for Zendesk — run it locally with Claude Desktop over stdio, or deploy it to the cloud as a secure, multi-tenant, OAuth-protected remote MCP server that any AI application can connect to.

Note — extension of the original project
This is an extended fork of reminia/zendesk-mcp-server. The original provides a local, stdio-only Zendesk MCP server with basic ticket tools. This edition keeps full backward compatibility with it (stdio mode, original tools, prompts, and knowledge-base resource) and extends it for remote, internet-facing production use.

Issues with the original repo that this edition addresses

#	Issue in original	How it's addressed here
1	stdio transport only — could not be reached over a network, so it only worked on the same machine as the AI client	Streamable HTTP transport (`/mcp` endpoint, MCP spec 2025-03-26+; SSE-as-transport is deprecated and intentionally not used) alongside stdio
2	No authentication of any kind — anyone who could reach the process could use it	Three auth modes: internal scoped API keys, OAuth 2.1 resource server (generic OIDC + RFC 9728 discovery), or both simultaneously
3	No permission model — every caller could read and write tickets	4-layer read/write control: per-tool scopes (fail-closed), tool-list filtering, human-in-the-loop confirmation, dual Zendesk identity backstop
4	Blocking I/O inside async handlers — sync Zenpy calls froze the event loop under concurrent HTTP load	All Zendesk calls run in worker threads (`run_in_thread`)
5	Deprecated offset pagination — Zendesk is sunsetting it; comments were not paginated at all (context blowout on long tickets)	Cursor pagination (`page[size]`/`page[after]`) for tickets and comments
6	Sparse Zendesk coverage — only 5 tools; user/assignee IDs could not be resolved, custom fields were opaque, no search	14 tools including search, users, groups, ticket-field metadata, KB article search, attachment upload
7	Single Zendesk account hard-wired at startup from `.env`	Multi-tenancy: per-tenant Zendesk credentials, keys/OAuth claims mapped to tenants, hot-swappable connection settings
8	No deployment story — no TLS, no health check, stdio-oriented Docker image	Docker (HTTP-first, healthcheck), docker-compose with Caddy auto-TLS, Terraform for EC2 and for ECS Fargate + ALB
9	No admin tooling — key rotation/credential changes required editing `.env` and restarting	Web admin console (separate port) + `zendesk-keys` CLI; connection hot-swap without restart
10	No tests	38 unit tests + HTTP/admin/OAuth smoke test suites; tests run in CI

Related MCP server: tokenless-zendesk-mcp

Feature overview

Original features (retained):

Ticket tools: get ticket, list tickets, get comments, create ticket, update ticket, comment on ticket
Image attachment download with security hardening (MIME allowlist, magic-byte validation, 10 MB cap)
Prompts: analyze-ticket, draft-ticket-response
Resource: zendesk://knowledge-base (all Help Center articles, cached 1 h)
stdio transport for Claude Desktop / Claude Code local use

New in this edition:

Streamable HTTP transport with /health endpoint
Internal API keys: zmk_ prefix, SHA-256 hashed at rest, scopes, expiry, instant revocation, audit log
OAuth 2.1 resource server: JWKS/issuer/audience JWT validation, RFC 9728 Protected Resource Metadata at /.well-known/oauth-protected-resource/mcp — works with Auth0, Descope, Cognito, Keycloak, WorkOS
Scope model: tickets:read, tickets:write, kb:read, * — enforced per tool, fail-closed, with tools/list filtering
Optional elicitation: in-client approve/decline before posting public (customer-visible) comments
Dual Zendesk identity: reads via a restricted user (e.g. light agent), writes via a full agent
Multi-tenancy with per-tenant Zendesk credentials
Web admin console: connection settings (hot-swap + test), tenant management, key lifecycle
New tools: search_tickets, get_user, search_users, list_groups, list_ticket_fields, search_articles, upload_attachment
Tool annotations (readOnlyHint / destructiveHint) and structured output on all tools
Deployment: Dockerfile, docker-compose + Caddy (auto-TLS), Terraform for EC2 and ECS Fargate
MCP Registry manifest (server.json) and publishing guide

Tools

Tool	Scope	Description
`get_ticket`	tickets:read	Get a ticket by ID
`get_tickets`	tickets:read	List tickets (cursor pagination, sortable)
`get_ticket_comments`	tickets:read	Ticket comments incl. attachment metadata (cursor pagination)
`search_tickets`	tickets:read	Zendesk search syntax, e.g. `status:open priority:high`
`get_ticket_attachment`	tickets:read	Download an image attachment (base64, validated)
`get_user`	tickets:read	Resolve a user ID to name/email/role
`search_users`	tickets:read	Search users by name or email
`list_groups`	tickets:read	Agent groups (teams) for routing
`list_ticket_fields`	tickets:read	Field metadata — interpret/set `custom_fields` `{id, value}`
`search_articles`	kb:read	Search Help Center articles (context-safe)
`create_ticket`	tickets:write	Create a ticket
`update_ticket`	tickets:write	Update status/priority/assignee/tags/custom fields/due date
`create_ticket_comment`	tickets:write	Comment on a ticket (optional elicitation for public comments; supports attachments)
`upload_attachment`	tickets:write	Upload a file (≤10 MB), returns token for comment attachment

Prompts: analyze-ticket, draft-ticket-response. Resource: zendesk://knowledge-base (kb:read).

Quick start (local, stdio — same as the original)

git clone <this-repo>
cd zendesk-mcp-server
uv venv && uv pip install -e .
cp .env.example .env   # fill in ZENDESK_SUBDOMAIN, ZENDESK_EMAIL, ZENDESK_API_KEY

Claude Desktop config:

{
  "mcpServers": {
    "zendesk": {
      "command": "uv",
      "args": ["--directory", "/path/to/zendesk-mcp-server", "run", "zendesk"]
    }
  }
}

stdio mode is trusted-local: no auth, full access, identical behavior to the original repo.

Remote mode (Streamable HTTP)

MCP_TRANSPORT=http zendesk        # serves http://0.0.0.0:8000/mcp  +  /health

Create scoped API keys (shown once, stored hashed):

zendesk-keys create --name "reader"  --scopes tickets:read,kb:read
zendesk-keys create --name "agent"   --scopes tickets:read,tickets:write,kb:read --expires-days 30
zendesk-keys create --name "admin"   --scopes "*"
zendesk-keys list
zendesk-keys revoke --id 2

Connect a client:

claude mcp add zendesk --transport http https://mcp.example.com/mcp \
  --header "Authorization: Bearer zmk_..."

Read-only keys never see write tools in tools/list; write calls without tickets:write are denied; unknown tools are denied by default (fail closed).

Configuration reference

All configuration is via environment variables (or .env; the admin console can override connection settings at runtime, persisted in the key-store DB).

Zendesk connection

Variable	Required	Default	Description
`ZENDESK_SUBDOMAIN`	yes	—	`<subdomain>.zendesk.com`
`ZENDESK_API_KEY`	yes	—	Zendesk API token
`ZENDESK_EMAIL`	yes*	—	Single-identity mode: agent email paired with the token
`ZENDESK_READ_EMAIL`	no	`ZENDESK_EMAIL`	Dual identity: restricted user (light agent) for all reads
`ZENDESK_WRITE_EMAIL`	no	`ZENDESK_EMAIL`	Dual identity: full agent for all writes

*Either ZENDESK_EMAIL or both ZENDESK_READ_EMAIL/ZENDESK_WRITE_EMAIL. Zendesk roles live on the user, not the token — pairing the same token with a restricted user email yields restricted permissions (Layer 4 backstop).

Transport

Variable	Default	Description
`MCP_TRANSPORT`	`stdio`	`stdio` (local, trusted) or `http` (remote)
`MCP_HOST`	`0.0.0.0`	HTTP bind address
`MCP_PORT`	`8000`	HTTP port; MCP endpoint is `/mcp`

Authentication

Variable	Default	Description
`MCP_AUTH_ENABLED`	`true`	Set `false` only for trusted private networks
`MCP_AUTH_MODE`	`keys`	`keys` \| `oauth` \| `both`
`MCP_KEYS_DB`	`data/keys.db`	SQLite store for keys, tenants, config, audit log
`MCP_PUBLIC_URL`	—	Public base URL (required for oauth/both; used in RFC 9728 metadata)
`MCP_OAUTH_ISSUER`	—	OIDC issuer, e.g. `https://your-tenant.auth0.com/`
`MCP_OAUTH_AUDIENCE`	`MCP_PUBLIC_URL`	Audience/identifier of this server at the IdP
`MCP_OAUTH_JWKS_URI`	`<issuer>/.well-known/jwks.json`	Override if your IdP differs
`MCP_OAUTH_AUTH_SERVERS`	issuer	Comma-separated authorization server URLs
`MCP_OAUTH_TENANT_CLAIM`	`zendesk_tenant`	JWT claim naming the caller's tenant (id or name)

Admin console & safety

Variable	Default	Description
`MCP_ADMIN_PASSWORD`	— (disabled)	Setting it enables the admin console
`MCP_ADMIN_HOST`	`127.0.0.1`	Keep loopback; reach via SSH/SSM tunnel
`MCP_ADMIN_PORT`	`9000`	Admin console port (never expose publicly)
`MCP_WRITE_CONFIRMATION`	`false`	Elicit user approval before PUBLIC comments (Layer 3)

Security model

Layer	Mechanism
Edge	TLS 1.2+ (Caddy or ALB/ACM), security headers, 80/443 only
AuthN	API keys (hashed, expiring, revocable) and/or OAuth 2.1 JWTs (PKCE at the IdP)
L1 AuthZ	Central `TOOL_PERMISSIONS` map, enforced pre-dispatch, fail-closed
L2 Visibility	`tools/list` filtered to caller's scopes — models can't attempt what they can't see
L3 Confirmation	`destructiveHint` annotations + optional elicitation for public comments
L4 Zendesk	Dual identity — reads through a restricted Zendesk user, writes through a full agent
Admin	Separate loopback port, password + CSRF, secrets never re-displayed
Audit	Append-only log: key lifecycle, admin actions, logins, writes

Multi-tenancy

By default every caller uses the server's own Zendesk connection. To let other teams/customers connect their Zendesk:

Admin console → Tenants → add name, subdomain, API token, read/write emails.
Bind credentials to the tenant: create an API key with that tenant selected (or zendesk-keys create ... --tenant-id N), or configure your IdP to issue the tenant's name/id in the MCP_OAUTH_TENANT_CLAIM JWT claim.
All tool calls from that identity are routed to the tenant's Zendesk. Deleting a tenant revokes its keys immediately.

Web admin console

Enable with MCP_ADMIN_PASSWORD. Reach it via tunnel — never expose it:

ssh -L 9000:localhost:9000 user@host          # or the SSM equivalent, see docs/DEPLOYMENT.md
# open http://localhost:9000

Provides: Zendesk connection editor with hot-swap (no restart) and "test connection", tenant management, API key create/revoke with scope checkboxes and expiry, and key usage visibility. Stored tokens are never re-displayed; new keys are shown exactly once.

Deployment

Docker (single container):

docker build -t zendesk-mcp-server .
docker run --rm -p 8000:8000 --env-file .env -v zmcp-keys:/data zendesk-mcp-server

Docker Compose + automatic TLS (recommended single-box): set MCP_DOMAIN in .env, then docker compose up -d — Caddy terminates TLS with Let's Encrypt and proxies to the server. Create keys with docker compose exec zendesk-mcp zendesk-keys create ....

AWS EC2 (Terraform): terraform/ provisions EC2 (SSM access, no SSH, IMDSv2), security group (80/443 only), Elastic IP, optional Route53, and bootstraps Docker + the repo. Full runbook: docs/DEPLOYMENT.md.

Windows Server without Docker: native Python + Caddy with your own TLS certificate + NSSM services, including a troubleshooting FAQ of real-world Windows issues (Node/PATH, cert chains, arg mangling): docs/WINDOWS_SETUP.md.

AWS ECS Fargate + ALB (scale-out): terraform/ecs/ provisions ECR, Fargate service, ALB with ACM/TLS 1.3, EFS-backed key store, Secrets Manager injection, and CloudWatch. Keep desired_count=1 until the key store is migrated off SQLite.

MCP Registry: fill in server.json and follow docs/REGISTRY.md to publish your deployed server to registry.modelcontextprotocol.io.

Development

uv sync --extra dev
uv run pytest tests/ -v        # 38 tests: tools, keystore, permissions, tenancy, auth modes

Project layout:

src/zendesk_mcp_server/
  server.py          # FastMCP app: tools, prompts, resources, transports
  zendesk_client.py  # Zendesk API client (dual identity, cursor pagination)
  auth.py            # API-key verifier, OIDC JWT verifier, auth-mode factory
  permissions.py     # Scope model + enforcement/filtering middleware
  keystore.py        # SQLite: keys, tenants, audit log
  runtime.py         # Client holder: hot-swap + per-tenant routing
  admin.py           # Web admin console (separate port)
  keys_cli.py        # zendesk-keys CLI
  config.py          # Env-based settings
terraform/           # EC2 deployment     terraform/ecs/  # Fargate deployment
docs/                # Architecture plan, deployment runbook, registry guide

Architecture decisions and full history: docs/REMOTE_MCP_ARCHITECTURE_PLAN.md.

License

Apache 2.0 — same as the original project. Original work by reminia; extensions as described above.

Available Tools

14 tools

create_ticketA

Create a new Zendesk ticket. Requires the tickets:write scope.

priority: low | normal | high | urgent. type: problem | incident | question | task. custom_fields: list of {id, value} objects (see list_ticket_fields).

ParametersJSON Schema

Name	Required	Description	Default
`tags`	No
`type`	No
`subject`	Yes
`priority`	No
`assignee_id`	No
`description`	Yes
`requester_id`	No
`custom_fields`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A3.7/5.0

Behavior3/5

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

Annotations already indicate readOnlyHint=false and destructiveHint=false. The description adds context about the write scope and allowed values for parameters, but lacks additional behavioral traits like rate limits or side effects.

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 concise, front-loaded with the main action, and each line adds value without redundancy or fluff.

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

Completeness3/5

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

Given the complexity of 8 parameters and an output schema present, the description covers the scope and three parameters but omits details for tags, assignee_id, and requester_id, making it partially incomplete.

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?

With 0% schema description coverage, the description partially compensates by listing allowed values for priority, type, and structure for custom_fields. However, it does not cover other parameters like tags, assignee_id, or requester_id.

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 clearly states 'Create a new Zendesk ticket.' with a specific verb and resource, and it is distinct from sibling tools like update_ticket and create_ticket_comment.

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?

The description mentions the required scope 'tickets:write' but does not explicitly state when to use this tool versus alternatives like update_ticket. No when-not guidance is provided.

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

create_ticket_commentA

Destructive

Add a comment to an existing Zendesk ticket. Requires the tickets:write scope.

WARNING: public=true comments are visible to the end customer. upload_tokens: tokens from upload_attachment to attach files.

ParametersJSON Schema

Name	Required	Description	Default
`public`	No
`comment`	Yes
`ticket_id`	Yes
`upload_tokens`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.5/5.0

Behavior4/5

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

Annotations already indicate destructive behavior, and the description adds context: write scope requirement, visibility consequences of public=true, and upload token usage. No contradiction.

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?

Three concise sentences: purpose+requirement, warning, parameter note. No unnecessary text.

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 output schema present, the description covers purpose, prerequisites, warnings, and key parameter behavior. Sufficient for an agent to use correctly.

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 0%, so description compensates by explaining the public parameter's effect and upload_tokens' purpose. Other parameters (ticket_id, comment) are self-explanatory from names.

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 starts with 'Add a comment to an existing Zendesk ticket', which is a specific verb and resource. It clearly distinguishes from siblings like create_ticket and get_ticket_comments.

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?

Requires the tickets:write scope, provides a warning about public visibility, and explains upload_tokens. While it doesn't explicitly list alternatives, the purpose is clear enough for proper selection.

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

get_ticketA

Read-only

Retrieve a Zendesk ticket by its ID.

ParametersJSON Schema

Name	Required	Description	Default
`ticket_id`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A3.9/5.0

Behavior3/5

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

Behavior is clear (read-only retrieve), and annotations already set readOnlyHint=true. Description adds no extra behavioral detail beyond purpose.

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?

Single 7-word sentence, front-loaded with verb, zero waste.

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 simple ID retrieval with an output schema, the description covers all necessary information.

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?

The description ties parameter to purpose ('by its ID'), but schema coverage is 0% and no format/range info is added.

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 is precise with verb 'Retrieve' and resource 'Zendesk ticket', and it distinguishes from siblings like get_tickets (plural) and search_tickets.

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?

The description implies usage for retrieving a ticket by ID but doesn't contrast with similar tools like get_tickets or search_tickets, leaving ambiguity.

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

get_ticket_attachmentA

Read-only

Fetch an image attachment by its content_url (from get_ticket_comments) and return it as base64-encoded data. Only safe image types are allowed.

ParametersJSON Schema

Name	Required	Description	Default
`content_url`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A4.4/5.0

Behavior4/5

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

Annotations already declare readOnlyHint=true, and the description adds value by specifying the return format (base64) and the restriction to safe image types, without contradicting annotations.

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?

Two sentences, front-loaded with the action, no redundancy. Every word earns its place.

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?

An output schema exists, so return format is not required but is helpfully mentioned. The description covers the input source and type restriction, making it complete for a simple fetch tool.

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?

With 0% schema coverage, the description explains the source and constraints of the sole parameter (content_url from get_ticket_comments, safe image types). This adds meaningful context beyond the raw 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?

The description clearly states the tool fetches an image attachment using a content_url and returns base64-encoded data. It distinguishes from siblings like upload_attachment by specifying the direction (fetch vs upload) and the data format.

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?

The description indicates that the content_url comes from get_ticket_comments, guiding the user on prerequisite tool usage. It also notes the 'only safe image types allowed' constraint, but does not explicitly mention when not to use or name alternatives.

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

get_ticket_commentsB

Read-only

Retrieve comments for a ticket (cursor-paginated), including attachment metadata.

ParametersJSON Schema

Name	Required	Description	Default
`cursor`	No
`per_page`	No
`ticket_id`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

B3.1/5.0

Behavior3/5

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

Annotations already declare readOnlyHint=true, so the description adds only cursor-pagination and attachment metadata context. It does not contradict annotations and provides moderate behavioral insight beyond the annotation.

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?

Single sentence with no redundant words; front-loads verb and resource. Every part earns its place.

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

Completeness2/5

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

Despite having an output schema, the description lacks details on pagination behavior (how to get next page via cursor), attachment metadata structure, or typical usage patterns, leaving gaps for a tool with three parameters.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, yet the description fails to explain the parameters (cursor, per_page, ticket_id) or their roles. The description adds no meaning beyond the schema's structure.

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 'Retrieve comments for a ticket (cursor-paginated), including attachment metadata' clearly states the verb (Retrieve), resource (comments for a ticket), and distinguishes from siblings like get_ticket or create_ticket_comment.

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

Usage Guidelines2/5

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

The description provides no explicit guidance on when to use this tool versus alternatives like search_articles or get_ticket. It does not mention prerequisites or typical scenarios.

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

get_ticketsA

Read-only

Fetch tickets with cursor pagination.

Pass the returned after_cursor as cursor to get the next page. sort_by: created_at | updated_at | priority | status. per_page max 100.

ParametersJSON Schema

Name	Required	Default
`cursor`	No
`sort_by`	No	created_at
`per_page`	No
`sort_order`	No	desc

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A4.2/5.0

Behavior4/5

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

The description adds behavioral transparency beyond the 'readOnlyHint' annotation by detailing cursor pagination, sort options, and per_page limitations. No contradictions with annotations.

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?

Two concise sentences: first states purpose, second provides critical usage details. Front-loaded with no redundant information.

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?

The description covers core functionality (pagination, sort, limit) for a 4-parameter list tool. An output schema exists, so return values need not be described. Slight missing guidance on sort_order and when to use it versus search_tickets.

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?

With 0% schema description coverage, the description compensates by explaining cursor (pagination), sort_by (options), and per_page (max 100). However, it omits sort_order, which is a parameter. The explanation adds meaning but could be more complete.

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 clearly states 'Fetch tickets with cursor pagination,' indicating a specific verb and resource. It differentiates from siblings like 'get_ticket' (single ticket) and 'search_tickets' (search with filters) by focusing on cursor-paginated listing.

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?

The description provides explicit guidance on pagination: 'Pass the returned after_cursor as cursor to get the next page.' It also specifies sort_by options and per_page max. However, it does not explicitly distinguish when to use this tool versus sibling tools like 'search_tickets' for filtered queries.

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

get_userA

Read-only

Get a Zendesk user by ID — resolve requester_id/assignee_id to name, email, role.

ParametersJSON Schema

Name	Required	Description	Default
`user_id`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A4.5/5.0

Behavior4/5

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

Annotations already indicate readOnlyHint=true. The description adds specific fields resolved (name, email, role), providing useful behavioral context beyond the annotations. It does not mention other behaviors, but with output schema present, this is sufficient.

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?

Single sentence with no wasted words, front-loaded purpose, and clear structure. Every part earns its place.

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 simple get-by-ID tool with output schema, the description covers the essential context (resolution use case) completely. No missing information for typical use.

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?

The description explains the purpose of the integer user_id parameter (resolving to user details), adding meaning beyond the bare schema. With 0% schema coverage, this compensation is effective.

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 clearly states the verb 'Get' and the resource 'a Zendesk user by ID', and explains the purpose of resolving requester_id/assignee_id to name, email, role, distinguishing it from sibling tools like search_users.

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?

The description implies usage when you have a user ID and need details, including resolution of IDs. It does not explicitly state when not to use, but the context is clear and differentiates from alternatives.

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

list_groupsA

Read-only

List agent groups (teams) for routing tickets.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.1/5.0

Behavior3/5

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

The readOnlyHint annotation already declares the tool as a safe read. The description adds context about the 'routing tickets' domain but does not disclose additional behavioral traits beyond what annotations provide. Score is adequate given annotation coverage.

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 a single sentence with no wasted words, front-loading the action and resource. Every part is essential.

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?

Given the tool has no parameters, an output schema, and annotations, the description is complete for its function. It covers the essential information without needing to explain return values.

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?

The input schema has no parameters, so the baseline is 4. The description correctly avoids adding redundant parameter information.

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 clearly states the verb 'List' and the resource 'agent groups', and provides context 'for routing tickets'. It distinguishes itself from sibling tools like list_ticket_fields, as it focuses on groups rather than tickets or users.

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?

No explicit when-to-use or alternatives are provided. However, for a simple list tool with no parameters, the usage is implied by its purpose. A higher score would require guidance on when to use this over other tools.

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

list_ticket_fieldsA

Read-only

List ticket fields including custom fields with their IDs, types, and options. Use this to interpret or set custom_fields {id, value} pairs on tickets.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.5/5.0

Behavior4/5

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

Annotations already mark as readOnlyHint=true. The description adds that it lists custom fields and options and helps with setting custom_fields pairs, which is helpful context beyond the annotation.

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?

Two clear sentences, front-loaded with purpose, and no unnecessary words.

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?

Given the tool's simplicity (no parameters, no nested objects), the description fully explains the purpose, output, and usage. Output schema exists but description already covers what is returned.

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?

There are no parameters, so schema coverage is 100%. The description adds meaning by explaining the output (IDs, types, options) and usage, which is valuable but not parameter-specific.

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 explicitly states it lists ticket fields including custom fields with IDs, types, and options. It clearly distinguishes from siblings like list_groups or get_ticket by focusing on field metadata.

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?

The description advises using the tool to interpret or set custom_fields pairs, providing clear context. It doesn't explicitly state when not to use, but for a read-only listing, this is sufficient.

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

search_articlesA

Read-only

Search Help Center knowledge-base articles. Prefer this over reading the whole zendesk://knowledge-base resource.

ParametersJSON Schema

Name	Required	Description	Default
`limit`	No
`query`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A3.5/5.0

Behavior3/5

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

Annotations already declare readOnlyHint=true, so the agent knows this is a safe read operation. The description adds that it searches articles but does not disclose additional behavioral traits like pagination, rate limits, or result format. With annotations covering the safety profile, a score of 3 is appropriate.

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 two sentences with no unnecessary words. It front-loads the core purpose and adds a usage hint, making it concise and well-structured.

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

Completeness2/5

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

Despite having an output schema, the description lacks coverage of parameters and fails to set expectations around how the search works (e.g., query meaning, limit behavior). Given the simplicity of the tool and the presence of siblings, more context is needed for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate by explaining parameter semantics. However, the description only says 'Search Help Center knowledge-base articles' without any mention of the query or limit parameters, adding no meaning beyond what the schema provides. This is a major gap.

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 clearly states 'Search Help Center knowledge-base articles', a specific verb and resource. It also distinguishes itself from a potential generic read tool by saying 'Prefer this over reading the whole zendesk://knowledge-base resource', making its purpose unambiguous and well-differentiated from siblings.

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?

The description provides a usage preference: 'Prefer this over reading the whole zendesk://knowledge-base resource', indicating when to use this tool vs. a generic read. However, it does not explicitly mention alternatives by name or provide when-not-to-use scenarios, leaving some ambiguity.

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

search_ticketsA

Read-only

Search tickets with Zendesk search syntax.

Examples: 'status:open priority:high', 'requester:jane@example.com', 'printer error created>2026-01-01'. limit max is 100.

ParametersJSON Schema

Name	Required	Description	Default
`limit`	No
`query`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.4/5.0

Behavior4/5

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

The annotation readOnlyHint=true already marks this as read-only. The description adds the behavioral constraint that limit max is 100, and examples show valid query syntax. No contradictions with annotations.

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 extremely concise: two sentences plus examples. It front-loads the purpose and immediately provides actionable examples. Every element earns its place, with no redundancy.

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?

Given that an output schema exists, return values are documented elsewhere. The description covers all input parameters (query with examples, limit with max) and provides clear context for a search tool. It could be slightly more explicit about when to use this over list tickets, but it's sufficiently complete for the tool's complexity.

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 0%, so the description carries the burden. It provides detailed example values for the 'query' parameter, showing format and operators. For 'limit', it specifies a maximum value (100), adding meaning beyond the schema's default. The description compensates well for the lack of schema descriptions.

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 clearly states the tool's purpose: searching tickets using Zendesk search syntax. It provides concrete examples that distinguish it from sibling tools like get_ticket (retrieve by ID) and get_tickets (list all). The verb 'search' and resource 'tickets' are explicit.

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?

The description includes examples that imply usage patterns (e.g., filtering by status, requester, date). It does not explicitly state when to use this tool versus alternatives, but the context is clear enough for an agent to infer. The sibling list provides additional differentiation.

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

search_usersB

Read-only

Search Zendesk users by name or email.

ParametersJSON Schema

Name	Required	Description	Default
`limit`	No
`query`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

B3.3/5.0

Behavior2/5

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

Annotations already declare readOnlyHint=true, so no contradiction. However, the description adds no behavioral details beyond the schema: e.g., pagination behavior, case sensitivity, or partial matching is not mentioned.

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?

Single sentence, no wasted words. Front-loaded with purpose. Could benefit from an additional sentence on usage, but remains concise.

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

Completeness3/5

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

Given the presence of an output schema (which covers return values), the description adequately states the basic purpose. However, for a search tool with two parameters, it omits detail on the limit parameter and query format. Minimum viable but not fully complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schemal description coverage is 0%, so the description must compensate. It mentions searching by name or email, which partly explains the 'query' parameter, but does not explain the 'limit' parameter or its default value. Incomplete compensation for low coverage.

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?

Description clearly states it searches Zendesk users by name or email. This specifies the resource and action, distinguishing it from siblings like search_tickets (tickets) and get_user (specific user lookup).

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?

Implied that it is used for finding users by name or email, but no explicit when-to-use or when-not-to-use guidance. No mention of alternatives like get_user for known IDs.

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

update_ticketA

Destructive

Update fields on an existing Zendesk ticket. Requires the tickets:write scope.

ParametersJSON Schema

Name	Required	Description	Default
`tags`	No
`type`	No
`due_at`	No
`status`	No
`subject`	No
`priority`	No
`ticket_id`	Yes
`assignee_id`	No
`requester_id`	No
`custom_fields`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A4.1/5.0

Behavior4/5

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

Annotations declare destructiveHint=true, and the description adds that it updates fields, listing allowed values for status, priority, and due_at format. This provides behavioral context beyond annotations, though it does not disclose all side effects (e.g., which fields are overwritten vs appended).

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 concise, with no unnecessary words. It front-loads the purpose and scope requirement, then lists parameter constraints in a compact format. Every sentence adds value.

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

Completeness3/5

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

Given the presence of an output schema and annotations, the description covers core purpose and key parameters but omits descriptions for 7 parameters and does not explain update semantics for custom_fields or tags. More detail would improve completeness.

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 coverage is 0%, and the description only documents 3 of 10 parameters (status, priority, due_at) with allowed values/format. This adds some value but leaves 7 parameters (e.g., tags, type, subject, assignee_id) undocumented, which is insufficient for full understanding.

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 clearly states it updates an existing Zendesk ticket, with a specific verb and resource. It distinguishes from sibling tools like create_ticket (for new tickets) and get_ticket (for read-only).

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?

The description mentions the required scope (tickets:write) and provides allowed values for key parameters, giving implicit usage context. However, it does not explicitly state when to use this tool versus alternatives like search_tickets or create_ticket.

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

upload_attachmentA

Upload a file (base64) to Zendesk. Returns an upload token to pass to create_ticket_comment's upload_tokens. Requires the tickets:write scope. Max 10 MB.

ParametersJSON Schema

Name	Required	Default
`file_name`	Yes
`data_base64`	Yes
`content_type`	No	application/octet-stream

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A4.2/5.0

Behavior4/5

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

Provides behavioral constraints (scope, size, token usage) beyond annotations which only indicate non-read-only and non-destructive. Does not contradict annotations.

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?

Two sentences with no filler; first sentence provides action and return value, second adds scope and size. Highly efficient and front-loaded.

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?

Covers all critical aspects: action, return token, usage in ticket comment, scope, size limit. Output schema exists, so return values are further detailed. Lacks error handling details but adequate for this tool.

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?

With 0% schema description coverage, description adds meaning: 'base64' clarifies data_base64 encoding. File_name is obvious, content_type lacks detail but has default. Partial compensation for coverage gap.

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?

Description clearly states the verb (Upload), resource (file to Zendesk), and purpose (returns upload token for create_ticket_comment), distinguishing it from siblings like get_ticket_attachment which is read-only.

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?

Specifies required scope (tickets:write) and size limit (10 MB), and explains the token's use in create_ticket_comment, guiding when to use this tool. Could be more explicit about when not to use, but context is clear.

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

14 tool updatesv0.3.0Jul 29, 2026
- First observedcreate_ticket
- First observedcreate_ticket_comment
- First observedget_ticket
- First observedget_ticket_attachment
- First observedget_ticket_comments
- First observedget_tickets
- First observedget_user
- First observedlist_groups
- First observedlist_ticket_fields
- First observedsearch_articles
- First observedsearch_tickets
- First observedsearch_users
- First observedupdate_ticket
- First observedupload_attachment

Install Server

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4/5.0

Disambiguation5/5

Each tool targets a distinct resource or action: groups, ticket fields, attachments, users, tickets (CRUD and search), comments, articles. Descriptions clearly differentiate similar tools like get_ticket vs get_tickets and search_tickets vs get_tickets.

Naming Consistency5/5

All tools follow a consistent verb_snake_case pattern (list_, get_, search_, create_, update_, upload_). No mixing of conventions or ambiguous verb choices.

Tool Count5/5

14 tools cover the essential operations for a Zendesk support MCP server: ticket lifecycle, user/group lookup, comment management, attachments, and article search. The count feels well-scoped without bloat.

Completeness4/5

Core ticket workflows are covered (CRUD, comments, attachments, search, user/group resolution). Missing delete ticket and some admin features, but these are reasonable omissions for an agent-focused server.

Maintenance

ActivitySlowing

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Muninx MCP Server AOAuth
com.muninx
Remote MCP server for managing Muninx tickets, messages, ticket search, and support analytics.
Customer Support Project Management
2
Zendesk B
io.github.pipeworx-io
Zendesk MCP Pack — tickets, users, organizations via OAuth.
Customer Support CRM
362
MANDATE Credential Broker B
io.github.projetnanocorp
MCP server for mandates, delegation, policy-gated execution, credential grants, and audit.
Security
111
mcp-serverOAuth
com.niftypm
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Project Management Communication File Systems
2

Related MCP Servers

Zendesk API MCP Server
Customer Support Communication
mattcoatsworth
F
license
D
quality
D
maintenance
A comprehensive MCP server for managing Zendesk Support, Talk, Chat, and Guide products, providing tools for tickets, users, organizations, search, and more.
Updated a year ago (2025-04-04 14:34 UTC)
49
30
-
tokenless-zendesk-mcp
Customer Support Communication
yutamago
A
license
A
quality
D
maintenance
MCP server that authenticates via browser session cookies to access Zendesk's REST API without API tokens, supporting reads and writes with agent permissions.
Updated 3 months ago (2026-06-12 23:40 UTC)
19
6
1
MIT
Zendesk MCP Server
Customer Support CRM
famousdrew
A
license
A
quality
C
maintenance
A Model Context Protocol server that enables AI assistants like Claude to interact with Zendesk Support through natural language for searching, creating, updating, and managing tickets.
Updated 15 days ago (2026-08-24 16:41 UTC)
41
146
3
MIT
zendesk-mcp
Customer Support CRM
chenzhaoxuan0
A
license
Not graded
quality
B
maintenance
MCP server for Zendesk support workflows that enables ticket search, lookup, creation, commenting, status updates, and user listing through natural language. It uses OAuth authentication and supports both internal notes and public comments.
Updated 3 months ago (2026-06-19 17:01 UTC)
MIT

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/srinivas-86/zendesk-mcp-server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server