Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already flag readOnlyHint=false and destructiveHint=true, so the safety profile is known; the description adds the concrete confirm gate for write methods, which is real behavioral context. It doesn't cover auth/permission requirements or what the raw response looks like, but the write-confirmation rule is the operationally important part.

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?

Front-loads the purpose, then covers path/query/body and the confirm rule in a few dense sentences with no filler. It is slightly jargon-heavy for non-Chinese readers but structurally tight.

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 generic passthrough tool with no output schema, the description needs to explain invocation and risk, and it does: the target path shape, how query/body are sent, and when confirm is required. The main remaining gap is that return values and error behavior are unmentioned, though the response is inherently arbitrary for a generic frontApi call.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3, but the description earns extra by explaining how each parameter maps to the request: path as a /frontApi path, query appended to the URL, body sent as JSON. This is meaning a caller would not infer purely from field descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific action (直接调用云信控制台内部 /frontApi 接口) and its role as the fallback for capabilities not yet wrapped by dedicated tools, which distinguishes it from all named sibling tools. The example path (/frontApi/app/queryAppInfo) makes the resource concrete.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly frames the tool as covering capabilities 尚未封装成专用工具, which routes the agent here only when no dedicated sibling exists. It also gives a hard precondition for writes: non-query POST/PUT/DELETE 必须传 confirm: true.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=false and destructiveHint=true, and the description usefully splits the mixed surface by verb, showing that create/update mutate while settings/msg_copy/change_records/function_matrix are 查询 (read) calls. However it says nothing about the `confirm` parameter that gates destructive actions, nor about irreversibility, required permissions, or rate limits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single compact sentence, front-loaded with the scope (应用级管理) followed by an action-by-action enumeration. Every clause carries information and nothing is redundant.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

This is a nine-parameter, action-multiplexed tool with a nested `data` object, destructive capability, and no output schema. The description does not say which parameters belong to which action, and omits the `confirm` boolean entirely, leaving an agent unable to know that mutations may need explicit confirmation.

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 only 44%, so the description must compensate: it names the action values with meanings and gives a `data` field example ({appname, category, appdesc}), which is real added value. But it leaves `confirm` (critical for a destructive tool), `app`, and `limit`/`offset` entirely unexplained, and never maps which parameters apply to which action.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description gives a specific verb+resource pair for each of the six actions (create 创建应用, update 修改应用名称/行业/简介, settings 查询应用设置, msg_copy 查询消息抄送, change_records 查询功能变更记录, function_matrix 查询功能矩阵), which is far richer than the bare enum in the schema. It never names a sibling tool (yunxin_app_get, yunxin_apps_list) as an alternative, so sibling differentiation is absent.

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?

Each action's meaning implies when to use it, but there is no explicit when-to-use vs when-not guidance and no mention of what selects this tool over yunxin_app_get or yunxin_apps_list for read operations. Prerequisites (permissions, the `confirm` gate before mutations) are unstated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=false and destructiveHint=true; the description earns credit by adding the consequence (修改回调会直接影响消息投递) and the mandatory confirm: true precondition, which annotations cannot express. It does not state whether changes are reversible or what the set call returns.

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, zero filler, with the operation scope first and the high-risk mutation warning plus confirm precondition front-loaded where an agent will see it before choosing action=set.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive, dual-mode tool with a nested-object parameter and no output schema, the description covers the mutation risk and the required safety flag. It stops short of describing what the get path returns or how callbackFlag keys affect delivery.

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 only 29%, so the description must carry the load, and it does: it maps callbackUrl, callbackTimeout, callbackResult, and callbackFlag to concrete meanings and states the confirm requirement. Only `app` remains undefined in both schema and 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?

States a specific verb pair (查询/设置) and a specific resource (第三方回调), enumerating the four configurable aspects: URL, timeout, failure policy, and event switches. This clearly separates it from siblings like yunxin_app_get or yunxin_im_config_update, though it never names an alternative explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The action enum (get/set) plus the statement that modification requires confirm: true gives a clear condition for the mutating path, and the delivery-impact warning warns when caution is needed. It lacks explicit routing rules to sibling tools such as yunxin_im_config_update.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=false and destructiveHint=true, so the safety profile is covered; the description usefully adds that deletion demands confirm:true. It does not say whether delete is irreversible, whether add/edit have prerequisites, or what happens on duplicate cert types, leaving meaningful behavioral gaps.

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?

