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., "@mcp-server-nacos check the health of the user-service"
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.
mcp-server-nacos 专为大语言模型（LLM）与智能体（AI Agent）设计，通过开放协议 Model Context Protocol (MCP) 将 Nacos 3.0 的服务发现、动态配置管理、命名空间隔离及健康探针能力全面工具化与资源化。
借助本服务，Claude Desktop、Cursor、Antigravity 以及私有化部署的多智能体平台能够直接化身为微服务智能运维管家，自主完成配置排查、服务拓扑分析、实例动态上下线与灰度流量治理。
Related MCP server: jewei-mcp-nacos
🎯 Nacos 3.0 深度适配：对齐 Nacos 3.0 Server (8848) 与 Console (8080) 解耦架构，无缝应对公网非对称 NAT 端口映射（如 58848/57206）；
🛠️ 全功能 CRUD 原子工具集 (16 Tools)：覆盖配置发布/回滚/检索、命名空间管理、微服务健康度分析、实例权重与上下线控制；
🛡️ 大模型安全防御守卫：客户端静默归一化命名空间入参、配置发布前置 JSON/YAML 语法强校验、长文本安全截断与按行切片读取；
📦 配置资源化挂载 (MCP Resources)：支持 nacos://config/{tenant}/{group}/{dataId} 资源协议，让 Agent 像读取本地文件一样直接检索动态配置；
💡 开箱即用运维模版 (MCP Prompts)：内置微服务健康全景体检（nacos_service_inspection）与配置版本漂移比对（nacos_config_drift_check）；
🔒 自愈式会话认证 (Self-Healing Auth)：针对开启鉴权的 Nacos 实例提供 Token 提前静默续期与 401 拦截重试机制，长会话零中断；
🐳 独立容器化与 SSE 预留：内置 docker-compose.yml，暴露 3000 端口，开箱支持远程 Agent / Dify 等多智能体平台接入；
⚡ 超轻量极速启动：基于 Node.js 运行时与 tsup 预编译打包，本地 Stdio 进程毫秒级冷启动，内存占用 < 50MB。
针对现代云原生及 Docker 公网 NAT 场景，服务端支持灵活的双端点独立寻址：
+-------------------------------------------------------------------------+
| 网络拓扑映射模型 |
+-------------------------------------------------------------------------+
| |
| [ MCP 客户端 (Claude / Cursor / Dify) ] |
| | (Stdio / Docker / SSE) |
| v |
| [ mcp-server-nacos (Port: 3000) ] |
| | |
| +--- (HTTP OpenAPI 主通道) ---> 8848 [公网 NAT: 58848] |
| | 路径: /nacos/ |
| | |
| +--- (Web Console 辅助通道) --> 8080 [公网 NAT: 57206] |
| | 路径: /next/ |
| | |
| x--- (客户端 gRPC 协议) --------> 9848 [公网 NAT: 59848] |
| (MCP 保持纯净 HTTP 通信，规避 NAT 端口偏移计算失效) |
+-------------------------------------------------------------------------+为防止大模型幻觉与不当参数引发生产事故，本项目在 MCP 客户端边界内置了三重刚性守卫：
命名空间智能静默归一化 (Silent Normalization)：
识别大模型常混淆的 undefined、"public"、"PUBLIC" 输入，并在客户端层统一静默转换为底层协议所需的 ""（空字符串）或配置环境变量的默认空间，确保接口请求 100% 成功。
发布前置语法安全守卫 (Syntax Guardrails)：
在向 Nacos 提交配置变更前，若声明了 type: "json" 或 type: "yaml"，客户端自动在本地执行解析校验。
一旦发现括号缺失、缩进错误等格式缺陷，立即就地阻断请求，并向大模型返回具体的行号与修复指引，杜绝脏配置污染存储导致下游服务崩溃。
超长配置按行切片防护 (Token Bloat Protection)：
当微服务配置超过 30,000 字符（约 800 行）时，自动返回前 200 行内容摘要与全文字符统计，并指导大模型传入 startLine 与 endLine 进行按需切片阅读，保护模型上下文窗口容量。
所有配置项均采用 MCP_NACOS_ 专业命名空间，支持命令行参数（CLI Flags）与环境变量双重注入：
环境变量名 | CLI 选项 | 必填 | 默认值 | 说明与 NAT 场景示例 |
|
| 是* |
| Nacos 核心 OpenAPI 地址（NAT: |
|
| 否 |
| Web 控制台地址（NAT: |
|
| 否 |
| 简写 Host:Port 格式（供本地极简推断） |
|
| 否 | - | Nacos 访问用户名（开启鉴权时必填） |
|
| 否 | - | Nacos 访问密码（开启鉴权时必填） |
|
| 否 |
| 默认命名空间 Tenant ID |
|
| 否 |
| HTTP 请求超时时间（毫秒） |
|
| 否 |
| 容器或网络模式下的监听端口 |
|
| 否 |
| 传输层模式： |
在 Claude Desktop 配置文件（Windows: %APPDATA%\Claude\claude_desktop_config.json，macOS: ~/Library/Application Support/Claude/claude_desktop_config.json）中添加：
{
"mcpServers": {
"nacos": {
"command": "npx",
"args": ["-y", "@atengk/mcp-server-nacos"],
"env": {
"MCP_NACOS_SERVER_URL": "http://127.0.0.1:8848/nacos",
"MCP_NACOS_USERNAME": "nacos",
"MCP_NACOS_PASSWORD": "nacos"
}
}
}
}{
"mcpServers": {
"nacos": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-e", "MCP_NACOS_SERVER_URL=http://host.docker.internal:8848/nacos",
"-e", "MCP_NACOS_USERNAME=nacos",
"-e", "MCP_NACOS_PASSWORD=nacos",
"ghcr.io/atengk/mcp-server-nacos:latest"
]
}
}
}在项目根目录 .cursor/mcp.json 或 Cursor 全局设置中配置：
{
"mcpServers": {
"nacos": {
"command": "npx",
"args": ["-y", "@atengk/mcp-server-nacos"],
"env": {
"MCP_NACOS_SERVER_URL": "http://127.0.0.1:8848/nacos",
"MCP_NACOS_USERNAME": "nacos",
"MCP_NACOS_PASSWORD": "nacos"
}
}
}
}在 VSCode 插件（如 Cline / Roo Code）的 MCP 设置中添加：
{
"mcpServers": {
"nacos": {
"command": "npx",
"args": ["-y", "@atengk/mcp-server-nacos"],
"env": {
"MCP_NACOS_SERVER_URL": "http://127.0.0.1:8848/nacos",
"MCP_NACOS_USERNAME": "nacos",
"MCP_NACOS_PASSWORD": "nacos"
},
"disabled": false,
"autoApprove": []
}
}
}仓库内置了 docker-compose.yml，用于将 MCP Server 部署为独立容器服务并暴露 3000 端口：
# 1. 复制环境变量模版并按需配置
cp .env.example .env
# 2. 启动服务 (后台运行)
docker compose up -d
# 3. 查看运行日志
docker compose logs -f当通过 Docker Compose 或后台网络模式运行后，在各类大模型智能体平台（如 Dify、FastGPT）的 MCP 工具集成页面中添加自定义 MCP 服务端：
集成类型：Server-Sent Events (SSE)
服务端端点 URL：http://<宿主机IP或域名>:3000/sse
消息回调 URL：系统自动协商绑定 http://<宿主机IP或域名>:3000/message
nacos_list_namespaces: 查询所有命名空间列表及元数据。
nacos_create_namespace: 创建新的命名空间（namespaceId, namespaceName, namespaceDesc）。
nacos_delete_namespace: 删除指定命名空间。
nacos_get_config: 获取指定配置项内容（支持大文本自动截断与 startLine/endLine 切片）。
nacos_publish_config: 创建或更新配置（内置客户端 JSON/YAML 语法强守卫）。
nacos_delete_config: 删除指定配置。
nacos_list_configs: 分页模糊搜索配置列表。
nacos_get_config_history: 查询指定配置的历史修订版本列表（用于审查和回滚）。
nacos_rollback_config: [专用回滚] 依据 historyId 原子化回滚至指定历史版本，杜绝长文本搬运截断。
nacos_list_services: 分页查询微服务列表。
nacos_get_service: 获取微服务元数据与保护阈值。
nacos_list_instances: 查询服务下的注册实例（支持过滤健康状态）。
nacos_register_instance: 手动向服务注册实例（默认持久化实例，支持显式声明临时实例）。
nacos_deregister_instance: 注销指定服务实例。
nacos_update_instance: 动态修改实例运行状态（上下线开关、权重比率调节与元数据打标）。
nacos_get_server_status: 探测 Nacos 集群节点当前运行状态与健康度。
URI 范式：nacos://config/{namespaceId}/{group}/{dataId}
功能：大模型无需多轮触发函数调用，可直接将微服务配置挂载至上下文用于分析审查。
nacos_service_inspection：服务全景体检，自动扫描无实例空服务、健康异常与被隔离实例。
nacos_config_drift_check：配置版本漂移比对，自动生成当前配置与上一历史版本的 Unified Git Diff。
本项目严格遵循高内聚领域驱动与工程架构决策规范：
📚 统一业务语言词典：CONTEXT.md（严格界定命名空间、配置项、实例权重、测试接缝等标准定义）
📐 架构决策记录 (ADR)：
📋 GitHub 任务看板与规格书：GitHub Issues 看板
从 GitHub Releases 页面下载分发产物与 checksums.txt 清单后，可一键验证文件防篡改完整性：
Linux：
sha256sum -c checksums.txt --ignore-missingmacOS：
shasum -a 256 -c checksums.txtWindows (PowerShell)：
Get-FileHash .\mcp-server-nacos-*-bundle.tar.gz -Algorithm SHA256# 1. 克隆代码仓库
git clone https://github.com/atengk/mcp-server-nacos.git
cd mcp-server-nacos
# 2. 安装项目依赖
pnpm install
# 3. 编译打包
pnpm run build
# 4. 本地启动运行
node dist/index.js本项目基于 Apache 2.0 开源许可证 分发与使用。
在 Nacos 中创建新的命名空间隔离环境（支持指定命名空间 ID、名称与描述）
| Name | Required | Description | Default |
|---|---|---|---|
| namespaceId | Yes | 命名空间租户唯一标识符 (Tenant ID)，不可使用保留关键字 public | |
| namespaceDesc | No | 命名空间业务用途描述信息 | |
| namespaceName | Yes | 命名空间显示名称 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It only states creation and supported fields; it omits permissions, side effects, idempotency, duplicate handling, and return 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?
A single front-loaded sentence with no filler. It efficiently conveys the core action and supported fields, though its brevity leaves gaps in other dimensions.
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 3-param create tool with full schema coverage but no annotations or output schema, the description covers the core action. However, it omits prerequisites, failure modes, and what the operation returns, which leaves meaningful gaps for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all three parameters are already documented in the schema. The description restates that ID, name, and description can be specified but adds no syntax, constraints, or defaults beyond what the schema provides. Baseline 3 applies.
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?
States a specific verb ('创建') and resource ('命名空间'), plus the scope ('隔离环境'). Clear what it does, but does not explicitly differentiate from sibling namespace operations like delete or list.
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 when-to-use guidance, alternatives, or prerequisites are provided. The implied usage is to create a namespace when isolation is needed, but nothing explicit is stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
删除 Nacos 中指定的配置项
| Name | Required | Description | Default |
|---|---|---|---|
| group | No | 配置分组 (Group)，默认 DEFAULT_GROUP | DEFAULT_GROUP |
| dataId | Yes | 待删除的配置集 ID (Data ID) | |
| namespaceId | No | 命名空间 Tenant ID，留空或 public 为公共空间 |
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 states a deletion but omits whether it is permanent, what permissions are required, and what side effects occur on clients or dependent services.
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?
A single front-loaded sentence with no filler or redundancy. Every word contributes to stating the operation.
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 destructive three-parameter tool with no annotations and no output schema, the description is under-specified. It does not explain whether deletion is reversible, how group/namespace defaults affect the target, or what happens if dataId is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents dataId, group, and namespaceId. The description adds no syntax or meaning beyond what the schema provides, making the baseline 3 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?
States a specific verb and resource (删除 Nacos 配置项), making the operation clear. It distinguishes itself from read/publish siblings by name, but does not explicitly name alternatives or clarify scope relative to nacos_delete_namespace.
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 such as nacos_get_config_history or nacos_rollback_config. The use case is only implied by the tool name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
删除 Nacos 中指定的命名空间（公共命名空间 public 受保护不可删除）
| Name | Required | Description | Default |
|---|---|---|---|
| namespaceId | Yes | 待删除的命名空间 Tenant ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It discloses that this is a destructive operation and notes the public-namespace protection, but does not state consequences such as cascading resource deletion, required permissions, reversibility, or error 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 a single front-loaded sentence with a concise parenthetical caveat. No unnecessary words are present.
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 one-parameter delete tool with no output schema and no annotations, the description covers the core action and the key protected-namespace caveat. It remains slightly incomplete on destructive side effects and permission requirements, but is largely sufficient given the low complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the sole parameter namespaceId is already fully documented in the schema. The description does not add format or semantics beyond the schema, making the baseline 3 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 states a specific verb (删除/delete) and resource (Nacos 命名空间/namespace), making the operation immediately identifiable. It is clearly distinct from sibling tools like nacos_create_namespace and nacos_list_namespaces.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides an explicit exclusion: the public namespace is protected and cannot be deleted. This is important usage guidance for avoiding an invalid call, though it does not name alternatives or describe broader when-to-use conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
从微服务中手动注销下线指定的实例节点
| Name | Required | Description | Default |
|---|---|---|---|
| ip | Yes | 待注销实例的 IP 地址 | |
| port | Yes | 待注销实例的端口号 | |
| ephemeral | No | 实例是否为临时节点（持久化实例注销传 false 或留空） | |
| groupName | No | 微服务分组，默认 DEFAULT_GROUP | |
| clusterName | No | 集群名称，默认 DEFAULT | |
| namespaceId | No | 命名空间 Tenant ID，留空或 public 为公共空间 | |
| serviceName | Yes | 微服务名称 (Service Name) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It indicates a manual deregistration/offline mutation, but omits whether the action is reversible, what permissions are required, how existing traffic or health checks are affected, and how the ephemeral flag changes behavior. This is too thin for a mutation tool with zero annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence with no redundant clauses. The operation and target are conveyed immediately, which is appropriate for a short definition.
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?
This is a mutation tool with no annotations and no output schema, yet the description is only a one-line purpose statement. It does not address side effects, usage context, or parameter nuances, leaving an agent with insufficient context beyond the structured schema to invoke it confidently.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so parameter meanings are already documented in the input schema. The description adds no further parameter semantics, such as guidance on using ephemeral, namespaceId, or groupName during deregistration, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: 注销下线 (deregister/offline) a specified 实例节点 (instance node). It clearly describes the core operation, but does not explicitly differentiate itself from sibling tools such as nacos_register_instance or nacos_update_instance, so it falls short of a 5.
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?
Provides no when-to-use guidance, no prerequisites, and no alternatives. The word 手动 (manually) implies deliberate invocation but does not explain when an agent should choose this tool over nacos_update_instance, nacos_register_instance, or other lifecycle tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
获取 Nacos 配置项全文内容，支持超长文本智能截断与按行切片精准读取
| Name | Required | Description | Default |
|---|---|---|---|
| group | No | 配置分组 (Group)，默认 DEFAULT_GROUP | DEFAULT_GROUP |
| dataId | Yes | 配置集 ID (Data ID) | |
| endLine | No | 切片结束行号（闭区间，必须大于等于起始行） | |
| startLine | No | 切片起始行号（从 1 开始，用于大文本分块读取） | |
| namespaceId | No | 命名空间 Tenant ID，留空或 public 为公共空间 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It usefully discloses automatic truncation of very long configs and that slicing is supported, which is real behavioral context beyond the schema. However, it omits what triggers truncation, whether the result is partial, permission requirements, and error behavior for missing dataId.
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?
A single compact sentence that front-loads the core action and then its two special capabilities. No filler or redundancy, though being one long clause it is less scannable than a structured split.
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?
Five parameters, no annotations, and no output schema mean description must cover more: it explains the read and slicing but not return shape, truncation thresholds/defaults, or error cases. Adequate but leaves meaningful gaps for an agent to call it correctly in edge cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so startLine/endLine/group/namespaceId are already fully documented in the schema. The description only generically echoes the slicing concept without adding formats, defaults, or interaction rules (e.g., how startLine/endLine interact with truncation), so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource ('获取 Nacos 配置项全文内容') and adds the tools' distinctive capability (truncation for long text, line-based slicing). It implicitly separates itself from listing siblings such as nacos_list_configs and nacos_get_config_history, though it never names them explicitly.
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 guidance on when to use this tool versus nacos_list_configs or nacos_get_config_history, nor any prerequisites. The mention of '分块读取' for large text hints at a use case but stops short of prescribing it, leaving the agent to infer.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
分页查询特定配置项的历史修改版本清单与审计快照元数据
| Name | Required | Description | Default |
|---|---|---|---|
| group | No | 配置分组 (Group)，默认 DEFAULT_GROUP | DEFAULT_GROUP |
| dataId | Yes | 目标配置集 ID (Data ID) | |
| pageNo | No | 分页查询页码，默认 1 | |
| pageSize | No | 每页查询数量，默认 20，上限 100 | |
| namespaceId | No | 命名空间 Tenant ID，留空或 public 为公共空间 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full behavioral burden. It discloses that the operation is a paginated query returning version history and audit snapshot metadata, but omits permissions required, whether the operation is read-only (only implied), rate limits, and the structure of the returned snapshots.
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?
A single, front-loaded sentence that states the operation and its scope without filler. Every component of the sentence contributes to 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?
For a read-oriented history tool with a fully described schema but no output schema or annotations, the description adequately states what is returned and the pagination aspect. It falls short by not clarifying usage relative to siblings or providing any behavioral guarantees, leaving gaps for an agent to infer.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all five parameters are documented in the schema. The description adds no additional meaning, syntax, or constraints beyond the parameter names, making the baseline of 3 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?
States a specific verb (分页查询) and resource (历史修改版本清单与审计快照元数据) scoped to a specific config item. The term 历史 makes it distinguishable from nacos_get_config and nacos_list_configs, which deal with current configurations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by the description—agents can infer this is the tool for inspecting historical versions of a config. However, there is no explicit guidance on when to use it versus nacos_rollback_config or nacos_get_config, nor any stated prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
探测 Nacos 集群各节点运行状态、版本与探针健康度
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. '探测' implies a non-mutating read, but there is no mention of auth requirements, whether it hits every node, latency/cost, or how failures are reported. Only the surface purpose is disclosed.
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?
A single focused sentence enumerating exactly what is probed (status, version, health) with no filler. Front-loaded on the core action. Slightly terse, but nothing is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, no-annotation tool with no output schema, the description names the conceptual return values (status, version, health) but does not describe the response shape or failure behavior, leaving some gaps an agent must discover at runtime.
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 takes zero parameters, so the baseline is 4. The description correctly conveys that no input is required to run the probe.
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?
States a specific verb (探测/probe) and resource (Nacos 集群各节点 running status, version, probe health), which is distinct from config/service siblings like nacos_get_service and nacos_get_config. It does not explicitly name a sibling to differentiate against, but the diagnostic scope 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 when-to-use guidance, prerequisites, or alternatives are given. An agent can infer this is a cluster-health diagnostic, but nothing states when to prefer it over other inspection tools or what triggers it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
查询指定微服务的元数据配置、保护阈值 (protectThreshold) 及集群元数据
| Name | Required | Description | Default |
|---|---|---|---|
| groupName | No | 所属分组名称，默认 DEFAULT_GROUP | |
| namespaceId | No | 命名空间 Tenant ID，留空或 public 为公共空间 | |
| serviceName | Yes | 微服务名称 (Service Name) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. The word 查询 implies a read-only lookup and it discloses the returned payload (metadata, protectThreshold, cluster metadata), but it says nothing about behavior when the service is absent, required permissions, or namespace/group resolution rules.
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?
A single front-loaded clause naming the action and the returned data, with zero filler or redundancy. It is efficient, though arguably so terse that it omits routing context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple three-parameter read tool with full schema coverage and no output schema, the description is adequate: it identifies the resource and the returned fields. It falls short on usage context and failure/permission behavior, which are unaddressed anywhere else.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all three parameters (groupName, namespaceId, serviceName) are already documented with defaults and semantics in the schema. The description adds no parameter-level detail beyond that, so the baseline 3 applies.
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 gives a specific verb (查询/query) and resource (指定微服务/specified microservice) and even enumerates what is returned: metadata config, protectThreshold, and cluster metadata. This distinguishes it from listing siblings like nacos_list_services, though it never names an alternative explicitly.
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 statement of when to use this tool versus nacos_list_services, nacos_list_instances, or nacos_get_config. Usage is only implied by the word 指定 (specified), leaving the agent to infer that this is for drilling into one known service.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
分页模糊搜索配置集列表（支持按 Data ID 或 Group 模糊匹配）
| Name | Required | Description | Default |
|---|---|---|---|
| group | No | 配置分组模糊匹配关键字 | |
| dataId | No | 配置集 ID 模糊匹配关键字 | |
| pageNo | No | 分页查询页码，默认 1 | |
| appName | No | 应用名称模糊匹配关键字 | |
| pageSize | No | 每页查询数量，默认 20，上限 100 | |
| namespaceId | No | 命名空间 Tenant ID，留空或 public 为公共空间 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It notes only that results are paginated, which the schema already conveys via pageNo/pageSize; it says nothing about read-only safety, permissions, namespace scoping, ordering, or what an empty result means for a 6-parameter query 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?
A single compact sentence that front-loads the action, the resource, and the matching scope with zero filler. It is arguably too terse for a six-parameter tool, but nothing is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only list tool whose parameters are fully described by the schema, the description is minimally adequate. However, with no annotations and no output schema, it leaves the agent without any signal about safety profile, namespace behavior, or result shape.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all six parameters are already documented by the schema, including defaults and the pageSize cap. The description only restates Data ID and Group fuzzy matching, adding no syntax, format, or matching-rule detail beyond what the schema supplies.
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?
States a specific verb (分页模糊搜索 / paginated fuzzy search) and resource (配置集列表 / config list), plus the matching scope (Data ID or Group). It is easily distinguished from the single-item nacos_get_config and write siblings like nacos_publish_config, though it does not explicitly name any alternative.
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 when-to-use or when-not-to-use guidance and no mention of alternatives such as nacos_get_config for a known Data ID. The agent must infer from the word '列表' (list) that this is the enumeration entry point.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
查询微服务下注册的实例列表，支持按健康状态过滤
| Name | Required | Description | Default |
|---|---|---|---|
| clusters | No | 集群名称列表（多个以逗号分割，如 DEFAULT） | |
| groupName | No | 所属分组名称，默认 DEFAULT_GROUP | |
| healthyOnly | No | 是否仅返回健康实例（true: 仅健康节点; false: 返回全部节点，默认 false） | |
| namespaceId | No | 命名空间 Tenant ID，留空或 public 为公共空间 | |
| serviceName | Yes | 微服务名称 (Service Name) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. '查询' implies a read-only lookup, and the health-filter behavior is disclosed, but there is no mention of pagination, result ordering, default group/namespace behavior, or what the returned instance records contain. Adequate for a simple read, but thin given zero annotation coverage and no output schema.
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?
A single front-loaded sentence with no filler; the core action comes first and the filtering capability follows. It is efficient, though its brevity reflects under-specification of behavior rather than tight editing, keeping it just below a 5.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With five well-documented parameters but no output schema, the description should ideally sketch what an instance list returns (instance IDs, IPs, health flags, cluster layout). It omits this, leaving the agent to infer the response shape. The essentials for calling the tool are present, so it is minimally complete rather than rich.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all five parameters (clusters, groupName, healthyOnly, namespaceId, serviceName) are already documented in the schema, including defaults. The description's mention of health filtering merely restates the healthyOnly parameter already covered, adding no syntax or format detail beyond the schema. Baseline 3 applies.
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?
States a specific verb and resource (查询...实例列表) scoped to instances registered under a microservice, which clearly separates it from siblings like nacos_list_services or nacos_get_service. It also names the filtering capability (按健康状态过滤). It does not explicitly name a sibling to contrast with, so it stops short of a 5.
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 when-to-use guidance, no prerequisites, and no alternatives named — nothing tells the agent why to pick this over nacos_list_services or nacos_get_service. The only usage hint is the implied ability to filter by health status, which is really a parameter capability rather than routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
查询 Nacos 集群所有命名空间列表及隔离元数据
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that the tool queries all namespaces and isolation metadata, implying a read-only scope, but does not explicitly state that no mutation occurs, whether authentication is required, or any pagination 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?
A single, front-loaded sentence with no wasted words. The purpose and scope are stated immediately and the description is appropriately sized for a zero-parameter list tool.
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 zero-parameter read tool, the description sufficiently conveys the resource being listed. However, without an output schema or annotations, it could have clarified the return shape or read-only safety profile a bit more.
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 zero parameters, so the baseline is 4. The empty input schema is fully documented, and there is no parameter nuance the description needs to clarify.
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?
States a specific verb ('查询') and resource ('所有命名空间列表及隔离元数据'), and clearly distinguishes itself from sibling mutation tools like nacos_create_namespace and nacos_delete_namespace. An agent can identify this as the read-only list operation without opening the schema.
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 only states what the tool returns; it gives no explicit guidance on when to use it versus alternatives such as nacos_get_service or nacos_list_services. There is no mention of prerequisites, filtering context, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
分页查询 Nacos 微服务列表及服务名称
| Name | Required | Description | Default |
|---|---|---|---|
| pageNo | No | 分页查询页码，默认 1 | |
| pageSize | No | 每页查询数量，默认 20，上限 100 | |
| groupName | No | 微服务分组名称 (Group)，默认 DEFAULT_GROUP | |
| namespaceId | No | 命名空间 Tenant ID，留空或 public 为公共空间 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It implies a read-only paginated lookup via '查询' but says nothing about return format, whether results span namespaces, or pagination behavior. For a tool with zero annotation coverage this is a significant gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single short sentence with no filler, fully front-loaded. It is efficient, though its extreme brevity is what leaves the other gaps unfilled.
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 read-only listing tool with four fully described optional parameters and no output schema, the minimum needed to call it correctly is present via the schema. However, the description omits any note on namespace/group scoping behavior or default pagination, leaving 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 100%, so all four parameters (pageNo, pageSize, groupName, namespaceId) are already documented with defaults and limits in the schema. The description adds no parameter meaning beyond that, so the baseline 3 applies.
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?
States a clear verb+resource: '分页查询 Nacos 微服务列表及服务名称' (paginated query of the Nacos microservice list and service names). An agent can distinguish it from nacos_get_service, which handles a single service, though the description never names that sibling explicitly.
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 when-to-use guidance, no exclusions, and no mention of alternatives such as nacos_get_service or nacos_list_instances. Usage must be inferred entirely from the tool name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
发布或更新 Nacos 配置项内容（内置 JSON/YAML 语法格式合法性前置拦截校验）
| Name | Required | Description | Default |
|---|---|---|---|
| desc | No | 配置描述信息 | |
| type | No | 配置格式类型（支持 text/json/xml/yaml/html/properties/toml） | |
| group | No | 配置分组 (Group)，默认 DEFAULT_GROUP | DEFAULT_GROUP |
| dataId | Yes | 目标配置集 ID (Data ID) | |
| appName | No | 所属应用名称 (App Name) | |
| content | Yes | 待发布的配置内容全文 | |
| namespaceId | No | 命名空间 Tenant ID，留空或 public 为公共空间 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden and usefully discloses built-in JSON/YAML validation. However, it omits mutation semantics such as overwrite behavior, permission requirements, and idempotency.
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?
It is a single, front-loaded sentence with zero filler; the validation caveat is appropriately placed in parentheses.
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 minimum viable for a write tool: it states purpose and one behavioral safeguard. For a mutation tool with no annotations and no output schema, it should say more about what happens on success/failure or when a config already exists.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all seven parameters are documented in the schema. The description adds no parameter-level meaning beyond mentioning JSON/YAML validation, which is the baseline 3 when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb+resource — publish or update Nacos configuration content — and adds the validation scope. It clearly differs from read/delete/list siblings, but it does not explicitly name or distinguish the similar rollback sibling.
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 says what the tool does but gives no when-to-use guidance, prerequisites, or alternatives. It does not route the agent between this and nacos_rollback_config or nacos_delete_config.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
向微服务注册新实例（遵循 ADR-0002 规范，默认采用持久化模式 ephemeral=false，可显式声明为临时节点）
| Name | Required | Description | Default |
|---|---|---|---|
| ip | Yes | 实例 IP 地址（如 192.168.1.10） | |
| port | Yes | 实例监听端口号 | |
| weight | No | 负载均衡权重，取值范围 0.0 ~ 1.0，默认 1.0 | |
| enabled | No | 是否接受流量调用（true: 启用; false: 隔离下线，默认 true） | |
| healthy | No | 实例初始健康度（默认 true） | |
| metadata | No | 实例自定义扩展元数据键值对 (Key-Value) | |
| ephemeral | No | 是否为临时节点（根据 ADR-0002 规定默认 false 为持久化节点；若为客户端自注册可显式传 true） | |
| groupName | No | 微服务分组，默认 DEFAULT_GROUP | |
| clusterName | No | 集群名称，默认 DEFAULT | |
| namespaceId | No | 命名空间 Tenant ID，留空或 public 为公共空间 | |
| serviceName | Yes | 目标微服务名称 (Service Name) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the behavioral burden. It usefully discloses that nodes are persistent by default (ephemeral=false per ADR-0002) and can be made ephemeral, which is meaningful write-behavior context. It still omits idempotency, behavior on duplicate registration, required permissions, and reversibility.
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?
It is a single, front-loaded sentence with no redundant filler; the parenthetical ADR-0002 reference is functional rather than wasteful. Slightly denser than ideal but 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?
For an 11-parameter mutation tool with nested metadata, no annotations, and no output schema, the description covers only the persistence default. Registration semantics such as duplicate handling, permissions, and return behavior are left unaddressed, so it is adequate but incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all 11 parameters including the ephemeral default. The description adds no parameter semantics beyond what the schema states, so the 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 states a specific verb and resource ('向微服务注册新实例' – register a new instance), which is clearly distinguishable from siblings like nacos_deregister_instance and nacos_update_instance. However, it never names an alternative tool or explicitly contrasts its role with them, so it falls short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is only implied by the verb 'register'; the description adds no explicit when-to-use, when-not-to-use, or sibling comparison. The note about ephemeral=false being the default and the option to declare ephemeral explicitly gives some operational context, but not enough to count as real routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
依据历史快照 ID (historyId) 原子化回滚配置至指定历史版本（自动提取历史快照全文覆盖发布，免去模型长文本搬运风险）
| Name | Required | Description | Default |
|---|---|---|---|
| group | No | 配置分组 (Group)，默认 DEFAULT_GROUP | DEFAULT_GROUP |
| dataId | Yes | 目标配置集 ID (Data ID) | |
| historyId | Yes | 目标历史快照唯一标识符 (historyId / nid) | |
| namespaceId | No | 命名空间 Tenant ID，留空或 public 为公共空间 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description does carry real behavioral weight: it discloses that the operation is atomic, that it overwrites and republishes using the full snapshot text, and that this avoids long-text transport. However it omits permission requirements, whether the rollback is itself reversible, and the effect on the current live config beyond 'overwrite'.
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?
A single dense sentence with the action, the input key, and the mechanism front-loaded; every clause earns its place. Minor density from the parenthetical, but no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive mutation with no annotations and no output schema, the description covers what happens and why it is safe from a text-transport standpoint. It leaves gaps on prerequisites (does the snapshot still exist? does it apply to the same group/namespace?), failure behavior, and confirmation/irreversibility.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds one useful clarification about historyId's role — the full snapshot body is fetched from it so no content needs to be passed — but says nothing extra about group, namespaceId, or the dataId/historyId pairing.
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?
Names a specific verb+resource (回滚配置 / roll back config) plus the exact selecting key (historyId) and the target state (指定历史版本), which clearly separates it from nacos_publish_config and nacos_get_config_history. It stops short of explicitly differentiating itself from siblings, so it is clear but not sibling-routing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is only implied: the agent must already hold a historyId, which suggests a prior nacos_get_config_history call, and this is the tool to use when reverting rather than editing content. No explicit when-to-use / when-not-to-use or named alternative (e.g. nacos_publish_config) is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
动态更新微服务实例状态（调整流量权重 0.0~1.0、在线/隔离下线开关 enabled、元数据）
| Name | Required | Description | Default |
|---|---|---|---|
| ip | Yes | 目标实例 IP 地址 | |
| port | Yes | 目标实例端口号 | |
| weight | No | 新权重值，取值范围 0.0 ~ 1.0 | |
| enabled | No | 是否接受流量调用（true: 启用上线; false: 隔离下线） | |
| metadata | No | 更新或覆盖的实例扩展元数据 | |
| ephemeral | No | 实例是否为临时节点 | |
| groupName | No | 微服务分组，默认 DEFAULT_GROUP | |
| clusterName | No | 集群名称，默认 DEFAULT | |
| namespaceId | No | 命名空间 Tenant ID，留空或 public 为公共空间 | |
| serviceName | Yes | 微服务名称 (Service Name) |
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 disclose real behavioral meaning for two fields (weight must stay in 0.0~1.0; enabled=false means the instance is isolated and taken offline), which is genuinely useful. But it omits permissions/auth requirements, what happens to the instance if the update fails, the effect on ephemeral nodes, and whether unspecified fields are left untouched.
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?
A single, front-loaded sentence with no filler. The parenthetical field list is slightly dense but each item is informative rather than redundant.
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 10-parameter mutation tool with no annotations and no output schema, the description is minimally viable. It identifies the update target and the three most consequential fields, but leaves the agent without guidance on preconditions, failure behavior, or the ephemeral/metadata interaction.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all 10 parameters are already documented in the schema. The description restates the weight range and the enabled boolean semantics but adds no syntax, defaults, or formats beyond what structured data supplies. Baseline 3 applies.
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?
States a specific verb and resource ('动态更新微服务实例状态') and enumerates the mutable facets (weight, enabled switch, metadata), which clearly separates it from nacos_register_instance / nacos_deregister_instance. It stops short of naming siblings or explicitly contrasting with registration/deregistration.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied: this mutates an already-registered instance rather than adding/removing one. However there is no explicit when-to-use, no statement of prerequisites (the instance must exist), and no alternative routing such as deregister+register for ephemeral changes.
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.0nacos_create_namespacenacos_delete_confignacos_delete_namespacenacos_deregister_instancenacos_get_confignacos_get_config_historynacos_get_server_statusnacos_get_servicenacos_list_configsnacos_list_instancesnacos_list_namespacesnacos_list_servicesnacos_publish_confignacos_register_instancenacos_rollback_confignacos_update_instanceScored across 16 tools
Each tool targets a distinct resource and action within Nacos config or service discovery. There is no overlap between similar-sounding tools like get_service (metadata for one service) and list_services (all services), or between get_config (current content) and get_config_history (past versions). The boundaries are clear from the names and descriptions.
All tools follow a strict nacos_<verb>_<noun> pattern in snake_case. Verbs like get, list, create, delete, publish, register, deregister, and update are used consistently, and plural nouns are used for list operations while singular nouns are used for single-resource operations.
16 tools across two major Nacos subdomains (config management and service discovery) is slightly above the typical 3–15 range but each tool earns its place. No redundant or filler tools are present, though the set could be marginally trimmed if some rarely used operations were merged.
Config lifecycle (get, publish/update, delete, list, history, rollback) and instance lifecycle (register, deregister, update, list) are well covered. Minor gaps exist, such as no explicit update_namespace tool and no way to delete a service directly, but these are workaroundable in typical Nacos usage.
MCP-Native LLM Orchestration Agent
MCP server for AI agents to plan, verify, and deploy Cloudflare-native apps.
LLM Orchestration Agent (Mcp)
MCP-first control plane for ProAgentStore agents and private instances.
