ingest_promote

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

links 指定時に本文末尾へ [[link]] を追記するという副作用を開示しており、注釈を超えた付加価値がある。ただし destructiveHint=true にもかかわらず、元ノートが _inbox から削除されるのか、既存の knowledge/ ファイルを上書きするのか、操作が取り消せるのかが述べられていない。

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?

核心的な目的を先頭に置き、続けて claim_strength と links の補足を続ける構成で、無駄な文がない。やや簡潔すぎて、破壊的挙動に関する情報が不足している。

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

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

出力スキーマがなく破壊的変更を伴うツールであり、スキーマ側のパラメータ説明も皆無である。パラメータの意味はかなり補えているが、昇格後の状態や戻り値、上書きや削除の挙動が不明なままで、破壊的ツールとしては説明が不足している。

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

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

スキーマの説明カバレッジが 0% で enum も定義されていない中、claim_strength の取り得る値（established / suggested / speculative）と links の追記挙動を記述しており、スキーマ以上の意味を補っている。ただし必須の slug については説明がない。

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?

「_inbox の保留ノートを knowledge/ へ昇格する」と具体的な動詞とリソースを明示し、「信頼知識化の唯一の経路」と述べて ingest_stage / ingest_reject との役割の違いを暗黙に区別している。エージェントはこの記述だけで他ツールと切り分けられる。

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?

claim_strength の値や links を渡したときの挙動には触れているが、いつ使うべきか、代わりに ingest_stage や ingest_reject を使うのはどんな場合かは明示されていない。用途は推測できるが、除外条件や前提条件の記述はない。

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