skill_search

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

由于没有任何 annotations，描述承担了全部行为披露责任。它补充了检索算法、打分维度和返回带理由候选列表等实质性信息，让 agent 知道这是只读检索；但未说明无结果时的行为、topK 截断/排序规则、打分分数区间或是否需要权限等边界行为。

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 也必须自己交代返回值，它做了这一点。但缺少 topK 默认值/含义、filters 各字段用法、候选列表数量及五维得分的具体解释，因此 agent 仍需试探或依靠反馈才能充分利用全部参数。

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

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

schema 说明覆盖率为 50%，query 和 context 已有描述，topK 和嵌套的 filters（5 个数组字段）均无描述。工具描述本身没有为任何参数新增语义，仅“按任务检索”间接对应 query，没能补偿 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?

描述以具体动词「检索」加资源「skill」开头，并明确混合检索算法（BM25 + 向量 + RRF）和五维任务匹配打分，还说明返回「带理由的候选列表」。它清楚地与 skill_inspect/skill_get/skill_run 等兄弟工具区分开，并给出「先做这个再动手」的使用定位。

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?

「先做这个再动手」明确告诉 agent 在执行任务前应该先调用此工具，给出了非常清晰的时机指引。但没有显式说明何时不该用、以及后续应改用哪个兄弟工具（如 skill_inspect 查看详情、skill_run 执行），故扣一分。

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