Three short clauses, front-loaded with the resource and the action mapping, and no filler. Slightly compressed to the point of terseness, but nothing is wasted.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

This is a 4-action tool with a free-form nested 'fields' object, no output schema, and 29% schema coverage, yet the description never explains what fields add/edit/delete require or what list returns. For that complexity, the definition is under-specified.

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 only 29% across 7 params, so the description must compensate; it does explain the action enum semantics, lists valid certtype values (ios/IOSP8/IOS_PUSHKIT/HARMONY), and flags confirm. It says nothing about app, limit, offset, or the structure of the nested fields object, which is the biggest unknown for add/edit/delete.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description gives a specific verb set (query/add/edit/delete) against a specific resource (push certificates) and enumerates which action enum values do what. It is clearly distinct from siblings like yunxin_app_keys or yunxin_app_third_push, though it never explicitly says how it differs from them.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The per-action mapping (list = query, add/edit/delete = mutate) implies which action to pick, and the confirm:true requirement for delete is a concrete usage rule. However, there is no guidance on when this tool is the right choice versus sibling certificate-adjacent tools such as yunxin_app_third_push or yunxin_app_custom_push.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is set. The description adds real value with the 'delete requires confirm:true' rule, but stays silent on what gets destroyed, whether deletion is reversible, or how data/params are consumed.

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?

Front-loaded with the resource and a compact enumerated action list plus the confirm rule. Efficient and largely waste-free, though the enumeration style is list-like rather than explanatory.

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 five-parameter, nested-object, multi-action tool with no output schema and only 40% param coverage, the description does not explain data/params payload structure or return behavior. An agent could select the right action but would likely fumble the payload shapes.

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 only 40% and the description compensates minimally: it clarifies the confirm flag and echoes the action enum, but leaves the meaning of app, data (nested body), and params (query fields) essentially unexplained beyond the terse schema hints. For a nested-object tool this leaves significant gaps.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names the resource (custom push content) and enumerates all six operations with their meanings (list/get/add/update/delete/set_default). It is clearly a custom-push management tool, though it never explicitly contrasts itself with siblings like yunxin_app_third_push or yunxin_app_callback.

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 action-to-operation mapping provides implied usage for each mode, and it adds a concrete prerequisite ('删除必须 confirm: true'). However, it offers no guidance on when to choose this tool versus the other push/callback siblings, nor any exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

