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

Annotations declare destructiveHint=false and readOnlyHint=false; the description reinforces this by saying skill files are not modified, so the agent knows only the pending preview is invalidated. It still does not say what happens to the token afterward or how it behaves with an expired/unknown token.

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 short sentence, front-loaded with the action and scoped with the non-effect clause. No wasted wording.

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

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

For a one-parameter, non-destructive cancel tool with no output schema this is nearly adequate: the action and its non-effect are clear. Missing is any statement of the token's role and the outcome of cancellation, which the bare schema does not supply.

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 single required 'token' parameter is documented nowhere; the description only implies a preview exists to be invalidated. It never says the token is the preview token or what happens on an unknown token, so the description fails 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?

States a specific verb+resource: invalidating a not-yet-executed archive or restore preview, and explicitly notes it does not modify skill files. The '尚未执行的' qualifier implicitly separates it from execute_skill_plan, though no sibling is 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 phrase '尚未执行的归档或恢复预览' implies the condition for use (a preview exists but has not been executed), which is enough to infer the scenario. However, it never names execute_skill_plan as the alternative or states what to do when no preview is pending.

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?

Adds context beyond the annotations by disclosing the authoritative data source and bounding scope (no marketplace pull, no log scan), and it implies the returned fields (version, enabled). It does not reconcile the readOnlyHint=false annotation with the read-oriented wording, nor does it say whether repeated calls are cheap or require auth — modest gaps the annotations do not cover.

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 sentence with no filler: mechanism first, then what is returned, then what is out of scope. It could have been front-loaded with the action rather than the transport path, but it is efficient overall.

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 parameters and no output schema, the description carries the return-value burden and does so by naming version and enabled state, plus the source of truth and exclusions. The one gap is that the readOnlyHint=false annotation is left unexplained for what reads like a pure 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline for a parameterless tool 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?

States a specific verb (读取) and resource (已安装插件版本和启用状态) plus the exact backend path (app-server plugin/installed), so the agent knows precisely what will be returned. It does not name a sibling tool by name, but the two negative scopes (no remote marketplace catalog, no activity-log scan) further narrow the intent.

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 '不拉取远程市场目录，不扫描活动日志' clause gives implicit when-not guidance, which is useful for steering away from catalog or log queries. However, there is no positive trigger ('use this when you need to verify whether a plugin is enabled before...') and no alternative tool is named among the siblings.

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 cover the read-only, non-destructive, closed-world profile, but the description adds real value beyond them: what is returned (total count and last-received timestamp) and the important interpretation trap that an empty ledger does not prove no activity. It also bounds the scope by stating it does not read chats or prove other sessions are onboarded.

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, front-loaded with the read-only purpose and return shape, followed by the exclusions and the empty-ledger caveat. Every clause carries information; nothing is redundant with the name or title.

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 parameters, no output schema and annotations already declaring the safety profile, the description is nearly self-sufficient: it describes the returned fields and the main misinterpretation risk. The only minor gap is that it never clarifies the scope of the ledger (global vs. current session) or the time format of the timestamp.

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

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

The tool takes zero parameters, so there is nothing to disambiguate and the baseline of 4 applies. The description correctly avoids wasting space on non-existent inputs.

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 (只读检查) plus the exact resources (采用账本 and 插件调用账本) and even summarizes the return payload (总数与最近接收时间). It implicitly separates itself from the write-side siblings record_skill_use/record_plugin_calls, but never names query_usage, so the boundary with the closest read sibling is 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?

The '不写测试事件' clause implies this is for verification rather than emitting events, and the empty-ledger caveat guides interpretation. However, no sibling is named as the alternative for writing events or for detailed usage breakdowns, so the when-to-use-vs-what guidance is only implied.

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?

Beyond the annotations (readOnlyHint=false, openWorldHint=false), the description discloses what is actually read (real MCP call events from sessions and archived_sessions), what is stored (identifiers and timestamps only), where config lives (local persistence), and explicit non-behaviors: no model calls, no network, no auto-confirming Skill adoption. That is exactly the side-effect and privacy boundary an agent needs for a config mutation.

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 tight clauses: the action first, then what enabling reads/stores, then the safety boundary. No filler, no restatement of the tool name.

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 a mutation annotation profile, the description covers scope, data touched, privacy, and persistence well. It is silent on what happens to already-captured data when capture is disabled and on the return shape, which would be useful for a state-changing config tool.

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

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

