インテントツール
MCPゲートウェイがエージェントに渡すのは汎用CRUDではなく、21個のインテント指向ツールです。どれもテーブルに対する操作ではなく、「ノートを作る」「コンテキストを思い出す」「プロジェクトをリネームする」といった意図を表現します。このセットは境界を構造として引きます。スペースもノートのクラスもエージェントは選べません。それを課すのはツール自身であり、そもそもどのツールが見えるかはトークンのスコープが決めます。
エージェントが tools/list で目にする名前と説明は静的です。ノートの内容がそこに混ざり込むことは決してありません(tool-poisoning への防御)。
トークンスコープ — 可視性の上限
read トークンには読み取り系のツールしか見えず、書き込み系は tools/list にそもそも現れません。そのうえで、呼び出しごとに個別のスペースへのアクセス権がチェックされます。したがって以下の表は最大構成であり、実際に使えるセットはあなたのトークン次第です。
Bootstrap
セッション開始時のツール。自分は誰か、何が使えるか、何が変わったか。
| ツール | 目的 |
|---|---|
start_session | 新しいセッションでは最初に呼ぶ。1回のリクエストで、ユーザープロファイル(常に読み込まれる)、利用可能なプロジェクト、さらに project ヒントを渡せばコンパクトなプロジェクトインデックス(ノート数+トップレベルのフォルダ)、前回の訪問以降の変更差分、knownValues(使用中のカテゴリ/タグの辞書)が返る。冪等。呼ぶ義務はなく、呼ばなければコンテキストが減るだけ。 |
whoami | 自分は誰か(プリンシパルID)、自分の権限上限(read/write)、プロジェクトのメンバーシップ、エンジンの capabilities(vector/trash/revisions)。手探りで試さずに済む。 |
get_my_projects | 利用可能なプロジェクトのフラットな一覧。project 引数にそのまま渡せるハンドル付き。ハンドルは通常 space/slug の形だが、スペースのルートプロジェクトでは1セグメントに縮まる。規則から導かず、レスポンスの値をそのまま使うこと。個人ドメインはこの一覧に含まれない(トークンから暗黙に定まる)。 |
start_session → (プロジェクトが必要?)get_my_projects → list_notes/recent_activity で構造を把握 → 書き込み前に search/recall → create_note/remember_*/edit_note/link。
この順序は推奨であって、仕組みではありません。どのツールを呼ぶかを決めるのはモデルです。促さなくても守らせたいなら、エージェントの常設の指示に書き留めておいてください — エージェントのルール。
Discover — ナビゲーション
| ツール | 目的 |
|---|---|
list_notes | ナレッジベースの ls。あるフォルダ直下のノートとサブフォルダを返す(決定論的、ページング対応)。project でスペースを選び、path がフォルダ(レスポンスの値をそのまま使う)、tag で絞り込む。列挙するのは可視のノートであって、エージェントのメモリではない。 |
recent_activity | 直近で編集されたノート(「最近触られた、レビューが要りそうなもの」)。各エントリには、誰が(人間/エージェント)、どう、どこで、いつ、が入る。start_session が返す差分とは別物。 |
Read — 読み取りと recall
| ツール | 目的 |
|---|---|
search | ハイブリッド検索(セマンティック+字句、RRF融合による)。ベクトルが使えないときは全文検索(字句検索、FTS)にフォールバックし、エラーにはならない。エージェント自身のメモリも対象なので、「書き込み前に検索」はメモリの重複も防ぐ。返るのは score と path の付いたランク付きスニペットで、ノート全文ではない。 |
get_note | ref(note-id または wiki-ref)で指定したノートの全体。本文、frontmatter、path、class、versionToken(安全な書き込み用)、そして来歴。detailed モードなら outline(見出し)と links(グラフの辺)も返る。 |
recall | トークン予算の範囲で、あるトピックの周辺からコンテキストバンドルを組み立てる。関連ノートに加えて、そのグラフ上の隣接ノートも含む。search より内容が厚く、知識と個人メモリの両方から引く。サイズの上限は budgetTokens で決まる。 |
search と recall の違いの詳細は エージェントメモリ を参照。
Write — 書き込みとインテント
| ツール | 目的 |
|---|---|
create_note | プロジェクトに共有(KB)ノートを新規作成する。クラスは user-doc。body(Markdown)の先頭の # H1 がノートのタイトルになる。path? は配置先フォルダ、type?/tags? は任意のオーバーライドパラメータ、links? は型付きの辺をその場で張る。クラスもスペースもエージェントは選ばない。 |
remember_about_user | ユーザーに関する長期的な事実(好み、コンテキスト)を、そのユーザーの個人メモリに記録する。category の下に observation を追記する。 |
remember_about_project | プロジェクトに関する事実をエージェントの個人メモリに記録する(クラス agent-memory、remember_about_user と対称)。共有知識ではない。共有知識には create_note を使う。 |
edit_note | ノートを位置ではなく語で増分編集する。append/prepend、replace(本文まるごと)、replaceSection(見出し指定)、findReplace(一意なスニペット。content を空にすると削除)。versionToken(CAS)が必要。 |
delete_note | ノートをゴミ箱へ移す。エージェントに許された唯一の破壊的操作であり、設計上、取り消し可能。復元も、ゴミ箱を空にすることも、人間だけが行える。 |
link | 型付きリンク from→ターゲット。ターゲットは to(note-id)か toTitle(まだ作られていないノートのタイトルによる前方参照)。2つのノートは同じスペース内にあること。 |
edit_note には、直前に取得した(最新の)get_note から得た versionToken が必要です。並行して編集が入ると versionConflict エラーが返ります。ツールが他人の変更を黙って上書きすることはなく、エージェントは読み直してやり直します。
Reorganize
再編成ツールの文法は verb_entity です。ノートは id、フォルダは path、プロジェクトはハンドルで指定します。
| ツール | 目的 |
|---|---|
move_note | ノートを別のフォルダへ移す。名前はそのまま。id と URL は変わらず、被リンクも壊れない。 |
rename_note | ノートのタイトルを変える。リンクセーフで、古いタイトルはエイリアス履歴に残り、被 [[リンク]] は解決し続ける。 |
move_folder | フォルダを中身ごと別の親の下へ移す。中にあるノートの id はすべてそのまま。 |
rename_folder | フォルダをその場でリネームする。そのフォルダがプロジェクトでも、ハンドルは変わらない(ハンドルを変えるなら rename_project)。 |
rename_project | プロジェクトのハンドル、人間可読な名前、またはその両方を変える。リンクセーフで、古いハンドルはエイリアスに残る。 |
Scale — 大規模移行
| ツール | 目的 |
|---|---|
create_notes | 1回の呼び出しで、同じプロジェクトに複数の KB ノートを作る。ベストエフォートで、トランザクショナルではない。results[] が1件ずつ ok/error を示すので、再試行するのは失敗したものだけ。 |
link_many | 1回の呼び出しで複数の型付きリンクを作る。ベストエフォートで冪等。 |
次へ
- エージェントメモリ — remember と recall を詳しく。
- コンテキストセットとピン留め —
start_sessionに何が入るか。 - セキュリティと可視性 — このセットがどう「lethal trifecta(致命的な三要素)」を断ち切るか。