readOnlyHint=true already establishes this as a safe read. The description adds that IM configuration is only returned on request, which is useful behavioral context, but says nothing about permissions, what happens with an unknown app name, or response shape beyond the field list.

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 compact sentences with no waste; the returned-data summary comes first and the parameter hint second, so the agent gets the essentials immediately.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-required-parameter read tool with full schema coverage and a readOnly annotation, the definition covers scope and the optional IM config flag adequately. Missing only edge-case behavior (unknown app, default resolution) to be fully 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 100%, so all three parameters are already documented, including the YUNXIN_CONSOLE_DEFAULT_APP fallback and the defaults for includeConfig/includeImConfig. The description repeats the app name/appid flexibility without adding new syntax or format detail, so baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (查询) and resource (单个应用) and enumerates what is returned: 基本信息、产品配置, with IM 配置 optional. The singular scope implicitly separates it from yunxin_apps_list, but no sibling is named, so it falls short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase '查询单个应用' implies usage for single-app lookups versus the list tool, but there is no explicit when-to-use guidance, no mention of alternatives such as yunxin_apps_list or yunxin_im_config_get, and no statement about failure behavior when the app is not found.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already flag destructiveHint=true, and the description adds genuinely useful context beyond them: that changes impact client-side login and that writes require confirm: true. It does not clarify that the 'get' action is itself a safe read within an otherwise destructive-annotated tool, which is the notable remaining gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tight sentences with the resource list first and the risk/confirm caveat second. No filler, though the confirm requirement could have been attached more explicitly to the write actions rather than the tool as a whole.

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 5-parameter tool with a nested object, partial schema coverage, and no output schema, the description covers impact and the confirm gate but omits action-enum semantics and what 'get' returns. Adequate but not complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is only 40%, so the description carries weight — and it does explain the confirm gate and the intent of the data object (iosbundle, packagename) and checkAppBundle. But the 'app' parameter and the exact meaning of the three action enum values are left unexplained in both places.

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 names a specific verb pair (查询/修改) and concrete resources — iOS Bundle Identifier, Android Package Name, HarmonyOS Package Name, and the identifier security-check switch. It is clearly distinct from sibling tools like yunxin_app_get or yunxin_app_admin, though it never explicitly contrasts itself with them.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It states the consequence of modification (affects client login) and a prerequisite for writes (confirm: true), which implies when caution is needed. However, it does not route the agent away from siblings such as yunxin_app_get for simple reads, nor does it say when set_check_bundle is preferred.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered structurally. The description adds one genuinely new behavioral fact — writes require confirm:true — and signals that 'set' overwrites the whole list. It stops short of saying which actions are irreversible or what delete/set return.

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 tight clauses, front-loaded with the resource and then the action breakdown; zero filler. It is arguably over-compressed for a destructive multi-action tool, but nothing is wasted.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 7 parameters, a destructive hint and no output schema, the description should at least distinguish read actions (list/status) from mutating ones and explain the app scoping parameter. It covers confirm and action well but leaves the agent guessing about the app parameter and what list/status return.

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 57%; id, ip, ids and ips are documented in the schema, and the description adds meaning for confirm (write precondition) and the action enum semantics. The app parameter and the exact confirm semantics (required only for writes, not for list/status) remain unexplained in both places.

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 names the specific resource (服务端 API IP 白名单) and enumerates the five operations mapped to the action enum, so an agent knows exactly what the tool covers. It does not differentiate itself from siblings like yunxin_app_admin or yunxin_app_keys, which keeps it from a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The action-to-operation mapping (list/status/set/edit/delete) implies which variant to pick, and '写入需 confirm: true' gives a concrete precondition for write paths. However, there is no explicit guidance on when to choose this tool over the many sibling app-management tools, and no when-not conditions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Goes beyond the destructiveHint annotation by naming the real-world consequence: clients still using the old secret will fail. It also states the hard requirement of confirm: true for the destructive path. It does not say whether the old secret is recoverable or whether there is a grace period, so it falls short of a 5.

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?

Three short clauses plus a warning sentence; the destructive consequence and confirm requirement are placed last but clearly flagged. There is no filler. Slightly telegraphic ('必须传 confirm: true') but every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 5-parameter, no-output-schema tool with destructive semantics, the description covers the action split, the destructive warning, and the confirm gate. It omits what get actually returns (masked vs. full secret) and whether the app parameter is required, but those are covered by the schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, and the description largely repeats what the schema already documents (action enum meanings, confirm requirement). The only marginal addition is restating the confirm gate as a hard rule rather than a field hint.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States specific verbs and resources: query AppKey/AppSecret or reset AppSecret, and enumerates the three actions with one-clause semantics each. Clear, but does not distinguish this from the sibling yunxin_app_get, which plausibly also returns app details.

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?

Maps each action value to a purpose (get = query, set_secret = set a supplied secret, random = generate a new one) and gives a clear precondition for reset (confirm: true). Lacks any explicit statement of when to prefer this over yunxin_app_get or yunxin_app_admin.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

