SanityのAI搭載ツールでコンテンツ運用を変革しましょう。お気に入りのAI対応エディターで自然言語による会話を通してコンテンツを作成、管理、探索できます。
Sanity MCP Serverは、モデルコンテキストプロトコルを実装し、SanityプロジェクトをClaude、Cursor、VS CodeなどのAIツールに接続します。これにより、AIモデルはコンテンツ構造を理解し、自然言語による指示に基づいて操作を実行できるようになります。
🤖コンテンツインテリジェンス: AIがコンテンツライブラリを探索して理解します
🔄コンテンツ操作：自然言語指示によるタスクの自動化
📊スキーマ認識: AIはコンテンツの構造と検証ルールを尊重します
🚀リリース管理: コンテンツのリリースを簡単に計画、整理
🔍セマンティック検索：キーワードだけでなく意味に基づいてコンテンツを検索します
Related MCP server: Context Bridge
MCP サーバーを使用する前に、次のことを行う必要があります。
スキーママニフェストを使用してSanity Studioをデプロイする
MCPサーバーが効果的に機能するには、コンテンツ構造にアクセスする必要があります。スキーママニフェストは、次のいずれかの方法でデプロイしてください。
# Option A: If you have the CLI installed globally
npm install -g sanity
cd /path/to/studio
sanity schema deploy
# Option B: Update your Studio
cd /path/to/studio
npm update sanity
npx sanity schema deploySanity ログインなしで CI 環境で実行する場合は、認証トークンを提供する必要があります。
SANITY_AUTH_TOKEN=<token> sanity schema deploy[!NOTE] スキーマのデプロイには、Sanity CLI バージョン 3.88.1 以降が必要です。
API認証情報を取得する
プロジェクトID
データセット名
適切な権限を持つAPIトークン
このMCPサーバーは、モデルコンテキストプロトコルをサポートするあらゆるアプリケーションで使用できます。以下に、よく使われる例をいくつか示します。
カスタムMCP互換アプリケーション
Sanity MCP サーバーを使用するには、アプリケーションの MCP 設定に次の構成を追加します。
{
"mcpServers": {
"sanity": {
"command": "npx",
"args": ["-y", "@sanity/mcp-server@latest"],
"env": {
"SANITY_PROJECT_ID": "your-project-id",
"SANITY_DATASET": "production",
"SANITY_API_TOKEN": "your-sanity-api-token",
"MCP_USER_ROLE": "developer"
}
}
}
}必須およびオプションの環境変数の完全なリストについては、 「構成」セクションを参照してください。
この構成の正確な場所はアプリケーションによって異なります。
応用 | 構成場所 |
クロードデスクトップ | Claude Desktop 構成ファイル |
カーソル | ワークスペースまたはグローバル設定 |
VSコード | ワークスペースまたはユーザー設定（拡張機能によって異なります） |
カスタムアプリ | アプリのMCP統合ドキュメントを参照してください |
動作しませんか？ Node.js の設定に関するセクションを参照してください。
get_initial_context – 重要: コンテキストを初期化し、使用方法の手順を取得するには、他のツールを使用する前に呼び出す必要があります。
get_sanity_config – 現在の Sanity 構成 (projectId、dataset、apiVersion など) を取得します。
create_document – 指示に基づいてAIが生成したコンテンツで新しいドキュメントを作成する
update_document – 指示に基づいてAIが生成したコンテンツで既存のドキュメントを更新する
patch_document - AI生成を使用せずにドキュメントの特定の部分を変更するために直接パッチ操作を適用します
transform_document – 書式と構造を維持しながらドキュメントの内容を変換します。テキストの置換やスタイルの修正に最適です。
translate_document – 書式と構造を維持しながら文書の内容を別の言語に翻訳する
query_documents – GROQクエリを実行してコンテンツを検索および取得する
document_action – ドキュメントの公開、非公開、削除などのドキュメントアクションを実行します。
list_releases – コンテンツリリースを一覧表示します。オプションで状態別にフィルタリングできます。
create_release – 新しいコンテンツリリースを作成する
edit_release – 既存のリリースのメタデータを更新する
Schedule_release – 特定の時間にリリースを公開するスケジュールを設定します
release_action – リリースに対するアクションを実行する（公開、アーカイブ、アーカイブ解除、スケジュール解除、削除）
create_version – 特定のリリースのドキュメントのバージョンを作成する
破棄バージョン– リリースから特定のバージョンのドキュメントを削除する
mark_for_unpublish – 特定のリリースが公開されたときに、ドキュメントを非公開としてマークします
get_datasets – プロジェクト内のすべてのデータセットを一覧表示する
create_dataset – 新しいデータセットを作成する
update_dataset – データセット設定を変更する
get_schema – 完全なスキーマまたは特定のタイプのスキーマの詳細を取得します。
list_workspace_schemas – 利用可能なすべてのワークスペーススキーマ名のリストを取得します
get_groq_specification – GROQ言語仕様の概要を取得する
list_embeddings_indices – 利用可能な埋め込みインデックスをすべて一覧表示する
semantic_search – 埋め込みインデックスでセマンティック検索を実行する
list_projects – アカウントに関連付けられているすべてのSanityプロジェクトを一覧表示します
get_project_studios – 特定のプロジェクトにリンクされたスタジオアプリケーションを取得する
サーバーは次の環境変数を受け取ります。
変数 | 説明 | 必須 |
| Sanity APIトークン | ✅ |
| SanityプロジェクトID | ✅ |
| 使用するデータセット | ✅ |
| ツールのアクセス レベル (開発者または編集者) を決定します | ✅ |
| API ホスト (デフォルトはhttps://api.sanity.io ) | ❌ |
[!WARNING] >本番環境データセットでのAIの使用についてMCPサーバーに本番環境データセットへの書き込みアクセス権を持つトークンを設定する場合、AIがコンテンツの作成、更新、削除といった破壊的なアクションを実行できることにご注意ください。読み取り専用トークンを使用している場合は、この問題は発生しません。現在、ガードレールの開発を積極的に進めておりますが、書き込みアクセス権を必要とするAI操作のテストには、開発/ステージングデータセットの使用をご検討の上、慎重にご対応ください。
MCPサーバーが正しく機能するには、適切なAPIトークンと権限が必要です。必要な情報は以下のとおりです。
ロボットトークンを生成する:
プロジェクトの管理コンソールに移動します: 設定 > API > トークン
「新しいトークンを追加」をクリックします
MCPサーバーの使用専用のトークンを作成する
トークンは安全に保管してください。表示されるのは 1 回だけです。
必要な権限:
トークンには使用状況に応じた適切な権限が必要です
基本的な読み取り操作の場合: viewerロールで十分です
コンテンツ管理の場合: editorまたはdeveloper役割を推奨
高度な操作（データセットの管理など）にはadministratorロールが必要になる場合があります
データセットアクセス:
公開データセット: 認証されていないユーザーでもコンテンツを読み取ることができます
プライベートデータセット: 適切なトークン認証が必要
下書きおよびバージョン管理されたコンテンツ: 適切な権限を持つ認証済みユーザーのみがアクセスできます
セキュリティのベストプラクティス:
異なる環境（開発、ステージング、本番）ごとに別々のトークンを使用する
トークンをバージョン管理にコミットしない
トークン管理には環境変数の使用を検討する
セキュリティのためにトークンを定期的にローテーションする
サーバーは 2 つのユーザー ロールをサポートします。
開発者: すべてのツールへのアクセス
エディター: プロジェクト管理のないコンテンツ重視のツール
Node Version Manager ユーザーの皆様へ：
nvm、mise、fnm、nvm-windowsなどのツールをご利用の場合は、MCP サーバーが Node.js にアクセスできるようにするために、以下の設定手順に従う必要があります。これは一度だけ行う設定で、後々のトラブルシューティングにかかる時間を節約できます。これは MCP サーバーで現在発生している問題です。
まず、希望する Node.js バージョンをアクティブ化します。
# Using nvm
nvm use 20 # or your preferred version
# Using mise
mise use node@20
# Using fnm
fnm use 20次に、必要なシンボリックリンクを作成します（OS を選択してください）。
macOS/Linuxの場合:
sudo ln -sf "$(which node)" /usr/local/bin/node && sudo ln -sf "$(which npx)" /usr/local/bin/npx[!NOTE] 一般的に
sudoの使用には注意が必要ですが、このコンテキストでは次の理由から安全です。
既存のNode.jsバイナリへのシンボリックリンクのみを作成します
ターゲットディレクトリ（
/usr/local/bin）は、ユーザーがインストールしたプログラムの標準的なシステムの場所です。シンボリックリンクは、すでにインストールされていて信頼できるバイナリのみを指します。
これらのシンボリックリンクは、後で
sudo rmで簡単に削除できます。
Windows の場合 (管理者として PowerShell を実行):
New-Item -ItemType SymbolicLink -Path "C:\Program Files\nodejs\node.exe" -Target (Get-Command node).Source -Force
New-Item -ItemType SymbolicLink -Path "C:\Program Files\nodejs\npx.cmd" -Target (Get-Command npx).Source -Forceセットアップを確認します。
# Should show your chosen Node version
/usr/local/bin/node --version # macOS/Linux
"C:\Program Files\nodejs\node.exe" --version # WindowsMCPサーバーは、 nodeおよびnpxバイナリを直接呼び出すことで起動されます。Nodeバージョンマネージャーを使用する場合、これらのバイナリはシステムアプリケーションから自動的にアクセスできない隔離された環境で管理されます。上記のシンボリックリンクは、バージョンマネージャーとMCPサーバーが使用するシステムパスの間にブリッジを作成します。
Node バージョンを頻繁に切り替える場合:
Nodeのバージョンを変更するときは、シンボリックリンクを更新することを忘れないでください
これを自動化するには、シェル エイリアスまたはスクリプトを作成します。
# Example alias for your .bashrc or .zshrc
alias update-node-symlinks='sudo ln -sf "$(which node)" /usr/local/bin/node && sudo ln -sf "$(which npx)" /usr/local/bin/npx'後でシンボリックリンクを削除するには:
# macOS/Linux
sudo rm /usr/local/bin/node /usr/local/bin/npx
# Windows (PowerShell as Admin)
Remove-Item "C:\Program Files\nodejs\node.exe", "C:\Program Files\nodejs\npx.cmd"依存関係をインストールします:
pnpm install開発モードでビルドして実行します。
pnpm run devサーバーを構築します。
pnpm run build構築したサーバーを実行します。
pnpm startデバッグには、MCP インスペクタを使用できます。
npx @modelcontextprotocol/inspector -e SANITY_API_TOKEN=<token> -e SANITY_PROJECT_ID=<project_id> -e SANITY_DATASET=<ds> -e MCP_USER_ROLE=developer node path/to/build/index.jsこれにより、利用可能なツールを検査およびテストするための Web インターフェイスが提供されます。
Create a new document in Sanity with AI-generated content based on instructions
| Name | Required | Description | Default |
|---|---|---|---|
| _type | Yes | The document type | |
| async | No | Set to true for background processing when creating multiple documents for better performance. | |
| schemaId | Yes | Schema ID to follow | |
| releaseId | No | Optional release ID for creating versioned documents. If provided, the document will be created under the specified release version instead of as a draft | |
| instruction | Yes | Optional instruction for AI to create the document content |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so description carries full burden. It only states basic creation with AI, but omits side effects (e.g., draft creation, permission needs, behavior when instruction is omitted or async is true).
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?
Single sentence, 13 words, no filler, directly communicates core purpose.
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?
Given 5 parameters, 3 required, no output schema, the description is too sparse. It does not cover return values, error handling, or the process of AI generation, leaving the agent underinformed for correct invocation.
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 100%, so baseline 3 applies. Description adds minimal extra meaning beyond schema; e.g., the qualifier 'AI-generated content' loosely ties to the instruction parameter but does not address default behavior or interaction with other parameters.
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?
Description states a specific verb 'Create', resource 'a new document in Sanity', and distinguishing qualifier 'with AI-generated content based on instructions', clearly differentiating it from siblings like patch or update.
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?
No explicit when-to-use, when-not-to-use, or alternatives provided. The description implies AI generation but does not clarify when this tool is preferred over create_release or create_version.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new content release in Sanity with an automatically generated ID
| Name | Required | Description | Default |
|---|---|---|---|
| title | Yes | Title for the release (e.g., "Spring 2025 Product Launch") | |
| description | No | Description for the release | |
| releaseType | No | Type of release (asap, undecided, scheduled) | |
| intendedPublishAt | No | Date can be ISO format (2025-04-04T18:36:00.000Z) or natural language like "in two weeks" |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description only states it 'creates' a release, implying a write operation. It does not disclose any behavioral traits such as permissions, idempotency, side effects, or error conditions.
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 description is a single sentence that is concise and front-loaded with the core purpose. Every word is informative with no 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?
Given the complexity (4 parameters, no output schema, no annotations), the description is insufficient. It does not explain the return value, usage patterns, or potential errors, leaving significant gaps for an 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 coverage is 100% with clear descriptions for each parameter (e.g., title example, releaseType enum, intendedPublishAt format). The description adds minimal extra meaning beyond the schema, achieving baseline adequacy.
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 clearly specifies the action (create), the resource (content release in Sanity), and a key detail (automatically generated ID). It distinguishes from sibling tools like create_document and edit_release.
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?
No guidance is provided on when to use this tool versus alternatives like schedule_release or edit_release. The description lacks context for appropriate usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a version of an existing document for a specific release, with optional AI-generated modifications
| Name | Required | Description | Default |
|---|---|---|---|
| schemaId | No | Schema manifest ID from dataset manifest, not document type. Get from context or listSchemaIdsTool | sanity.workspace.schema.default |
| releaseId | Yes | ID of the release to associate this version with | |
| documentId | Yes | ID of the document to create a version for | |
| instruction | No | Optional instruction for AI to modify the document while creating the version |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It mentions creation and optional AI modifications, but does not disclose whether the operation is destructive, required permissions, or what happens to existing versions. Significant gaps for a mutation tool.
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 description is a single, clear sentence with no unnecessary words. It conveys the core purpose and key feature (optional AI modifications) efficiently.
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?
The description is adequate for a simple create operation, but there is no output schema and the description does not explain the expected return value, what the version contains, or behavior when creating a version for an existing release. Could be more complete.
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 100%, so baseline is 3. The description adds minimal value beyond schema: it mentions AI modifications but does not elaborate on parameter meaning or constraints. The schema itself provides detailed descriptions for all 4 parameters.
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 clearly states the tool creates a version of an existing document for a specific release, with optional AI modifications. It is distinct from siblings like create_document (new document) and create_release (new release).
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 description implies when to use (creating a version for a release) but does not explicitly state when not to use or provide alternatives such as discard_version or patch_document. Usage context is implied but not detailed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Discard a draft or delete a specific version document from a release
| Name | Required | Description | Default |
|---|---|---|---|
| versionId | Yes | ID of the version document to discard (with versions.releaseId prefix or a draft ID) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description implies destructive behavior but lacks details on permissions, reversibility, side effects (e.g., impact on the release), or whether the operation is idempotent. With no annotations, the description should explicitly address these aspects.
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 description is a single, well-structured sentence that efficiently conveys the tool's purpose. It is concise without being overly brief.
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?
Given the simple schema (one parameter, no output schema) and lack of annotations, the description is insufficiently complete. It fails to provide critical behavioral context such as when the operation is valid, error conditions, or post-operation state.
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 input schema covers 100% of the parameter (versionId) with a description of expected ID format. The tool description adds context about discarding drafts or versions but does not enhance parameter semantics beyond 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 clearly states the tool discards or deletes a draft or version document, distinguishing it from creation tools. However, it does not differentiate from similar sibling tools like release_action or document_action, which might also handle deletion.
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?
No usage guidance is provided; the description does not specify when to use this tool versus alternatives or any prerequisites. For instance, it doesn't clarify whether the version must be in draft status before discarding.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Perform document actions like publishing, unpublishing, or deleting documents
| Name | Required | Description | Default |
|---|---|---|---|
| versionId | No | ID of the draft document to publish (with drafts. prefix) | |
| actionType | Yes | Type of document action to perform | |
| publishedId | Yes | ID of the published document (without drafts. prefix) | |
| includeDrafts | No | Array of draft document IDs to include in deletion |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It fails to disclose that actions like delete and unpublish are destructive, or any other behavioral traits such as required permissions or irreversible changes.
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 description is a single sentence that efficiently conveys the core purpose without any wasted words.
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 tool with 4 parameters, multiple actions, and no output schema, the description is incomplete. It does not explain which parameters are required for each action or what the output looks like.
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 100%, so the baseline is 3. The description adds no parameter-specific information beyond what the schema already provides.
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 clearly states the tool performs document actions and explicitly lists three specific actions: publishing, unpublishing, and deleting. This distinguishes it from sibling tools like create_document or patch_document.
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?
No guidance is provided on when to use this tool versus alternatives. It does not mention prerequisites, side effects, or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update metadata for an existing content release
| Name | Required | Description | Default |
|---|---|---|---|
| title | No | Title for the release (e.g., "Spring 2025 Product Launch") | |
| releaseId | Yes | ID of the release | |
| description | No | Description for the release | |
| releaseType | No | Type of release (asap, undecided, scheduled) | |
| intendedPublishAt | No | When the release is intended to be published (informational only) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description must disclose behavioral traits. It only states 'Update metadata' without mentioning side effects, permissions, idempotency, or whether partial updates are allowed. This is insufficient for a mutation tool.
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 description is a single sentence, which is concise but overly brief. It could include a second sentence to clarify usage or behavior. The structure is minimal.
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?
Given 5 parameters and no output schema, the description is incomplete. It does not explain return values, error conditions, or how to use effectively. An agent would need to infer too much from the schema alone.
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 100% with each parameter described. The description adds no extra meaning beyond the schema. For example, it does not explain the relationship between releaseType and intendedPublishAt. Baseline 3 is appropriate.
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 'Update metadata for an existing content release' clearly identifies the action (update) and resource (existing content release). It distinguishes from siblings like create_release (creation) and list_releases (listing), but does not differentiate from other mutation tools like release_action or schedule_release.
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?
No guidance on when to use this tool versus alternatives (e.g., release_action for approval, schedule_release for scheduling). No prerequisites mentioned, such as the requirement that the release must already exist.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the GROQ language specification summary
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral details. It only states 'Get', implying read-only, but does not confirm no side effects, authentication needs, or return characteristics.
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 concise sentence, front-loaded with the action and resource. No wasted words.
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?
No output schema exists, and the description only says 'summary' without explaining format or content. Given zero parameters, more detail on the return value is needed for completeness.
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?
There are no parameters, so schema coverage is 100%. With zero params, the description adds no parameter info, but the baseline is 4 as per guidelines.
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 clearly states the action 'Get' and the specific resource 'GROQ language specification summary', distinguishing it from sibling tools like those for documents or releases.
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?
While no explicit when-to-use or alternatives are given, the tool's unique purpose (spec retrieval) makes context clear. No guidance on exclusions, but it's a simple get operation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
IMPORTANT: This tool must be called before using any other tools. It will get initial context and usage instructions for this MCP server.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full responsibility and clearly indicates it is a prerequisite call that delivers context and instructions, revealing its essential init behavior.
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 with bold imperative warning, no fluff, front-loaded with critical usage note.
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?
Fully adequate: zero parameters, no output schema needed, description covers purpose and usage order completely.
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?
No parameters exist, so baseline 4 applies; description adds no parameter info but none is needed.
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 clearly states the tool retrieves initial context and usage instructions, a distinct purpose from sibling tools that handle documents, releases, etc. The verb 'get' specifies the action.
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?
Explicitly states the tool 'must be called before using any other tools', providing unambiguous guidance on when to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get current Sanity configuration (projectId, dataset, API settings)
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It states 'Get' implying a read-only operation, but does not explicitly confirm no side effects, authentication requirements, or rate limits. While acceptable, it lacks explicit behavioral disclosure.
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, front-loaded sentence with no unnecessary words. Every part of the description adds value.
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 simple tool with no parameters and no output schema, the description is adequate. It names the key pieces of configuration returned. Could be slightly improved by mentioning if authentication is required or specifying the return format, but overall it is sufficient.
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 has zero parameters, so schema coverage is 100%. The description adds value beyond the schema by listing the specific configuration items returned (projectId, dataset, API settings), which improves usability.
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 clearly states the tool retrieves Sanity configuration (projectId, dataset, API settings). It uses a specific verb 'Get' and specifies the resource, distinguishing it from sibling tools that focus on documents, releases, or 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?
The description implicitly indicates when to use (when configuration is needed) but does not provide explicit when-not-to-use or alternatives. However, given the tool is simple and has no parameters, the implied usage is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the full schema of the current Sanity environment
| Name | Required | Description | Default |
|---|---|---|---|
| lite | No | Get a simplified version of the schema without field details. Useful for quick overviews. | |
| type | No | Optional: Specific type name to fetch. If not provided, returns the full schema | |
| schemaId | No | Schema manifest ID from dataset manifest, not document type. Get from context or listSchemaIdsTool | sanity.workspace.schema.default |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must convey all behavioral traits. It states 'Get the full schema' but does not mention potential large response size, any required permissions, or that 'lite' reduces detail. The description is adequate but could add more context.
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 description is a single sentence with no redundant words or irrelevant information, efficiently conveying the tool's purpose.
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?
Given no output schema and no annotations, the description provides the essential purpose. It could mention the structure or scope of the returned schema (e.g., includes all document types) for greater completeness, but is still fairly adequate.
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?
All three parameters have descriptions in the input schema (100% coverage), so the description adds no new semantic value beyond what the schema provides. Baseline of 3 is appropriate.
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 clearly states the verb ('Get'), the resource ('the full schema'), and the context ('current Sanity environment'), effectively distinguishing it from sibling tools like list_schema_ids or get_sanity_config.
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 description lacks explicit guidance on when to use this tool vs alternatives (e.g., list_schema_ids for fetching schema IDs). The 'schemaId' parameter implies prior use of list_schema_ids, but no clear usage context or exclusions are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all available embeddings indices for a dataset
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so description carries the burden. It correctly implies a read-only operation ('list'), but does not disclose any potential side effects, authentication requirements, or performance implications. For a simple list tool, this is minimally adequate.
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?
Single sentence, no redundant information. Front-loaded with action and object.
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?
The description is too minimal. It lacks any indication of the return format (no output schema) and does not clarify how the dataset is specified. Given the tool's simplicity, some additional context about implicit context or expected output would be beneficial.
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?
Tool has no parameters (schema coverage 100% with empty schema). The description adds context that the listing is 'for a dataset', which is not captured in the schema. This is acceptable for a parameterless tool.
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?
Description clearly states the action ('list') and resource ('embeddings indices'). It distinguishes from sibling tools by being the only one listing embeddings indices. However, it ambiguously says 'for a dataset' without specifying how the dataset is determined, given no parameters.
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?
No guidance provided on when to use this tool versus alternatives. The description only states what it does, without context on prerequisites, typical use cases, or when to avoid it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List content releases in Sanity, optionally filtered by state (active, scheduled, etc)
| Name | Required | Description | Default |
|---|---|---|---|
| state | No | Filter releases by state (active, scheduled, published, archived, deleted, or all) | active |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden. It does not disclose behavior such as pagination, ordering, or side effects. The description is too brief for a tool without annotations.
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 description is a single, well-structured sentence that front-loads the main purpose. No unnecessary words.
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?
Given the lack of output schema, the description should explain what is returned (e.g., list structure, fields). It does not, leaving the agent with incomplete context for a simple 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 100% for the single parameter, so the description adds minimal value beyond repeating the existence of a filter. Baseline 3 is appropriate.
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 clearly states the tool lists content releases with an optional state filter. It is specific about the resource (releases) and action (list), and distinguishes from sibling tools like release_action or edit_release.
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 description implies when to use (to list releases, with possible filtering) but provides no explicit guidance on when not to use or mention alternatives among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a list of all available schema IDs
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It only says 'get a list' but doesn't disclose read-only nature, authentication needs, rate limits, or what happens if no schema IDs exist. The tool's behavior is implied but not explicit.
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 description is a single concise sentence, front-loaded with the action and resource. Every word is necessary and efficient.
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?
Given no output schema and no annotations, the description is minimal. It explains the tool's output vaguely ('list of all available schema IDs') but doesn't clarify what 'available' means, response format, or how to interpret the IDs. It's adequate for a simple list but lacks completeness.
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?
There are no parameters, and the schema coverage is 100% (vacuous). The description adds no parameter info, but baseline for 0 parameters is 4, and no additional detail is needed.
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 clearly states the tool returns a list of all available schema IDs. The verb 'Get' and resource 'list of all available schema IDs' are specific. However, it doesn't differentiate from sibling tools like 'get_schema' which might return a specific schema, but the purpose is unambiguous.
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?
No guidance is provided on when to use this tool versus siblings. It doesn't mention alternatives or prerequisites, which is important given many schema and document-related sibling tools exist.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Mark a document to be unpublished when a specific release is published
| Name | Required | Description | Default |
|---|---|---|---|
| releaseId | Yes | ID of the release to associate with this unpublish action | |
| documentId | Yes | ID of the document to mark for unpublishing |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, but the description clearly indicates this tool marks a document for unpublishing upon release publication. It does not disclose side effects or permissions, but the behavior is straightforward.
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 description is a single, efficient sentence with no wasted words.
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 tool with 2 simple parameters and no output schema, the description is fairly complete. It explains the purpose and condition, though it could mention that the actual unpublishing occurs later.
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 100%, with both parameters described in the schema. The description adds no additional meaning beyond 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 clearly states the verb 'Mark' and the resource 'document to be unpublished' with the condition 'when a specific release is published'. It uniquely identifies the tool's action among siblings like 'document_action' or 'release_action'.
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 description implies usage context (scheduling unpublishing with a release) but provides no explicit when-to-use or alternative tools like 'release_action' or 'schedule_release'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Apply direct patch operations to modify specific parts of a document without using AI generation
| Name | Required | Description | Default |
|---|---|---|---|
| releaseId | No | Optional release ID for patching versioned documents. If provided, the document in the specified release will be patched. | |
| documentId | Yes | The ID of the document to patch | |
| operations | Yes | Array of patch operations to apply |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must cover behavioral traits. It only says 'apply direct patch operations', missing side effects, auth requirements, or failure behavior. For a mutation tool, this is insufficient.
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?
Single sentence, front-loaded with key information. No redundant words; every part contributes to understanding.
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?
Despite complex schema with 6 operation types and no output schema, description is minimal. Doesn't explain return values, error handling, or patch application semantics (e.g., JSON Patch RFC). Adequate but has 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 100%, so baseline 3. Description adds minimal value beyond schema, merely restating 'patch operations'. Schema already details each operation type.
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?
Description uses specific verb 'modify specific parts' and resource 'document', and distinguishes from AI generation tools. Sibling 'update_document' implies full replacement, while this tool is for targeted patches, making purpose clear.
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?
States 'without using AI generation', giving context but not explicitly listing when to use vs alternatives like 'update_document'. Implied usage for granular changes, but no exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Query documents from Sanity using GROQ query language
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number for paginated results (starts at 1) | |
| filter | Yes | The GROQ filter condition to apply (e.g., "_type == \"post\" | |
| params | No | Optional parameters for the GROQ query | |
| pageSize | No | Number of results per page | |
| projection | No | The fields to include in the result | ... |
| perspective | No | Optional perspective to query from: "raw", "drafts", "published", or a release ID | raw |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description does not mention read-only nature, rate limits, authentication, or side effects. Only repeats the GROQ language aspect.
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?
Single sentence, no unnecessary words, effectively front-loaded with purpose.
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?
Despite 100% schema coverage, description lacks details on output format, pagination behavior, and GROQ syntax usage. With no output schema, more context is needed.
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 100%, so schema already documents parameters. Description adds no additional parameter meaning beyond what's 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?
Clearly states it queries documents using GROQ language. Distinguishes from sibling tools like create_document and patch_document, but not from semantic_search which also queries.
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?
No guidance on when to use this tool versus alternatives like semantic_search or get_schema. Missing explicit when-to-use or when-not-to-use context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Perform basic actions on existing content releases (publish, archive, unschedule, delete)
| Name | Required | Description | Default |
|---|---|---|---|
| releaseId | Yes | ID of the release | |
| actionType | Yes | Type of release action to perform |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must disclose behavior. It only states the actions but does not explain consequences (e.g., deletion is irreversible) or any side effects. The agent lacks information about what happens after an action.
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 sentence, to the point, and lists actions. However, it omits 'unarchive' from the list, which is a minor inaccuracy. Still, it is very concise.
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?
The description, combined with the schema, covers the basic purpose and parameters. However, it lacks guidance on when to use and behavioral implications, making it adequate but not complete given the context of sibling tools.
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 covers all parameters with descriptions. The tool description adds no additional semantics beyond listing actions, which matches the enum values. Thus, no added value over 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 explicitly states it performs basic actions on existing content releases and lists the actions, distinguishing it from siblings like create_release and edit_release. However, it omits 'unarchive' from the listed actions, which is present in the 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?
The description implies use for basic actions on existing releases but does not provide explicit guidance on when to use this tool versus alternatives like schedule_release or mark_for_unpublish, nor does it state any prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Schedule a content release to be published at a specific time
| Name | Required | Description | Default |
|---|---|---|---|
| publishAt | Yes | Date can be ISO format (2025-04-04T18:36:00.000Z) or natural language like "in two weeks" | |
| releaseId | Yes | ID of the release |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Minimal disclosure: implies setting a future publish time but doesn't clarify behavior for past dates, rescheduling, or conflicts.
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?
Single sentence, no fluff, directly captures the tool's purpose.
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?
Adequate for a simple 2-parameter tool without output schema, but lacks context on behavior nuances like overwriting or status effects.
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 has 100% coverage with descriptions. Description adds value by noting 'publishAt' accepts ISO format or natural language, enhancing understanding beyond 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?
Clearly states verb 'schedule', resource 'content release', and specific action 'to be published at a specific time'. Distinguishes from siblings like 'edit_release' and 'create_release'.
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?
No guidance on when to use this tool vs alternatives like 'edit_release' or 'mark_for_unpublish'. No exclusions or context provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Perform a semantic search on an embeddings index
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | The search query to find semantically similar content | |
| indexName | Yes | The name of the embeddings index to search |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden but only states the tool's purpose. It does not disclose whether the operation is read-only, what permissions are needed, or any side effects. The behavior is virtually unspecified.
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 description is a single, clear sentence with no unnecessary words. It is appropriately concise and directly states the tool's purpose.
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 simple search tool with two parameters and no output schema, the description lacks crucial details such as what is returned (e.g., documents, scores) and whether it requires any index setup. It feels incomplete.
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 100% for both parameters, as they have descriptions in the schema. The tool description adds minimal additional meaning beyond the schema, so baseline 3 applies.
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 'Perform a semantic search on an embeddings index' clearly states the action (perform search), the method (semantic), and the resource (embeddings index). It distinguishes this tool from siblings like query_documents, which likely does lexical 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?
The description provides no guidance on when to use this tool versus alternatives such as query_documents or other search tools. It does not mention any prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing document or version with AI-generated content based on instructions
| Name | Required | Description | Default |
|---|---|---|---|
| async | No | Set to true for background processing when updating multiple documents for better performance. | |
| paths | No | Target field paths for the instruction. Specifies fields to update. Should always be set if you want to update specific fields. If not set, targets the whole document. ie: ["field", "array[_key=="key"]"] | |
| schemaId | No | Schema manifest ID from dataset manifest, not document type. Get from context or listSchemaIdsTool | sanity.workspace.schema.default |
| releaseId | No | Optional release ID for creating versioned documents. If provided, the document will be created under the specified release version instead of as a draft | |
| documentId | Yes | The ID of the document to update | |
| instruction | Yes | Instruction for AI to update the document content |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. While it indicates mutation, it does not disclose important traits such as whether the update is destructive, permission requirements, or the effect of the async parameter. The AI generation process is also vague.
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 description is a single, front-loaded sentence that wastes no words. It is concise but could be slightly more informative with a second sentence about output or usage context.
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?
Given the tool has 6 parameters, no output schema, and moderate complexity, the description lacks coverage of return values, error conditions, and behavioral details for versioned updates. It is incomplete for an agent to correctly invoke the 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 coverage is 100%, so baseline is 3. The description adds minimal value beyond the schema: it confirms that the instruction is for AI generation, but the schema already describes each parameter adequately.
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 clearly states the verb ('Update') and the resource ('existing document or version'), with a specific method ('AI-generated content based on instructions'). This distinguishes it from sibling tools like patch_document (manual patching) and create_document (creation).
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?
No guidance is given on when to use this tool versus alternatives. There is no mention of prerequisites, exclusions, or comparative context with siblings like patch_document or document_action.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.0create_documentcreate_releasecreate_versiondiscard_versiondocument_actionedit_releaseget_groq_specificationget_initial_contextget_sanity_configget_schemalist_embeddings_indiceslist_releaseslist_schema_idsmark_for_unpublishpatch_documentquery_documentsrelease_actionschedule_releasesemantic_searchupdate_documentScored across 20 tools
Most tools have distinct purposes (e.g., create_document vs update_document, list_releases vs release_action). Slight overlap arises with document_action and mark_for_unpublish both involving unpublishing, but descriptions clarify the release-specific context.
The majority follow a verb_noun pattern (create_document, list_releases, query_documents). Minor deviations include get_initial_context (more imperative than descriptive) and action-based names (document_action, release_action) that break the pattern.
20 tools is slightly above the typical 3-15 range but still reasonable for a full-featured CMS server. Each tool covers a distinct operation, and no obvious bloat is present.
Core document and release lifecycles are covered (create, query, update, delete, schedule, publish). A notable gap is the absence of a direct get_document by ID tool, though query_documents can substitute with GROQ. Auxiliary features like semantic search and schema retrieval add value.
Direct access to your Sanity projects (content, datasets, releases, schemas) and agent rules
Connect your team's living knowledge base — docs, data, issues, CRM — to Claude and ChatGPT.
Context and control for any AI. Agent identity, scoped access, and proof across tools.
The AI brain for builders: ChatGPT, Claude and your other AIs share one workspace and one method.
