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., "@SeaTalk MCP Server show profile of employee EMP123"
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.
This server provides Model Context Protocol (MCP) tools to interact with the SeaTalk API. It enables AI assistants to send and retrieve messages, access employee information, and interact with group chats via SeaTalk.
Install dependencies:
npm installCreate a .env file with your SeaTalk credentials:
SEATALK_APP_ID=your_app_id
SEATALK_APP_SECRET=your_app_secretBuild the server:
npm run buildStart the server:
npm startRelated MCP server: Feishu/Lark OpenAPI MCP
You can install this package via npm:
# Install globally
npm install -g seatalk-mcp-server
# Or use directly with npx (auto-install without prompts)
npx -y seatalk-mcp-serverThis package can be used directly via npx without installing it globally. The -y flag automatically accepts installation prompts for seamless automation.
Configure the SeaTalk server in your MCP settings by providing the required environment variables:
{
"mcpServers": {
"seatalk-mcp-server": {
"command": "npx",
"args": ["-y", "seatalk-mcp-server"],
"env": {
"SEATALK_APP_ID": "your_app_id_here",
"SEATALK_APP_SECRET": "your_app_secret_here"
},
"disabled": false
}
}
}Required environment variables:
SEATALK_APP_ID: Your SeaTalk application ID
SEATALK_APP_SECRET: Your SeaTalk application secret
After configuring the server in your MCP settings, SeaTalk tools will be available for use in Cursor or other MCP-compatible environments.
If you prefer to clone the repository and build the server yourself, follow these steps:
Node.js 16.0.0 or higher
npm or yarn package manager
Clone the repository:
git clone https://github.com/muhammad-iqbal/seatalk-mcp-server.git
cd seatalk-mcp-server/seatalk-serverInstall dependencies:
npm installCreate environment configuration:
# Create .env file with your credentials
echo "SEATALK_APP_ID=your_app_id_here" > .env
echo "SEATALK_APP_SECRET=your_app_secret_here" >> .envBuild the project:
npm run buildRun the server directly:
node build/index.jsWhen using the locally built version, configure your MCP settings to point to the built file:
{
"mcpServers": {
"seatalk-mcp-server": {
"command": "node",
"args": ["/path/to/your/seatalk-mcp-server/seatalk-server/build/index.js"],
"env": {
"SEATALK_APP_ID": "your_app_id_here",
"SEATALK_APP_SECRET": "your_app_secret_here"
},
"disabled": false
}
}
}Note: Replace /path/to/your/seatalk-mcp-server/seatalk-server/build/index.js with the actual absolute path to your built index.js file.
For active development, you can use the watch mode:
# Build and watch for changes
npm run watch
# In another terminal, run the server
node build/index.jsThis approach is useful for:
Contributing to the project
Customizing the server for specific needs
Testing unreleased features
Running in environments where npx is not available
get_employee_profileGet an employee's profile by employee code.
Example:
{
"employee_code": "EMP123"
}Response:
{
"code": 0,
"employee": {
"employee_code": "EMP123",
"name": "John Doe",
"company_email": "john.doe@company.com",
"department": {
"department_code": "DEP001",
"department_name": "Engineering"
}
}
}get_employee_code_with_emailGet employee codes by email addresses.
Example:
{
"emails": ["john.doe@company.com", "jane.smith@company.com"]
}Response:
{
"code": 0,
"results": [
{
"email": "john.doe@company.com",
"employee_code": "EMP123",
"exists": true
},
{
"email": "jane.smith@company.com",
"employee_code": "EMP456",
"exists": true
}
]
}check_employee_existenceVerify whether employees exist in the organization via SeaTalk ID.
Example:
{
"id": "ST12345"
}Response:
{
"code": 0,
"exists": true
}get_user_language_preferenceGet a user's language preference.
Example:
{
"employee_code": "EMP123"
}Response:
{
"code": 0,
"language": "en"
}get_joined_group_chat_listObtain group chats the bot joined.
Example:
{
"page_size": 10
}Response:
{
"code": 0,
"groups": [
{
"group_id": "group123",
"group_name": "Engineering Team",
"member_count": 15
},
{
"group_id": "group456",
"group_name": "Project Alpha",
"member_count": 8
}
],
"has_more": true,
"next_cursor": "cursor_token_for_next_page"
}get_group_infoGet information about a group chat, including member list.
Example:
{
"group_id": "group456"
}Response:
{
"code": 0,
"group_info": {
"group_id": "group456",
"group_name": "Project Alpha",
"description": "Group for Project Alpha discussion",
"created_at": 1615000000,
"owner": {
"employee_code": "EMP123",
"name": "John Doe"
}
},
"members": [
{
"employee_code": "EMP123",
"name": "John Doe",
"is_admin": true
},
{
"employee_code": "EMP456",
"name": "Jane Smith",
"is_admin": false
}
],
"has_more": false
}get_thread_by_thread_idRetrieve all messages within a thread of a group chat.
Example:
{
"group_id": "group456",
"thread_id": "thread123",
"page_size": 20
}Response:
{
"code": 0,
"messages": [
{
"message_id": "msg001",
"sender": {
"employee_code": "EMP123",
"name": "John Doe"
},
"tag": "text",
"text": {
"plain_text": "Hello team!"
},
"created_at": 1615456789
}
],
"has_more": false
}get_message_by_message_idRetrieve a message by its message ID.
Example:
{
"message_id": "msg001"
}Response:
{
"code": 0,
"message_id": "msg001",
"sender": {
"employee_code": "EMP123",
"name": "John Doe"
},
"tag": "text",
"text": {
"plain_text": "Hello team!"
},
"created_at": 1615456789
}get_chat_historyObtain the group chat history (messages sent within 7 days).
Example:
{
"group_id": "group456",
"page_size": 50
}Response:
{
"code": 0,
"messages": [
{
"message_id": "msg001",
"sender": {
"employee_code": "EMP123",
"name": "John Doe"
},
"tag": "text",
"text": {
"plain_text": "Hello team!"
},
"created_at": 1615456789
},
{
"message_id": "msg002",
"sender": {
"employee_code": "EMP456",
"name": "Jane Smith"
},
"tag": "image",
"image": {
"content": "https://example.com/image.jpg"
},
"created_at": 1615456890
}
],
"has_more": true,
"next_cursor": "next_page_cursor"
}send_message_to_group_chatSend a message to a group chat which the bot has been added to.
Example (Text Message):
{
"group_id": "group456",
"message": {
"tag": "text",
"text": {
"content": "Hello everyone! This is an announcement.",
"format": 1
}
}
}Example (Image Message):
{
"group_id": "group456",
"message": {
"tag": "image",
"image": {
"content": "base64_encoded_image_data"
}
}
}Response:
{
"code": 0,
"message_id": "msg123"
}send_message_to_bot_userSend a message to a user via the bot.
Example (Text Message):
{
"employee_code": "EMP123",
"message": {
"tag": "text",
"text": {
"content": "Hi there! Just checking in.",
"format": 1
}
}
}Example (Interactive Message):
{
"employee_code": "EMP123",
"message": {
"tag": "interactive_message",
"interactive_message": {
"elements": [
{
"tag": "header",
"text": {
"content": "Task Assignment",
"tag": "plain_text"
}
},
{
"tag": "section",
"text": {
"content": "You have been assigned a new task.",
"tag": "plain_text"
}
},
{
"tag": "action",
"elements": [
{
"tag": "button",
"text": {
"content": "Accept",
"tag": "plain_text"
},
"value": "accept_task"
}
]
}
]
}
}
}Response:
{
"code": 0,
"message_id": "msg125"
}All API responses include a code field that indicates the status of the request:
Code | Description |
0 | Success |
2 | Server error |
5 | Resource not found |
8 | Server error |
100 | App access token is expired or invalid |
101 | API is rejected due to rate limit control |
102 | Request body contains invalid input |
103 | App permission denied |
104 | Bot capability is not turned on |
105 | App is not online |
Code | Description |
1000 | App Secret is invalid |
2000 | Single Sign-On Token is expired or invalid |
2001 | User is not an employee of the current company |
2002 | Token belongs to another app |
2003 | Cursor invalid |
2004 | Cursor expired |
Code | Description |
3000 | User not found with the current email |
3001 | User not found with the current code |
3002 | User is not a subscriber of the bot |
3003 | User is not signed in to SeaTalk |
3004 | Invalid custom field name |
Code | Description |
4000 | Message type is invalid |
4001 | Message exceeds the maximum length |
4002 | Message sending failed |
4003 | Message cannot be empty |
4004 | Fail to fetch the quoted message due to SeaTalk's internal error |
4005 | The quoted message cannot be found |
4009 | Message cannot be found via the message id provided |
4010 | The thread cannot be found |
4011 | Mention everyone (@all) is not allowed in thread replies |
4012 | No permission to update this message |
Code | Description |
5000 | appID mismatch |
5001 | linkID expired |
5002 | App not released yet |
5003 | App link amount has reached the upper limit |
Code | Description |
7000 | Group chat not found with the current code |
7001 | Bot is not a member of the group chat |
MIT
Verify whether employees exist in the organization via SeaTalk ID
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | One or more SeaTalk ID(s) |
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 only states the tool verifies existence, but does not indicate the return format (e.g., boolean), error handling, or side effects. For a verification tool, this is insufficient.
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 10-word sentence, front-loaded with the core action. Every word is necessary, no redundancy.
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 (1 parameter, no output schema, no annotations), the description is minimally adequate. However, it lacks details on output, error cases, or behavior for multiple IDs, which would improve completeness.
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% (the parameter 'id' is described as 'One or more SeaTalk ID(s)'). The description repeats 'via SeaTalk ID' but does not add additional meaning such as format or multiple ID handling. 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 the verb 'Verify' and the resource 'employees exist in the organization via SeaTalk ID'. It distinguishes from sibling tools like get_employee_profile or send_message_to_bot_user, 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?
The description implies usage for existence checks, but does not explicitly state when to use this tool versus alternatives (e.g., get_employee_profile could also check existence). No when-not-to-use or prerequisite information is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Obtain the group chat history (messages sent within 7 days)
| Name | Required | Description | Default |
|---|---|---|---|
| cursor | No | Cursor for pagination | |
| group_id | Yes | The ID of the group chat | |
| page_size | No | Number of messages included in one response (1-100) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, description must disclose behavior. It mentions the 7-day window but does not indicate whether the tool is read-only, how pagination works, or if results are sorted. Insufficient for a list 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?
Single sentence, no extraneous words. Concise but could front-load more critical details without being verbose.
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?
No output schema and no description of return format. For a paginated list tool with cursor and page_size, missing explanation of pagination behavior and default order. Sibling tools mentioned but no differentiation.
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 covers 100% of parameters with descriptions. Description adds no extra meaning beyond schema, so baseline 3 applies. No compensation needed.
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 verb 'Obtain', resource 'group chat history', and a specific constraint 'messages sent within 7 days'. Differentiates from siblings like get_message_by_message_id and get_thread_by_thread_id by focusing on a list of recent messages.
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 information on when to use this tool versus alternatives such as get_message_by_message_id for a single message or get_thread_by_thread_id for a thread. Missing context about prerequisites or comparison to siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get an employee's code by email address
| Name | Required | Description | Default |
|---|---|---|---|
| emails | Yes | List of employee email addresses (between 1 and 500 items) |
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 does not disclose whether the tool is read-only, what happens if an email is not found, or any other behavioral traits. Merely stating 'Get' implies a read operation, but this is not explicit.
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 efficiently conveys the tool's purpose without any redundant or irrelevant 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?
For a simple tool with one parameter and no output schema, the description is adequate but lacks details on the return format or potential errors. It does not fully prepare the agent for all scenarios.
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 parameter 'emails' is well-described in the schema. The description adds no additional meaning beyond the schema, meeting the baseline 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 tool name and description clearly indicate it retrieves an employee code using email addresses. It is distinct from siblings like get_employee_profile or check_employee_existence, which serve 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 is provided on when to use this tool versus alternatives such as get_employee_profile or check_employee_existence. The description only states what it does, without usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get an employee's profile by employee ID
| Name | Required | Description | Default |
|---|---|---|---|
| employee_code | Yes | The employee code of the employee |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility for behavioral disclosure. It only states the basic action ('Get an employee's profile') without detailing return format, permissions, or rate 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?
The description is a single, front-loaded sentence with no unnecessary words. It earns its place by being succinct and clear.
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 low complexity (1 param, no output schema), the description is minimally adequate. However, it could be improved by hinting at the type of data returned or any preconditions, which would aid an agent's decision-making.
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% (parameter 'employee_code' already described). The description adds no extra meaning beyond the schema, aligning with the baseline score for high coverage.
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 'Get an employee's profile by employee ID', specifying the verb (Get), resource (employee's profile), and the key parameter (employee ID). It effectively distinguishes from sibling tools like 'check_employee_existence' and 'get_employee_code_with_email'.
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. With sibling tools performing similar lookups (e.g., check_employee_existence), explicit usage context is missing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get information about a group chat, including member list
| Name | Required | Description | Default |
|---|---|---|---|
| cursor | No | Pagination cursor for members | |
| group_id | Yes | The ID of the group chat | |
| page_size | No | Number of members per page (1-100) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It implies a read operation but does not confirm read-only behavior, mention pagination implications, or any limitations. The description lacks depth 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 with no redundant information. Every word is useful.
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?
No output schema is present, and the description does not explain what fields are returned besides 'member list'. Pagination behavior is implied by parameters but not described. The description is insufficient for a tool with 3 parameters and no output schema.
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 parameter descriptions for group_id, cursor, and page_size. The description adds no extra meaning beyond the schema, so 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 it retrieves group chat information including member list. It uses a clear verb and resource, but does not differentiate from sibling tools like get_joined_group_chat_list (which lists groups) or get_chat_history (messages).
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. The sibling list exists but the description provides no context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Obtain group chats the bot joined
| Name | Required | Description | Default |
|---|---|---|---|
| cursor | No | Cursor for pagination | |
| page_size | No | Number of items included in one response (1-100) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description should disclose behavioral traits. It doesn't mention that the tool is read-only, that results are paginated (despite having 'cursor' and 'page_size' parameters), or any authentication 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?
The description is a single sentence and concise, but it lacks necessary information to be truly helpful. It could be more informative without being longer.
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 is too minimal for a tool with pagination. It doesn't explain return format, pagination behavior, or error conditions. Sibling tools are not differentiated.
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% (both parameters described in schema). The description adds no additional meaning beyond the schema, so 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 'Obtain group chats the bot joined' clearly states the verb 'obtain' and the resource 'group chats the bot joined'. It distinguishes from siblings like 'get_group_info' (specific group) and 'get_chat_history' (messages).
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 explain when to use this over 'get_group_info' or other getter tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve a message by its message ID within a group chat thread
| Name | Required | Description | Default |
|---|---|---|---|
| message_id | Yes | The ID of the target message, which can be obtained via the event "New Mentioned Message From Group Chat" |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It states 'Retrieve a message' which indicates a read operation with no side effects, but does not disclose error handling (e.g., if ID is invalid) or performance characteristics. For a simple retrieval, this is minimally adequate.
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 directly states the purpose. No extraneous words, front-loaded with the action and target.
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 is simple with one parameter and no output schema. The description provides the basic purpose but lacks details on return format or behavior when message is missing. Given the low complexity, it is somewhat complete but could be improved.
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 description for message_id. The tool description adds no additional meaning beyond the schema. Baseline 3 is appropriate as the schema already provides the needed semantics.
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 'Retrieve' and the resource 'a message by its message ID within a group chat thread', making the tool's purpose unambiguous. It distinguishes from sibling tools like get_chat_history (list messages) and get_thread_by_thread_id (retrieve thread).
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 a specific message ID is known, especially from the 'New Mentioned Message From Group Chat' event in the parameter description. However, it does not explicitly state when not to use or compare to alternatives like get_chat_history.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve all messages within a thread of a group chat
| Name | Required | Description | Default |
|---|---|---|---|
| cursor | No | Cursor for pagination | |
| group_id | Yes | The ID of the group chat | |
| page_size | No | Number of messages included in one response (1-100) | |
| thread_id | Yes | The ID of the thread |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It correctly indicates a read operation ('Retrieve'), but does not mention pagination behavior (though cursor and page_size parameters exist), ordering, or any constraints. The description is minimal for a tool with multiple parameters.
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, which is concise and front-loaded. It avoids fluff, but is perhaps too brief given the tool's complexity. Every word is relevant, but could be slightly expanded without losing conciseness.
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 4 parameters, no output schema, and no annotations, the description is incomplete. It does not explain pagination, return format, or prerequisites. Sibling tools provide some context, but the description itself lacks completeness for an agent to use the tool reliably.
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 baseline is 3. The description does not add any additional meaning beyond the schema's parameter descriptions. It does not clarify parameter relationships or usage constraints, meeting but not exceeding the baseline.
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 'Retrieve' and the resource 'all messages within a thread of a group chat'. It distinguishes from sibling tools like get_chat_history (which likely gets full chat history) and get_message_by_message_id (single message). However, it could be more explicit about the scope (all messages in a thread) and does not differentiate from siblings in the description itself.
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?
There is no explicit guidance on when to use this tool versus alternatives. It implies usage for retrieving thread messages but does not mention when not to use it or provide comparisons to sibling tools like get_chat_history. The context signals indicate sibling tools exist, but the description lacks usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a user's language preference
| Name | Required | Description | Default |
|---|---|---|---|
| employee_code | Yes | The employee code of the user |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description only states the tool's purpose. It does not disclose behavioral traits such as idempotency, error handling (e.g., if employee_code is invalid), or permission 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?
The description is a single sentence of five words, with zero wasted content. It is appropriately front-loaded and concise.
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 (1 param, no output schema), the description is too minimal. It lacks return value information and behavioral context that an AI agent would need to handle errors or interpret results.
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% (employee_code described), but the description adds no additional meaning beyond the schema. Baseline of 3 is appropriate as the schema already documents the 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?
The description 'Get a user's language preference' clearly indicates the verb (get) and resource (user's language preference), but does not differentiate from sibling tools like get_employee_profile which might also return language preference.
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, no prerequisites, and no context about typical use cases or limitations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Send a message to a user via the bot
| Name | Required | Description | Default |
|---|---|---|---|
| message | Yes | ||
| employee_code | Yes | The employee code of the recipient. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden for behavioral disclosure. It fails to mention error handling (e.g., if recipient not found), size limits (though in schema), rate limits, or any side effects. The one-sentence description is insufficient.
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 (one sentence) but lacks essential details. It is not verbose, but conciseness should not sacrifice completeness. A balanced description would be more effective.
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 annotations, output schema, and the complexity of nested objects, the description is inadequate. It does not explain return values, error states, or how to use different message types, leaving the agent without sufficient context.
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 contains detailed descriptions for most parameters (e.g., file size limits, message types). The description adds no additional meaning, so a baseline score of 3 is appropriate given the schema coverage.
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 'Send a message to a user via the bot' clearly indicates the action (send), resource (message to a user), and agent (bot). It distinguishes from the sibling 'send_message_to_group_chat' by implying individual user, though it does not explicitly state the difference.
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 alternatives like 'send_message_to_group_chat' or prerequisites such as verifying the employee exists. The description lacks context for proper selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Send a message to a group chat which the bot has been added to
| Name | Required | Description | Default |
|---|---|---|---|
| message | Yes | ||
| group_id | Yes | The ID of the group chat | |
| thread_id | No | The ID of the thread to send the message to | |
| quoted_message_id | No | The ID of the message to quote |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description bears full responsibility for disclosing behavioral traits. It only states the basic action without mentioning side effects, permission requirements, rate limits, or what happens if the bot is not in the group. The tool creates a message, but the description does not confirm whether it returns a message ID or confirms delivery.
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, which is concise but arguably too minimal. It front-loads the core action but omits details that could be included without excessive wordiness. A slightly expanded description could improve clarity without sacrificing conciseness.
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 complexity (nested objects, optional parameters, no output schema), the description is insufficient. It does not address what the tool returns, how to construct the message object, or any constraints (e.g., file size limits). The presence of 10 sibling tools suggests a richer environment, and this description lacks the depth needed for safe 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?
Although the input schema covers most parameters (75% description coverage), the message property itself lacks a description. The tool description adds no new meaning beyond 'send a message', failing to explain the structure of the message object or the meaning of parameters like thread_id and quoted_message_id. It does not compensate for the missing schema description of the message field.
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 ('Send a message') and the target ('group chat which the bot has been added to'). It implicitly distinguishes from the sibling 'send_message_to_bot_user' by specifying the recipient type. However, it does not explicitly contrast itself with that tool or other chat tools.
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 alternatives, what prerequisites are needed (e.g., bot must be added to the group), or any scenarios where this tool would be inappropriate. The description lacks any usage context or exclusion criteria.
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.
v0.0.5check_employee_existenceget_chat_historyget_employee_code_with_emailget_employee_profileget_group_infoget_joined_group_chat_listget_message_by_message_idget_thread_by_thread_idget_user_language_preferencesend_message_to_bot_usersend_message_to_group_chatScored across 11 tools
Each tool targets a distinct aspect of the SeaTalk domain: employee verification, profile retrieval, various chat operations, and language preference. No two tools have overlapping purposes.
All tool names follow a consistent verb_noun pattern (e.g., check_employee_existence, get_chat_history, send_message_to_group_chat), making them predictable and easy to navigate.
11 tools cover the core functionalities of an employee and group chat server without being excessive or insufficient. Each tool serves a clear role.
The tool surface covers essential operations like employee lookup and chat retrieval/messaging, but lacks update/delete capabilities for messages or group management, which are minor gaps.
Connect AI assistants to Stellary projects, boards, documents, and governed agent workflows.
Give AI agents secure access to RevDesk calling, SMS, phone numbers, caller IDs, and usage.
Give your AI agents the tools to build, manage, and run automation workflows.
Give your AI agents trusted access to the full Postman platform.