readOnlyHint=true already covers the safety profile, and the description adds genuinely useful context: which fields come back and that results are searchable and paginated. It does not mention whether a total count is returned or any rate/account-scope limits, but with annotations present a 4 is warranted.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with the resource first, followed by return contents, then capabilities. No filler, and everything stated is relevant to deciding whether to call it.

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, the description usefully lists the return fields, and all parameters are covered by the schema. It falls short only on pagination response semantics (total count, ordering) and on how it relates to the many app-scoped sibling 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 description coverage is 100%, so all three parameters (limit, offset, keyword) are already documented with defaults and bounds. The description only restates that keyword search and pagination are supported, adding no format or behavior detail beyond the schema; baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource (list the cloud apps under the current account) and enumerates what is returned (name, appid, enabled products, plan, creation time). An agent can distinguish this from yunxin_app_get by name and scope, though no sibling is explicitly named.

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 — browse all apps, optionally search by name keyword, or page through results — but never states when to prefer this over yunxin_app_get or other app-level siblings. The reader must infer that this is the discovery/entry point.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations declare destructiveHint=true, so the safety profile is partly covered; the description adds the non-obvious guardrail that mutations require confirm: true, which the annotations do not express. It stops short of saying deletes are irreversible or what happens to existing categories on set.

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 clauses, front-loaded with the resource and action mapping; every element carries information. It is terse to the point of omitting needed detail, but nothing is wasted.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a mutating tool with a nested free-form 'data' object, no output schema and zero schema descriptions, the definition says nothing about what fields belong in data, what get returns, or what delete removes. An agent could pick the right action but not construct a correct call.

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 clarifies that 'set' is an upsert (新增/更新) and that confirm gates writes, but leaves the 'app' and especially the nested 'data' object entirely unexplained — a real gap for a 4-parameter tool with a free-form object.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific resource (third-party push message category configuration) and the three operations it covers (get/set/delete). An agent can tell it's a CRUD manager for push categories, though it doesn't distinguish itself from the sibling yunxin_app_custom_push.

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 'write requires confirm: true' line gives one concrete prerequisite for set/delete, but there is no guidance on when to prefer this tool over yunxin_app_custom_push or yunxin_app_get, and no exclusions are stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, and the description adds real value beyond that: it lists exactly which state is returned, flags a 'write operation switch' that is important for gating mutations, and discloses the failure path (re-login prompt on expired session). It stops short of describing the response shape or whether failure is an error vs. a status field.

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 compact sentences, front-loaded with purpose followed by return contents and then the failure case. Every clause carries information; no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no input params and no output schema, the description carries the return-value burden and does so by enumerating the four things returned plus the expiry behavior. Only the exact shape/typing of those values remains unspecified, which is a minor gap for a status check.

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, so there is nothing to disambiguate; the baseline applies. The description correctly avoids inventing parameter detail.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('检查云信控制台登录态') and enumerates what it surfaces (account, enterprise info, default app, write switch), which clearly separates it from the app/IM/stats siblings. It does not name a sibling explicitly, keeping it just short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is only implied: an agent can infer this is a pre-flight auth/context check, but the description never says when to call it versus calling a sibling directly, nor any exclusions. The expiry sentence describes output behavior rather than invocation guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already flag the tool as mutating and destructive, and the description adds the non-obvious operational requirement that switch actions must pass confirm: true — a real gate the agent would otherwise miss. It stops short of explaining what close actually affects or whether it is reversible, so it is not fully 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?

One compact sentence, front-loaded with the domain and then the action-by-action breakdown; every clause maps to a distinct action value. It is terse to the point of being dense, but nothing is wasted.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, so the description should ideally indicate what `status`, `config`, and `suspect` return; it only says they are queries. Combined with two undocumented parameters, the definition is usable but leaves the agent guessing about return shapes and the `app` scope.

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 only 25% schema description coverage, the description compensates well for `action` by defining all six enum values, and it explains `confirm`. However, `app` and `productType` receive no explanation at all (productType only has a terse '默认 IM' in the schema), leaving two of four parameters undocumented.

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 opens with the resource domain (内容安全 / 易盾 anti-spam) and then enumerates every action verb with its meaning: status = query activation state, open/close = enable/disable, probation = free trial, config/suspect = query configurations. An agent can distinguish this from siblings like yunxin_im_config_get or yunxin_im_lexicon purely from the text.

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?

Each of the six enum values is mapped to a concrete intent, so the agent knows which action to pick for a given goal, and the prerequisite 'confirm: true' for toggle operations is stated explicitly. What is missing is any routing guidance relative to sibling tools (e.g., when to use this config action vs. yunxin_im_config_get), so it falls short of a 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The readOnlyHint annotation already establishes the safety profile, and the description adds value beyond it by enumerating the returned config domains (总开关、鉴权方式、多端登录、撤回时长、漫游、群聊、聊天室、圈组、回调、安全通、推送). That partial disclosure of return content is meaningful since no output schema exists, though it doesn't state whether all fields are always returned or how large the payload is.

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 well-formed sentence that leads with the action and resource before listing fields. Efficient with no filler; the enumeration is dense but each item adds scope 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?

