This MCP server provides comprehensive management of Intercom Help Center articles and collections through CRUD operations, multilingual support, and search functionality.
Article Management:
Get a single article by ID (title, body, author, state, etc.)
List articles with pagination (configurable page/per-page, up to 50)
Create articles with required title, HTML body, and author ID; optional description, draft/published state, parent collection, and multilingual content
Update articles with partial changes — title, body, state, author, or translations — without affecting other fields
Search articles by keyword, filtering by state or Help Center ID, with optional match highlighting
Collection Management:
List all Help Center collections with pagination
Get a single collection by ID
Update collection names, descriptions, and multilingual translations
Delete a collection permanently
Multilingual Support: Create and update both articles and collections with translated content for multiple locales via translated_content.
Integration: Configure with Claude Desktop or Claude Code CLI using an Intercom Access Token, then manage content via natural language commands.
Provides tools for managing Intercom Help Center articles, enabling users to list, retrieve, create, and update articles, including support for multilingual content and draft/published states.
Click on "Install 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., "@Intercom Articles MCP Server list my first 10 help center articles"
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.
Intercom MCP server for Help Center content management and CS workflow automation.
v0.9.0 - Added send_outbound_email — start a NEW outbound email to a contact by email address (resolves/creates the contact, retries on the post-create 404 propagation delay). Complements reply_conversation, which only replies within an existing conversation.
v0.8.4 - Internal cleanup: removed the unused zod dependency; extracted shared ok() (tool-result wrapper) and clamp() (pagination) helpers to cut ~140 lines of repetition; dropped four decorative pass-through interfaces. No tool, schema, or output changes.
v0.8.3 - get_conversation no longer drops message-bearing open parts (customer email replies that reopen a closed conversation) or assignment parts (the first admin reply); also surfaces per-part attachments and lifts ticket-form content into explicit ticket.title / ticket.description — fixes triage missing the latest customer message or screenshots
v0.8.2 - get_conversation keeps triage essentials (source/delivered_as, ticket-form attributes, contacts, per-part from_quick_reply flag) instead of stripping them — needed to tell "typed a reply" from "tapped a quick-reply button"
v0.8.1 - Fix: search_conversations accepts the query even when the MCP client serializes the object as a JSON string (Intercom rejected the stringified form)
v0.8.0 - Added search_conversations & get_conversation; slimmed all action-tool responses (reply/close/note/article/ticket) to return only confirmation fields instead of the full Intercom object — prevents flooding the MCP client's context window
v0.7.0 - Added delete_article, create_collection, list_admins; optimized search_articles response
Related MCP server: MCP Help Scout
✅ get_article - Get a single article by ID
✅ list_articles - List articles with pagination
✅ search_articles - Search articles by keywords with highlighting support
✅ create_article - Create new articles with multilingual content
✅ update_article - Update existing articles with partial updates
✅ delete_article - Delete an article permanently
✅ list_collections - List all Help Center collections
✅ get_collection - Get a single collection by ID
✅ update_collection - Update collection info and translations
✅ delete_collection - Delete a collection (permanent)
✅ create_collection - Create new Help Center collections
✅ list_admins - List workspace admins (useful for finding valid author_id)
✅ search_conversations - Search conversations (slim list: id/state/contact/timestamps, no parts)
✅ get_conversation - Get one conversation with message history (slim: keeps comment/note/quick_reply plus any message-bearing open/assignment part + attachments; pure system events filtered out)
✅ reply_conversation - Reply to a conversation as an admin (returns slim confirmation)
✅ send_outbound_email - Start a NEW outbound email to a contact by email address (resolves/creates contact, returns new conversation_id)
✅ add_conversation_note - Add an internal note to a conversation
✅ close_conversation - Close a conversation
✅ update_ticket_state - Update a ticket's state
Clone the repository:
git clone https://github.com/kaosensei/intercom-mcp.git
cd intercom-mcpInstall dependencies:
npm installBuild the project:
npm run buildGo to Intercom Settings → Developers → Developer Hub
Create a new app or use existing one
Get an Access Token with Articles and Conversations read and write permissions
Variable | Required | Description |
| ✅ Always | Your Intercom API access token |
| ✅ For CS tools | Admin ID used for |
If you're using Claude Code CLI, you can easily add the MCP server:
claude mcp add --transport stdio intercom-mcp \
--env INTERCOM_ACCESS_TOKEN=<your_token> \
--env INTERCOM_ADMIN_ID=<your_admin_id> \
-- node /ABSOLUTE/PATH/TO/intercom-mcp/dist/index.jsReplace:
<your_token> with your Intercom Access Token
/ABSOLUTE/PATH/TO/ with your actual project path
To verify it's configured:
claude mcp listAlternatively, edit your Claude Desktop config file:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Add this configuration:
{
"mcpServers": {
"intercom-mcp": {
"command": "node",
"args": [
"/ABSOLUTE/PATH/TO/intercom-mcp/dist/index.js"
],
"env": {
"INTERCOM_ACCESS_TOKEN": "your_intercom_access_token_here",
"INTERCOM_ADMIN_ID": "your_admin_id_here"
}
}
}
}Important:
Replace /ABSOLUTE/PATH/TO/intercom-mcp with your actual project path
Replace your_intercom_access_token_here with your actual token
Replace your_admin_id_here with your Intercom admin ID (required for CS tools)
Completely quit Claude Desktop and restart it.
Once configured, you can use these commands in Claude Desktop:
List Intercom articlesor
Show me the first 20 Intercom articlesGet Intercom article with ID 9876543Search for Intercom articles about "subscription"or
Search published articles containing "播客" with highlighted matchesor
Find articles with keyword "訂閱" in ChineseCreate a new Intercom article titled "Getting Started Guide" with content "Welcome to our platform" by author ID 123456, save as draftUpdate article 9876543 and change its state to publishedList all Intercom Help Center collectionsGet collection with ID 14608214Update collection 14608214 and add Japanese translationDelete collection 16036040One of the key features of v0.4.0 is the ability to manage multilingual collections efficiently.
You can easily add translations to collections that are missing certain languages:
Update collection 14608214 and add the missing Japanese translation: name "アカウント管理", description "アカウント設定を管理する"Check which collections are missing translations:
List all collections and show me which ones are missing Japanese translationsThen update them one by one or create a plan to update multiple collections.
After updating, verify the changes:
Get collection 14608214 and show me all available translationsget_articleGet a single article by ID.
Parameters:
id (string, required): Article ID
Example:
{
"id": "9876543"
}list_articlesList articles with pagination.
Parameters:
page (number, optional): Page number (default: 1)
per_page (number, optional): Articles per page (default: 10, max: 50)
Example:
{
"page": 1,
"per_page": 20
}search_articlesSearch for articles using keywords. Supports full-text search across article content with multilingual support (English, Chinese, Japanese, etc.).
Parameters:
phrase (string, optional): Search keywords/phrase to find in articles
state (string, optional): Filter by article state - "published", "draft", or "all" (default: "all")
help_center_id (string, optional): Filter by specific Help Center ID
Example (Search by keyword):
{
"phrase": "subscription"
}Example (List all drafts, no keyword needed):
{
"state": "draft"
}Example (Chinese keyword search):
{
"phrase": "訂閱制",
"state": "all"
}Response includes:
total_count: Total number of matching articles
articles: Array of summary fields per article (id, title, description, state, url, author_id, created_at, updated_at, parent_id, parent_type)
Use get_article to fetch the full content of a specific article.
Use Cases:
Find all articles about a specific topic
Search for Chinese/Japanese content in multilingual help centers
Locate articles that need updating
Discover related content for cross-linking
create_articleCreate a new article with multilingual support.
Parameters:
title (string, required): Article title
body (string, required): Article content in HTML format
author_id (number, required): Author ID (must be a valid Intercom team member)
description (string, optional): Article description
state (string, optional): "draft" or "published" (default: "draft")
parent_id (string, optional): Collection or section ID
parent_type (string, optional): "collection" (default)
translated_content (object, optional): Multilingual content
Example (Simple):
{
"title": "Getting Started Guide",
"body": "<p>Welcome to our platform</p>",
"author_id": 123456,
"state": "draft"
}Example (Multilingual):
{
"title": "Getting Started Guide",
"body": "<p>Welcome to our platform</p>",
"author_id": 123456,
"state": "published",
"translated_content": {
"zh-TW": {
"title": "入門指南",
"body": "<p>歡迎使用我們的平台</p>",
"author_id": 123456,
"state": "published"
},
"ja": {
"title": "スタートガイド",
"body": "<p>プラットフォームへようこそ</p>",
"author_id": 123456,
"state": "published"
}
}
}update_articleUpdate an existing article. Only provided fields will be updated.
Parameters:
id (string, required): Article ID
title (string, optional): Updated title
body (string, optional): Updated content
description (string, optional): Updated description
state (string, optional): "draft" or "published"
author_id (number, optional): Updated author ID
translated_content (object, optional): Updated translations
Example (Change state):
{
"id": "9876543",
"state": "published"
}Example (Update content):
{
"id": "9876543",
"title": "Updated Title",
"body": "<p>Updated content</p>"
}Example (Add translation):
{
"id": "9876543",
"translated_content": {
"zh-TW": {
"title": "更新的標題",
"body": "<p>更新的內容</p>"
}
}
}list_collectionsList all Help Center collections (top-level categories).
Parameters:
page (number, optional): Page number (default: 1)
per_page (number, optional): Collections per page (default: 50, max: 150)
Example:
{
"page": 1,
"per_page": 50
}get_collectionGet a single collection by ID.
Parameters:
id (string, required): Collection ID
Example:
{
"id": "14608214"
}update_collectionUpdate an existing collection. Only provided fields will be updated. Perfect for adding missing translations!
Parameters:
id (string, required): Collection ID
name (string, optional): Updated collection name (updates default language)
description (string, optional): Updated description (updates default language)
parent_id (string, optional): Parent collection ID (null for top-level)
translated_content (object, optional): Updated translations
Example (Update name and description):
{
"id": "14608214",
"name": "Account Management",
"description": "Manage your account settings"
}Example (Add missing Japanese translation):
{
"id": "14608214",
"translated_content": {
"ja": {
"name": "アカウント管理",
"description": "アカウント設定を管理"
}
}
}Example (Update multiple language translations):
{
"id": "14608214",
"translated_content": {
"ja": {
"name": "アカウント管理",
"description": "アカウント設定を管理する"
},
"id": {
"name": "Manajemen Akun",
"description": "Kelola pengaturan akun Anda"
}
}
}delete_collectionDelete a collection permanently. WARNING: This action cannot be undone!
Parameters:
id (string, required): Collection ID to delete
Example:
{
"id": "16036040"
}⚠️ Important Notes:
Deleted collections cannot be restored
All content within the collection may be affected
Always backup important data before deletion
delete_articleDelete an article permanently. WARNING: This action cannot be undone!
Parameters:
id (string, required): Article ID to delete
Example:
{
"id": "9876543"
}create_collectionCreate a new Help Center collection.
Parameters:
name (string, required): Collection name
description (string, optional): Collection description
parent_id (string, optional): Parent collection ID for nesting (omit for top-level)
translated_content (object, optional): Multilingual content by locale code
Example (Simple):
{
"name": "Getting Started"
}Example (With translation):
{
"name": "Getting Started",
"translated_content": {
"zh-TW": {
"name": "入門指南",
"description": "開始使用我們的平台"
}
}
}list_adminsList all workspace admins. Useful for finding valid author_id values when creating or updating articles.
Parameters: None
Response includes:
id: Admin ID (use this as author_id)
name: Display name
email: Email address
has_inbox_seat: Whether the admin has an inbox seat
search_conversationsSearch conversations with an Intercom query object. Returns a slim list (no conversation parts) — call get_conversation for full content.
Parameters:
query (object, required): Intercom search query object, e.g. {"operator":"AND","value":[{"field":"state","operator":"=","value":"open"}]}. Add {"field":"admin_assignee_id","operator":"=","value":<id>} to filter by assignee, or source.author.email by contact. Also accepts the object serialized as a JSON string.
per_page (number, optional): Results per page (default: 20, max: 50)
starting_after (string, optional): Pagination cursor from a previous response's next
Example (all open conversations):
{
"query": {"operator":"AND","value":[{"field":"state","operator":"=","value":"open"}]},
"per_page": 50
}Response includes:
total_count: Total matching conversations
next: Pagination cursor (present if more pages)
conversations: Array of slim items (id, state, open, title, subject, contact, admin_assignee_id, timestamps) — no parts
get_conversationGet a single conversation with message history, slimmed for triage: pure system-event parts filtered out, but every message-bearing part (including reopen email replies and the first admin reply) and its attachments kept.
Parameters:
id (string, required): Conversation ID
Example:
{
"id": "12345678"
}Response includes:
Top level: id, state, open, title, timestamps, waiting_since
source: incl. delivered_as (identifies the real asker), subject, body, author
ticket: ticket-form essentials — type, state, and title / description (the real request, pulled out of the internal _default_title_ / _default_description_ keys; present only when the ticket has them)
ticket_attributes: all ticket-form custom attributes with non-empty values
contacts: contact references
total_parts / included_parts: counts before / after filtering
parts: comment / note / quick_reply, plus any open / assignment part that carries a real body or attachments (reopen email replies, the first admin reply). Each { part_type, body, author, from_quick_reply, attachments, created_at } — from_quick_reply distinguishes a typed reply from a tapped quick-reply option; attachments (when present) lists { name, url, content_type }
reply_conversationReply to a conversation as an admin. The reply is visible to the customer. Returns a slim confirmation object (id, state, last_part_id, timestamps).
Parameters:
conversation_id (string, required): The conversation ID to reply to
body (string, required): The reply message body (supports HTML)
admin_id (string, optional): Admin ID to reply as (defaults to INTERCOM_ADMIN_ID env var)
Example:
{
"conversation_id": "12345678",
"body": "<p>Thank you for reaching out. We'll look into this right away.</p>"
}send_outbound_emailStart a new outbound email to a contact identified by email address — not a reply to an existing conversation. The tool resolves the email to an Intercom contact (creating a lead if none exists), then sends via the Messages API. Because a freshly-created contact can briefly return 404 on send, the call retries with backoff. Returns the new conversation_id so you can note/track it.
Use reply_conversation instead when responding inside an existing conversation.
Parameters:
email (string, required): Recipient's email address
subject (string, required): Email subject
body (string, required): Email body (supports HTML)
admin_id (string, optional): Admin ID to send as (defaults to INTERCOM_ADMIN_ID env var). Determines the sender name/address the recipient sees.
template (string, optional): plain or personal (defaults to personal — a 1:1 personal-email look)
Example:
{
"email": "member@example.com",
"subject": "About your subscription",
"body": "<p>Hello, ...</p>",
"admin_id": "8530422"
}Note: the Messages API requires to.id to be an Intercom contact id, never a raw email — this tool handles the lookup/creation for you.
add_conversation_noteAdd an internal note to a conversation. Notes are only visible to team members, not customers.
Parameters:
conversation_id (string, required): The conversation ID to add a note to
body (string, required): The note content (supports HTML)
admin_id (string, optional): Admin ID adding the note (defaults to INTERCOM_ADMIN_ID env var)
Example:
{
"conversation_id": "12345678",
"body": "<p>Customer has been refunded. Follow up in 3 days.</p>"
}close_conversationClose a conversation.
Parameters:
conversation_id (string, required): The conversation ID to close
Example:
{
"conversation_id": "12345678"
}update_ticket_stateUpdate the state of a ticket.
Parameters:
ticket_id (string, required): The ticket ID to update
state (string, required): The new ticket state — one of in_progress, waiting_on_customer, resolved
Example:
{
"ticket_id": "87654321",
"state": "resolved"
}npm run buildnpm run watchCheck config file path is correct
Verify JSON format (no trailing commas)
Completely restart Claude Desktop
Check absolute path to dist/index.js
Verify your Access Token is correct
Ensure token has Articles and Conversations read/write permissions
Check Intercom API status
Ensure TypeScript version >= 5.0
Delete node_modules and dist, then:
npm install && npm run buildintercom-mcp/
├── package.json # Project configuration
├── tsconfig.json # TypeScript configuration
├── src/
│ └── index.ts # Main server code
├── dist/ # Compiled output
└── README.md # This file✅ Get Article (v0.1.0)
✅ List Articles (v0.1.0)
✅ Create Article (v0.2.0)
✅ Update Article (v0.2.0)
✅ Multilingual support for Articles (v0.2.0)
✅ List Collections (v0.3.1)
✅ Get Collection (v0.3.1)
✅ Update Collection (v0.4.0)
✅ Delete Collection (v0.4.0)
✅ Multilingual support for Collections (v0.4.0)
✅ Search Articles with keyword matching and highlighting (v0.5.0)
✅ Reply to conversations (v0.6.0)
✅ Add internal notes to conversations (v0.6.0)
✅ Close conversations (v0.6.0)
✅ Update ticket state (v0.6.0)
✅ Delete Article (v0.7.0)
✅ Create Collection (v0.7.0)
✅ List Admins (v0.7.0)
✅ Optimized search_articles response (v0.7.0)
✅ Search conversations — slim list (v0.8.0)
✅ Get conversation — slim, triage-aware (system events filtered, from_quick_reply flag) (v0.8.0)
✅ Slim action-tool responses to protect client context (v0.8.0)
✅ Get conversation — keep reopen/assignment message parts + attachments, surface ticket title/description (v0.8.3)
🔜 Batch operations
🔜 Better error handling
🔜 Modular file structure
MIT
Add an internal note to an Intercom conversation. Notes are only visible to team members, not customers.
| Name | Required | Description | Default |
|---|---|---|---|
| conversation_id | Yes | The conversation ID to add a note to (required) | |
| body | Yes | The note content (required). Supports HTML. | |
| admin_id | No | Admin ID adding the note (optional, defaults to INTERCOM_ADMIN_ID env var) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It mentions internal visibility but lacks details on authentication, rate limits, or side effects. Still, the core behavior is clear.
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?
Two sentences convey all necessary information with no redundancy. Highly concise and 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?
Given the simple create operation and no output schema, the description adequately explains the purpose and key constraint (visibility). Could mention return value but not critical.
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 100%, and the description adds no parameter-specific information beyond what the schema already provides. Baseline score of 3 is appropriate.
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 tool adds an internal note to an Intercom conversation, specifying visibility to team members only. This distinguishes it from sibling tools like reply_conversation.
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 when to use (add internal note) and contrasts with customer-facing replies, but does not explicitly state when not to use or list alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Close an Intercom conversation.
| Name | Required | Description | Default |
|---|---|---|---|
| conversation_id | Yes | The conversation ID to close (required) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries full burden for behavioral disclosure. It only states 'close', implying a mutation, but fails to mention side effects, permissions, or consequences (e.g., whether conversations become unmodifiable). This is insufficient for a mutation 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 a single concise sentence that conveys the core action efficiently. However, it could be slightly more informative without sacrificing brevity.
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 one-parameter action, the description is minimally adequate. However, it lacks context on when to use, side effects, or prerequisites, making it incomplete for a comprehensive agent.
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 100% with a clear parameter description. The tool description adds no extra meaning beyond the schema's parameter description, warranting a baseline score of 3.
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 explicitly states the verb 'close' and the resource 'Intercom conversation', clearly defining the action. It distinguishes from siblings like add_conversation_note, reply_conversation, and update_ticket_state, which have different purposes.
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?
No guidance on when to use this tool versus alternatives. For example, it doesn't specify if closing is appropriate only after a reply or if it prevents further interaction. The description lacks context for conditional usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new Intercom Help Center article. Supports multilingual content and draft/published states.
| Name | Required | Description | Default |
|---|---|---|---|
| title | Yes | Article title (required) | |
| body | Yes | Article content in HTML format (required) | |
| author_id | Yes | Author ID - must be a valid Intercom admin ID (required). Use list_admins to find valid IDs by name. | |
| description | No | Article description (optional) | |
| state | No | Article state (optional, default: draft) | |
| parent_id | No | Parent ID - collection or section ID (optional) | |
| parent_type | No | Parent type (optional, default: collection) | |
| translated_content | No | Multilingual content. Key is locale code (e.g., "zh-TW"), value is translation object |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries the burden. It does not disclose behavior beyond creation, such as success indications, error handling, or permissions.
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?
One sentence with no wasted words. It could include more guidance without being overly long.
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?
With 8 parameters and nested objects, the description covers only two features. Lacks explanation of author_id, parent hierarchy, and output behavior, but schema fills many gaps.
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 has 100% coverage with descriptions, so baseline is 3. The description adds high-level context about multilingual and state support, but doesn't deepen understanding beyond the 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 clearly states 'Create a new Intercom Help Center article' with a specific verb and resource, and distinguishes from siblings like update_article by the verb 'create'.
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?
No guidance on when to use this tool vs alternatives (e.g., update_article) or prerequisites (e.g., needing admin IDs). The description only lists features.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new Intercom Help Center collection. Collections are top-level categories that contain sections and articles.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Collection name (required) | |
| description | No | Collection description (optional) | |
| parent_id | No | Parent collection ID for nesting (optional, null for top-level) | |
| translated_content | No | Multilingual content. Key is locale code (e.g., "zh-TW"), value is translation object |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description bears full responsibility for behavioral disclosure. It only states the basic creation action, omitting any details about side effects, success/failure behavior, rate limits, required scopes, or whether the operation is idempotent. This is insufficient for an agent to understand the tool's runtime impact.
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 extremely concise at two sentences, with no redundancy. The first sentence clearly states the action and resource, and the second provides useful context. Every word earns its place, making it easy to parse quickly.
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 no output schema, but the description does not mention what is returned upon success (e.g., the created collection object). It also lacks explanation of nested structures like parent_id or translated_content usage. Given the tool's moderate complexity (4 parameters, nested objects), the description leaves significant gaps that an agent would need to infer.
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?
The input schema has 100% description coverage on all parameters, so the baseline is 3. The description does not add extra meaning beyond the schema; it only provides context about collections being top-level. Since the schema already documents each parameter well, the description meets the minimum but does not enhance parameter understanding.
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 action ('Create') and the resource ('a new Intercom Help Center collection') and distinguishes it from sibling tools like 'create_article' or 'delete_collection' by specifying that collections are top-level categories. The verb+resource combination is specific and 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 provides no guidance on when to use this tool versus alternatives. It does not mention prerequisites, when not to use it, or how to choose between creation and other operations (e.g., update_collection). The agent receives no contextual cues for decision-making.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete an Intercom Help Center article. WARNING: This action cannot be undone. The article will be permanently removed.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Article ID to delete (required) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description adds the critical behavior that deletion is permanent and irreversible. However, it does not disclose other potential side effects, such as cascading deletions or access requirements.
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?
Two sentences are concise and front-loaded with the primary action. The warning is useful but could be integrated more efficiently.
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 tool with one parameter and no output schema, the description covers the essential purpose and a key behavioral trait. Missing minor details like confirmation steps or authorization hints, but sufficient for basic usage.
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?
The input schema already provides 100% coverage for the single parameter 'id' with a clear description. The tool description adds no additional semantic value beyond what the schema states.
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 action (Delete) and resource (Intercom Help Center article), distinguishing it from siblings like update_article or get_article. The warning adds clarity about the irreversible nature.
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?
No explicit guidance on when to use this tool vs alternatives. The description implies it's for deletion when needed, but lacks context about prerequisites or situations to avoid.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete an Intercom Help Center collection. WARNING: This action cannot be undone. The collection and all its contents will be permanently removed.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Collection ID to delete (required) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Since no annotations are provided, the description carries the full burden and effectively discloses that deletion is irreversible and removes all contents. This is sufficient for a destructive 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?
Two short sentences: the first states the action, the second provides the critical warning. No unnecessary words; each sentence earns its place.
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 single-parameter tool with no output schema, the description completely explains what the tool does and its irreversible nature. No additional information is needed.
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 100% with the parameter described as 'Collection ID to delete (required)'. The description does not add additional meaning beyond what the schema already provides, so a baseline score of 3 is appropriate.
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?
Description clearly states verb 'Delete' and resource 'Intercom Help Center collection', distinguishing it from sibling tools like create_collection, get_collection, list_collections, and update_collection.
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 warns that the action is permanent and irreversible, implying it should only be used when deletion is intended. However, it does not explicitly mention when not to use it or suggest alternatives like archiving.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a single Intercom article by ID. Returns full article details including title, body, author, and state.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The article ID (e.g., "123456") |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavior. It mentions it returns full article details, but omits critical information such as authentication requirements, error handling (e.g., what happens if ID is invalid), or that it is a read-only operation. This is insufficient for a tool with no annotations.
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 a single sentence that front-loads the key information (action and resource) and includes output details. No superfluous words – every part is meaningful.
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 input (one required parameter) and no output schema, the description covers the essential purpose and return fields. However, it lacks usage guidelines and behavioral transparency, which for a simple tool is a minor gap. Still, it is largely complete.
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?
The schema already describes the 'id' parameter with 100% coverage, so the description adds no new semantic information beyond what the schema provides. Baseline of 3 is appropriate.
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 verb 'Get' and the resource 'single Intercom article by ID', distinguishing it from sibling tools like list_articles or search_articles. It also lists the returned fields, making the purpose 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 implies the tool should be used when you have a specific article ID, but does not explicitly mention when not to use it or compare it to alternatives like list_articles (for multiple) or search_articles (for queries). No exclusionary guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a single Intercom Help Center collection by ID. Returns full collection details including name, description, and metadata.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The collection ID (e.g., "123456") |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It accurately states it is a read operation ('Get') and describes the output ('full collection details'). It does not mention auth or error conditions, but for a simple retrieval this is adequate and not misleading.
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 a single sentence that states the action first then the output. It is concise and front-loaded with no redundant information.
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 one-parameter retrieval tool with no output schema, the description adequately covers purpose and return content. It could mention error behavior if ID is invalid, but overall it is complete enough for the complexity.
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?
The input schema already provides 100% coverage for the single parameter ('id') with a clear description. The tool description adds no new parameter information beyond stating 'by ID', so it does not improve on the 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 clearly specifies the verb ('Get'), resource ('Intercom Help Center collection'), and retrieval method ('by ID'). It distinguishes from siblings like 'list_collections' by implying singular retrieval and mentions returned fields ('name, description, and metadata').
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 usage when you have a specific ID and need full details, but does not explicitly state when to use versus alternatives like 'list_collections' or 'search_articles'. No when-not or prerequisite guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a single Intercom conversation by ID. SLIM: keeps triage essentials — source (incl. delivered_as), ticket (type/state/title/description from ticket forms) + ticket_attributes (custom fields), contacts — and message-bearing parts: comment/note/quick_reply PLUS any open/assignment part carrying a real body or attachments (reopen email replies, first admin reply), each flagged with from_quick_reply and including attachments. Pure system events filtered out, with total_parts/included_parts counts.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The conversation ID (required) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses behavior: it returns a SLIM version including triage essentials, filters out pure system events, flags parts from_quick_reply, and provides total_parts/included_parts counts. This goes beyond basic functionality.
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 detailed but front-loaded with the main purpose and structured logically. Each sentence adds value, though it could be slightly more concise without losing meaning.
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 no output schema, the description thoroughly explains the return structure, including what elements are included (source, ticket, contacts, message parts) and excluded (pure system events), as well as counts. This is sufficient for an agent to understand the output.
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?
The single parameter 'id' is fully described in the schema (100% coverage). The description adds no new semantic information beyond 'by ID', which is already clear. Thus, baseline 3 is appropriate.
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 it retrieves a single Intercom conversation by ID and details the SLIM structure, which differentiates it from siblings like search_conversations. The verb 'Get' and specific resource 'Intercom conversation' make the purpose 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 tool's single-purpose nature is evident, but it lacks explicit guidance on when to prefer this over alternatives like search_conversations. However, the description's focus on a single conversation implicitly directs usage for retrieving one specific conversation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all Intercom workspace admins/team members. Returns IDs, names, and emails. Useful for discovering valid author_id or admin_id values.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses that the tool lists all admins/team members and returns IDs, names, and emails. This is adequate for a simple read-only list operation, though it could optionally mention any implicit filtering or limits.
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?
Two sentences, no wasted words. The first sentence defines purpose and output, the second adds a practical usage hint. Every sentence earns its place.
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 no parameters, no output schema, and no annotations, the description covers the essential aspects: purpose, return fields, and a usage scenario. It could mention pagination or scope (e.g., 'all' meaning across workspace), but for a simple admin list it is reasonably complete.
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?
The input schema has zero parameters, so baseline 4 applies. The description does not need to add parameter details, but it effectively explains the return content beyond the schema, fulfilling the role of adding meaning.
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 verb 'List' and the resource 'Intercom workspace admins/team members', specifies return values (IDs, names, emails), and gives a concrete use case (discovering valid author_id or admin_id). This distinguishes it well from sibling tools focused on conversations, articles, or collections.
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 suggests when to use the tool: 'Useful for discovering valid author_id or admin_id values.' This provides clear context for the agent, though it does not mention when not to use it or name explicit alternatives. Given the sibling tools are distinctly different, this is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List Intercom articles with pagination. Returns a list of articles with basic information.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number (default: 1) | |
| per_page | No | Number of articles per page (default: 10, max: 50) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must disclose behavioral traits. It only states basic listing behavior, omitting details on authentication, rate limits, or whether the operation is read-only. The agent cannot assess side effects or requirements.
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?
Two sentences with no wasted words. The description is front-loaded with the core action and context.
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?
Without an output schema, the description should explain the return format; 'basic information' is vague. For a simple list tool with two parameters, it is adequate but not fully complete.
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 100%, so the schema already documents both parameters with defaults and max. The description adds no additional meaning beyond what the schema provides, meeting the baseline but not surpassing it.
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 it lists Intercom articles with pagination, using specific verb and resource. It distinguishes from search_articles and create_article by indicating a list operation, though it could be more explicit about the difference from search_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?
No guidance on when to use this tool versus alternatives like search_articles or get_article. The description does not mention prerequisites or exclusions, leaving the agent to infer usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all Intercom Help Center collections. Collections are top-level categories that contain sections and articles.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number (default: 1) | |
| per_page | No | Number of collections per page (default: 50, max: 150) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden of behavioral disclosure. It fails to mention that the operation is read-only, that results are paginated (implicit in the schema but not stated), or any ordering or rate limits. The phrase 'List all' is misleading because pagination means a single call does not return truly all items.
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 two sentences: the first clearly states the action and scope, the second provides necessary context about what collections are. No redundant words or filler. It is front-loaded and efficient.
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 low complexity and lack of annotations/output schema, the description should compensate. It does not explain that responses are paginated or how to handle pagination to retrieve all collections. The agent might assume a single response suffices, leading to incomplete data retrieval.
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 100% (page and per_page both have descriptions), so the baseline is 3. The description adds no additional meaning beyond the schema. It could have explained that page controls which page of results and per_page limits items per request, but that is already in the 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 clearly states the verb 'List' and the resource 'all Intercom Help Center collections', immediately identifying the tool's purpose. It also explains what collections are ('top-level categories that contain sections and articles'), distinguishing it from sibling tools like list_articles or create_collection.
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 tool is for listing collections but provides no explicit guidance on when to use it versus alternatives like get_collection (single item) or create_collection. It lacks when-not-to-use instructions or context about filtering, sorting, or pagination.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Reply to an Intercom conversation as an admin. Use this to send a message visible to the customer.
| Name | Required | Description | Default |
|---|---|---|---|
| conversation_id | Yes | The conversation ID to reply to (required) | |
| body | Yes | The reply message body (required). Supports HTML. | |
| admin_id | No | Admin ID to reply as (optional, defaults to INTERCOM_ADMIN_ID env var) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It indicates this is a write operation ('Reply') and notes visibility to customer but does not disclose authentication needs, rate limits, or side effects like whether it appends to existing conversation.
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 two sentences, front-loaded with key information, no wasted words. Every sentence adds value.
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 3 parameters and no output schema, the description provides core purpose and context about customer visibility. However, it lacks details on whether replies can be added to closed conversations, how admin_id interacts with the env var, or return behavior.
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 100%, so each parameter is described. The description does not add extra meaning beyond the schema, such as clarifying the body format or admin_id usage. Baseline of 3 is appropriate.
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 verb 'Reply' and the resource 'Intercom conversation' with context 'as an admin' and 'visible to the customer'. This distinguishes it from sibling tools like add_conversation_note which are for internal notes.
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 clear context for when to use this tool (to send a customer-visible message) but does not explicitly exclude when not to use it or mention alternatives like add_conversation_note for internal notes. It implies usage but lacks an explicit when-not.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for Intercom Help Center articles using keywords. Returns summary fields (id, title, description, state, url, author_id, created_at, updated_at, parent_id, parent_type) for each match. Use get_article to fetch the full content of a specific article.
| Name | Required | Description | Default |
|---|---|---|---|
| phrase | No | Search phrase/keywords to find in articles (optional) | |
| state | No | Filter by article state (optional, default: all) | |
| help_center_id | No | Filter by specific Help Center ID (optional) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, describes that it returns a set of summary fields and directs to get_article for full content. Discloses the specific fields returned, but lacks details on pagination, ordering, or case sensitivity.
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?
Two sentences, no wasted words. First sentence states purpose and return fields, second gives sibling guidance. Efficient and well-structured.
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 3 optional parameters and no output schema, the description adequately covers what the tool does and what it returns. Could mention default state or pagination, but not essential for a search 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 has 100% coverage with descriptions for each parameter. Description adds no extra meaning beyond the schema; it only mentions 'using keywords' which aligns with the 'phrase' parameter.
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?
Clearly states 'search for Intercom Help Center articles using keywords', specifying verb and resource. Distinguishes from siblings like list_articles and get_article by emphasizing keyword-based search and listing return fields.
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?
Explicitly tells when to use get_article for full content, providing a clear alternative. Implies search_articles is for summaries and keyword-based lookup, but does not say when not to use it (e.g., if no keywords).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search Intercom conversations. Returns a SLIM list (id, state, contact, timestamps) with NO conversation parts — call get_conversation for full content. Pass a raw Intercom query object.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Intercom search query object, e.g. {"operator":"AND","value":[{"field":"state","operator":"=","value":"open"}]}. Add {"field":"admin_assignee_id","operator":"=","value":<id>} to filter by assignee, or {"field":"source.author.email","operator":"=","value":"<email>"} by contact email. | |
| per_page | No | Results per page (default 20, max 50) | |
| starting_after | No | Pagination cursor from a previous response's "next" field |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It reveals that the tool returns only slim data without conversation parts, which is good. However, it does not mention that this is a read-only operation, potential rate limits, or authentication requirements, leaving some gaps.
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 extremely concise: two sentences that front-load the purpose and key constraints. Every sentence provides critical information without waste.
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 absence of an output schema, the description adequately explains the slim return format and mentions pagination via the 'next' cursor. It could be enhanced by explicitly listing the returned fields or describing pagination response shape, but for 3 parameters it is largely sufficient.
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?
The description adds significant value beyond the schema by providing a concrete example of the query object format and showing how to filter by assignee or contact email. It also clarifies the default and max for per_page and explains the pagination cursor.
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 tool searches Intercom conversations, specifies the return format ('SLIM list with id, state, contact, timestamps') and explicitly contrasts with get_conversation for full content, distinguishing it from siblings.
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 tells when to use get_conversation for full content, implying this tool is for slim results. However, it does not explicitly state when not to use this tool or provide alternatives for other scenarios, but the context is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Send a NEW outbound email to a contact (by email address) as an admin — i.e. START a fresh conversation, not reply to an existing one. Resolves the email to an Intercom contact (creating a lead if none exists), then sends. Returns the new conversation_id. Use reply_conversation instead when responding within an existing conversation.
| Name | Required | Description | Default |
|---|---|---|---|
| Yes | Recipient's email address (required). Resolved to an Intercom contact; a lead is created if none exists. | ||
| subject | Yes | Email subject (required). | |
| body | Yes | Email body (required). Supports HTML. | |
| admin_id | No | Admin ID to send as (optional, defaults to INTERCOM_ADMIN_ID env var). Determines the sender name/address the recipient sees. | |
| template | No | Email style (optional, defaults to 'personal' = 1:1 personal-email look). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavior. It states that it starts a fresh conversation, resolves email to a contact (creating a lead), and returns the conversation_id. While it does not mention potential failure modes or rate limits, the core behavioral traits are transparent. A score of 4 reflects good disclosure but minor gaps.
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 with two sentences, no wasted words, and front-loads the key distinction (new vs. reply). Every sentence adds value.
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 moderate complexity (5 parameters, no output schema), the description adequately explains the main behavior, return value, and key side effects. It lacks details on error handling but is sufficient for an agent to use the 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 100%, so baseline is 3. The description adds extra context beyond the schema for some parameters, such as explaining that email resolution may create a lead and that admin_id defaults to an env var. This additional value justifies a score of 4.
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 verb 'Send', the resource 'outbound email', and specifies it starts a new conversation, distinguishing it from the sibling tool 'reply_conversation'. This meets the criteria for a specific verb+resource with sibling differentiation.
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 tells when to use this tool versus the alternative 'reply_conversation', and explains that it resolves the email to an Intercom contact, creating a lead if needed. This provides clear usage context and exclusion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing Intercom Help Center article. Supports partial updates and multilingual content.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Article ID (required) | |
| title | No | Updated article title (optional) | |
| body | No | Updated article content in HTML format (optional) | |
| description | No | Updated article description (optional) | |
| state | No | Updated article state (optional) | |
| author_id | No | Updated author ID (optional). Use list_admins to find valid IDs by name. | |
| translated_content | No | Updated multilingual content. Only provided fields will be updated. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the burden. It adds value by mentioning 'partial updates' and 'multilingual content', but does not disclose aspects like destructive effects, auth requirements, or return format. The behavioral disclosure is adequate but incomplete.
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 a single sentence that is front-loaded with action and resource. It is concise and efficient, though it could be slightly more structured or include a brief usage note.
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 has 7 parameters (including nested translated_content) and no output schema, the description is relatively sparse. It covers the basics but leaves many details to the schema. It is adequate for a familiar tool but incomplete for full autonomous use.
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 100%, so the baseline is 3. The description's mention of 'partial updates' and 'multilingual content' adds context but does not significantly enhance parameter understanding beyond what the schema already provides.
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 action ('Update'), the resource ('existing Intercom Help Center article'), and adds specificity with 'supports partial updates and multilingual content', distinguishing it from siblings like create_article or delete_article.
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 tool is for updating existing articles but does not explicitly state when to use it vs alternatives like create_article or delete_article. The context is clear, but no exclusions or alternative guidance are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing Intercom Help Center collection. Supports updating name, description, and multilingual translations.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Collection ID (required) | |
| name | No | Updated collection name (optional, updates default language) | |
| description | No | Updated collection description (optional, updates default language) | |
| parent_id | No | Updated parent collection ID (optional, null for top-level) | |
| translated_content | No | Updated multilingual content. Key is locale code (e.g., "zh-TW"), value is translation object |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden for behavioral traits. It only lists updatable fields but does not disclose update behavior (e.g., partial vs full replace, idempotency, error conditions, or whether changes are immediately visible). This lack of transparency is a significant gap for a mutation 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 a single, focused sentence with no unnecessary words. It efficiently communicates the core 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 tool has 5 parameters, a nested object, and no output schema or annotations, the description is too brief. It omits details about return values, side effects, or validation behavior, leaving the agent underinformed for correct usage.
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 100%, and the schema already provides detailed parameter descriptions. The description adds minimal value beyond the schema, only noting that name and description update the default language. Baseline of 3 is appropriate.
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 action ('Update an existing... collection') and specifies the resources (name, description, multilingual translations). It effectively distinguishes from sibling tools like create_collection or delete_collection by indicating it modifies an existing entity.
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 does not explicitly specify when to use this tool over alternatives or when not to use it. While the context of 'update' implies existing collections, there is no guidance on prerequisites or exclusions, such as when to use update_article instead.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update the state of an Intercom ticket.
| Name | Required | Description | Default |
|---|---|---|---|
| ticket_id | Yes | The ticket ID to update (required) | |
| state | Yes | The new ticket state (required) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without any annotations, the description carries the full burden of disclosing behavioral traits. It merely states 'update' but does not reveal side effects, permissions, idempotency, or error conditions, leaving the agent with insufficient context for mutation.
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 a single, concise sentence that gets straight to the point with no extraneous words, making it efficiently scannable.
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 update tool with no output schema, the missing return value description and lack of behavioral detail (e.g., success/failure indications) make it incomplete. The agent has to infer too much from the schema alone.
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 100%, so the schema already documents both parameters thoroughly. The description adds no additional meaning beyond the schema, meeting the baseline expected value.
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 action ('Update') and the resource ('state of an Intercom ticket'), making the purpose unambiguous. However, it does not differentiate from potential siblings that might also modify tickets.
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?
No guidance is provided on when to use this tool versus others, nor are there any conditions or prerequisites mentioned. The description is too brief to aid in decision-making.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Each tool targets a distinct action and resource combination. Conversation tools (add note, close, reply, get, search) are clearly differentiated from article and collection CRUD, tickets, admins, and email. No ambiguity.
All tools follow a consistent verb_noun pattern in snake_case (e.g., create_article, list_collections, search_conversations). No mixed conventions or irregular names.
19 tools cover articles, collections, conversations, tickets, admins, and outbound email. While slightly high for a single server, the scope justifies the count, and each tool has a clear role.
Articles and collections have full CRUD, but conversations lack update and delete operations, tickets only have state update, and there is no search for collections. Notable gaps exist in the conversation and ticket lifecycle.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Help center for SaaS teams. 14-tool MCP server for articles, collections, and search.
Remote MCP server for supportsheep: run AI interviews and manage support content for your blog.
Create, edit, preview, publish, and manage web pages from MCP-capable AI clients.
Read-only MCP server for Flamel.ai's public content: company overview, blog, case studies, FAQs.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/kaosensei/intercom-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
