The AstrBot MCP server provides comprehensive programmatic control and automation for AstrBot through MCP tools, enabling AI agents to manage, configure, and interact with AstrBot instances.
Core Capabilities:
Control & Monitoring
Restart the AstrBot Core service and wait for availability
Retrieve real-time or historical logs with optional SSE streaming for live monitoring
List all configured message platforms
Messaging Operations
Send rich message chains (text, images, files, videos, voice, replies/quotes) via Web Chat API or directly to platform targets, bypassing the LLM
Retrieve recent conversation history for specific platform sessions (groups/users)
Configuration Management
List, inspect, and search AstrBot configuration files using flexible path notation (dot notation, JSON Pointer, or segment lists)
Apply batch edits (set, add_key, append) with auto-save and hot reload
Drill down into JSON config nodes with optional secret redaction for security
Plugin Ecosystem
Browse the plugin market with search and sorting by update time
Install plugins via URL or local zip path with proxy support for GitHub access
Configure plugins using the same config operation system
MCP Panel Management
Manage MCP server configurations through panel APIs (list, add, update, delete, test)
Key Features: Automatic file upload for local media, proxy handling to avoid request interception, and flexible configuration path handling.
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., "@AstrBot MCP show me the latest AstrBot logs from the last 5 minutes"
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.
# AstrBot MCP (Node/TypeScript)
MCP server for operating AstrBot through:
AstrBot REST Gateway (astrbot_plugin_mcp_tools) at http://127.0.0.1:6324
This project is a full rewrite in Node + TypeScript.
npm install
npm run buildRelated MCP server: System Monitor MCP Server
node dist/src/index.jsor in development:
npm run dev{
"mcpServers": {
"astrbot-mcp": {
"command": "node",
"args": ["D:/绋嬪簭/astrbotmcp/dist/src/index.js"],
"env": {
"ASTRBOT_GATEWAY_URL": "http://127.0.0.1:6324",
"ASTRBOT_GATEWAY_TOKEN": "iaushdqwuikdwq78ui"
}
}
}
}Required:
ASTRBOT_GATEWAY_TOKEN
Optional:
ASTRBOT_GATEWAY_URL (default: http://127.0.0.1:6324)
ASTRBOT_GATEWAY_TIMEOUT (default: 30000, milliseconds)
ASTRBOT_CAPABILITY_MODE (search | readonly | minimize | full, default: full)
ASTRBOT_ENABLE_SEARCH_TOOLS (false by default)
ASTRBOT_LOG_VIEW (compact by default, or raw)
ASTRBOT_ENABLE_LOG_NOISE_FILTERING (true by default)
ASTRBOT_GITHUB_ACCELERATION (optional GitHub acceleration base URL override for plugin repo install/update; use off to disable MCP auto acceleration)
system: status, compact logs, logs by id, restart
platforms: list, stats, details
providers: list, current, details
configs: inspect core/plugin, search, patch core/plugin
plugins: list/details/config read+replace/install/set-enabled/reload/update/uninstall
messages: trigger replies, recent sessions, history
astrbot_tools: list/details/invoke/task/stream
mcp_servers: list/register/update/uninstall/test
personas: list/details/upsert/delete
skills: list/install/toggle/delete
subagents: list/config inspect/config update
cron: list/upsert/delete
discovery: search_tools (only when ASTRBOT_ENABLE_SEARCH_TOOLS=true)
capabilityMode=full by default (as requested)
search_tools is disabled by default
logs return compact/noise-filtered output by default
restart and logs use the gateway only; no separate dashboard auth is required
npm run check - type check
npm run build - build to dist/
npm run dev - run directly from TypeScript
trigger_message_reply: injects an inbound message through /events/injections/message, optionally overrides the target LLM provider/model/streaming flags, waits for the event to settle, and by default returns only the bot reply text. Internal metadata is hidden unless include_debug=true.
trigger_message_reply: session_id can be caller-created for tests. Reuse the same id to continue one synthetic conversation; use a fresh id to start an isolated test session. For GroupMessage, session_id is usually the real group id.
trigger_message_reply accepts include_logs=false when you want a low-context response but still keep the send-and-wait behavior.
get_message_history: for webchat, use conversation_id or target_id; do not pass the sender id as user_id. conversation_id may also be a synthetic id you created earlier during injection tests.
list_astrbot_tools: compact list of AstrBot internal tools. This is the clearest discovery entry for LLMs.
list_internal_tools: same compact list, kept for backward compatibility.
get_internal_tool_details: compact tool metadata by default, with full parameter schema controlled by include_parameters.
invoke_internal_tool: compact invoke result by default. It returns the tool parameter schema only on the first call for the same tool within the current MCP process, then hides it on later calls to reduce context use.
invoke_internal_tool: now defaults to wait_for_completion=true. If AstrBot returns a background task_id, MCP will keep polling /tools/tasks/{task_id} until the task is terminal or wait_timeout_seconds is reached.
invoke_internal_tool: when a tool only returns a background acceptance message, MCP now puts that text into accepted_reply instead of pretending it is the final reply.
invoke_internal_tool: include_logs=true appends simplified task logs to the JSON result; default is false to keep the response short.
invoke_internal_tool: include_image_content=true makes MCP return completed image attachments as real MCP image content blocks in addition to compact JSON metadata.
invoke_internal_tool: use show_parameters=true to force showing the tool parameter schema, show_parameters=false to hide it, show_arguments=true to echo the actual call arguments, and show_debug=true to include debug payloads.
get_internal_tool_task: compact query for one internal tool task by task_id.
stream_internal_tool_task: collects compact SSE task events from /tools/tasks/{task_id}/stream and returns the latest task snapshot plus streamed events.
list_plugins: compact plugin list for discovery only. It no longer returns full handlers/config noise.
get_plugin_details: compact metadata plus command list for one plugin. Config is intentionally separated.
get_plugin_config_file: fetch the full editable plugin config object. This is the main read step before changing a plugin config.
replace_plugin_config_file: replace the full plugin config object and auto-reload the plugin.
Normal plugin config workflow: get_plugin_details -> get_plugin_config_file -> edit the returned config object -> replace_plugin_config_file.
patch_plugin_config: only for small path-level edits. Prefer the full read-edit-save flow above for normal configuration work.
install_plugin / update_plugin: for GitHub repos, MCP now auto-detects a reachable GitHub acceleration prefix and uses it by default.
install_plugin / update_plugin: prefer github_acceleration; proxy is kept only as a deprecated alias for backward compatibility.
Recommended flow: install_plugin -> get_plugin_details -> get_plugin_config_file -> replace_plugin_config_file -> uninstall_plugin when needed.
Apply multiple edits to an AstrBot config, then save + hot reload.
Supported ops (batch in a single tool call):
{"op":"set","path":,"value":}
{"op":"add_key","path":,"key":,"value":}
{"op":"append","path":,"value":}
path accepts dot path, JSON Pointer, or segment list.
| Name | Required | Description | Default |
|---|---|---|---|
| conf_id | Yes | ||
| ops | Yes | ||
| create_missing | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions 'save + hot reload' which implies mutation and side effects, but does not address critical aspects like permissions needed, error handling, or whether changes are reversible, leaving significant gaps 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 efficiently structured with a clear purpose upfront, followed by specific details on operations and path syntax. Every sentence adds value without redundancy, 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?
For a mutation tool with no annotations, 0% schema coverage, and an output schema (which reduces need to explain returns), the description covers core operations and syntax but lacks completeness in addressing behavioral risks, parameter details for 'conf_id' and 'create_missing', and integration context with siblings.
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?
Given 0% schema description coverage, the description compensates well by detailing the structure and examples of the 'ops' parameter (e.g., set, add_key, append operations with path/value formats) and mentions 'path' syntax, adding substantial meaning beyond the bare schema. However, it does not explain 'conf_id' or 'create_missing' parameters.
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 specific action ('apply multiple edits', 'save + hot reload') and resource ('AstrBot config'), distinguishing it from sibling tools like inspect_astrbot_config or list_astrbot_config_files by emphasizing batch editing and reloading functionality.
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 ('batch in a single tool call') and implies usage for multiple edits, but does not explicitly state when not to use it or name specific alternatives among siblings like inspect_astrbot_config for read-only operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
查看 AstrBot 插件市场（支持搜索与按时间排序）。
用法：
mode="latest": 按 updated_at 倒序，返回第 start ~ start+count-1 条（start 从 1 开始）
mode="search": 按 query 搜索（名称/简介/标签/作者/仓库），再按 updated_at 倒序
返回字段：
total_plugins: 插件市场总数（未过滤）
matched_plugins: 搜索命中数（mode=search）
plugins: 列表（包含 name/desc/tags/stars/updated_at）
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | latest | |
| query | No | ||
| start | No | ||
| count | No | ||
| custom_registry | No | ||
| force_refresh | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key behaviors: pagination mechanics (start and count parameters), sorting order (updated_at descending), and what fields are returned in the output. However, it doesn't mention potential rate limits, authentication requirements, or error conditions, leaving some behavioral aspects unspecified.
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 well-structured and appropriately sized. It begins with a clear purpose statement, followed by a '用法' (usage) section detailing modes, and a '返回字段' (return fields) section. Each sentence adds specific value—no wasted words—and information is front-loaded with the most critical details about modes and parameters.
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 moderate complexity (6 parameters, no annotations, but with an output schema), the description is complete enough. It covers purpose, usage modes, parameter semantics, and output structure. Since an output schema exists, the description doesn't need to exhaustively explain return values, and it provides sufficient context for an agent to use the tool effectively.
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?
With 0% schema description coverage for 6 parameters, the description compensates excellently. It explains the semantics of 'mode' (latest vs. search), 'query' (search across multiple fields), 'start' (starting index from 1), and 'count' (number of results). While it doesn't cover 'custom_registry' or 'force_refresh', it provides substantial value beyond the bare schema, making parameter purposes clear.
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's purpose: '查看 AstrBot 插件市场（支持搜索与按时间排序）' which translates to 'Browse AstrBot plugin market (supports search and sorting by time)'. It specifies the exact resource (plugin market) and actions (browse with search/sorting), distinguishing it from sibling tools that handle configuration, logs, messages, or restart operations.
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 explicit usage guidelines with two distinct modes: 'mode="latest"' for chronological browsing and 'mode="search"' for query-based filtering. It explains when to use each mode based on the user's intent (browse latest vs. search), including details on how results are ordered and paginated, making it clear when this tool is appropriate versus alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
获取 AstrBot 日志。
如果 wait_seconds <= 0：立即返回 /api/log-history 的数据。
如果 wait_seconds > 0：通过 /api/live-log SSE 持续读取指定秒数内的新日志。
| Name | Required | Description | Default |
|---|---|---|---|
| wait_seconds | No | ||
| max_events | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses key behavioral traits: the tool can operate in two modes (immediate historical retrieval vs. live streaming via SSE), mentions specific API endpoints (/api/log-history, /api/live-log), and describes time-based triggering. It doesn't cover aspects like rate limits, authentication needs, or error handling, but provides substantial operational context.
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 and well-structured: a brief purpose statement followed by two bullet points that clearly explain the conditional behavior. Every sentence earns its place with no wasted words, and it's front-loaded with the core functionality.
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 an output schema (which handles return values), no annotations, and simple parameters, the description is reasonably complete. It explains the dual-mode operation and API endpoints well. The main gap is the undocumented 'max_events' parameter, but overall it provides sufficient context for an agent to understand when and how to use the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains the semantics of 'wait_seconds' thoroughly (immediate vs. streaming behavior based on value). However, it doesn't mention 'max_events' at all, leaving one of the two parameters undocumented. The description adds significant value for one parameter but misses the other.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the tool '获取 AstrBot 日志' (gets AstrBot logs), which is a clear verb+resource combination. However, it doesn't distinguish this from potential sibling tools that might also retrieve logs or differentiate between historical vs. live log retrieval. The purpose is understandable but lacks specificity about what kind of logs or scope.
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 explicit guidance on when to use different behaviors based on the 'wait_seconds' parameter: immediate return for historical logs vs. streaming live logs. This gives clear context for parameter-driven usage. However, it doesn't mention when to use this tool versus sibling tools like 'get_platform_session_messages' or other logging-related tools that might exist.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
获取 AstrBot 中配置的消息平台列表，对应 /api/config/platform/list。
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It states it retrieves a list but doesn't disclose behavioral traits such as permissions needed, rate limits, pagination, or error handling. The API endpoint reference adds minimal context, leaving key operational details unspecified.
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, efficient sentence that directly states the tool's purpose and includes the API endpoint without unnecessary elaboration. It is front-loaded and wastes no words, making it highly concise 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 the tool's simplicity (0 parameters, output schema exists), the description is minimally adequate. However, with no annotations and siblings present, it lacks context on usage scenarios and behavioral details, making it incomplete for optimal agent guidance despite the output schema covering return values.
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 tool has 0 parameters with 100% schema description coverage, so no parameter details are needed. The description doesn't add parameter semantics, but this is acceptable given the absence of parameters, aligning with the baseline for zero parameters.
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 ('获取' meaning 'get') and the resource ('消息平台列表' meaning 'message platform list'), specifying it retrieves configured platforms in AstrBot. It doesn't explicitly differentiate from siblings like 'get_platform_session_messages' or 'send_platform_message', but the purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. It mentions the API endpoint ('/api/config/platform/list'), but doesn't explain scenarios, prerequisites, or exclusions relative to siblings like 'inspect_astrbot_config' or 'list_astrbot_config_files'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a platform target's recent messages from AstrBot logs.
This tool intentionally uses AstrBot's log broker history (/api/log-history) as the source of truth, since some AstrBot builds do not persist platform conversation history under /api/conversation/detail for group/user targets.
Args:
target_id: Platform target ID (e.g. group_id like "1030223077").
platform_id: Optional platform id (e.g. "napcat"). If omitted, use the first enabled platform.
message_type: "GroupMessage" or "FriendMessage" (default: "GroupMessage").
wait_seconds: If > 0, poll and return SSE-like events for up to this many seconds.
max_messages: Max number of history items to return (from the tail).
poll_interval_seconds: Poll interval when wait_seconds > 0.
| Name | Required | Description | Default |
|---|---|---|---|
| target_id | Yes | ||
| platform_id | No | ||
| message_type | No | GroupMessage | |
| wait_seconds | No | ||
| max_messages | No | ||
| poll_interval_seconds | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden and does well by explaining the data source rationale, polling behavior when wait_seconds > 0, and that it returns 'history items from the tail.' It doesn't mention rate limits, authentication needs, or error conditions, but provides substantial behavioral context 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 efficiently structured with a clear purpose statement, usage rationale, and well-organized parameter documentation. Every sentence earns its place, with no redundant information. The parameter explanations are front-loaded with the most critical information first.
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 (6 parameters, polling behavior, multiple data sources) and the presence of an output schema (which handles return values), the description provides excellent context. It covers the why (source rationale), when (build-specific usage), how (polling behavior), and what (parameter semantics) without needing to duplicate output schema information.
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?
With 0% schema description coverage for 6 parameters, the description fully compensates by providing clear semantic explanations for all parameters: target_id examples, platform_id default behavior, message_type options and default, wait_seconds polling behavior, max_messages scope, and poll_interval_seconds usage context. This adds significant value beyond the bare 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 specific action ('Get'), resource ('platform target's recent messages'), and source ('from AstrBot logs'). It explicitly distinguishes this tool from alternatives by explaining it uses '/api/log-history' instead of '/api/conversation/detail' for certain builds, making it distinct from any potential sibling tools that might use different endpoints.
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 explicit guidance on when to use this tool versus alternatives: 'This tool intentionally uses AstrBot's log broker history... since some AstrBot builds do not persist platform conversation history under /api/conversation/detail.' This clearly indicates this is the preferred tool for certain build configurations and implicitly suggests alternatives might exist for other scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Inspect a node in an AstrBot config JSON.
This tool is designed for step-by-step exploration:
Start with path=None to list top-level keys.
Then drill down by providing a deeper path.
| Name | Required | Description | Default |
|---|---|---|---|
| conf_id | Yes | ||
| system_config | Yes | ||
| path | Yes | ||
| include_value | Yes | ||
| max_children | Yes | ||
| redact_secrets | Yes | ||
| max_string_length | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
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 mentions 'step-by-step exploration' and drilling down, which hints at iterative use, but doesn't cover critical aspects like whether this is a read-only operation, potential rate limits, authentication needs, or what happens with invalid inputs. For a tool with 7 parameters and no annotations, this leaves significant gaps in understanding its behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized and front-loaded: the first sentence states the core purpose, followed by a brief explanation of usage. Every sentence adds value without redundancy, making it efficient and well-structured for quick understanding.
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 (7 parameters, no annotations, but with an output schema), the description is incomplete. It covers the purpose and basic usage but lacks details on parameter meanings and behavioral traits. The output schema helps by documenting return values, but the description doesn't fully address the gaps in parameter semantics and transparency, making it only minimally adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, meaning none of the 7 parameters are documented in the schema. The description only mentions 'path' and implies its usage for exploration, but doesn't explain other parameters like conf_id, system_config, include_value, max_children, redact_secrets, or max_string_length. This fails to compensate for the low coverage, leaving most parameters semantically unclear.
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's purpose: 'Inspect a node in an AstrBot config JSON.' It specifies the verb ('inspect') and resource ('node in an AstrBot config JSON'), making it distinct from siblings like list_astrbot_config_files or search_astrbot_config_paths. However, it doesn't explicitly differentiate from all siblings, such as get_astrbot_logs, which might also involve inspection but of logs rather than configs.
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 usage: 'This tool is designed for step-by-step exploration' with examples like starting with path=None and drilling down. This implies when to use it (for exploration) but doesn't explicitly state when not to use it or name alternatives like list_astrbot_config_files for listing files instead of inspecting nodes. The guidance is helpful but lacks explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List AstrBot config files (abconfs), via /api/config/abconfs.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
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 states the action ('List') and API endpoint, but lacks details on permissions, rate limits, pagination, or response format. For a read operation with zero annotation coverage, this is a significant gap in transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the core purpose ('List AstrBot config files (abconfs)') and includes the API endpoint as supplementary detail. There is zero waste, and every word 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 the tool's simplicity (0 parameters, read-only list operation) and the presence of an output schema, the description is minimally adequate. However, it lacks context on behavioral aspects like permissions or pagination, and no annotations compensate. For a tool with siblings, more guidance 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?
The tool has 0 parameters, and schema description coverage is 100%, so no parameter documentation is needed. The description correctly omits parameter details, aligning with the schema. A baseline of 4 is appropriate as it avoids redundancy, though it doesn't add value 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 the verb ('List') and resource ('AstrBot config files (abconfs)'), making the purpose unambiguous. It distinguishes from siblings like 'inspect_astrbot_config' (which inspects rather than lists) and 'search_astrbot_config_paths' (which searches paths rather than listing files). However, it doesn't specify if this lists all files or has implicit filters, preventing a perfect score.
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 like 'search_astrbot_config_paths' or 'inspect_astrbot_config'. It mentions the API endpoint ('/api/config/abconfs'), but this is technical detail rather than usage context. No exclusions, prerequisites, or comparative advice are included.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
重启 AstrBot Core，对应 /api/stat/restart-core。 重启后会等待 AstrBot 重新启动并可用。
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output 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 triggers a restart and waits for AstrBot to become available again, which is useful behavioral context. However, it lacks details on permissions required, whether it's idempotent, potential downtime duration, or error handling (e.g., what happens if restart fails).
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 that directly explain the action and post-action behavior. It's front-loaded with the core purpose. While efficient, it could be slightly more structured by explicitly separating purpose from behavioral notes.
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 (a system restart operation with no annotations), the description is minimally adequate. It explains what the tool does but lacks critical context like permissions, side effects, or error scenarios. The presence of an output schema helps, but the description doesn't leverage it to clarify return values or success criteria.
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 tool has 0 parameters, and schema description coverage is 100%, so no parameter documentation is needed. The description appropriately doesn't discuss parameters, focusing instead on the tool's effect. A baseline of 4 is applied as per rules for 0-param tools.
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 ('重启' meaning restart) and the target resource ('AstrBot Core'), making the purpose understandable. It distinguishes from siblings by focusing on core restart rather than configuration, messaging, or logging operations. However, it doesn't explicitly contrast with potential similar tools like 'apply_astrbot_config_ops' which might also affect system state.
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 doesn't mention prerequisites (e.g., needing admin permissions), when it's appropriate (e.g., after config changes, during troubleshooting), or what side effects might occur (e.g., temporary service interruption). Without such context, an agent might misuse it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search AstrBot config and return only matched key paths (no big values).
Modes:
key only: provide key_query
key + value: provide key_query and value_query (matches leaf values of primitive types)
Returns:
results: [{path, path_pointer, path_dot, type}, ...]
| Name | Required | Description | Default |
|---|---|---|---|
| conf_id | Yes | ||
| system_config | Yes | ||
| key_query | Yes | ||
| value_query | Yes | ||
| case_sensitive | Yes | ||
| max_results | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It mentions the tool returns only matched key paths (no big values) and describes return format, which is helpful. However, it doesn't address important behavioral aspects like whether this is a read-only operation, potential performance impacts, rate limits, authentication needs, or error conditions.
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 efficiently structured with clear sections (purpose, modes, returns). Every sentence earns its place, with no redundant information. The front-loaded purpose statement is followed by necessary details in bullet format.
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 6 parameters with 0% schema coverage and no annotations, the description provides some context but has significant gaps. While it explains the tool's purpose and return format (and an output schema exists), it doesn't adequately cover parameter semantics or behavioral aspects needed for a search tool with multiple configuration options.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for all 6 undocumented parameters. While it explains the purpose of key_query and value_query in the 'Modes' section, it doesn't address the semantics of conf_id, system_config, case_sensitive, or max_results parameters. This leaves significant gaps in 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 tool searches AstrBot config and returns matched key paths without big values, specifying the verb 'search' and resource 'AstrBot config'. It distinguishes from siblings like 'inspect_astrbot_config' by focusing on searching rather than inspecting, but doesn't explicitly differentiate from all siblings like 'list_astrbot_config_files'.
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 implied usage through 'Modes' section, explaining when to use key-only vs. key+value queries. However, it doesn't explicitly state when to use this tool versus alternatives like 'inspect_astrbot_config' or 'list_astrbot_config_files', nor does it mention prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
通过 AstrBot 的 Web Chat API 发送消息链（支持文本、图片、文件等）。
参数：
platform_id: 平台 ID，例如 "webchat" 或配置中的平台 ID。
message_chain: 消息链，由 MessagePart 列表组成。
文本: {"type": "plain", "text": "..."}
回复: {"type": "reply", "message_id": "..."}
图片/文件/语音/视频: {"type": "image"|"file"|"record"|"video", "file_path": "本地路径或URL"} 或 {"type": "...", "url": "http(s) URL"}
message / images / files / videos / records: 可选便捷参数；当未传 message_chain 时，会自动拼成消息链。
session_id: 可选的平台会话 ID；如果为空，会自动为该平台创建新会话。
selected_provider / selected_model: 可选，指定 AstrBot 内部的 provider/model。
enable_streaming: 是否启用流式回复（影响 AstrBot 返回的 SSE 事件类型）。
| Name | Required | Description | Default |
|---|---|---|---|
| platform_id | Yes | ||
| message_chain | No | ||
| message | No | ||
| images | No | ||
| files | No | ||
| videos | No | ||
| records | No | ||
| target_id | No | ||
| message_type | No | GroupMessage | |
| session_id | No | ||
| conversation_id | No | ||
| use_last_session | No | ||
| new_session | No | ||
| reply_to_message_id | No | ||
| reply_to_last_saved_message | No | ||
| reply_to_last_user_message | No | ||
| selected_provider | No | ||
| selected_model | No | ||
| enable_streaming | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It describes the tool's core functionality (sending message chains) and mentions some behavioral aspects: optional parameters that auto-build message chains, automatic session creation if session_id is empty, and that enable_streaming affects SSE event types. However, it doesn't cover important behavioral traits like whether this is a read-only or destructive operation, rate limits, authentication requirements, error conditions, or what the response looks like.
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 well-structured with a clear purpose statement followed by parameter explanations. It's appropriately sized for a complex tool with 19 parameters. Most sentences add value, though some parameter explanations could be more concise. The information is front-loaded with the core purpose first.
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 (19 parameters, no annotations, 0% schema description coverage, but with output schema), the description is moderately complete. It explains the core functionality and many parameters but leaves 8 parameters undocumented. The existence of an output schema means the description doesn't need to explain return values, but for a mutation tool with no annotations and poor schema documentation, more behavioral context would be helpful.
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?
With 0% schema description coverage, the description must compensate for the schema's lack of parameter documentation. The description provides meaningful semantic information for 7 parameters (platform_id, message_chain, message, images, files, videos, records, session_id, selected_provider, selected_model, enable_streaming), explaining what they represent and how they interact. However, it doesn't cover the remaining 8 parameters (target_id, message_type, conversation_id, use_last_session, new_session, reply_to_message_id, reply_to_last_saved_message, reply_to_last_user_message), leaving significant gaps.
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's purpose: '通过 AstrBot 的 Web Chat API 发送消息链（支持文本、图片、文件等）' which translates to 'Send message chains via AstrBot's Web Chat API (supports text, images, files, etc.)'. It specifies the verb 'send', the resource 'message chains', and the mechanism 'AstrBot's Web Chat API'. It also distinguishes from sibling 'send_platform_message_direct' by implying this is the standard API-based method.
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 usage: it's for sending messages via AstrBot's Web Chat API. It mentions alternative parameters ('message / images / files / videos / records') that can be used instead of 'message_chain' for convenience. However, it doesn't explicitly state when to use this tool versus the sibling 'send_platform_message_direct', nor does it mention any prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Directly send a message chain to a platform group/user (bypass LLM).
This calls AstrBot dashboard endpoint: POST /api/platform/send_message
Notes:
This is for sending to a real platform target (group/user), not WebChat.
Media parts:
If file_path is a local path, this tool will upload it to AstrBot first, then send it as an AstrBot-hosted URL.
If file_path/url is an http(s) URL, it will be forwarded as-is.
| Name | Required | Description | Default |
|---|---|---|---|
| platform_id | Yes | ||
| target_id | Yes | ||
| message_chain | No | ||
| message | No | ||
| images | No | ||
| files | No | ||
| videos | No | ||
| records | No | ||
| message_type | No | GroupMessage |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses key behavioral traits: it calls a specific endpoint (POST /api/platform/send_message), handles media uploads for local files, and forwards URLs as-is. However, it doesn't mention authentication requirements, rate limits, error conditions, or what the output contains, which are important 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 appropriately sized and front-loaded with the core purpose in the first sentence. The 'Notes' section efficiently covers key behavioral details. However, the second sentence about the endpoint is somewhat technical and could be integrated more smoothly, and there's minor redundancy in the media parts explanation.
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 complex mutation tool with 9 parameters, 0% schema coverage, no annotations, but an output schema, the description is moderately complete. It covers the purpose, some behavioral traits, and media handling, but lacks parameter explanations, error handling, authentication needs, and doesn't leverage the output schema to describe return values. It's adequate but has significant 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 description coverage is 0%, so the description must compensate for 9 parameters. It only provides semantics for 'file_path' and 'url' in media parts, ignoring 'platform_id', 'target_id', 'message_chain', 'message', 'images', 'files', 'videos', 'records', and 'message_type'. The description adds minimal value beyond what the bare schema provides, failing to explain parameter purposes or relationships.
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's purpose: 'Directly send a message chain to a platform group/user (bypass LLM).' It specifies the verb ('send'), resource ('message chain'), and target ('platform group/user'), but doesn't explicitly differentiate from its sibling 'send_platform_message' (without '_direct'), leaving some ambiguity about what 'bypass LLM' means in practice.
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 some usage context with 'This is for sending to a real platform target (group/user), not WebChat,' which implies when to use it (real platforms) and when not (WebChat). However, it doesn't explain when to choose this tool over its sibling 'send_platform_message' or other messaging alternatives, leaving the 'bypass LLM' distinction unclear for agent decision-making.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.0apply_astrbot_config_opsbrowse_plugin_marketget_astrbot_logsget_message_platformsget_platform_session_messagesinspect_astrbot_configlist_astrbot_config_filesrestart_astrbotsearch_astrbot_config_pathssend_platform_messagesend_platform_message_directScored across 11 tools
Most tools have distinct purposes, such as config management, message handling, and logging. However, send_platform_message and send_platform_message_direct could be confusing as both involve sending messages, though one targets WebChat and the other real platforms. The descriptions help clarify this, but some overlap exists.
Tool names generally follow a consistent snake_case pattern with descriptive verbs and nouns, like apply_astrbot_config_ops and get_astrbot_logs. There are minor deviations, such as browse_plugin_market using 'browse' instead of 'list' or 'get', but overall the naming is predictable and readable.
With 11 tools, the count is well-suited for managing an AstrBot instance, covering config operations, messaging, logging, and system control. Each tool serves a clear function without redundancy, making the set comprehensive yet manageable for the domain.
The toolset provides strong coverage for AstrBot management, including config inspection, editing, messaging, logging, and system restarts. A minor gap is the lack of tools for plugin installation or management beyond browsing the market, but core workflows are well-supported.
Give your AI agents the tools to build, manage, and run automation workflows.
Build and deploy websites, Telegram and Discord bots from chat via the DreamAgent platform.
Agentic CI operations for build inspection, failure diagnosis, and runner troubleshooting.
Operate Linux, macOS and Windows from your LLM. Every action runs through an auditable allowlist.
