Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@mdymcp list my pending workflow approvals"
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.
⬆️ 已装过的用户升级
升级程序（推荐这条，绕开 uv 索引缓存偶发不更新）：
uv tool install --force --refresh mdymcp（或
uv tool upgrade mdymcp；升完重启 IDE / 重开会话。）0.5.x（v1 token 多机集中刷新）
单机用户：升级程序即可，无需任何改动（默认仍是本地刷新，全向后兼容）。
多台机器/服务器共用同一明道账号：必须切「服务器集中刷新」。原因——多端各自持有 token 各自刷新，明道每次 refresh 都轮换 refresh_token，会把彼此顶成孤儿（
error_code 10101）。 把刷新集中到一台常驻服务器当唯一 owner，其余端只读：在做初始部署的那台跑mdymcp-install选[2] 服务器集中（或mdymcp-server-setup），其余机器把生成的~/.mdymcp/server_token_key+.env里 4 个MD_V1_TOKEN_*拷过去（别在其余机器重新授权）。详见server/README.md。⚠️ 若某个项目自己的 venv 里也
import mdymcp（不是只走全局 binary），那份要单独升：uv pip install --python <项目>/.venv/bin/python -U mdymcp。0.3.0（HAP 改用个人 PAT）— 仍停在 0.2.x 的老用户才需要
0.3.0 起 HAP 改用个人 PAT，不再走旧的
refresh_token / hap_key。去 https://www.mingdao.com/personal?type=pat 生成 PAT（pat_开头），然后任选其一：
省事：重跑
mdymcp-install，走到 HAP 步骤粘进去；手动：编辑
~/.mdymcp/.env，删掉MD_HAP_KEY/MD_HAP_REFRESH_TOKEN/MD_HAP_TOKEN，加上MD_HAP_PAT=pat_xxx。
Related MCP server: mingdao-mcp-server
macOS / Linux
curl -LsSf https://raw.githubusercontent.com/andyleimc-source/mdymcp/main/install.sh | shWindows（PowerShell）
powershell -c "irm https://raw.githubusercontent.com/andyleimc-source/mdymcp/main/install.ps1 | iex"脚本做三件事：
检测 uv，没装就从官方源装上（uv 会自己拉合适的 Python，你机器上是 3.14 / 3.9 还是没装都没关系）
uv tool install mdymcp
启动 mdymcp-install 交互向导 —— 浏览器 OAuth 拿 v1 凭据 → 自动打开 HAP 个人 PAT 页粘 MD_HAP_PAT → 让你选范围（用户级/项目级/两个都要）+ 编号多选要注册的 IDE → 检测到 Claude Code 时自动安装 mdymcp skill（使用心智 + 故障 SOP）到 ~/.claude/skills/mdymcp/
配置写在 ~/.mdymcp/.env（Windows: %USERPROFILE%\.mdymcp\.env），跨目录都能用。
装完后想重跑：mdymcp-install
明道（Mingdao）统一 MCP Server —— 一次安装，98 个工具：
v1 协作 API（50 个，本地实现）：动态 / 日程 / 私信 / 收件箱 / 群组 / 用户 / 组织 / 个人账户
HAP 网关（48 个，透明代理 api2.mingdao.com/mcp）：应用 / 工作表 / 记录 / 角色成员 / 工作流审批 / 图表 / 选项集 / 知识库 / 地区组织
HAP 工具由远端网关动态提供；具体参数 schema 以启动时 tools/list 返回的为准。
IDE | 配置文件 | 支持范围 |
Claude Code |
| 用户级 + 项目级 |
Codex CLI |
| 用户级 |
Cursor |
| 用户级 + 项目级 |
Windsurf |
| 用户级 |
Gemini Antigravity |
| 用户级 |
Trae（含国内版 Trae CN） | mac: | 用户级 |
VS Code（Copilot Chat） |
| 项目级 |
mdymcp-install 会自动检测已装的 IDE，范围 + 客户端两个问题你挑完即可。手动指定：mdymcp-install --client=cursor,windsurf,trae（--client=all 全装）。
Antigravity：写完后去 IDE 里「Manage MCP Servers → Refresh」一下才能看到 mdymcp。
Cursor / Windsurf / Trae / VS Code：通常需要重启 IDE 或在 MCP 设置里手动刷新。
mdymcp-install走到 HAP 步骤时会自动开浏览器到 PAT 页，复制粘贴即可。
PAT 页：https://www.mingdao.com/personal?type=pat
已登录 → 直接在页面生成/管理个人 PAT（pat_ 开头）。
未登录 → 先登录，会自动跳回该页。
复制 pat_xxx，在向导提示 MD_HAP_PAT: 时粘进去即可。PAT 本身就是 Bearer token，长期有效、你自己可随时吊销重发，无需服务端交换。留空 = 跳过 HAP，只用 v1 工具。
┌──────────────────────┐ stdio ┌──────────────────────────────┐
│ Claude Code / Cursor │──────▶│ mdymcp.server │
│ / Codex / Windsurf / │ ├──────────────────────────────┤
│ Antigravity / Trae / │ │ [静态注册] 50 个 v1 工具 │──┐
│ VS Code Copilot │ ├──────────────────────────────┤ │HTTP
└──────────────────────┘ │ [动态注册] HapGateway │──┤
│ 48 个 HAP 工具（透明代理） │ │
└──────────────────────────────┘ ▼
┌──────────────────────────────────────┐
│ api.mingdao.com/v1/* (v1 API) │
│ api2.mingdao.com/mcp (HAP gateway) │
└──────────────────────────────────────┘v1 access_token | HAP token | |
install 时 | 本地 OAuth → token 写入 | 粘 PAT → |
运行时 | 本地 token 文件，过期用 refresh_token 本地续期 | 直接用 |
缓存 TTL | 跟随明道下发的 expires_in（已发布应用 7 天） | 不需要（PAT 即 token） |
v1 token 全程本地：mdymcp-auth 授权一次拿 access_token + refresh_token 落盘（chmod 600），过期自动用 refresh_token（14 天有效）续期，refresh 也过期才需重新授权。app_key/app_secret 内嵌在包里（公共客户端模式，同 Google/GitHub CLI），零配置。已有旧凭据（MD_ACCOUNT_ID/MD_KEY）且未授权的机器回落老的远端 hook 链路。HAP 直接用 .env 里的 PAT 当 Bearer token。HAP 网关握手失败时不崩 server，仅跳过远端工具注册，v1 工具仍可用。
多机共用同一账号？用 server 模式。 多台机器/服务器持同一对 token 会互相抢刷（明道每次 refresh 都轮换 refresh_token），把对方顶成孤儿（error_code 10101）。把刷新集中到一台常驻服务器当唯一 owner：跑一次 mdymcp-server-setup（或 bash server/provision.sh <IP> <user>），其余机器只读、永不刷新。详见 server/README.md。
~/.mdymcp/.env（或各 IDE 的 MCP JSON 里的 env 块）：
# HAP 网关 PAT（在 https://www.mingdao.com/personal?type=pat 生成，pat_ 开头）
MD_HAP_PAT= # install 时粘贴；留空 = 跳过 HAP
# 可选（通常不用动）
# MD_APP_KEY= / MD_APP_SECRET=<换成自己的 OAuth 应用>
# MD_CALLBACK_PORT=8080
# 旧链路回落（未配 MD_APP_SECRET 时才用）
# MD_ACCOUNT_ID= / MD_KEY= / MD_HOOK_URL=现象 | 解决 |
| 重开终端；或 |
curl / irm 拉 astral.sh 失败 | 走代理；或从 https://github.com/astral-sh/uv/releases 下载 tarball 手动解压到 |
Windows 下 | 管理员 PowerShell： |
| 跑 |
| 去 https://www.mingdao.com/personal?type=pat 重新生成 PAT，更新 |
IDE 里看不到 mdymcp | 重启 IDE；或在 IDE 的 MCP 设置里点 Refresh。GUI 启动找不到 |
启动显示 |
|
HAP 工具返回 | HAP 后端既有问题（Node 版也有），非 mdymcp bug |
明道开放平台：https://open.mingdao.com/document
MIT
给日程添加成员。member_ids 逗号分隔（明道用户），invited_accounts 为非明道用户（格式 ["电话","邮箱"]）。
| Name | Required | Description | Default |
|---|---|---|---|
| event_id | Yes | ||
| member_ids | No | ||
| invited_accounts | No | ||
| event_recurring_time | No | ||
| modifying_all_recurring_events | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; the description only states the action (add members). It does not disclose side effects (e.g., notifications), permissions, or behavior for recurring events. The recurring-event parameters are mentioned in schema but not explained.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with no wasted words. Purpose first, followed by parameter details. Highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Lacks completeness for an agent to use correctly. Does not explain required field (event_id), recurring event handling, or return output. For a 5-parameter tool with no output schema, the description is too sparse.
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%. The description adds meaning for member_ids and invited_accounts (format and user types), but fails to explain event_id (required), event_recurring_time, and modifying_all_recurring_events. Covers 2 of 5 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 it adds members to a schedule/event. It distinguishes between internal (member_ids) and external (invited_accounts) members, but does not explicitly differentiate from sibling tools like calendar_edit_event.
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 format guidelines for member_ids (comma-separated) and invited_accounts (array format ['phone','email']). Implies when to use each parameter, but does not state when not to use the tool or suggest alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
创建日程。日期格式 YYYY-MM-DD HH:MM。member_ids 用逗号分隔多个用户ID。
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| address | No | ||
| end_date | Yes | ||
| begin_date | Yes | ||
| member_ids | No | ||
| category_id | No | ||
| remind_time | No | ||
| repeat_times | No | ||
| reminder_type | No | ||
| repeat_interval | No | ||
| is_all_day_event | No | ||
| is_private_event | No | ||
| repeat_frequency | No | ||
| event_description | No | ||
| is_recurring_event | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description only reveals date format and member_ids format. It does not disclose behavioral traits like creation limits, validation, or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences and to the point. It could be improved by structuring parameter hints but is efficient for its length.
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 15 parameters, no output schema, and no annotations, the description is far from complete. Essential details like required parameters (name, begin_date, end_date) are not explicitly noted.
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 only mentions date format and member_ids, leaving 13 of 15 parameters unexplained. This is insufficient for the agent.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states '创建日程' (create schedule), indicating the tool creates a calendar event. It provides date format and member_ids format, and distinguishes from siblings like calendar_edit_event.
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 calendar_edit_event or calendar_remove_event. The description lacks context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
修改日程属性（名称、时间、地点、描述等）。日期格式 YYYY-MM-DD HH:MM。
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | ||
| address | No | ||
| end_date | No | ||
| event_id | Yes | ||
| begin_date | No | ||
| repeat_times | No | ||
| repeat_weekday | No | ||
| repeat_end_date | No | ||
| repeat_interval | No | ||
| is_all_day_event | No | ||
| repeat_frequency | No | ||
| event_description | No | ||
| is_recurring_event | No | ||
| event_recurring_time | No | ||
| modifying_all_recurring_events | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations, and description only states purpose without disclosing behavioral traits like auth needs, rate limits, or potential destructive effects.
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?
Very short but lacks structure; could benefit from separating attributes and date format.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Incomplete for 15 parameters, no output schema, no annotations; missing return behavior and explanation of recurring event interactions.
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?
Only lists a few attributes (name, time, location, description) and date format, but fails to explain 15 parameters, especially recurring fields. Schema coverage 0%.
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 modifies calendar attributes (name, time, location, description) and provides date format. Distinguishes from sibling tools like create or remove.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives, no prerequisites or exclusions mentioned.
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 |
|---|---|---|---|
| event_id | 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 'get details' without mentioning read-only nature, authentication, rate limits, or what '详细信息' entails. Lacks transparency beyond the obvious.
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 in Chinese with no redundancy. It is front-loaded and efficient, but could benefit from additional structured details without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, so the description should clarify what '详细信息' includes (e.g., fields like time, attendees). It is vague for a detail-retrieval tool. Without annotations, the description is insufficiently 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 description coverage is 0%, and the description does not elaborate on the event_id parameter. While the parameter name is self-explanatory, the description adds no value beyond the schema. For a tool with 0% coverage, more explanation is expected.
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 (get) and resource (single schedule details). It distinguishes from list operations like calendar_get_events by specifying '单个' (single). However, it closely mirrors the tool name, lacking additional context.
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 siblings such as calendar_get_events (list) or calendar_get_unconfirmed_events. The description implies fetching details of a single event but does not explicitly state when it is appropriate or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
获取日程列表。通过日历订阅接口拉取 iCal 数据并解析。
日期格式 YYYY-MM-DD（北京时间）。
不传日期：默认取 [今天-30, 今天]（订阅 feed 通常只到当天，查未来多为空）。 全量约 2600+ 条会撑爆上下文，故有默认范围，需更早请显式传 start_date。
organizer：按组织者过滤（邮箱或姓名子串，大小写不敏感）。看某人日程用这个， 例：organizer="phil.ren" 查任向晖。
keyword：按标题(summary)子串过滤。
limit：最多返回条数（默认 200），超出按时间倒序截断并标记 truncated。
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| keyword | No | ||
| end_date | No | ||
| organizer | No | ||
| start_date | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
无注释，但描述充分披露了行为：通过iCal订阅拉取解析、日期格式（YYYY-MM-DD北京时间）、默认范围、过滤逻辑、limit截断并标记truncated。无矛盾。
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?
无输出模式，但描述了返回截断标记。未说明返回字段，但考虑到是列表工具，基本够用。对iCal订阅来源的解释增加了上下文。
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为0%，但描述为所有5个参数提供了详细语义：start_date/end_date的默认值、organizer和keyword的匹配规则（子串、大小写不敏感）、limit的默认值和截断行为。完全补偿了结构描述不足。
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?
描述明确说明工具用于“获取日程列表”，动词+资源明确。虽然未明确与兄弟工具如calendar_search区分，但通过解释iCal订阅来源和参数过滤，用途清晰。
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?
描述详细说明了何时使用：按日期、组织者、关键词筛选日程。给出了默认行为（不传日期时的范围）和示例（organizer='phil.ren'），帮助选择是否使用此工具而非其他。还说明了limit默认值和截断行为，指导用户避免上下文溢出。
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 |
|---|---|---|---|
| page_size | No | ||
| page_index | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description indicates it's a read operation, but with no annotations, it does not disclose authentication needs, pagination behavior, or output format, which is minimal but adequate for a simple tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence, but it is only in Chinese; an English translation would improve accessibility for multilingual agents.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Without an output schema or parameter details, the description fails to explain return values or pagination, leaving the agent underinformed for a simple listing tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The two parameters (page_size, page_index) are not explained in the description, and schema coverage is 0%, so the agent must infer their purpose 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?
The description clearly states the tool gets unconfirmed event invitations for the current user, using a specific verb and resource, and distinguishes it from sibling calendar tools like calendar_get_events.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives, such as when to use calendar_get_events for confirmed events.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
删除日程。removing_all_recurring_events: 是否删除所有循环日程。
| Name | Required | Description | Default |
|---|---|---|---|
| event_id | Yes | ||
| event_recurring_time | No | ||
| removing_all_recurring_events | No | false |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility for behavioral disclosure. It only states deletion occurs, without detailing permissions, reversibility, side effects (e.g., cascading deletions for recurring events), or confirmation steps. The mention of 'removing_all_recurring_events' hints at behavior for recurring events but is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, consisting of two short sentences. While this avoids verbosity, it sacrifices completeness. Every sentence serves a purpose, but the overall economy leaves significant gaps.
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 three parameters, no output schema, and no annotations, the description lacks critical context. It does not explain return behavior, success/failure indications, or error conditions. The brief explanation of the recurring event parameter is a start, but the description is far from complete for effective tool usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains only one parameter ('removing_all_recurring_events') but does not clarify 'event_id' (the sole required parameter) or 'event_recurring_time'. The meaning of these parameters is left to the schema titles alone, which are minimal.
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 removes a calendar event ("删除日程"), using a specific verb and resource. Though brief, it effectively communicates the primary action and distinguishes from sibling tools like calendar_create_event or calendar_edit_event.
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, such as calendar_edit_event for modifying events. There are no exclusions or contextual hints about prerequisites or typical scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
按关键词搜索日程。begin_date/end_date 格式 YYYY-MM-DD。
| Name | Required | Description | Default |
|---|---|---|---|
| keyword | Yes | ||
| end_date | No | ||
| begin_date | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It only mentions keyword search and date format, lacking details on result behavior (e.g., pagination, ordering, case sensitivity, or what happens if no results). This is insufficient for a mutation-ambiguous operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two clauses that front-load the core purpose (keyword search) and immediately specify parameter format. Every word is earned with zero 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 no output schema and no annotations, the description is too sparse. It fails to mention return format, error handling, result limits, or how dates interact with keyword search. An agent would need to infer critical operational details.
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 must compensate. It provides the date format (YYYY-MM-DD) for begin_date and end_date, and clarifies that keyword is for searching. This adds essential meaning beyond the bare schema properties.
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 '按关键词搜索日程' (search calendar by keywords), which is a specific verb and resource. It also mentions date parameters, distinguishing this tool from sibling tools like calendar_get_events which list events without keyword filtering.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for searching calendar events by keyword and optionally by date range, but it does not explicitly state when to use this tool versus alternatives like calendar_get_events. No contextual guidance or examples are provided.
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 | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. The description does not disclose any behavioral traits beyond the basic query, such as read-only nature, required permissions, or error scenarios. The mismatch between parameter name and description undermines transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise (one sentence) and front-loaded, but the conciseness comes at the cost of completeness and accuracy. The parameter mismatch adds confusion.
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 and low parameter info, the description is insufficient for an agent to understand the tool's behavior fully. The mismatch between the described ID and the actual parameter further reduces completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, and the description's reference to 'organization ID' conflicts with the required parameter 'project_id'. The description fails to clarify the parameter's meaning or format, likely misleading an agent.
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 (query) and resource (organization information) by ID. It is distinct from sibling tools like 'company_get_departments' and 'company_get_projects'. However, the parameter name 'project_id' contradicts the 'organization ID' in the description, causing potential confusion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs. alternatives. There is no mention of prerequisites, context, or exclusions. The description only states what it does, not when to use it.
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 |
|---|---|---|---|
| project_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; the description fails to disclose behavioral traits such as authentication needs, return format, or whether results are paginated. The minimal text does not compensate for missing annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no redundancy, efficient for a simple 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?
Lacks detail on output or behavior; with no output schema and sparse description, the agent lacks sufficient context to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% and the description does not explain the project_id parameter, leaving its purpose and format ambiguous.
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 department lists for an organization. It distinguishes from sibling tools like company_get_projects by focusing on departments, though lacks explicit 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?
No guidance on when to use or alternatives; the description does not mention context or prerequisites.
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 |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. Description lacks disclosure of read-only nature, authentication needs, or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no waste, front-loaded with purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Concise but no output schema or description of return format; lacks detail on list contents.
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?
Zero parameters, schema coverage 100%, baseline 4. Description adds no param info but none is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states verb ('获取') and resource ('组织列表'), with specific scope '当前用户所属'. Easily distinguishable from siblings like company_get_departments.
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 company_get_departments or company_get_by_id.
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_id | Yes | ||
| account_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description indicates a mutation operation but provides no additional behavioral info beyond the basic function. No annotations to supplement. Lacks details on side effects, permissions, or 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?
Single sentence, no fluff, directly to the point. Ideal conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Missing output schema, no annotations, and minimal description. For a tool with two required parameters and no return info, the description is incomplete for safe agent use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so description must compensate. It does not explain what group_id and account_id represent, leaving the agent without meaningful parameter context.
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 the action (add) and resource (group admin). It distinguishes from sibling tools like group_create or group_get_members by specifying the admin role.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives like group_create or group_edit. No context on prerequisites or scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
创建一个新群组。group_name 为群组名称。
| Name | Required | Description | Default |
|---|---|---|---|
| about | No | ||
| group_name | Yes | ||
| project_id | No | ||
| is_approval | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description must fully disclose behavior. It only states 'creates a new group' but does not mention side effects, required permissions, rate limits, or the return value. The mutation nature is implied but not elaborated.
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 and front-loaded, with no wasted words. However, the extreme brevity sacrifices essential information, making it less helpful than a longer but more complete description would be.
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 parameters, no output schema, and no annotations, the description is grossly incomplete. It does not describe what the tool returns, the meaning of optional parameters, or any behavioral expectations, leaving the agent with insufficient information for correct invocation.
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%, leaving the description to explain all parameters. It only explains group_name; about, project_id, and is_approval are left undefined. Their types (string, integer) offer no semantic meaning, so the agent cannot correctly infer how to fill them.
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 creates a new group, and identifies the required parameter group_name. The verb 'create' and resource 'group' are specific, and the tool name itself is unambiguous, differentiating it from other group-related siblings like group_create_discussion.
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 or when not to use this tool, nor does it compare to alternatives. For example, it doesn't mention whether this is for creating a top-level group or one associated with a project, or if other permissions are needed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
创建讨论组。account_ids 用逗号分隔。
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| account_ids | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, and the description does not disclose behavioral traits such as whether the action is destructive, request side effects, or permission requirements. Only basic creation is implied.
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?
Extremely concise: one sentence. However, it could be structured to include more context without being verbose. Still, no fluff.
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?
Missing return value description, no context for when to use this tool over alternatives, and no explanation of the discussion object. Incomplete for a creation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description only notes 'account_ids separated by commas' but does not explain the purpose of 'name' or that account_ids likely refer to user IDs. Minimal semantic value added.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a discussion group', which is a specific verb and resource. It distinguishes from sibling tools like group_create (general) and group_add_admin by specifying 'discussion'.
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 provided on when or when not to use this tool. No alternatives mentioned, despite many sibling group tools.
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 | No | ||
| about | No | ||
| group_id | Yes | ||
| is_approval | No |
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 only states 'edit group information' without mentioning permissions, side effects (e.g., whether fields not provided are reset), or any constraints. This is insufficient for safe tool invocation.
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 short sentence, which is concise but lacks substance. While it is not verbose, it sacrifices completeness for brevity. Ideally, it should be slightly expanded to cover key aspects.
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 edits a group and has 4 parameters (1 required), the description should cover what each parameter does, any special behavior (e.g., null meaning no change), and return value expectations (no output schema). It fails to provide this context, making it inadequate for an edit tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description should explain the parameters. It does not mention any of the four parameters (group_id, name, about, is_approval), leaving the agent to infer their meaning from names alone. No additional context is provided.
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 '编辑群组信息' (Edit group information) clearly states the action (edit) and the resource (group). It is not a tautology and distinguishes the tool's purpose from siblings like 'group_create' or 'group_get_detail', though it does not elaborate on specific editable fields.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives such as 'group_add_admin' or 'group_create'. There is no mention of prerequisites, typical use cases, or when not to use it. The description simply states the action without context.
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_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries the full burden of behavioral disclosure. It only states a read operation ('get') but does not mention permissions, side effects, or any other behavioral traits. The agent has no information on safety or potential impacts.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. It efficiently conveys the core purpose and distinguishes the tool from siblings.
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 the tool's moderate complexity (one parameter, no output schema), the description fails to specify return values or the full scope of 'group details.' The agent lacks information on what fields are returned beyond 'member information,' making it incomplete for confident use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage for the single parameter group_id. The description does not add any meaning about the parameter, such as its format, source, or constraints. The agent must rely solely on the parameter name, which is insufficient 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 tool's purpose: getting group details including member information. It uses a specific verb ('get') and resource ('group detail'), effectively distinguishing it from siblings like group_get_members which retrieves only members.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like group_get_members or group_get_project_groups. The description lacks any context about prerequisites or typical use cases, leaving the agent to infer usage.
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_id | Yes | ||
| pagesize | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description only states the basic function. Does not disclose pagination (despite pagesize parameter), ordering, or any behavioral traits beyond listing members.
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 short sentence, but it is under-specified. Conciseness here sacrifices necessary detail about parameters and usage, earning its place only minimally.
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, incomplete parameter descriptions, and no behavioral details, the description is insufficient for an agent to fully understand the tool's usage and output.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the tool description does not explain the purpose of group_id or pagesize. The description adds no value beyond the parameter names and types.
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 '获取群组成员列表' (get group member list), matching the tool name. It specifies the verb and resource, but does not differentiate from sibling tools like group_get_project_members.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives such as group_get_project_members or group_get_detail. The description provides no context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
获取当前用户创建的所有群组。
| 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 bears full responsibility. It indicates a read operation but does not disclose details like authentication requirements, pagination, or response format. However, the operation is simple and likely safe.
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 short sentence in Chinese that efficiently conveys the purpose with no extraneous 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 simplicity of the tool (no parameters, no output schema, no annotations), the description adequately states the purpose but lacks any behavioral or contextual details such as return value format or usage context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters, and the schema coverage is 100%. Per rubric, 0 parameters yields a baseline of 4. The description does not need to add parameter details.
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 'get' and the resource 'groups created by the current user'. It distinguishes from sibling tools like group_get_my_joined, which retrieves groups the user joined, not created.
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 retrieving self-created groups, but does not provide explicit when-to-use or when-not-to-use guidance, nor does it mention alternative tools.
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 |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are absent, so the description carries the burden. It correctly indicates a read operation but lacks details on authentication, pagination, or scope of 'joined'. Adequate but no extra behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, short sentence that conveys the essential function without any wasted words. Front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with no parameters and no output schema, the description is complete enough. It could hint at the returned information structure, but it is not necessary for this straightforward operation.
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?
There are no parameters, so the description does not need to add parameter meaning. Schema coverage is trivially 100%, and the baseline for zero parameters is high.
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: get all groups the current user has joined. It uses a specific verb and resource, and distinguishes from sibling tools like group_get_my_created.
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. It does not specify when to use this tool versus alternatives like group_get_my_created or group_get_detail.
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 |
|---|---|---|---|
| project_id | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description must carry the full behavioral burden. It fails to disclose any behavioral traits such as output format, authentication requirements, or whether subgroups are included.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise (one sentence), but lacks substance. It is not a comprehensive description; it is under-specified rather than efficiently informative.
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 one optional parameter and no output schema, the description should provide more context about return values and use cases. It fails to meet basic completeness for an API with moderate complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter 'project_id' has 0% schema description coverage and the description does not explain its meaning or effect. The agent cannot infer how the parameter filters results.
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 'Get all groups under the organization.' which identifies the resource (groups) and action (get), matching the tool name. However, the tool name suggests project-specific groups, while the description mentions 'organization', creating slight ambiguity.
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 sibling tools like 'group_get_project_members' or 'group_get_detail'. The context of usage is entirely implicit.
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_id | Yes | ||
| pagesize | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose behavioral traits such as read-only vs. destructive nature, authentication requirements, or rate limits. For an unannotated tool, the description should carry this burden but fails to do so.
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 short sentence, which is efficient. However, it could benefit from slightly more detail to improve clarity without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of sibling tool 'group_get_members', the description is incomplete as it does not clarify the difference between 'project members' and regular members. Also lacks details on pagination or output format, though no output schema 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?
The description does not explain any parameters. Schema description coverage is 0%, and the description adds no meaning beyond the raw schema. Parameters 'group_id' and 'pagesize' are left without explanation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb '获取' (get) and resource '成员列表' (member list) of '组织群组' (organizational group). However, it does not differentiate from sibling tool 'group_get_members', which may have similar 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?
No guidance on when to use this tool versus alternatives like 'group_get_members'. The description lacks context about prerequisites or appropriate scenarios.
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 |
|---|---|---|---|
| pagesize | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations present, and description only briefly states the action. Does not disclose behavioral traits like pagination, filtering, or what 'related to posts' means.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence is concise but lacks sufficient detail. Not bloated, but could be more informative.
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 one optional parameter, no output schema, and no annotations, the description is too minimal. It does not explain the context of usage or return values.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not mention the 'pagesize' parameter or any other parameter details.
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 states the tool gets inbox messages related to posts, with a specific verb and resource. However, it does not distinguish from siblings like message_get_system or webchat_get_messages.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. No context or exclusions provided.
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 |
|---|---|---|---|
| pagesize | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations and a terse description, behavioral traits such as side effects, permissions, or rate limits are absent. The description only states it retrieves a list, adding no depth to what the agent needs to know for safe invocation.
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 concise (one sentence), which is efficient, but it is too brief to be fully useful. It sacrifices necessary detail for brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of output schema, parameter documentation, and behavioral hints, the description is incomplete. The agent cannot confidently use this tool without additional information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description does not explain the 'pagesize' parameter at all. The agent is left to infer its meaning solely from the schema, which lacks any description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb '获取' (get) and the resource '系统消息列表' (system message list), making the tool's purpose straightforward. It distinguishes itself from sibling tools like message_get_post by specifying 'system' messages.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool compared to alternatives. There is no mention of context, preconditions, or exclusions, leaving the agent without decision-making support.
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 |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden but only says it returns detailed info. It does not disclose any behavioral traits like authentication requirements, rate limits, or safety characteristics. The agent cannot infer whether this tool has side effects or prerequisites.
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 with no unnecessary words. It is front-loaded with the action and resource, making it quickly scannable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (no parameters, no output schema, no annotations), the description adequately states its purpose. However, it could be improved by listing the kinds of details returned, providing the agent a better expectation of the output.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has zero parameters, so the baseline is 4. The description correctly indicates there are no arguments needed, matching the schema. However, it could have elaborated on what '详细信息' returns to add context, but that is not required for this dimension.
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 returns detailed information of the currently logged-in user. It uses the specific verb '获取' and resource '当前登录用户的详细信息', distinguishing it from sibling tools like passport_get_user_card or passport_get_setting.
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 provided. The description does not specify when to use this tool versus alternatives such as passport_get_user_card. An agent with many sibling tools would benefit from explicit context on when this is appropriate.
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 |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive 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?
一句简洁描述，无冗余信息，完全聚焦核心功能。
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?
无输出模式描述，未说明返回设置的结构或内容，但工具本身简单，信息基本够用。
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，描述无需额外补充。
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?
明确指定了操作为“获取”，目标资源为“当前用户的账户设置”，与同类工具（如passport_get_detail、passport_get_unread_count）区分明确。
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?
未提供使用场景、前置条件或替代工具说明，AI无法判断何时使用此工具。
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 |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must fully disclose behavioral traits. It only states the tool retrieves counts, but fails to indicate required authentication, the types of messages counted, whether it is read-only, or the response format.
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 phrase with no wasted words. However, it could be more informative while remaining concise. Still, it is front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no annotations, the description is too brief. It does not explain the structure of the returned counts (e.g., a list of message types with counts) or any other behavior. The tool is simple but lacks necessary completeness for an AI agent to use it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema is empty (no parameters). The description adds meaning by specifying '各类' (various types), implying the tool returns categorized counts, which goes beyond the empty schema. With 0 parameters, a baseline of 4 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 counts of various types of unread messages, specifying the verb (get) and resource (unread message counts). This distinguishes it from sibling tools like webchat_get_unread_count, which likely focuses on chat messages only.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as webchat_get_unread_count or other passport tools. The description does not mention prerequisites, exclusions, or explicit use cases.
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 |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so description carries full burden. It only states what the tool does without mentioning behavioral aspects such as authentication needs, idempotency, or side effects. For a read operation, this is minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single short sentence, no wasted words. Perfectly concise for the simple 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?
Given 0 parameters and no output schema, description is adequate but could be improved by describing what the card contains or its format. The minimal info might be insufficient for an agent to understand the return value.
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?
Input schema has 0 parameters, so baseline is 4. Description adds value by specifying 'current user', clarifying the scope. Schema coverage is 100% as no params exist.
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 the tool retrieves the current user's personal business card. It uses specific verb '获取' (get) and resource '个人名片' (personal card). Sibling 'user_get_card' exists but this specifies 'current user', adding some distinction, though not explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like 'user_get_card'. The context does not explain why one would choose this tool over siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
发布一条新动态。post_type: 0=普通,1=链接,2=图片,3=文档,4=提问,7=投票。group_ids/project_ids 逗号分隔。
| Name | Required | Description | Default |
|---|---|---|---|
| post_msg | Yes | ||
| group_ids | No | ||
| post_type | No | ||
| project_ids | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses the action (create) and parameter format, but does not mention authentication, rate limits, error responses, or whether the action is immediate. For a write operation, more transparency is needed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise—two short sentences with no unnecessary words. Each sentence adds value: the first states the action, the second clarifies parameter formats.
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 parameters, no output schema, and no annotations, the description is too sparse. It omits details about the required post_msg, return value, and relationship to sibling tools (e.g., post_add_post_reply). An agent would lack sufficient context for correct invocation.
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 description must compensate. It explains post_type values and that group_ids/project_ids are comma separated. However, it does not describe the required post_msg parameter, nor default values or other constraints, leaving a significant gap.
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 '发布一条新动态' (publish a new post), specifying the primary action. It also explains the post_type enum values, providing precise semantics. The tool name and description together distinguish it from siblings like post_add_post_reply.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives (e.g., reply, delete, get posts). The description implies its purpose for creating a new post, but lacks context on prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
给指定动态添加评论。reply_id 为回复某条评论时填写。
| Name | Required | Description | Default |
|---|---|---|---|
| post_id | Yes | ||
| reply_id | No | ||
| reply_msg | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries full burden. It only states the action (add comment) and parameter purpose, but fails to disclose behavioral traits like mutability, reversibility, authentication needs, or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with no fluff. Front-loaded purpose and parameter explanation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 3 parameters, no output schema, and no annotations, the description is minimal. It lacks context on return values, error handling, or interaction with other tools.
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%. The description adds meaning for reply_id by explaining it is used when replying to a comment, but provides no additional semantics for post_id or reply_msg beyond what the schema states.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the purpose: '给指定动态添加评论' (add a comment to a specified post). It also explains the reply_id parameter, but it does not distinguish this tool from sibling tools like post_add_post or post_delete_post_reply.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. No exclusions, prerequisites, or usage context provided beyond a brief parameter note.
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 |
|---|---|---|---|
| post_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It indicates deletion but fails to disclose consequences like irreversibility, whether it deletes replies, or required permissions. Minimal behavioral disclosure.
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?
Description is extremely concise (6 characters). While efficient, it could include a bit more context without being verbose. Structure is acceptable for a simple 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?
Given the tool has one parameter and no output schema, the description is minimally adequate. It fails to mention any side effects or return behavior, which would be helpful for a mutation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%; the description does not elaborate on the post_id parameter beyond what the schema provides. No details on format, source, or constraints. Adds no extra 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?
Description clearly states '删除一条动态' (Delete a post), specifying the verb 'delete' and the resource 'post'. This distinguishes it from siblings like post_add_post (add) and post_get_all_posts (get).
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 post_delete_post_reply or any prerequisites. The description only states what it does, not when it should be used.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
删除一条动态评论。post_id 必填，reply_id 为要删除的评论ID。
| Name | Required | Description | Default |
|---|---|---|---|
| post_id | Yes | ||
| reply_id | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided. The description discloses the deletion action but does not mention any side effects, permissions, or confirmation steps. For a delete operation, more transparency would be beneficial.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences with no extraneous information. It is front-loaded with the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple deletion tool, the description covers the purpose and key parameters. It does not explain the return value or handling of null reply_id, but the tool's simplicity makes this acceptable.
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 that post_id is required and reply_id is the comment ID, but lacks format details (e.g., expected ID type). The meaning is conveyed but minimally.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'delete' and the resource 'post comment' (动态评论). It distinguishes from sibling tools like post_add_post_reply (add) and post_delete_post (delete post).
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 specifies that post_id is required and reply_id is the comment to delete. While it does not explicitly state when not to use or provide alternatives, the context makes it clear for this straightforward operation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
获取全公司可见的动态流。可按关键词、类型、群组过滤。用 max_id 翻页。
| Name | Required | Description | Default |
|---|---|---|---|
| max_id | No | ||
| group_id | No | ||
| keywords | No | ||
| pagesize | No | ||
| post_type | No | ||
| project_id | No | ||
| post_filter_share | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It implies a read operation ('get') and mentions pagination, but does not explicitly state it is read-only, side-effect-free, or disclose authentication or rate limits. Adequate but not explicit.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with front-loaded purpose. No wasted words. Efficiently communicates core functionality and filtering/pagination.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, so description should hint at return structure. It mentions 'activity feed' but not the fields or format. Given moderate complexity and sibling tools, it is minimally adequate but could specify that a list of posts is returned.
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 description must compensate. It explains three parameters (keywords, type, group_id as filters) and pagination via max_id, but omits pagesize, project_id, and post_filter_share. Partially helpful but incomplete.
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 the company-wide visible activity feed (‘获取全公司可见的动态流’), specifying the verb (get) and resource (activity feed), and distinguishes it from siblings that target specific scopes like group or user posts.
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 company-wide feed, but provides no explicit guidance on when to use this vs alternatives like post_get_my_posts or post_get_group_posts. There are no when-not or alternative suggestions.
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 |
|---|---|---|---|
| max_id | No | ||
| group_id | Yes | ||
| pagesize | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; the description is a single sentence with no disclosure of behavioral traits like authentication requirements, rate limits, or error handling.
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?
Extremely concise but lacks structure; it does not front-load key information or organize content meaningfully. Every sentence should add value, but this single sentence is insufficient.
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 and no output schema, the description is severely incomplete, omitting return value format, pagination behavior, and necessary context for invocation.
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 does not explain any parameters (group_id, max_id, pagesize) beyond implying group_id from the tool name.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it gets posts for a specified group ('获取指定群组的动态'), but does not differentiate from sibling tools like post_get_all_posts or post_get_my_posts.
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 post_get_all_posts or post_get_user_posts. The description provides no context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
获取当前用户自己发布的动态。
| Name | Required | Description | Default |
|---|---|---|---|
| max_id | No | ||
| pagesize | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must convey behavioral traits. It only states the basic action without disclosing read-only nature, authentication requirements, rate limits, or error conditions. The agent gains no additional behavioral insights beyond the action verb.
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, well-formed sentence with no waste. However, it lacks structured elements like usage context or parameter hints that would improve its utility.
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 retrieval tool with pagination parameters and no output schema, the description fails to explain return format, pagination behavior, or how 'max_id' functions. The sibling tools suggest a complex environment, but this description provides minimal context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, yet the description does not explain the two parameters ('max_id' and 'pagesize'). The agent cannot infer their purpose or format from the description, failing to compensate for the schema's lack of documentation.
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 the current user's own published updates, using a specific verb ('获取') and resource ('当前用户自己发布的动态'). It distinguishes from siblings like 'post_get_all_posts' and 'post_get_user_posts' by explicitly limiting to the user's own content.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as 'post_get_user_posts' or 'post_get_all_posts'. It does not mention prerequisites, pagination context, or scenarios where this tool is preferred.
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 |
|---|---|---|---|
| post_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility. It only states 'get detailed information,' which implies a read operation but does not confirm safety, idempotency, authentication needs, or any side effects.
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, clear sentence that directly states the tool's purpose with no extraneous words. It is front-loaded and concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter and no output schema, the description covers the basic purpose. However, it lacks usage guidelines and behavioral details, making it only minimally complete for an agent to invoke correctly without additional context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description does not elaborate on the single parameter post_id. The name and tool imply it's the post identifier, but no format or constraints are given, offering little added value over 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 tool retrieves detailed information of a single post, which matches the name and distinguishes it from sibling list tools like post_get_all_posts.
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 using this tool to get details of one post, which is clear from context. However, it does not explicitly state when not to use it or mention alternatives, but the sibling names make differentiation straightforward.
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 |
|---|---|---|---|
| max_id | No | ||
| post_id | Yes | ||
| pagesize | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fails to disclose any behavioral traits beyond the basic function. No mention of pagination behavior, ordering, or whether results are truncated. The agent cannot infer how max_id and pagesize affect results.
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 fluff, but it is too brief for a tool with 3 parameters. It earns its place by stating the core purpose, but lacks structure like bullet points or parameter 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?
Given the tool has 3 parameters, no output schema, and no annotations, the description is severely incomplete. It does not explain pagination, default values, or what the return data looks like, leaving the agent with insufficient information to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. However, the description does not mention any parameters (post_id, pagesize, max_id), leaving the agent to rely solely on the schema with no context on their meaning or 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 '获取某条动态的评论列表' (Get the comment list of a certain post) clearly states the verb (get) and resource (comment list of a post), and it distinguishes from sibling tools like post_add_post_reply (add) and post_delete_post_reply (delete).
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 (e.g., post_get_post_detail for post content, post_get_all_posts for listing posts). No context or exclusions provided.
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 |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It only states the basic function without mentioning authentication requirements, rate limits, side effects (write/read-only), or any constraints. For a read-only tool, it is insufficiently transparent.
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 gets straight to the point. It is concise, but could be very slightly expanded to include return format or behavior without being verbose. It is appropriately front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no parameters, no output schema, and low inherent complexity, the description is minimally adequate. However, it does not explain return format, pagination, or what 'can post' exactly means (e.g., based on permissions, group type). It meets the minimum but leaves questions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters, and schema description coverage is 100% (trivially). The description adds no parameter semantics because there are none. Baseline is 3, but the tool has no parameters, so the description does not need to compensate; it is not lacking. Score 4 reflects adequate handling of absent 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's purpose: 'Get the list of groups that the current user can post to.' It uses a specific verb ('get') and resource ('groups'), and the qualifier 'that the current user can post to' distinguishes it from sibling tools like 'group_get_detail' or 'group_get_my_joined'.
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 or when to prefer alternatives. Among many sibling tools related to groups and posts, there is no mention of when this tool should be selected over others, nor any exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
获取指定用户的动态。account_id 为目标用户ID。
| Name | Required | Description | Default |
|---|---|---|---|
| max_id | No | ||
| pagesize | No | ||
| account_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description bears full responsibility for behavioral disclosure. It only states the action (get user posts) without mentioning idempotency, pagination behavior, rate limits, or authentication needs.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two brief sentences with no redundancy. However, the description sacrifices informativeness for brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a retrieval tool with three parameters and no output schema, the description lacks details on return format, pagination behavior, and required permissions, making it incomplete for optimal agent use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description only explains account_id (target user ID), but provides no meaning for max_id (pagination cursor) or pagesize (default 20). Given 0% schema description coverage, this is insufficient.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it retrieves posts for a specific user, with a brief note about the required account_id parameter. It distinguishes itself from sibling tools like post_get_all_posts and post_get_group_posts by targeting a single user's posts.
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 post_get_all_posts or post_get_group_posts. The description omits any context about prerequisites, scenarios, or limitations.
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 |
|---|---|---|---|
| identifier | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description is the sole source. It only states 'find user' without clarifying if it is read-only, returns single/multiple users, or any other behavioral traits such as authentication requirements or potential side effects.
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, front-loaded with the core purpose. No redundant information, though more structure (e.g., bullet points) could improve clarity for complex use cases.
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 1-parameter lookup tool with no output schema, the description is minimally complete. It lacks return value details or error scenarios, which are somewhat acceptable given the simplicity, but could be more helpful.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the description adds meaning by stating the 'identifier' can be a phone number or email, which is beyond the schema's 'string' type. However, no format constraints or edge cases are mentioned.
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 'find user by phone number or email,' specifying the resource (user) and lookup method. It differentiates from sibling tools like user_get_card or user_get_friends by indicating the identifier type.
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. It implies use when you have a phone/email, but does not mention when not to use it or list alternative tools for other lookup scenarios.
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 |
|---|---|---|---|
| account_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description only says 'get', implying a read operation. It does not disclose potential errors, authentication needs, or what happens if the user does not exist.
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. It could add a bit more detail without becoming verbose, but it is front-loaded and to the point.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no annotations, the description should explain return values and relationships to similar tools. It fails to do so, leaving the agent underinformed.
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 'account_id' parameter has no description in the schema (0% coverage), and the tool description does not explain its meaning or format. The agent needs more context to provide a valid ID.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the tool gets a user's business card info, which is clear. However, it does not differentiate from the sibling 'passport_get_user_card', which likely serves a similar 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?
No guidance is provided on when to use this tool versus alternatives like 'passport_get_user_card' or other user tools. The description only states what it does.
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 |
|---|---|---|---|
| pagesize | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, and the description does not disclose behavioral traits such as authentication requirements, rate limits, pagination behavior, or what happens if the user has no contacts. The pagesize parameter implies pagination but is not explained.
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 extraneous words. It is efficient but sacrifices necessary detail. Front-loading is fine for the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description lacks information about the return format, error handling, or any conditional behavior. Since there is no output schema, the agent is left guessing what the response contains. For a simple list retrieval, 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?
The single parameter pagesize has no description in the schema or the tool description. The agent cannot infer its purpose (e.g., max results, page number) or valid ranges. With 0% schema coverage, the description should compensate but does not.
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 (get) and resource (current user's contact list). It distinguishes itself from sibling tools like user_get_card or user_get_by_phone by specifying 'friends/contacts'. However, it could be more explicit about the scope being the authenticated user.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. No mention of prerequisites, typical use cases, or exclusions. The agent has no context on when to prefer this over other user-related tools.
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 |
|---|---|---|---|
| keywords | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided. The description discloses the tool returns a list with optional filtering, but does not mention authentication requirements, rate limits, or default behavior when no keywords are provided. It is adequate for a simple read operation but lacks depth.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is concise and front-loaded, containing no extraneous information. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one optional parameter, no output schema), the description is fairly complete. It explains the purpose and filtering capability. It could mention the output format, but that is often inferred from context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, so the description must compensate. It explicitly states the parameter 'keywords' can be used for filtering, linking the parameter to its functional purpose. This adds value beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool gets a list of users that can be @mentioned, with optional keyword filtering. This specific verb+resource distinguishes it from other user-related sibling tools like user_get_friends or user_get_subordinate.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when you need mentionable users but does not explicitly state when to use this tool over alternatives or provide exclusions. Usage context is implied rather than articulated.
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 |
|---|---|---|---|
| pagesize | No | ||
| project_id | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description does not disclose pagination behavior, authentication needs, or response format. The effect of the default null project_id is unclear.
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?
Description is extremely short (one phrase) but lacks critical details. It is under-specified rather than efficiently concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given two parameters, no output schema, and no annotations, the description fails to provide a complete picture. Key behavioral aspects (filtering, response structure) are 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?
With 0% schema description coverage, the description adds no explanation for pagesize or project_id parameters. Their semantics (e.g., how project_id affects results) are completely absent.
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 states 'get organization address book (all members)', which indicates purpose of retrieving user list. However, the tool name includes 'project' while description omits project context, and there is no mention of the optional project_id parameter, creating ambiguity.
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 sibling tools like group_get_members or user_get_friends. The context for using the project_id filter is not explained.
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 |
|---|---|---|---|
| project_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must disclose behavior. It does not mention that this is a read-only operation, any permissions required, or what the returned list contains (e.g., user IDs, names). No info on pagination or limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short (one sentence), but it under-specifies the tool. It is front-loaded but insufficiently informative for an agent to use correctly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, and the description does not explain what the tool returns. Missing important context about the 'subordinate' concept and how the project parameter is used.
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 only parameter 'project_id' has no description in the schema or the tool description. The agent cannot know what values are valid or how the project_id affects the result.
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 states 'Get subordinate list', which is a clear verb+resource combo. However, it does not differentiate from sibling tools like 'user_get_project_users', and the meaning of 'subordinate' in project context is not elaborated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives such as 'user_get_project_users' or other user retrieval tools. No prerequisites or context for usage.
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 |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description bears full responsibility for behavioral disclosure. It only states '获取聊天会话列表' without mentioning read-only nature, authentication needs, rate limits, or return format. This is insufficient for a tool with no annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that efficiently states the purpose. It is front-loaded and earns its place, though additional context could be added without being verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (no parameters, no output schema), the description minimally states the function. However, it lacks details on what constitutes a chat session or the format of the list, which would aid completeness for an AI 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?
The input schema has no parameters, so baseline score is 4. The description adds no parameter information, but no additional meaning is needed beyond the schema. The schema coverage is 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?
The description '获取聊天会话列表' clearly indicates the tool retrieves a list of chat sessions. However, it does not differentiate from sibling tools like webchat_get_messages, though that tool is for messages rather than session lists. The verb and resource are clear, but no additional context is given.
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 such as webchat_get_messages or webchat_get_unread_count. There is no mention of prerequisites or context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
根据消息ID获取前后消息。account_id 和 group_id 二选一。
| Name | Required | Description | Default |
|---|---|---|---|
| size | No | ||
| group_id | No | ||
| account_id | No | ||
| message_id | 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 the basic behavior (get surrounding messages) but omits details like read-only nature, pagination, or size effect.
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 a single sentence to convey purpose and a key constraint, with 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?
Given no output schema and no annotations, the description is incomplete. It fails to explain the return format, default behavior for size, or what 'surrounding' entails.
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 description must compensate. It clarifies that account_id and group_id are mutually exclusive, adding value, but does not explain size or message_id beyond their schema definitions.
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 surrounding messages by message ID, distinguishing it from sibling tools like webchat_get_messages which list messages.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for fetching context around a specific message but lacks explicit when-not-to-use or alternatives guidance. It mentions the mutual exclusivity of account_id and group_id but doesn't elaborate on selection criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
获取与某人或某群的消息总数。account_id 和 group_id 二选一。
| Name | Required | Description | Default |
|---|---|---|---|
| group_id | No | ||
| account_id | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It only states it gets a count, but does not disclose any behavioral traits like permissions required, rate limits, or response format. The tool may have side effects or constraints not mentioned.
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, consisting of two short sentences. It front-loads the main purpose and the key parameter constraint. Every sentence earns its place with no waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no annotations and no output schema, the description is too minimal. It does not explain the return value, behavior when both parameters are provided, or error handling. The tool's context is not fully covered.
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 0% coverage (no parameter descriptions). The description adds meaning by stating that account_id and group_id are mutually exclusive, which is valuable beyond the schema. However, it does not explain what these IDs represent or provide any further semantic context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it retrieves the total number of messages for a person or group. It specifies the verb '获取' and resource '消息总数'. However, it does not differentiate from sibling tools like webchat_get_messages or webchat_get_unread_count, which could cause ambiguity.
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 a usage guideline that account_id and group_id are mutually exclusive ('二选一'). But it lacks explicit context on when to use this tool versus alternatives, such as when to use get_message_count vs get_messages.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
获取与某人或某群的消息记录。account_id 和 group_id 二选一。
| Name | Required | Description | Default |
|---|---|---|---|
| keyword | No | ||
| group_id | No | ||
| pagesize | No | ||
| pageindex | No | ||
| account_id | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It does not disclose behavioral traits such as pagination behavior, sorting, rate limits, or whether the operation is read-only. The implicit read nature is clear, but more context is needed.
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, consisting of two short sentences. The primary purpose is front-loaded, and every word adds value. No unnecessary 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 no output schema and low schema coverage, the description is lacking. It does not explain return format, default behavior (e.g., ordering, maximum results), or how pagination works. For a tool with 5 parameters and no annotations, the description is 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 0%, so the description must compensate. It adds meaning by noting the mutual exclusivity of account_id and group_id. However, it does not explain the remaining three parameters (keyword, pagesize, pageindex) which are crucial for usage. Partial improvement over 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 explicitly states the tool retrieves message records with someone or a group ('获取与某人或某群的消息记录'), using a clear verb and resource. However, it does not distinguish from sibling tools like webchat_get_message_by_id or webchat_get_chat_list, so it loses a point.
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 guidance on parameter selection by noting 'account_id 和 group_id 二选一' (choose one), but lacks explicit when-to-use or alternative comparisons. It does not mention when to prefer this over related tools like webchat_get_message_count.
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 |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description lacks behavioral details such as side effects, authorization requirements, or scope of the unread count. With no annotations, the description carries the full burden but only provides the basic function name.
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 short sentence, which is very concise. It could benefit from additional context without sacrificing brevity, but it is not overly verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no parameters and no output schema, the description is minimally sufficient. However, it lacks context about the scope (e.g., for all chats or a specific one) and the return format, making it less complete 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?
The tool has no parameters, and the schema coverage is 100%. The description does not need to add parameter information. The baseline for zero parameters is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves the total number of unread messages, specifying the action and resource. However, it does not differentiate from sibling tools like 'webchat_get_message_count' which might have a similar 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?
No guidance is provided on when to use this tool versus alternatives. The description only states what it does without any context about when it should be invoked or excluded.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
给用户或群组发送文本消息。account_id 和 group_id 二选一。
| Name | Required | Description | Default |
|---|---|---|---|
| message | Yes | ||
| group_id | No | ||
| account_id | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description bears full burden, but it only says 'send text messages' and the parameter constraint. It does not disclose side effects, permissions, rate limits, or behavior when both or neither target parameter is provided.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with purpose, then constraint. No extraneous 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?
Despite low complexity (3 params, no output schema), the description lacks details on return values, error handling, or prerequisites. For a write operation, an agent would benefit from knowing if the message was sent successfully.
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 adds meaning by clarifying that account_id targets users and group_id targets groups, and that one must be chosen. It does not elaborate on message parameter constraints like length or format.
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 sends text messages to users or groups, and specifies the use of account_id or group_id. This distinguishes it from sibling webchat tools which are primarily read-oriented.
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 the key guideline that account_id and group_id are mutually exclusive (二选一). It doesn't explicitly state when not to use this tool, but sibling context makes it clear this is for sending, not retrieving.
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. Dates show when Glama detected each change.
v0.5.3calendar_add_memberscalendar_create_eventcalendar_edit_eventcalendar_get_event_detailscalendar_get_eventscalendar_get_unconfirmed_eventscalendar_remove_eventcalendar_searchcompany_get_by_idcompany_get_departmentscompany_get_projectsgroup_add_admingroup_creategroup_create_discussiongroup_editgroup_get_detailgroup_get_membersgroup_get_my_createdgroup_get_my_joinedgroup_get_project_groupsgroup_get_project_membersmessage_get_postmessage_get_systempassport_get_detailpassport_get_settingpassport_get_unread_countpassport_get_user_cardpost_add_postpost_add_post_replypost_delete_postpost_delete_post_replypost_get_all_postspost_get_group_postspost_get_my_postspost_get_post_detailpost_get_post_replypost_get_post_select_groupspost_get_user_postsuser_get_by_phoneuser_get_carduser_get_friendsuser_get_mentioneduser_get_project_usersuser_get_subordinatewebchat_get_chat_listwebchat_get_message_by_idwebchat_get_message_countwebchat_get_messageswebchat_get_unread_countwebchat_send_messageMost tools have distinct purposes through different resource+verb combinations (e.g., calendar_get_events vs calendar_search), but the sheer number of similar 'get' tools and overlapping scope (e.g., post_get_all_posts vs post_get_group_posts) may cause occasional misselection. Overall, descriptions help differentiate.
Tools consistently follow a prefix_verb_noun snake_case pattern (e.g., group_create, post_delete_post). Minor inconsistencies exist like 'webchat_get_message_by_id' vs 'webchat_get_messages' and 'post_add_post' redundancy, but the pattern is predictable.
With 50 tools, the set is far beyond the typical well-scoped range (3-15). Although the platform covers many domains, the high count risks overwhelming agents and increasing selection errors. A more focused subset would improve usability.
The tool set covers major CRUD-like operations for calendars, posts, groups, and chat, but lacks some obvious actions like group deletion, user information updates, or file handling. The coverage is decent but not fully comprehensive for the implied collaboration domain.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Unified MCP Server is a remote MCP connector for AI agents and vertical AI products that provides access to 22,000+ authorized SaaS tools across 400+ integrations and 24 categories directly inside LLMs (Claude, GPT, Gemini, Cohere). Tools operate only on explicitly authorized customer connections, enabling agents to safely read and write against live third-party systems.
MCP server connecting AI agents to 100+ apps (Gmail, Slack, Notion, GitHub) via one-click OAuth.
MCP server unifying ERPs, CRMs, APIs and knowledge base for Claude, ChatGPT and Gemini.
Zero-setup MCP gateway securely connecting AI to your tools with authentication and workflows
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/andyleimc-source/mdymcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