With no output schema, the description is the only source for return content, and it does provide a field-domain overview. However, it omits how the app parameter resolves, whether results are app-wide or default-app, and any note on response shape/size, leaving gaps for a zero-coverage schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There is one optional parameter (app) with 0% schema description coverage, so the description must carry it, and it only indirectly implies app-scoping via '应用'. It does not explain the expected app identifier format or what happens when app is omitted.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (读取/get) and resource (应用完整的 IM 配置) and enumerates the config domains covered, which clearly distinguishes it from the sibling yunxin_im_config_update (the mutating counterpart). It is clear what the agent gets, though it doesn't explicitly contrast with yunxin_app_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?

Usage is only implied: the tool is described as reading the full IM config, and the presence of yunxin_im_config_update in the sibling list hints this is the read variant. There is no explicit when-to-use/when-not-to-use statement or guidance on choosing between this and yunxin_app_get for overlapping app data.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructiveHint=true and readOnlyHint=false, so the description's job is to add detail beyond that. It does: each field fans out to a separate backend write call and results come back per field, which signals possible partial application. It does not state whether a partial failure is rolled back or which fields are irreversible, which is the main remaining gap for a destructive 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?

Three short sentences, front-loaded with the partial-update contract, followed by the fan-out behavior and then the confirm requirement. No filler and nothing redundant with the schema.

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?

Covers the essentials an agent needs to avoid a bad call (partial update + confirm), but with a destructive 18-parameter write and no output schema, the definition should say more about what the per-field result looks like when something fails and what the many undocumented fields do. Adequate but with clear gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 18 parameters and only 39% schema coverage, the description should compensate but mostly doesn't. It does add real meaning for confirm (must be true for service-level switches) and flags imMainSwitch/callbackUrl as the dangerous ones; the other cryptic fields (callbackResult, checkAppBundle, publishoffline, customKickPolicy) stay undocumented in both places.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('按字段更新 IM 配置') and clarifies the partial-update semantics ('only pass fields to modify'). It never distinguishes itself from the sibling read tool yunxin_im_config_get, so the agent must infer the pair from names alone.

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?

Gives an actionable rule: send only the fields you want changed and pass confirm: true for service-level switches such as imMainSwitch and callbackUrl. It does not say when to prefer yunxin_im_config_get or what to do if a per-field write fails, so exclusions/alternatives are missing.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=false and destructiveHint=true, so the safety profile is known. The description adds value by flagging that delete/rag_embed need confirm: true, which the annotations do not convey. It stops short of saying what is actually destroyed (a digital human persona? its knowledge base?), whether deletes are recoverable, or what rag_embed training costs in time.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single dense line with zero filler; the action enumeration is front-loaded and the confirm rule closes it. The terse comma-separated listing is efficient, though the lack of any separation between the CRUD group and the rag_* group slightly blunts scanability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive, multi-action tool with nested free-form objects and no output schema, the description should explain what belongs in data/params for each action. It does not, leaving the agent to guess payload shape for add/update/rag_embed — the highest-risk operations here.

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 carries the full burden and largely fails it: of seven parameters, only action and confirm are addressed. The meaning of app, data, params, limit, and createTime is left entirely undocumented, and for a tool where data/params are free-form nested objects whose expected keys differ per action, that is a serious 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 enumerates all eight action verbs against the resource (list/get/add/update/delete plus the three rag_* document operations), so an agent knows precisely what capability set is behind this multiplexed tool. It does not, however, distinguish itself from near-neighbours such as yunxin_im_robot or yunxin_im_lexicon, which also manage IM sub-entities.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is one real usage rule: delete and rag_embed (train) operations require confirm: true. That is genuinely helpful routing guidance. But nothing says when to pick this tool over yunxin_im_robot, nor when rag_list versus get is appropriate, and there are no stated prerequisites or side-effect conditions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The annotations already declare destructiveHint: true, and the description adds the important safety requirement that delete and publish must pass confirm: true. It does not describe irreversible effects, permission requirements, or response behavior, but it adds key operational context beyond the 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 two compact sentences with no wasted text; the action list is front-loaded, and the confirm warning follows directly. It is appropriately sized for a multiplexed action tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a seven-parameter tool with a required action enum, a nested data object, and no output schema or schema descriptions, the definition is too thin. The critical data shape for create/update and the meanings of app, keyword, limit, and offset are absent.

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, yet it explains only the action values and the confirm requirement for delete/publish. It leaves app, data, limit, offset, and keyword undocumented, and the nested data object used by create/update is especially opaque.

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 that the tool manages sensitive words and regex entries, and it enumerates every action supported by the action enum. An agent can identify the resource and the operation set without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It maps each action to its purpose (list, create, update, delete, fuzzy, publish, thesaurus) and explicitly states that delete and publish require confirm: true. It does not explain when to choose one action over another or describe prerequisites, but the action-level guidance is clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations declare destructiveHint=true, and the description usefully adds that status changes require confirm: true, which is real behavioral context. It does not disclose what create/update/status affect, whether changes are reversible, or that read-style actions coexist in a destructive-annotated 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?