Schema description coverage is 0%, so the description must carry the load: it explains the enabled flag as start/stop of capture and gives the interval's valid range (5–3600 seconds), matching the schema's minimum/maximum. It does not mention the default of 10 or whether the interval matters when disabling, leaving a small 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?

States a specific verb+resource pair in '启停跨会话本地日志采集并设置 5 至 3600 秒检查间隔', identifying both the toggle and the interval knob in one clause. This configuration role is clearly distinct from siblings like record_plugin_calls (recording), query_usage (querying), and check_recording_status (status check).

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?

'按用户要求启停' implies the tool is invoked at the user's request, but it never states when to prefer this over check_recording_status or record_plugin_calls, nor any prerequisite (e.g., must capture be enabled before recording applies). Usage is inferable from the scope but not 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 flag destructiveHint=true, and the description adds real context beyond them: the token is single-use, the operation moves the user's skill directory, a restore record is retained, and system/plugin scopes are read-only. It stops short of describing what happens on an expired or reused token or what the 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 short clauses with zero waste; the safety precondition is front-loaded ahead of the effect and scope, which is exactly the order an agent needs for a destructive commit 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 one-parameter destructive mutation with no output schema, the description covers precondition, effect, recoverability, and scope boundaries. The remaining gap is failure/return behavior, which is minor given the simplicity of the interface.

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 single token param is only typed as a UUID, so the description must carry the meaning — it does, explaining that the token is a one-time preview token tied to a specific preview. It omits where the token comes from (the preview_* tools) and its lifetime/error semantics, keeping it below a 5.

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 concrete verb+object: moves the user's skill directory using a preview token, and the title adds that it covers both archive and restore. An agent can tell this is the commit step of the preview workflow, though the description itself never names preview_skill_archive/preview_skill_restore as the source of the token.

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?

