架构定位：盘古「实时接口」
在四层架构中，本 MCP 是日志、数据库、猪齿鱼和代码的实时事实来源；脚本平台当前源码、 版本、Fixture 和启用状态由独立的
zhenyun-script-platform-mcp提供：
层
回答什么
载体
Skill
这个任务应该怎么做
custom-skills/的 SKILL.md（编排流程）Knowledge
业务/系统/字段是什么
本 MCP 的
knowledge_base/（稳定事实，沉淀于 knowledge_docs）Template
以前类似问题怎么解决
本 MCP 的
knowledge_base/（SQL 模板，沉淀于 sql_templates）zhenyun-pangu-mcp
现在业务环境真实是什么/发生了什么
本 MCP（日志 / 数据 / 猪齿鱼 / 代码 / 脚本身份发现）
zhenyun-script-platform-mcp
平台当前脚本是什么、如何真实调试与安全保存
Script Platform API / DEV GraalJS Runtime
边界原则：
所有可能变化的实时事实（当前日志、当前数据、当前 Schema、当前状态、当前服务状态）一律走本 MCP。
静态知识（Skill Markdown / Knowledge / Template）只负责帮助 Agent 理解这些实时数据意味着什么，不替代实时查询。
Pangu 的脚本搜索只负责发现精确身份；当前源码、版本、Fixture、Debug、Save、Deploy 必须使用
zhenyun-script-platform-mcp。旧的独立
log-ops/sql-ops/gitlab-codeMCP 已被本 MCP 整合取代，不再是正式概念，请勿引用。能力分类（供 Agent 理解"何时用哪类工具"）：
认知层（知识/模板/表）：
search_knowledge/get_knowledge/search_sql_templates/get_sql_template/search_tables/get_table/get_table_relations/search_pangu（统一搜索）/diagnose_context（组合诊断）日志能力：
obs_sls_query/obs_sls_targets（国内公有云盘古 prod/dev/test，阿里云 SLS）/obs_log_query/obs_log_trace/obs_log_datasources（AWS 海外，Loki）数据能力：
archery_query/archery_describe_table/archery_list_columns/archery_query_tenant/archery_list_databases/archery_list_instancesES 只读能力：
es_search/es_count/es_get（prod/dev/test，未配置时返回明确降级提示）业务系统能力：
choerodon_*系列（猪齿鱼协作，以只读查询为主，评论新增、编辑和删除为需授权的写操作）代码与脚本能力：
search_repo（本地跨仓搜索）+search_adapter_scripts/search_standalone_scripts（只发现脚本身份）+ 已知路径的gitlab_list_branches/list_tree/get_file精确读取。当前脚本正文统一由 Script Platform MCP 获取；GitLab 项目/代码搜索默认禁用。只读/写边界（安全）：日志查询、Schema/数据查询、猪齿鱼查询类（
choerodon_*_issue/choerodon_list_*/choerodon_search_*/choerodon_get_*/choerodon_download_*）、代码检索为只读，Agent 可自主调用。archery_query的用户 SQL 允许单条SELECT、EXPLAIN SELECT、SHOW CREATE TABLE；SELECT 支持CASE WHEN表达式、IN (...)/NOT IN (...)值列表，以及COUNT、SUM、AVG、MIN、MAX、IFNULL、NULLIF、CONCAT、CONCAT_WS、CAST。不支持其它SHOW/DESC、WITH、子查询、多语句、注释、窗口函数、集合运算或任何写入语法；实例/库/表结构由专用工具提供。任何生产 INSERT/UPDATE/DELETE 不在本 MCP 提供，统一由 Skill 生成 SQL 后交用户人工确认执行。认知层的search_*/get_*/diagnose_context/list_sql_templates为只读；save_*、update_*、delete_*、add_table_relation、upsert_table_knowledge和使用统计工具会写入 knowledge_docs / sql_templates / table_catalog / table_relations 元数据，不影响业务数据，调用前应确认沉淀内容。choerodon_add_comment、choerodon_update_comment和choerodon_delete_comment会真实修改猪齿鱼评论，须先确认完整最终正文或删除目标；新增/编辑正文传规范 Markdown，由工具渲染为 HTML。
甄云盘古通用工具 MCP，供任意 MCP 客户端（Claude Desktop / Cursor / 各类 agent）复用。
跨 agent 接入、通用导出命令和本轮协作优化见 WORKFLOW_OPTIMIZATION.md。
猪齿鱼评论格式说明：choerodon_add_comment / choerodon_update_comment 接收规范 Markdown，但接口写入的
commentText 是统一渲染后的 HTML 富文本。Markdown 表格会转换为 <table>，代码块
会转换为 <pre><code class="language-xxx">；因此从评论区复制代码时不会带回 Markdown
的 ``` 围栏，这是浏览器复制 HTML 内容的正常表现。不要在同一条评论中手工拼接 HTML 和
Markdown，否则编辑器二次解析时可能出现表格或代码块样式互相覆盖。
完全自包含：不依赖任何外部项目目录，仅需在 .env 配置真实凭据即可使用。
Related MCP server: OpenObserve MCP Server
工具按前缀/能力分组（旧脚本正文工具默认隐藏；实时清单可用 get_workflow_guide(topic="capabilities") 查看）：
前缀 | 工具 | 说明 |
协作协议 |
| 需求/排障/修复/知识/证据交接的按需指引；本地读取，零业务调用，适用于未加载技能的 MCP 客户端 |
|
| 业务知识/排查经验：混合检索（语义+关键词）+ 详情（沉淀于 knowledge_docs） |
|
| 可复用 SQL/修复模板：混合检索 + 详情 + 总览（沉淀于 sql_templates） |
|
| 表目录 + 关联关系（沉淀于 table_catalog / table_relations） |
|
| 统一搜索：一次检索 知识 + 模板 + 表 + 关系 |
|
| 组合诊断：自动汇集 认知 → 模板 → 表 → 关系 的诊断上下文 |
知识库维护写操作 |
| 沉淀、维护知识/模板/表目录/关联关系；仅写认知层元数据，不修改业务库 |
|
| 日志能力：阿里云 SLS（国内公有云盘古 prod + 非生产 dev/test 全覆盖）+ Loki（仅 AWS 海外全环境） |
|
| 数据能力（Archery 双站点 cn/aws + 盘古专属租户/库/实例能力）； |
|
| 工作台 ES 的 prod/dev/test 只读查询；禁止写入，单次最多返回 |
脚本身份发现 |
| 只按租户、服务、编码或描述发现候选；命中后使用 |
|
| 业务系统能力：猪齿鱼协作；评论预览为离线只读，新增、按版本编辑和删除是写操作，需明确授权并预览完整内容 |
|
| 仅对已知 project/ref/path 做精确读取； |
|
| 普通代码检索的默认入口：跨本地代码仓库搜索（内容 / 文件名 / 模块结构） |
旧 get/search_*_script_source Python 实现暂时保留作紧急回滚，但默认不注册为 MCP 工具，避免
与 Script Platform MCP 形成两个正文来源。只有显式设置
PANGU_EXPOSE_LEGACY_SCRIPT_READ_TOOLS=true 才临时暴露；常规 Agent/Skill 不得依赖该开关。
认知层存放的是可复用的稳定知识和目录元数据，不是生产实时事实。调用顺序按问题类型选择：
你要解决的问题 | 首选工具 | 下一步 |
不知道某个业务规则、状态、机制是否已有结论 |
| 用结果 |
处理排障或复杂 SQL，尚不清楚要查什么 |
| 按返回的知识/模板/表/关系，分别调用专项工具和实时日志/Archery |
不知道真实表名或业务描述对应哪些表 |
| 用表名调 |
想复用以前的查询/修复方案 |
| 用模板 |
只知道一句跨域关键词，想快速发现线索 |
| 这是关键词发现，不替代专项检索和实时数据查询 |
认知层与实时事实的边界：search_knowledge/get_knowledge 回答“业务和机制是什么”；
search_sql_templates/get_sql_template 回答“以前怎么处理”；search_tables/get_table/
get_table_relations 提供目录注释和已沉淀关系。当前日志、数据、DDL、字段存在性必须分别使用
obs_*、archery_query、archery_describe_table/archery_list_columns，不能仅凭知识库内容下结论。
知识库写工具会修改 Supabase 认知层元数据，不会执行模板 SQL，也不会修改业务数据库；除统计工具外， 调用前应先向用户确认要写入的内容：
save_knowledge(title, content_md, ...)：沉淀已确认的规则、机制、排查结论或数据模型说明。
content_md 使用规范 Markdown；core_tables、tags、related_template_ids 为逗号分隔字符串；
默认 status=draft，核验后再标 verified。
update_knowledge(doc_id, ...)：只修改明确传入的字段，适合修正正文/标题/归类、把核验过的
知识标为 verified（verified_at 自动写入）或将过时知识标 deprecated/archived；修改正文等
影响语义检索的字段时会自动重新生成 embedding。过时但仍有参考价值的知识优先置
deprecated/archived，避免直接删除丢失上下文。
delete_knowledge(doc_id)：破坏性维护操作，仅清理错误、重复或彻底作废的知识，必须明确确认；
删除前先 get_knowledge 核对 id。
save_sql_template(title, category, scenario, sql_text, ...)：沉淀复杂查询或供人工确认的修复方案。
sql_text 只写入模板库，不会被 MCP 执行；parameters 必须是 JSON 对象字符串，例如
{"tenant_id":{"type":"bigint","required":true}}。数据修复模板可保存 execution_flow
和脱敏 example_case；排障模板可保存 problem_description、symptom、root_cause、
preconditions、diagnosis_steps、verify_sql、rollback_sql。
list_sql_templates(...)：只读总览；update_sql_template(id, ...)：只修改明确传入的字段，
适合纠正模板或补充验证标记；delete_sql_template(id) 是破坏性维护操作，必须明确确认。
add_table_relation(...)：仅在 Archery/SELECT 验证 join 后沉淀关系，join_on 例如
a.order_id = b.order_id，confidence 为 0~1；upsert_table_knowledge(...)：在 Archery
确认表真实存在后补录/修正目录描述和标签。两者都不创建外键、不改业务表。
record_template_usage(id) 和 record_table_usage("a,b")：仅在实际复用模板/使用表后记录统计，
不要为了提高排序而虚增计数。
推荐的最小工作流：
问题/排障 → diagnose_context 或 search_knowledge
→ get_knowledge / search_sql_templates / search_tables
→ Archery / 日志工具确认当前事实
→ 输出结果；确认后才 save_knowledge/save_sql_template
→ 实际复用后 record_template_usage/record_table_usage盘古日志分布在两个平台，查询前需先确认目标环境落在哪个平台：
能力 | 环境 | 平台 | 数据源 / project | 标签体系 |
| cn 国内盘古 | 阿里云 SLS |
|
|
| cn 国内盘古 | 阿里云 SLS |
|
|
| AWS 海外（全部环境） | Grafana/Loki |
|
|
国内公有云（cn）盘古全部环境（prod / dev / test）都是阿里云 SLS，一律用 obs_sls_query(environment=...)；system/environment 到 project/logstore/namespace 的映射由 MCP 完成，调用方不接触 AccessKey。
**AWS 海外（jp-saas-1，无论 prod/非生产）**用 obs_log_query(region="aws")。
⚠️ 路由铁律：国内盘古（含非生产）走 SLS，只有 AWS 海外走 Loki。obs_log_* 已不接受 region="cn"（会返回「请改用 obs_sls_query」的提示）；盘古非生产不要调 obs_log_query。
变迁记录：盘古非生产曾短暂迁移到 Loki（logs.going-link.net），现已迁回阿里云 SLS，相关 LOKI_API_BASE_CN / CN_LOG_* / CN_LOG_DS_* 配置已移除。
常用参数提示：
obs_sls_query(environment="prod"|"dev"|"test", trace_id=..., keyword=..., level="ERROR"|"", container_name=...)：trace_id 走「ERROR/WARN + 全链路」两阶段查询；keyword 传 SLS 查询子句（会与 _namespace_ 过滤组合）；二开排障传 container_name="srm-script-container"，把 traceId 或关键字检索限制在脚本容器。
时间：time_range 支持 最近30分钟 / 最近2小时 / 最近3天 / 今天 / 昨天 / 本周 / 上月，或 30m / 2h / 1d，或 YYYY-MM-DD HH:mm~HH:mm（北京时间）。
auto_expand（默认 true）：未显式指定时间窗且 0 命中时，自动扩到最近 24h、72h 各重试一次，实际窗口见 meta.attempted_windows。
不确定支持哪些环境时，用 obs_sls_targets() 列出真实映射；AWS 侧用 obs_log_datasources(region="aws") 列出真实数据源名。
两个平台的凭据（SLS AccessKey / Grafana 账号密码）均在
.env独立配置，详见.env.example。
cd zhenyun-pangu-mcp
uv sync
cp .env.example .env # 填写真实凭据运行测试（统一通过 uv 管理解释器和依赖）：
uv sync --dev
uv run pytest -q以 stdio 运行：
uv run zhenyun-pangu-mcp
# 或
uv run python -m zhenyun_pangu_mcp语义检索统一使用 Cloudflare Workers AI 的 @cf/qwen/qwen3-embedding-0.6b（1024 维），
向量写入单列 embedding（vector(1024)）。免费层每天 10,000 Neurons，对本知识库规模足够。
历史说明：早期支持 NVIDIA / Voyage 双 provider 并预留 embedding_voyage 双列做 A/B 对比。
nvidia/nv-embed-v1 已被官方下线（410），Voyage 免费额度限速（3 RPM / 10K TPM）不适合批量回填，
故整体切换到 Cloudflare Workers AI；双列设计与 *_voyage 检索 RPC 均已废弃，向量列维度由 2048 改为 1024。
回填 / 重建向量（默认只处理 embedding IS NULL 的行，支持断点续跑）：
uv run python scripts/rebuild_embeddings.py --table all --batch-size 50
uv run python scripts/rebuild_embeddings.py --table knowledge_docs --limit 20换模型或需要全量覆盖重算时加 --force（会覆盖该表全部已有向量）。
未配置 CF_API_TOKEN / CF_ACCOUNT_ID 时，检索自动降级为关键词检索（不报错，但召回率下降）。
工作区中的 custom-skills/、本 MCP 与独立的 zhenyun-script-platform-mcp 已打包为个人插件
zhenyun-pangu-toolkit。
修改任意 skill 或 MCP 源码后，在本目录执行：
./scripts/update_codex_plugin.sh脚本会先校验全部 Skill、运行 MCP 全量测试和 Skill↔MCP 合同检查，再同步源文件、
更新 Codex cachebuster，并重新安装个人 marketplace 中的插件；
完成后新建 Codex task 以加载最新版本。同步过程不会复制 .env、.venv 或本地 token 缓存。
{
"mcpServers": {
"zhenyun-pangu-mcp": {
"command": "uvx",
"args": ["--from", "/path/to/zhenyun-pangu-mcp", "zhenyun-pangu-mcp"],
"env": {
"MCP_ENV_DIR": "/path/to/zhenyun-pangu-mcp"
}
}
}
}.env）分组 | 环境变量 | 说明 |
Archery |
| 数据库网关 cn/aws 凭据 |
| 实例别名 → 真实实例名 | |
Loki |
| Grafana 登录凭据（仅 AWS 海外） |
| 环境 → 数据源名映射（AWS 海外） | |
Choerodon |
| 猪齿鱼网关与登录凭据 |
SLS |
| 盘古 prod 阿里云日志凭据 |
| 盘古非生产（dev/test）阿里云日志凭据 | |
GitLab |
| GitLab 仓库地址与凭据 |
| 默认 | |
| 代码搜索根目录（限定 group/project，避免全站噪声） | |
脚本发现/兼容 |
| 默认 |
| 仅旧正文工具启用时使用的解码缓存与返回范围配置 | |
Embedding |
| Cloudflare Workers AI 凭据（默认 |
其他 |
| 本地跨仓搜索根目录（默认本仓库根） |
凭据请勿提交 git；
.env已由.gitignore排除，仅.env.example（占位符版）入库。
成功返回：结构化工具返回 JSON 字符串，认知层工具按设计返回可读 Markdown。结构化结果尽量包含 summary / total / results 等摘要 + 关键结果，避免一次性返回数千行吃 Agent Context：
日志查询：obs_log_query / obs_log_trace 返回 total（命中总数）+ 截断后的 results（按 limit），obs_log_trace 附 meta.error_count / warn_count，可用 level=error 省 token。
数据查询：archery_query 返回行集与数量；查询大结果集建议缩小 limit 或用更精准 WHERE。
脚本查询：Pangu 只返回 Adapter/Independent Script 候选身份；命中后用 Script Platform MCP 的
adapter_get / independent_script_get 获取当前正文、版本和 Fixture。
失败返回：结构化工具返回 {"ok": false, "error": {"code": "...", "message": "...", "retryable": true|false}}；认知层工具按设计返回可读 Markdown。Archery/SLS 的参数错误和缺失配置返回 retryable=false，需要先修正输入或配置；网络等临时后端错误可能为 true。空结果是成功响应，不代表工具失败。
Archery 工具的 site Schema 限定为 cn / aws，默认 cn；省略 instance 使用该站点的默认实例。archery_query_tenant 的 tenant 是必填参数。ES 环境和 search_repo.mode 也通过 Schema 暴露为有限选项，客户端可在调用前校验常见拼写错误。
获取表结构（SHOW CREATE TABLE）。
| Name | Required | Description | Default |
|---|---|---|---|
| db | No | ||
| site | No | cn | |
| table | Yes | ||
| instance | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
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. The description states that the tool executes 'SHOW CREATE TABLE', implying it is a read operation, but it does not disclose whether it requires specific permissions, has rate limits, or what the output format is (though an output schema exists). As a database introspection tool, it could benefit from clarifying if it only reads metadata or might trigger side effects in some databases.
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 very short (one Chinese sentence) and front-loaded with the purpose. Every word adds value. However, it could be slightly improved by being more explicit about the parameters or usage, but for its brevity, it is efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool complexity (4 parameters, 0% schema coverage, no annotations, but with an output schema), the description is incomplete. The output schema exists and may fill some gaps, but the lack of parameter explanations and usage context makes it hard for an AI agent to use correctly. For example, the agent might not know whether 'db' or 'instance' is required or how they interact with 'site'.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, meaning the description must compensate. The description only mentions the 'table' parameter implicitly via the SQL command, but does not explain the other three parameters ('db', 'site', 'instance'). For example, 'db' and 'instance' are nullable with defaults, but the description does not clarify their role or whether 'site' affects which database environment is queried. This leaves the agent guessing about how to properly invoke the tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('获取', meaning 'get') and resource ('表结构', meaning 'table structure') with an explicit SQL command ('SHOW CREATE TABLE'). This clearly states the tool retrieves the CREATE TABLE statement for a given table. However, it does not distinguish itself from the sibling tool 'archery_list_columns', which also deals with table structure, so it loses a point for lacking differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. The sibling tools include 'archery_query' (a general query tool) and 'archery_list_columns' (lists columns), but the description does not explain when a user should choose 'archery_describe_table' over them. There is no mention of prerequisites or context for use.
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 |
|---|---|---|---|
| db | No | ||
| site | No | cn | |
| table | Yes | ||
| instance | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden for behavioral disclosure. It only states 'list columns' but omits details like return format, authentication needs, read-only nature, or scope of column info (types, constraints).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no wasted words. It is front-loaded with the action ('获取') but lacks any structural elements like examples or 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 4 parameters, no parameter descriptions, no annotations, and sibling tools, the description is too minimal. It does not clarify parameter roles, output behavior, or when to prefer this over similar tools like 'archery_describe_table'.
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% and the description adds no parameter-level meaning. Parameters like 'db', 'site', and 'instance' are not explained; the agent must infer their roles from the schema alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description '获取表的字段列表' (get field list of table) clearly states the action (list columns) and the resource (table), which is specific and distinct from siblings like 'archery_query' or 'archery_describe_table'.
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 usage guidance is provided; the description does not specify when to use this tool versus alternatives (e.g., 'archery_describe_table'), nor does it mention prerequisites or limitations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
列出实例下的数据库列表（SHOW DATABASES）。
| Name | Required | Description | Default |
|---|---|---|---|
| site | No | cn | |
| instance | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description bears full responsibility for behavioral disclosure. It only states that the tool lists databases (a read operation), but it does not explain what happens when 'instance' is null, what the 'site' parameter controls, or any side effects. The behavioral profile is severely under-documented.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, which is concise but lacks structure. Important information is missing, so the brevity sacrifices completeness. The sentence is clear and front-loaded with the purpose, but it does not earn its place by covering necessary details.
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 no parameter explanations, no usage guidance, and no behavioral details beyond the listing action, the description is incomplete for practical use. The presence of an output schema helps document return values, but the input side remains opaque. Given the tool's complexity (simple but with two unexplained parameters), more context is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, meaning the schema itself provides no parameter explanations. The description also fails to explain the 'site' and 'instance' parameters, their allowed values, or how they affect the listing. With no parameter semantics anywhere, the agent cannot correctly invoke the tool without external knowledge.
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 lists databases under an instance and provides the SQL equivalent 'SHOW DATABASES'. This is a specific verb (list) and resource (databases), and it naturally distinguishes from siblings like archery_list_instances (list instances) and archery_list_columns (list columns).
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 usage guidelines are provided. The description does not indicate when to use this tool versus alternatives like archery_list_instances or archery_query, nor does it mention prerequisites (e.g., needing an instance identifier first) or typical workflow context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
列出 Archery 实例别名映射（短名 -> 真实实例名，按站点分组）。
返回结构明确标注每个别名归属的 site（cn/aws），调用方据此显式传 site， 避免「用 cn 站点查 aws 实例」导致的「未关联该实例」歧义错误。
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
无注释，描述承担全部透明度责任。它说明了操作是列出映射并按站点分组，返回结构包含site信息。但未明确声明该操作是否只读、是否需要权限、是否有数据一致性保证等。考虑到工具无参数且行为简单，基本行为已披露，但缺少一些常见透明声明（如只读提示）。
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?
描述仅两行，第一句点明功能，第二句解释输出用途和避免的错误。无冗余信息，完全前置负载，每个句子都有价值。
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?
工具无参数，有输出模式（但未提供）。描述已足够完整：说明做什么（列出映射），输出中包含什么（site分组），以及为什么重要（避免歧义）。对于这样一个简单工具，无需更多细节。
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?
工具无参数，根据规则基线为4。描述未涉及参数语义，因为不存在参数，且模式覆盖率为100%（空模式），无需额外解释。
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?
描述明确说明工具功能：列出Archery实例别名映射（短名->真实实例名，按站点分组）。动词"列出"与特定资源"实例别名映射"结合，且与兄弟工具（如archery_query、archery_describe_table）明显区分，后者操作数据或查询其他信息。
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?
描述指出调用方应根据返回的site显式传参以避免歧义错误，隐含了使用场景（在查询实例前先获取映射关系）。但没有明确说明何时不使用或替代品，不过上下文已足够清晰，偏差较小。
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
执行 SQL 查询（只读）。
site=cn 国内 / aws 日本云。instance 可用别名：prod/prod-ro/dev/test。 db 默认 srm。仅允许 SELECT/SHOW/DESC/EXPLAIN/WITH 前缀。
| Name | Required | Description | Default |
|---|---|---|---|
| db | No | ||
| sql | Yes | ||
| site | No | cn | |
| limit | No | ||
| instance | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
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 read-only behavior and allowed SQL prefixes, and gives site/instance aliases. However, it does not mention behavior like result limits, error handling, or data size implications, which are important for a 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?
The description is extremely concise (three lines), front-loaded with the core purpose, and every sentence adds value. No wasted words or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 5 parameters, an output schema, and no annotations, the description covers the main aspects (purpose, allowed SQL, site/instance/db defaults) but omits the limit parameter and does not explain how to interpret the output or handle errors. This leaves some gaps in 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?
With 0% schema description coverage, the description compensates well by explaining the site parameter (cn vs aws), instance aliases (prod/prod-ro/dev/test), db default (srm), and the sql parameter (allowed prefixes). The limit parameter is not mentioned, but overall the description adds significant meaning 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 'Execute SQL query (read-only)' and specifies allowed SQL prefixes (SELECT/SHOW/DESC/EXPLAIN/WITH), making the purpose clear. However, it does not explicitly differentiate from sibling tools like archery_describe_table or archery_list_databases, though the context implies this is for arbitrary read-only queries.
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 usage context (site, instance aliases, default db, allowed SQL prefixes) but does not explicitly state when to use this tool versus alternatives. It implies it's for custom read-only queries, but lacks direct guidance on alternatives or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
查询租户信息（hpfm_tenant）。tenant 为空时列出前 100 个租户。
盘古专属能力：sql-ops-mcp 未覆盖的多租户查询。 site=cn 国内 / aws 日本云(JP-SaaS-1)。instance 可用别名： cn: prod/prod-ro/dev/test；aws: aws(=aws-prod, 正式环境 JP-SaaS-1-Prod-RW-8.0)。
| Name | Required | Description | Default |
|---|---|---|---|
| db | No | ||
| site | No | cn | |
| tenant | No | ||
| instance | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses that when tenant is empty the tool returns the first 100 tenants, implying a limit. It also details site and instance configuration behavior. However, it does not state whether the operation is read-only, destructive, or requires special permissions, nor does it cover error behavior or rate limits. The provided behavioral insight is useful but incomplete.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, with the purpose and default behavior in the first sentence. Subsequent lines add environment details and a note on exclusivity. It is front-loaded and free of redundancy. Slightly more could be trimmed, but it efficiently conveys critical information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 4 optional parameters, an output schema, and multiple siblings, the description covers purpose, default behavior, and environment configuration for site/instance. It misses the db parameter's purpose and does not explain prerequisites or error cases. It is adequate for basic usage but leaves the db parameter ambiguous.
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 tenant parameter's effect (default listing behavior), and provides detailed aliases and meanings for site and instance. The db parameter is not explained, leaving a gap. Overall, the description adds significant meaning beyond the schema for three of four 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 tool queries tenant information from hpfm_tenant, with specific behavior when tenant is empty (lists top 100). It distinguishes itself from siblings like archery_query and general sql-ops-mcp by being a dedicated multi-tenant query tool, which is a specific resource and verb.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for tenant queries and provides environment context (site and instance aliases). It mentions this is a Pangu exclusive capability not covered by sql-ops-mcp, which differentiates usage. However, it does not explicitly state when not to use it or list alternatives beyond the exclusivity note. The guidance is clear 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.
通过猪齿鱼 hfle 接口将附件 URL 解析为可下载的签名地址。
| Name | Required | Description | Default |
|---|---|---|---|
| file_url | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It states the tool resolves to a signed download address, implying it is a read/transform operation. It does not mention authorization requirements, rate limits, or what happens if the URL is invalid. The description is adequate but lacks depth for a full behavioral picture.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that fully conveys the tool's core action. Every word is meaningful, and it is front-loaded with the tool's purpose. No unnecessary information is 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?
The tool has one parameter, no nested objects, and an output schema exists. The description is minimal but complete enough given this low complexity: it explains what the tool does with the single input. It does not detail the output, but the output schema can handle that. Remaining gaps (e.g., error cases) are minor.
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 the description must compensate. It succinctly explains the purpose of the file_url parameter: it is an attachment URL to be resolved. While no additional syntax or format details are given, for a single required parameter with a self-explanatory name, this provides sufficient meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool converts an attachment URL to a downloadable signed address via the hfle interface. However, it does not explicitly differentiate from siblings like choerodon_list_attachments, which lists attachments but does not download them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when needing to download an attachment, but provides no guidance on when to avoid using it, no prerequisites, and no comparison to alternatives. Given the tool has only one required parameter, the context is clear but minimal.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
获取猪齿鱼项目状态映射（状态名 -> 加密 id），供列表过滤用。
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral transparency. It informs that the map is from 'status name -> encrypted id', which adds some value, but does not disclose whether the operation is read-only, requires authentication, or any side effects. The output schema exists but the description does not explain the return format beyond the mapping.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that clearly states the tool's purpose and the mapping direction. It fronts the key information without extraneous details, earning its place efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has one parameter with a default, an output schema, and no nested objects, complexity is low. The description adequately specifies the mapping direction and use case, but lacks details on authentication requirements, error cases, or how the output schema extends the description. It is minimally complete for the complexity level.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has only one parameter (project_id) with 0% description coverage but a default value. The description states it is 'for a specific project' but does not elaborate on the parameter's meaning, format, or how to obtain a valid project_id. Given the low parameter count and the marginal clarification, a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves a status map for a specific project, mapping status names to encrypted IDs. The purpose is specific and distinguishes it from siblings like 'choerodon_query_issue' which query issues, not status maps.
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 mentions the tool is 'for list filtering', which implies when to use it, but provides no guidance on when not to use it or alternatives. It does not explain prerequisites for the project_id parameter or when this tool is preferred over other sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
查看猪齿鱼任务的附件列表（文件名 + URL）。
| Name | Required | Description | Default |
|---|---|---|---|
| issue_id | Yes | ||
| project_id | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist to provide hints like read-only or destructive behavior. The description only states what the tool returns (filenames+URLs) but does not disclose authentication needs, rate limits, error scenarios, or whether the list is paginated or subject to permissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that efficiently states the tool's purpose. No wasted words, front-loaded with the core action.
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?
Despite having an output schema (not shown), the description is terse for a tool with 2 parameters and no annotation coverage. It does not mention pagination, sorting, error handling, or scope of attachments (e.g., all files or just those with URLs). Adequate for a simple list but lacking completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, meaning the properties in the input schema have no descriptions. The tool description adds no explanation of parameters; it does not specify that issue_id is required, nor does it clarify the role of project_id (optional, default empty string). The agent must guess parameter meanings from names alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it lists attachments for a task, including filenames and URLs. It uses specific verb+resource and distinguishes from sibling tools like 'choerodon_download_attachment' (downloads a single attachment) and 'choerodon_list_issue' (lists issues).
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 (e.g., download vs list). No prerequisites or exclusions are mentioned. The description leaves the agent to infer usage from sibling tool names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
条件查询猪齿鱼任务列表。
keyword 为概要模糊搜索；assignee 为经办人姓名（自动解析成员）； status 为状态名（自动解析状态 id）。返回任务摘要列表。
| Name | Required | Description | Default |
|---|---|---|---|
| size | No | ||
| status | No | ||
| keyword | No | ||
| assignee | No | ||
| project_id | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It discloses that keyword does fuzzy search on summary, and that assignee/status auto-resolve. However, it does not mention whether the operation is read-only, what happens with empty filters (returns all?), pagination behavior, or performance constraints. This is adequate but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact (two sentences) and front-loaded with purpose. Every sentence adds value. However, it could be slightly more structured (e.g., listing parameters clearly) and fully cover all 5 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?
There is an output schema (not shown in detail), so the description doesn't need to explain return values. The tool has 5 parameters with 0% schema coverage, so the description's partial coverage of 3/5 parameters leaves gaps (project_id and size unmentioned). For a list tool, pagination and scope are important – not explained. Adequate but not complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% (all parameters have no descriptions in JSON Schema), so the description must compensate. It explains keyword (fuzzy on summary), assignee (name auto-resolves to member), and status (name auto-resolves to id). size and project_id are not explained – they have default values but project_id is critical context. Still, the description adds significant meaning beyond skeleton schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states '条件查询猪齿鱼任务列表' (query Choerodon task list with conditions), which is a specific verb+resource. It distinguishes from siblings like 'choerodon_query_issue' (likely single issue) and 'choerodon_search_tasks_by_person' (by person) by being a list with multiple filters.
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 explains what each parameter does and notes that assignee and status are auto-resolved, which helps usage. However, it does not explicitly say when to use this tool versus sibling tools like choerodon_search_tasks_by_person or choerodon_query_issue, nor does it provide exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
查询猪齿鱼单个任务/缺陷详情（含附件列表）。
issue_id 为工单加密 ID（来自列表结果）；project_id 可选,默认用 CHOERODON_PROJECT_ID。 返回 summary/状态/优先级/类型/创建人/描述(HTML)/附件。
| Name | Required | Description | Default |
|---|---|---|---|
| issue_id | Yes | ||
| project_id | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description implies a read-only operation (querying details) and lists returned fields (summary/status/优先级/类型/创建人/描述/附件). However, it does not disclose if the operation has side effects, authorization requirements, or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact (3 lines), front-loaded with the purpose, and each sentence adds value: first line states the action, second explains parameters, third lists return fields.
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 no output schema provided, the description lists key return fields and attachments, which is sufficient for an agent to assess result usage. It covers the core behavior despite missing edge cases like empty results or error handling.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description bears full burden. It clarifies that issue_id is an 'encrypted ID from list results' and project_id defaults to CHOERODON_PROJECT_ID, adding essential context not in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('查询...单个任务/缺陷详情') and resource ('含附件列表'), distinguishing it from siblings like 'choerodon_list_issue' which lists issues, while this retrieves a single item with attachments.
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 specifies that issue_id is a required encrypted ID from a list and project_id is optional with a default. However, it does not explicitly mention when not to use this tool vs alternatives like 'choerodon_list_attachments' for attachments alone.
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 |
|---|---|---|---|
| name | Yes | ||
| size | No | ||
| project_id | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals the internal two-step process (lookup members then filter tasks), which is helpful. However, it does not mention other important behaviors such as authentication requirements, error handling, or what happens if the member is not found.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that efficiently conveys the core purpose and workflow. It is front-loaded with the action and resource, with no redundant or irrelevant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 3 parameters (one required), no annotations, and no parameter descriptions in the schema, the description is insufficient for complete understanding. It omits parameter semantics, usage boundaries, and behavioral details beyond the two-step process. The existence of an output schema does not compensate for these 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 parameter meaning. The description implies that the 'name' parameter is the person's name, but it does not explain 'size' (default 50) or 'project_id' (default ''). Parameters are only partially covered, leaving significant ambiguity for correct invocation.
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 'search' and the resource 'tasks by person name', with additional explanation of the two-step process (first look up members, then filter). This distinguishes it from sibling tools like choerodon_query_issue or choerodon_search_users, which have different scopes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no explicit guidance on when to use this tool versus alternatives (e.g., choerodon_query_issue, choerodon_list_issue). It implies the use case (search tasks by person name) but does not mention when not to use it or suggest other tools for different scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
按姓名模糊搜索猪齿鱼项目成员（返回加密 id / 真实名 / 登录名）。
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| size | No | ||
| project_id | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
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 'fuzzy search' as a behavioral trait but does not disclose side effects, authentication needs, rate limits, pagination, or error behavior. Important details like what happens with no results or empty input are omitted.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, very concise and front-loaded with the action. It is well-structured and avoids unnecessary words. However, it could include a bit more detail without losing conciseness, such as parameter explanations or usage hints.
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?
Despite having an output schema and 3 parameters, the description is minimal. It mentions return fields but does not explain parameters or usage context. The tool is simple, but the description lacks completeness for effective agent invocation, especially regarding the size and project_id parameters.
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 the description adds no explanation for the parameters. The description only mentions 'by name' which aligns with the required 'name' parameter, but it does not explain the optional 'size' (default 50) or 'project_id' (default ''). The schema itself provides no descriptions, so the tool is poorly documented for parameter usage.
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: fuzzy search for Choerodon project members by name. It specifies the return fields (encrypted id, real name, login name). It distinguishes from sibling tools like choerodon_query_issue or choerodon_list_issue, which deal with issues, not users.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly state when to use this tool versus alternatives. It implies usage for searching users by name, but no guidance on when not to use it or what prerequisites exist. The context of sibling tools indirectly suggests the domain, but explicit guidelines are missing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
列出指定日志平台的 Loki 数据源（用于确认环境名与数据源名映射）。
| Name | Required | Description | Default |
|---|---|---|---|
| region | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavior. It only mentions listing data sources for mapping, but does not describe if the list is full or filtered, if it requires specific permissions, or if it returns any live status. The behavioral disclosure is minimal and insufficient for a tool with no annotation fallback.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the purpose. It earns its place by clarifying the tool's intent (mapping confirmation), but could be slightly more efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has one parameter, no annotations, and an output schema (not shown). The description partially explains the tool's purpose but lacks key context such as output structure, required permissions, or when to use sibling tools. Given the simplicity, it is minimally adequate but could be more self-sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It mentions '指定日志平台' (specified log platform) which hints at the 'region' parameter, but adds no detail about valid values or format. The schema defines one required parameter with no additional info, so the description adds some context but not enough to fully interpret the parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the tool lists Loki data sources for a specified log platform, and clarifies its purpose is to confirm the mapping between environment names and data source names. The verb '列出' (list) and resource 'Loki 数据源' are clear, but it does not differentiate from siblings that also query log platforms like obs_log_query.
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 vs. alternatives like obs_log_query. The description implies first-step use for mapping, but does not state that obs_log_query should be used for actual log searching or that this tool is a prerequisite.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
查询日志（Loki）。
区分两套平台：region=aws 查 AWS 海外(jp-saas-1)，region=cn 查国内公有云。 国内非 prod 已切换至 Loki 风格，地址 logs.going-link.net。 query 为 LogQL 表达式，如 '{app="srm-gateway"} |= "403"'。 time_range 支持 30m/2h/1d/today/yesterday 或 "YYYY-MM-DD HH:mm~HH:mm"（北京时间）。
| Name | Required | Description | Default |
|---|---|---|---|
| env | Yes | ||
| limit | No | ||
| query | Yes | ||
| region | Yes | ||
| to_time | No | ||
| direction | No | BACKWARD | |
| from_time | No | ||
| time_range | No | 2h |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the burden of behavioral disclosure. It explains query language (LogQL), time range formats, and platform-specific details. However, it does not disclose what happens on error (e.g., invalid query), pagination limits, or authentication requirements. Enough for a 3, but not higher.
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 very compact with only a few sentences, each adding unique value. It is well-structured with bullet-like insights (region split, LogQL example, time_range formats). No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 8 parameters (3 required) and an output schema, so completeness is judged against this complexity. The description covers the key custom parameters well (region, query, time_range) but omits mention of 'env', 'limit', 'direction', and temporal bounds. Still sufficient for most use cases given the LogQL focus.
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 adds meaning to 'query' (LogQL examples), 'time_range' (accepted formats), and 'region' (platform mapping). However, it does not cover all 8 parameters (e.g., 'env', 'limit', 'direction', 'from_time', 'to_time'). Still, the most critical ones are well-explained.
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 queries logs (Loki), and distinguishes between two platforms (region=aws vs region=cn) with specific addresses. It also provides practical details about query syntax (LogQL) and time range formats, making the purpose very specific and actionable.
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 each region (aws vs cn) and mentions a sibling context indirectly by noting that domestic non-prod has switched to Loki style. However, it does not explicitly compare this tool against sibling tools like obs_sls_query or provide exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
查询阿里云 SLS 日志（仅 cn 国内盘古 prod 用阿里云日志；非生产请走 Loki）。
仅 environment=prod 适用（project=pangu-cn-saas-3-prod-shared-sls-project-0）。 盘古 dev/test 等非生产环境日志在 Loki，应使用 obs_log_query(region="cn")。 传入 trace_id 做「ERROR/WARN + 全链路」两阶段查询;否则用 keyword, 自动加上 namespace 过滤。level 默认 ERROR(传空则不过滤级别)。
| Name | Required | Description | Default |
|---|---|---|---|
| level | No | ERROR | |
| limit | No | ||
| system | No | 盘古 | |
| keyword | No | ||
| to_time | No | ||
| trace_id | No | ||
| from_time | No | ||
| time_range | No | 最近2小时 | |
| environment | No | prod |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It discloses automatic _namespace_ filtering, default level=ERROR, and trace_id behavior. However, it does not mention return format, pagination, rate limits, or whether results are ordered. It also does not explicitly state it's a read-only operation (though implied by 'query').
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact (three paragraphs with clear separation of environment, query modes, and defaults). Every sentence adds value. Minor nit: environment constraint could be consolidated for brevity, but overall well-structured and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 9 parameters, 0% schema coverage, and no annotations, the description does a good job covering environment constraints, query modes, and default level. However, it lacks documentation for time-range parameters (from_time, to_time, time_range), limit, and system, and does not describe the output schema behavior that exists. A complete description would cover all parameter behaviors and return value structure.
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 purpose of trace_id, keyword, level, environment, and the two-phase query approach. However, it doesn't explain time_range, from_time, to_time, limit, or system parameters in detail. The narrative context adds meaning beyond the schema titles but leaves some parameters underspecified.
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 queries Alibaba Cloud SLS logs, provides the exact project name, and distinguishes it from the Loki-based alternative. The verb '查询' (query) combined with the specific resource '阿里云 SLS 日志' makes the purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states this is only for cn Pangu prod (environment=prod), and instructs to use obs_log_query(region='cn') for non-prod environments. It also specifies two query modes: trace_id for two-stage ERROR/WARN + full trace, or keyword otherwise. This provides clear when-to-use and when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
跨本地代码仓库搜索（内容 / 文件名 / 模块结构）。
mode: content(内容搜索,返回命中行与上下文) / filename(文件名模糊匹配) / modules(列出服务-模块-层结构)。 扫描根目录由 PG_ROOT 指定(默认本仓库根)。max_results 限制命中数量, context 为内容搜索上下文行数,depth 为递归深度。
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | content | |
| depth | No | ||
| context | No | ||
| keyword | Yes | ||
| max_results | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description is the sole source of behavioral information. It effectively discloses key behaviors: the scanning root directory (controlled by PG_ROOT), default repository root, and effects of parameters like max_results, context (line count for content), and depth (recursion depth). The 'content' mode's behavior of returning hit lines with context is transparent. A slight gap is the lack of explicit statement about non-destructive nature.
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, using only four sentences. The first sentence introduces the tool's purpose and modes, front-loading key information. Each subsequent sentence explains parameters efficiently without redundancy. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 5 parameters (2 defaults omitted from schema description), 0% schema coverage, no annotations, but includes an output schema, the description is quite complete. It explains the three modes, all parameters, and their effects. However, a missing detail is how the 'modules' mode output is structured (returns a tree?), which is important given no annotation for output schema contents. The output schema exists but isn't described.
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 add meaning beyond the schema. It successfully explains that 'mode' selects among three types (content, filename, modules), 'context' adds lines around hits in content mode, 'depth' controls recursion, 'max_results' limits total hits, and 'keyword' is the search term. This covers the purpose of each parameter, though 'keyword' could be clarified (e.g., regex vs exact).
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 across local code repositories with three specific modes: content (hits and context), filename (fuzzy matching), and modules (service-module-layer structure). The verb 'search' along with the detailed mode differentiation provides a precise understanding of the tool's purpose.
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 explains the three search modes and their intended use cases (content, filename, modules), providing clear guidance on when to use each. However, it does not explicitly exclude alternative tools or mention when NOT to use this tool compared to siblings like 'obs_log_query' or 'archery_query', preventing a score of 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0archery_describe_tablearchery_list_columnsarchery_list_databasesarchery_list_instancesarchery_queryarchery_query_tenantchoerodon_download_attachmentchoerodon_get_status_mapchoerodon_list_attachmentschoerodon_list_issuechoerodon_query_issuechoerodon_search_tasks_by_personchoerodon_search_usersobs_log_datasourcesobs_log_queryobs_sls_querysearch_repoScored across 17 tools
Each tool serves a distinct purpose within its domain: log query tools are clearly separated by data source (Loki vs. SLS) and environment, database tools cover different schema operations, and issue tools handle specific retrieval tasks. No two tools overlap in function.
Most tools follow a consistent 'service_operation' pattern (e.g., obs_log_query, archery_query, choerodon_list_issue). The only deviation is 'search_repo' which lacks the service prefix, but it still uses a clear verb_noun format. Overall naming is predictable and readable.
17 tools covering logging, database operations, issue tracking, and code search is on the higher side but justified given the diverse domains. Each tool serves a specific need, and the count is appropriate for the server's multi-purpose scope.
The tool surface is heavily read-oriented: logging and database tools allow querying but not modification. Issue tracking is particularly incomplete, lacking create, update, and delete operations. Agents will encounter dead ends when trying to perform standard CRUD workflows.
Query application logs, traces, and metrics from your AI coding assistant via Foam's MCP server.
The Cortex MCP server provides read-only access to real-time engineering context from the Cortex developer portal, allowing AI coding assistants to answer natural language questions about your organization's catalog (microservices, libraries, domains, teams, infrastructure), scorecards (engineering standards and best practices), initiatives (goals and deadlines), and Engineering Intelligence metrics. It includes tools for querying documentation, tracking personal entities, and accessing AI-assisted insights across the entire Cortex ecosystem.
Search your AI chat history (ChatGPT, Claude, Codex) from any MCP client. Remote, private, read-only
Agent-native launch platform and tool directory: search, alternatives, trending, launch via MCP.