It is a compact, front-loaded line that packs the action list, the confirm rule, and the channel mapping without filler. Slightly terse given the complexity it must cover.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an 8-parameter, destructive-annotated mutation tool with nested objects and no output schema, the description covers the action surface and confirm guard but leaves the shape of data/params and pagination entirely implicit. Adequate but incomplete for the complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, and the description explains only three of eight parameters: the action enum, channel (1=default, 2=custom), and confirm. The nested data/params payloads plus app, limit, and offset remain undocumented in both schema and description, leaving a meaningful 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 names the resource (IM robots) and enumerates every action the tool supports (list/get/create/update/status), so an agent understands the multi-action surface immediately. It stops short of explicitly contrasting itself with siblings like yunxin_im_user or yunxin_im_digital_human.

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 action glossary implies which operation to use for which intent, and the confirm requirement for status is stated. However, there is no guidance on when to choose this tool over sibling tools or on prerequisites for each action.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=false and destructiveHint=true, and the description adds the meaningful detail that non-query actions require confirm: true and that 'confirm' deletes and 'recover' restores from the recycle bin. It does not describe what is destroyed, whether deletes are reversible, or what permissions are needed, so the added behavioural context is useful but thin.

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 one dense, front-loaded block: resource first, then action glossary, then the confirm rule. Every clause carries information and there is no padding.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

This is a multi-action tool with five parameters, nested objects, 0% schema descriptions, and no output schema. The description explains the action names and the confirm gate but gives no guidance on what data or params each action needs, so an agent cannot reliably invoke create, cancel, recover, or send_sms without guessing at payload shapes.

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 carry the parameter burden. It does translate the action enum into meaningful Chinese labels and explains the confirm parameter's role, but it says nothing about app, data, or params, leaving the nested-object parameters undocumented.

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 names the resource (IM storage cleanup) and enumerates its seven operations (list, get, create, cancel, confirm, recover, send_sms), so an agent can tell this is a task-management tool distinct from the app/config/user siblings. It stops short of explicitly contrasting with any named sibling tool.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It states an important usage rule: all actions except queries require confirm: true. That much is explicit. It does not say when to choose this tool over alternatives, or which action applies in which situation beyond the one-word labels.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations declare destructiveHint=true and readOnlyHint=false, so mixed read/write is already implied structurally. The description adds one genuinely new behavioral fact beyond the annotations: block requires an explicit confirm: true flag. However, it never says what blocking does to an account, whether it is reversible, or that list is a safe read within an otherwise destructive 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?

