skill_feedback

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

没有 annotations，描述承担了行为披露责任：它明确说明会覆盖同一 skill_run 的自动记账，且不重复计数，还说明会影响 bandit/Elo 排名与备选检索。这比“提交反馈”这类模糊表达透明得多，但未提权限、失败条件或响应行为。

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?

工具用途和最重要的副作用都已覆盖，但 9 个参数的实际取值范围和含义仍依赖 schema，而 schema 覆盖又很低；无输出 schema、无 annotations，描述也缺少对如 rating 刻度和 beatenBy 委托等字段的解释。整体可执行，但有关参数语义的缺口明显。

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 覆盖率只有 11%，描述也没有对 skill、outcome、rating、costCents、latencyMs 等参数做补充说明。描述中的“结果与评分”和“覆盖自动记账”只能间接关联到 outcomlights/rating/cost/latency，无法弥补 9 个参数中 8 个缺少描述的问题。

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?

描述以“报告执行结果与评分”这个具体动词+对象开头，并说明它“驱动 bandit/Elo 排名与备选检索”，清楚定义了工具的核心职责。它与 skill_run、skill_search 等兄弟工具区分明显，不是对工具名的同义重复。

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?

描述通过“学习闭环”和“覆盖同一次 skill_run 的自动记账”暗示了应在 skill_run 之后用于提交反馈，并明确说明不会重复计数。虽然没有逐个对照兄弟工具给出 when-not-to-use，但已给出足够的调用时机与副作用边界。

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