Explicit gating precondition: call only after the user has explicitly requested execution for that specific preview, which also implies the when-not case (no explicit request → don't call). It does not name the alternatives (cancel_skill_plan, the preview_* tools) that an agent should reach for instead, so routing relies on inference from the sibling list.

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 description adds real context beyond annotations: it discloses the write target (usage-index.json in a separate persistent data directory), what is deliberately not stored (chat body text), and that it stays offline, consistent with openWorldHint=false and a non-readOnly write. It does not say whether the index is merged or replaced, or what happens if the log directory is missing.

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, no filler: the first states the read/extract action, the second states the write target and the two negative guarantees. The most important constraint (writes a separate index, no chat content) is front-loaded in the second sentence.

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

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

For a zero-parameter tool with no output schema, the description covers the source, the extraction semantics, and the persistence side effect. It leaves the return value unstated (e.g., counts of newly indexed signals), which the agent cannot recover from anywhere else.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The description does clarify that scope selection (which sessions) is implicit in the machine's own logs rather than parameterized.

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 concrete verb and resources: read local Codex sessions/archived_sessions logs, incrementally extract explicit markers and read requests, and write a usage-index.json. That is far more specific than the title alone and clearly separates it from query_usage or record_plugin_calls, though it never names a sibling to contrast with 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 word 'incremental' implies this can be re-run to refresh the index, and the write target implies it should precede a query, but no when-to-use/when-not condition or ordering against query_usage is stated. Usage is inferable rather than prescribed.

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=false、destructiveHint=false、openWorldHint=false；描述进一步说明自动采集时增量读取本机日志，且只保存调用标识和时间、不保存正文，提供了额外的数据副作用与隐私边界。但仍未说明权限要求或打开管理器后的具体影响。

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?

对于无参数、无输出 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 覆盖率为 100%，描述无需补充参数语义。基线为 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?

描述明确说明“扫描技能并打开管理器”，并补充自动采集时读取本机日志的副作用，属于具体动词+资源。但没有明确区分 check_plugin_status、configure_auto_capture 等兄弟工具的使用边界。

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?

仅说明工具行为，没有说明何时应使用本工具而非 configure_auto_capture、check_plugin_status 或 query_usage。也没有前置条件、排除场景或替代工具指引。

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description still adds real value by stating no move is performed and by disclosing a domain constraint the annotations cannot express: system and plugin content cannot be archived. It does not say what happens when such content is targeted (silent omission vs. error).

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, zero filler, with the read-only scope stated first and the exclusion rule second. Nothing could be removed without losing 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?

For a one-parameter read-only tool this is nearly adequate, but with no output schema the agent is left guessing what the '范围与影响' preview actually returns, and the required skillId format/derivation is entirely undocumented.

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 skillId has 0% schema description coverage, and the description never mentions it. The schema pattern ^[0-9a-f]{64}$ hints at a SHA-256 hex hash, but the description adds no meaning about what the ID identifies or how to obtain it, so it fails 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?

States a specific verb (只读预览) plus resource (用户技能目录归档) and explicitly says it does not execute the move, which separates it from execution siblings like execute_skill_plan and from the different preview_skill_restore. It stops short of naming the sibling it pairs with, so an agent must infer the archive/restore split from the wording.

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 negation '不执行移动' implies this is the dry-run step before a real archive operation, but the description never states when to call it versus execute_skill_plan or preview_skill_restore. Usage is inferable rather than instructed.

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 destructiveHint=false, which matches the stated 只读 nature, so no contradiction exists. The description adds a genuine behavioral fact beyond the annotations: the operation refuses to proceed when content already exists at the target location. It does not describe what the preview contains or how failure is reported, and with no output schema that leaves a gap.

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

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

A single compact sentence with two clauses: the read-only preview action first, then the refusal condition. No filler, and the most important information leads.

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

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

For a one-parameter, non-destructive tool this is close to sufficient, but the absence of an output schema means the description should say what a '恢复预览' returns and what the agent does with it next. The refusal-on-existing-content rule is mentioned without saying how the agent should react.

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 burden for the single archiveId parameter and says nothing about it — no mention of where the archive ID comes from or whether it refers to a specific skill archive version. Only the parameter name and uuid format in the schema give hints.

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 (只读核对 + 生成预览) and the resource (已归档技能的恢复), which lets an agent distinguish it from the sibling preview_skill_archive: this tool previews a restore, not an archive. It never names a sibling explicitly, so the differentiation is implicit rather than stated.

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 this is a pre-flight step before actually restoring, and the refusal condition ('原位置已有内容时拒绝覆盖') gives one concrete circumstance. However, it never names the follow-up action (e.g., execute_skill_plan) or states when to call preview vs. act, leaving the workflow to inference.

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 readOnlyHint=false, which is otherwise puzzling for a 'query' tool; the description earns credit by explaining why — when auto-capture is enabled it first incrementally ingests local host call events, i.e. it has a write side effect. It also discloses the interval semantics (start inclusive, end exclusive). It stops short of saying what gets persisted or how much data is ingested.

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 clauses: the operation first, the time-format constraint second. Every sentence carries information, though the ingestion clause is packed densely enough that its conditional nature is easy to skim past.

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 say what comes back (index entries? ledger rows? ingested event counts) and whether results are paged or scoped to the interval. It also leaves the `timeZone` parameter and the trigger conditions for ingestion unexplained, which is thin for a three-parameter tool with zero schema documentation.

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 does add real meaning for `from`/`to` (timezone required, half-open interval), but `timeZone` is never explained — whether it overrides the offset in the timestamps or is a fallback — leaving one of three parameters 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 gives a specific verb ('查询') and names the resources queried — the Skill index and the plugin ledger — plus the side effect of ingesting host call events. It is clear what the tool does, but it never names a sibling (e.g. import_usage, record_plugin_calls) to delineate its scope, so the agent must infer the boundary.

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 clause about auto-capture describes an internal conditional ('启用自动采集时先增量接收…') rather than when an agent should choose this tool over import_usage or record_plugin_calls. Usage is implied by the word '查询' but no exclusions or alternatives 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?

With annotations already declaring a non-read-only, non-destructive, closed-world write, the description still adds real behavior: batch-at-source recording, one record per attempt even on failure, retry semantics (reuse the id), new id for new invocations, and an explicit note that it does not capture parameters or result bodies. It doesn't say what happens if the batch partially fails or whether writes are atomic, which keeps it from 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?

The sentences are dense and front-loaded, starting with the action and scope before the id and field rules. It is a little packed for one paragraph, but every clause carries information the agent needs.

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 single-parameter write tool with no output schema, it covers what to record, what not to record, and the identity rules. Gaps around partial-batch failure, ordering, and response behavior are minor but real.

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 load, and it does: id is a call ID or a pre-generated UUID reused on retry, plugin is the tool's namespace (e.g. github), and tool is the full mcp__codex_apps__github_get_repo name. That gives meaning beyond the patterns in the schema.

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

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

The description states a specific verb and resource: it records actual plugin tool invocations in batches at the nearest point, with one record per call attempt. It also distinguishes itself from sibling record_skill_use ("与 Skill 采用分开"), so an agent can route calls between the two without opening either 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 gives an explicit negative scope: only calls that actually happened are recorded, never discovery, planning, or retroactive/backfill entries. It also separates this from Skill recording, so the choice between siblings is stated rather than inferred.

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 a non-destructive, closed-world write, so the bar is lower. The description adds genuinely non-obvious behavior: the id is reused on retry (implying idempotent retry semantics) and repeated skill entries each count separately, which is real counting semantics an agent could otherwise get wrong.

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 action, then parameter semantics, then exclusions in three dense sentences with no filler. Every clause carries information about behavior or routing.

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?

A two-parameter write with no output schema needs idempotency, input format, and scope boundaries, all of which are present. It does not say what happens when a skill name is unrecognized (error vs. ignored) or describe the return payload, which are the remaining 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 coverage is 0%, so the description must carry the load, and it does for both parameters: id is the new batch's unique ID, reused across retries; skills accepts plain names, plugin:skill form, or exact paths, is repeatable, and is counted per item. It omits the id's 16-80 character alphanumeric pattern and the 32-item cap, both of which live in the schema.

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

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

States a specific verb+resource: batch-recording skill adoption, with the trigger condition ('采用技能时') built in. The exclusion ('不用于历史补记') implicitly separates it from import_usage and record_plugin_calls, so an agent can route between them without opening schemas.

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 a clear positive trigger (when a skill is adopted) and two explicit negative cases: historical backfill and read-only auditing, which maps onto the import_usage / query_usage siblings. It does not name those siblings directly, so the routing is implied rather than spelled out.

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 (readOnlyHint=false, destructiveHint=false, openWorldHint=false) already declare a safe, local, non-destructive write, so the baseline is low. The description goes further by disclosing the optimistic-concurrency model and the conflict-rejection behavior, which the annotations do not convey. It omits success semantics and any permission/authorization requirements, keeping it at 4.

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 padding: the first front-loads what is saved and what is explicitly out of scope, the second covers the concurrency prerequisite. Nothing redundant. It is terse to the point that the revision requirement is compressed into a clause an agent must parse carefully.

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-required-param write tool with no output schema and 0% schema coverage, the description covers purpose, non-effects, preconditions and conflict handling, which is decent. It still leaves `id` undefined, says nothing about the return value or what a successful save yields, and does not mention note-size limits. Adequate but not a complete contract.

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% across 5 required params, so the description must carry the load. It glosses 4 of them in prose (备注, 保留标记, 文件指纹, 备注版本) and gives fingerprint/revision their operational meaning. It never explains the `id` parameter or the 64-char hex / <=1000-char constraints, and 版本 vs expectedRevision is left for the agent to map.

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+resource (保存备注/保留标记) and bounds scope by naming what is NOT touched: 技能文件或启停状态. An agent can immediately tell this is a metadata-only write, not a skill installer or toggler. It stops short of naming the sibling it defers to (e.g. execute_skill_plan), so a 4 rather than 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 second sentence gives a precondition for calling (must hold the current fingerprint and note revision) and the failure policy (refuse to overwrite on conflict), which implies when the tool is valid. However, it never states when to prefer this over a sibling write path or when not to call it. Usage is inferable rather than spelled out.

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