One compact sentence with the action mapping front-loaded and the confirm constraint attached last. It is efficient, though the terseness edges toward under-specification rather than optimal density.

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 8 parameters, a nested request-body object, no output schema, and a destructive annotation, the description should clarify the data payload for create/update, what identify fields are needed, and the consequences of block/unblock. It covers only the action list and one flag, leaving the agent to infer how to actually construct a working call.

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 only 38% and the description compensates for almost none of it, mentioning only the confirm flag for block. Parameters such as app, data (the create/update request body), limit, and offset are left entirely to the schema, with no explanation of payload shape or pagination semantics.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names the resource (测试账号 / IM test accounts) and enumerates each action verb (list, create, update, block, unblock), so an agent can map action enum values to intent without opening the schema. It does not explicitly contrast with siblings like yunxin_stats_users or yunxin_im_config_update, so it stops short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The only usage rule given is that block requires confirm: true. There is no guidance on when to pick this tool over sibling tools, no prerequisites (app id, auth), and no indication of which actions are safe vs irreversible.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

readOnlyHint=true already tells the agent this is a safe read. The description adds that the call also returns IM security-check status, which is useful beyond the annotations. However, it doesn't describe what the statistics contain, time ranges, or response shape.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single compact sentence that is front-loaded with the primary purpose and adds the secondary security-check scope. No filler, though it is arguably too terse given the gaps it leaves.

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 2-parameter stats tool with no output schema and an undocumented app parameter, the definition should clarify the app identifier and what the statistics represent. The annotations cover safety, but the description does not fill the remaining informational gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Only 50% schema coverage: includeYidun is documented in the schema, but the app parameter has no description in either the schema or the description. The description's mention of '应用功能' hints at the app parameter but adds no format, type, or meaning beyond the field name, failing to compensate for the coverage 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 names a specific verb (查询/query) and two concrete resources: application feature usage and IM security-check (安全通) detection status. This is clear enough to distinguish it from the config or auth siblings, though it doesn't explicitly contrast with close statistics siblings like yunxin_stats_im or yunxin_stats_users.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to use this tool versus yunxin_stats_im or yunxin_stats_users, which cover adjacent statistics. The usage is only implied by the resource name, with no exclusions, prerequisites, or alternative routing.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The readOnlyHint annotation already establishes that this is a safe read operation. The description adds useful scope by naming the statistics categories and common tab values, but it does not describe return behavior, pagination, or any limits beyond what the schema and annotations provide.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact and front-loaded, immediately stating the tool's purpose and then giving the most common tab/childTab values. Every sentence adds useful selection information without repetition.

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 7-parameter statistics query with no output schema, the description covers the central required parameter and common childTab values but does not explain several optional parameters or what the result contains. It is minimally adequate but has clear gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is only 57%, so the description must carry more weight. It meaningfully explains tab and childTab with examples, but it leaves optional parameters such as app, productNumber, and yiDunBusinessId undocumented in both the description and schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: query IM statistics by tab/childTab, and lists the data categories it covers. It is clear what the tool does, though it does not explicitly distinguish itself from sibling stats tools such as yunxin_stats_users or yunxin_stats_app.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives useful common values like tab=MESSAGE_COUNT and childTab=SINGLE_MESSAGE_COUNT, but it does not explain when to use this tool versus the other stats siblings or when to prefer different tabs. Usage is implied rather than fully guided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, so safety is covered. The description adds date-format support and the natural-day caveat for province/city, but does not describe return shape, pagination, or rate limits; with annotations carrying the safety profile this is adequate but not rich.

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 compact sentences with the action list front-loaded and a date caveat appended; no repetition or filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 10-parameter read-only stats query, the description gives enough action-selection and date-format context to invoke correctly. The absence of an output schema means return details are not described, but the action labels convey what each query returns.

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 70%, and the description adds important meaning for the action enum (five modes) plus date format and province/city date semantics. Other parameters (os, app, type, area, datacycle) remain unexplained, so it improves on the schema without fully covering all ten 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?

States the resource (用户统计) and enumerates five action modes (day/count/province/city/realtime), so the agent knows exactly what the tool reports. It does not name sibling stats tools (yunxin_stats_im/yunxin_stats_app) to differentiate, so it is clear but not fully sibling-differentiated.

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?

Maps each action to its statistical view (昨日概览, 按日/小时趋势, 省份分布, 城市分布, 实时在线), giving clear selection guidance within the tool. No when-not-to-use or sibling alternatives are stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.