Allows browsing and searching public Zendesk Help Centers, fetching articles, categories, sections, and community content.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Zendesk Help Center MCP Server Search support.zendesk.com for articles about API documentation"
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.
A read-only MCP (Model Context Protocol) server for querying public Zendesk Help Center APIs. Lets AI agents browse, search, and fetch documentation from any public Zendesk Help Center.
Browse Help Center structure (categories, sections, articles)
Fetch article content as clean markdown
Search articles by keyword
Browse community posts and comments
Locale-aware (filter by language)
HTTP response caching (7-day TTL via hishel)
Works with any public Zendesk Help Center (no auth required)
Related MCP server: mcp-server-zendesk
Requires Python 3.10+.
git clone <repo-url>
cd zendesk
uv syncOr with pip:
pip install -e .Add a .mcp.json file to your project root (or any project that needs Zendesk HC access):
{
"mcpServers": {
"zendesk-hc": {
"command": "uv",
"args": ["--directory", "/path/to/zendesk-hc-mcp", "run", "zendesk-hc-mcp"]
}
}
}Replace /path/to/zendesk-hc-mcp with the absolute path to where you cloned this repo. Do not use ~ — tilde expansion does not work in MCP config.
Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):
{
"mcpServers": {
"zendesk-hc": {
"command": "uv",
"args": ["--directory", "/path/to/zendesk-hc-mcp", "run", "zendesk-hc-mcp"]
}
}
}Note: uv must be on PATH for the MCP host process to find it.
All tools take subdomain as the first parameter (e.g., "support.zendesk.com"). All tools accept force_refresh=True to bypass the cache. Most tools accept an optional locale parameter (e.g., "en-us", "ru") to filter by language.
Tool | Description |
| Entry point: shows locales, categories, and section counts |
| Sections, optionally filtered by category |
Tool | Description |
| Single article with full markdown body |
| Batch fetch multiple articles concurrently |
| TOC by default; set |
| Keyword search with snippets (no bodies) |
Tool | Description |
| Forum topics |
| Posts with body previews and comment counts |
| Full post with comments |
Discover a Help Center's structure:
list_categories("support.zendesk.com")Browse sections in a category:
list_sections("support.zendesk.com", category_id=360001006608)Fetch all articles in a section (TOC only):
get_section_articles("support.zendesk.com", section_id=360000031847)Fetch articles with full content:
get_section_articles("support.zendesk.com", section_id=360000031847, include_body=True, max_articles=5)Search for articles:
search_articles("support.zendesk.com", query="API")Responses are cached for 7 days in .cache/ (project-local) using hishel (SQLite-backed HTTP cache).
Use force_refresh=True on any tool to bypass the cache
Delete the .cache/ directory to clear all cached data
The .cache/ directory is gitignored
Override the default TTL (in seconds) with the ZENDESK_HC_CACHE_TTL environment variable in your .mcp.json:
{
"mcpServers": {
"zendesk-hc": {
"command": "uv",
"args": ["--directory", "/path/to/zendesk-hc-mcp", "run", "zendesk-hc-mcp"],
"env": {
"ZENDESK_HC_CACHE_TTL": "86400"
}
}
}
}# Install dev dependencies
uv sync
# Run tests
uv run pytest -v
# Run the server (stdio mode)
uv run zendesk-hc-mcpContributions are welcome! To get started:
Fork the repository
Create a feature branch (git checkout -b feature/my-feature)
Install dev dependencies: uv sync
Make your changes following TDD (write tests first)
Run the test suite: uv run pytest -v
Ensure coverage stays above 90%: uv run pytest --cov=zendesk_hc_mcp --cov-report=term-missing
Submit a pull request
See CLAUDE.md for architecture details and development conventions.
This project is not affiliated with, endorsed by, or sponsored by Zendesk, Inc. "Zendesk" is a registered trademark of Zendesk, Inc. This tool accesses the publicly available Zendesk Help Center API and is intended for lawful, read-only use.
Fetch a single article with its full content converted to markdown.
Args: subdomain: Help Center hostname article_id: Article ID to fetch force_refresh: Bypass cache and fetch fresh data
| Name | Required | Description | Default |
|---|---|---|---|
| subdomain | Yes | ||
| article_id | Yes | ||
| force_refresh | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses meaningful behavior: the output is converted to markdown, and force_refresh bypasses cache to fetch fresh data. It does not mention read-only nature explicitly, but 'Fetch' implies a read operation; still, some edge case behavior like missing articles is absent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with a one-sentence purpose, followed by a compact Args list. Every line earns its place, and there is no filler or repeated schema boilerplate beyond the concise parameter meanings.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-article fetch with an output schema present, the description covers the purpose, all parameters, and the cache behavior. It lacks explicit alternative routing or error/authentication notes, but those are not critical for this low-complexity read tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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. The Args section covers all three parameters and adds real meaning: subdomain is a 'Help Center hostname,' and force_refresh 'Bypass cache and fetch fresh data.' This goes well beyond the raw schema types and titles.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'Fetch a single article with its full content converted to markdown.' It explicitly says 'single article,' which distinguishes it from siblings like get_articles and get_article_articles, and the markdown conversion detail adds a distinguishing behavior.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description makes the use case clear: when you need exactly one article by ID and want its full content as markdown. It does not explicitly name alternatives or say when not to use it, but 'single article' plus the article_id parameter gives enough context for an agent to select it over list-style siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Batch fetch multiple articles with full markdown bodies (concurrent requests).
Args: subdomain: Help Center hostname article_ids: List of article IDs to fetch force_refresh: Bypass cache and fetch fresh data
| Name | Required | Description | Default |
|---|---|---|---|
| subdomain | Yes | ||
| article_ids | Yes | ||
| force_refresh | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description provides some behavioral detail: concurrent requests and cache-bypass behavior via force_refresh. It does not mention error handling, partial failures, rate limits, or authentication requirements, so it only partially carries the transparency burden.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded with the core behavior, followed by a clean single-purpose Args block. Every sentence and bullet contributes useful information without filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has only three parameters, and all are semantically explained; the output schema covers the return shape, so the description need not repeat it. Missing guidance on when to prefer get_article or search_articles is the main gap, but it does not cripple callability.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description fully compensates by naming each parameter and giving its meaning: subdomain is the Help Center hostname, article_ids are the IDs to fetch, and force_refresh bypasses cache. This adds real value beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('fetch'), resource ('articles'), and scope ('batch', 'multiple', 'full markdown bodies'). It clearly distinguishes this tool from the singular get_article sibling by emphasizing multiple articles at once.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied: fetch this batch of known article IDs by passing article_ids. The description does not explicitly name alternatives, but 'batch fetch multiple articles' signals it is for multi-ID retrieval rather than search or singular lookup.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch a community post with its full body and comments.
Args: subdomain: Help Center hostname post_id: Post ID to fetch force_refresh: Bypass cache and fetch fresh data
| Name | Required | Description | Default |
|---|---|---|---|
| post_id | Yes | ||
| subdomain | Yes | ||
| force_refresh | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the behavioral disclosure burden. It discloses the return content ('full body and comments'), clarifies subdomain as the Help Center hostname, and explains force_refresh as cache-bypassing. It does not go into error cases or authorization, but the read-only nature is clearly conveyed by 'Fetch'.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized: one clear purpose sentence followed by three compact parameter explanations. The main action is front-loaded, and there is no redundant or filler content. Every sentence serves a purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple three-parameter tool and the presence of an output schema, the description covers the essential purpose, parameter semantics, and cache behavior. It does not explain likely error responses or when to pick this over a sibling, but for a basic read operation the core calling requirements are met.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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 fully. It provides meaningful semantics for subdomain ('Help Center hostname') and force_refresh ('Bypass cache and fetch fresh data'), while post_id ('Post ID to fetch') is minimally informative but still mapps to the schema property. This is strong compensation for the schema gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb- resource pair, 'Fetch a community post with its full body and comments,' which clearly identifies both the action and the target object. It also distinguishes itself from sibling tools like list_community_posts by framing it as a single-post fetch rather than a listing operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the intended usage scenario: retrieving one community post by ID along with its comments. However, it does not explicitely state when to choose this over list_community_posts or any other sibling, nor does it mention any exclusions or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch articles in a section. Returns TOC by default; set include_body=True for full text.
Use section IDs from list_sections. Use article IDs from the TOC with get_article or get_articles.
Args: subdomain: Help Center hostname section_id: Section ID from list_sections locale: Optional locale filter include_body: If True, include full markdown article bodies max_articles: Max articles to include bodies for (default 10) force_refresh: Bypass cache and fetch fresh data
| Name | Required | Description | Default |
|---|---|---|---|
| locale | No | ||
| subdomain | Yes | ||
| section_id | Yes | ||
| include_body | No | ||
| max_articles | No | ||
| force_refresh | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full behavioral burden. It discloses the default TOC behavior, the include_body switch, the max_articles cap, and force_refresh cache bypass. It does not mention auth, rate limits, or error behavior, but it clearly conveys the important behavioral traits that would change how an agent calls the tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured: two brief sentences establish purpose and workflow, followed by a tight Args list. The Args list is justified because the schema provides no parameter descriptions, and every line in the description adds necessary information without fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with six parameters and an output schema, the description covers all required and optional parameters, gives defaults, explains the cache behavior, and connects this tool to its siblings. An agent has enough information to call it correctly without needing to inspect sibling schemas or infer hidden prerequisites.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the parameter explanations in the description are essential. Every parameter gets a meaningful explanation: subdomain is the Help Center hostname, section_id comes from list_sections, locale is an optional filter, include_body controls full article bodies, max_articles limits bodies, and force_refresh bypasses the cache. This fully compensates for the schema's lack of descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with the specific action, 'Fetch articles in a section,' and immediately clarifies the default output ('Returns TOC by default') versus the full-text mode. It also creates clear separation from siblings by telling the agent to use article IDs from the TOC with get_article or get_articles, so the tool's role in the workflow is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly routes the agent through the workflow: 'Use section IDs from list_sections' before calling this tool, and 'Use article IDs from the TOC with get_article or get_articles' after. This names the relevant sibling tools and tells the agent where this tool sits relative to them, which is exactly the usage guidance needed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Browse a Zendesk Help Center's structure: available locales, categories, and section counts.
This is the recommended first call to understand what content a Help Center offers.
Args: subdomain: Help Center hostname, e.g. "support.zendesk.com" locale: Optional locale filter, e.g. "en-us" force_refresh: Bypass cache and fetch fresh data
| Name | Required | Description | Default |
|---|---|---|---|
| locale | No | ||
| subdomain | Yes | ||
| force_refresh | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden. It discloses caching behavior via force_refresh ('Bypass cache and fetch fresh data') and implies a read-only operation through 'Browse' and 'fetch.' It does not discuss rate limits or authentication, but for a simple listing tool this is adequate transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: a one-sentence purpose, a one-sentence usage recommendation, then a clear Args list. Every line earns its place and there is no redundant or repetitive content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, an output schema exists to describe return values, and the description covers usage positioning, parameter semantics, and caching behavior, nothing important is missing for an agent to select and invoke this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description fully compensates by explaining each parameter: subdomain is the Help Center hostname with an example, locale is an optional filter, and force_refresh means bypassing cache. This adds real meaning beyond the raw schema properties.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action and resource: browsing a Zendesk Help Center's structure including locales, categories, and section counts. It also positions itself as the recommended first call to understand available content, which helps distinguish it from sibling tools like list_sections or get_articles.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly says 'This is the recommended first call to understand what content a Help Center offers,' giving clear usage context. It does not explicitly list exclusion cases or name alternative tools, but the first-call framing strongly implies this should precede more specific queries.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List community posts with body previews and comment counts.
Args: subdomain: Help Center hostname topic_id: Optional topic ID to filter posts limit: Max posts to return (default 10) force_refresh: Bypass cache and fetch fresh data
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| topic_id | No | ||
| subdomain | Yes | ||
| force_refresh | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description bears the burden of behavioral disclosure. It adds useful behavior via 'body previews' and 'force_refresh: Bypass cache and fetch fresh data', which go beyond the schema. However, it does not mention read-only guarantees, pagination, or any rate-limiting/auth requirements, leaving some transparency gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a single-sentence summary followed by a compact Args block. Every line earns its place, and the purpose statement is front-loaded. No fluff or repetition of schema types or defaults.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a list operation with an output schema and fully documented parameters, the description is mostly complete. It covers the operation, return content hints (previews, comment counts), and the one custom behavior (bypass cache). It could be more explicit about when not to use it, but that gap is already captured under usage guidelines.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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, and it does. All four parameters receive clear purpose definitions: subdomain is the Help Center hostname, topic_id filters posts, limit caps results, and force_refresh bypasses cache. This is a complete semantic layer that the schema entirely lacks.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the operation (List community posts) and the resource (community posts), with additional detail about body previews and comment counts. It is easily distinguishable from siblings like get_community_post or list_community_topics by name and action, though it never explicitly names alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no explicit guidance on when to use this tool versus alternatives. It relies entirely on the imperative 'List' to imply its use case, and does not mention the get_community_post sibling for single-post retrieval or list_community_topics for topics. No prerequisites or exclusions are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List community/forum topics in a Help Center.
Args: subdomain: Help Center hostname force_refresh: Bypass cache and fetch fresh data
| Name | Required | Description | Default |
|---|---|---|---|
| subdomain | Yes | ||
| force_refresh | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral disclosure burden. It adds one meaningful behavior—force_refresh bypasses cache and fetches fresh data—and 'List' implies a read-only operation. However, it does not disclose pagination, ordering, or other response characteristics, leaving the output schema to fill that gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well structured: a single lead sentence followed by two argument definitions. There is no repetition, filler, or unnecessary detail, and the core purpose is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter list tool with an output schema, the mechanical details are mostly covered: purpose and both parameters are explained. The main completeness gap is the missing relationship to sibling community-topic tools, which matters for correct tool selection.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the 'Args' section is essential. It explains subdomain as the 'Help Center hostname' and force_refresh as cache-bypass behavior, providing real semantic value beyond the bare property names and types.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the action ('List') and the resource ('community/forum topics'), so an agent can understand the basic function. However, it does not differentiate this tool from the sibling list_community_posts, leaving the topics-vs-posts distinction implicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus list_community_posts, list_categories, or list_sections. It names no alternatives, no conditions, and no exclusions, so the agent must infer selection from the tool name and sibling names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List sections in a Help Center, optionally filtered to a category.
Use category IDs from list_categories. Then use section IDs with get_section_articles.
Args: subdomain: Help Center hostname category_id: Optional category ID from list_categories locale: Optional locale filter force_refresh: Bypass cache and fetch fresh data
| Name | Required | Description | Default |
|---|---|---|---|
| locale | No | ||
| subdomain | Yes | ||
| category_id | No | ||
| force_refresh | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden. It discloses cache behavior via 'force_refresh: Bypass cache and fetch fresh data' and clarifies that category_id and locale are optional filters. However, it does not mention pagination, list ordering, rate limits, or error behavior for an invalid subdomain, which are relevant unknowns for a list operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The one-line summary is front-loaded, followed by a two-sentence workflow hint and a compact Args block, with no filler. The only minor redundancy is that the optional category filter appears in both the summary and the Args list, which is acceptable for readability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the core invocation requirements: what is listed, the optional filters, the cache flag, and the surrounding workflow (list_categories → list_sections → get_section_articles). An output schema exists to describe return values, though pagination and rate-limit behavior are still unaddressed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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 — and it does, explaining all four parameters: subdomain as a hostname, category_id with provenance ('from list_categories'), locale as a filter, and force_refresh's cache semantics. Each entry adds meaning beyond the bare schema types, though entries like 'Optional locale filter' are terse.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource: 'List sections in a Help Center, optionally filtered to a category.' It names the data source (Help Center), the resource (sections), and the optional filter, and its workflow hints ('Use category IDs from list_categories') distinguish it from the siblings list_categories and get_section_articles.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives an explicit data-flow chain: category IDs come from list_categories and section IDs feed into get_section_articles, which tells an agent exactly where this tool sits in the workflow. It does not state explicit when-not-to-use conditions or name alternatives to prefer, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search articles by keyword. Returns titles and snippets (no full bodies).
Args: subdomain: Help Center hostname query: Search query string locale: Optional locale filter limit: Max results to return (default 10) force_refresh: Bypass cache and fetch fresh data
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | Yes | ||
| locale | No | ||
| subdomain | Yes | ||
| force_refresh | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden. It discloses the return scope (titles and snippets, not full bodies) and, via force_refresh, reveals cache behavior. It does not mention auth, rate limits, or error behavior, but for a read-only search tool the key behaviors are covered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The summary is two focused sentences that lead with the core action and return limitation. The Args block is compact and each line adds meaningful semantics beyond the bare schema, so no words are wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
All parameters, the return shape, and caching behavior are covered, and an output schema exists to carry return-value details. It is slightly incomplete in routing guidance—there is no explicit pointer to get_article for full bodies—but otherwise an agent has enough to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, yet the description's Args section explains all five parameters: subdomain as Help Center hostname, query as the search string, locale as an optional filter, limit with default 10, and force_refresh as a cache bypass. This fully compensates for the schema's lack of descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Search articles by keyword,' and immediately clarifies that only titles and snippets are returned, not full bodies. This distinguishes it from sibling tools like get_articles and get_article, which handle listing and full retrieval.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The keyword-search framing implies the tool should be used when the goal is full-text search rather than navigation, listing, or retrieval. However, it never names alternatives or states when not to use it, leaving the agent to infer routing from sibling names and the 'no full bodies' caveat.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.0get_articleget_articlesget_community_postget_section_articleslist_categorieslist_community_postslist_community_topicslist_sectionssearch_articlesScored across 9 tools
Each tool targets a distinct resource and action: categories, sections, articles, search, and community topics/posts. While get_article and get_section_articles both return article content, their inputs and purposes are clearly separated.
All tools use a consistent lowercase snake_case verb_noun pattern, such as list_categories, get_article, and search_articles. The naming clearly reflects what each tool does with no mixed conventions.
Nine tools is a well-scoped size for a Help Center browsing server. Each tool serves a distinct purpose in the content hierarchy without redundancy or bloat.
The server covers the core read-only Help Center workflows: exploring structure, retrieving articles, searching, and browsing community content. Minor gaps include not having dedicated get_category or get_section detail tools, but these are not blocking for typical browsing use cases.
Web search and page-reading for AI agents. One-click OAuth connect, or a Caesar API key.
Shared knowledge base for AI agents. Semantic search across agents, no setup required — just a URL.
Search your knowledge bases from any AI assistant using hybrid RAG.
Your company's brain for AI agents. Cited, permission-aware knowledge across every system.
