使用 Sanity 的 AI 驱动工具，革新您的内容运营。在您喜爱的 AI 编辑器中，通过自然语言对话创建、管理和探索您的内容。
Sanity MCP 服务器实现了模型上下文协议 (MCP) ，将您的 Sanity 项目与 Claude、Cursor 和 VS Code 等 AI 工具连接起来。它使 AI 模型能够理解您的内容结构并通过自然语言指令执行操作。
🤖内容智能：让 AI 探索并理解您的内容库
🔄内容运营：通过自然语言指令自动执行任务
📊 Schema-Aware ：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 deploy在没有 Sanity 登录的 CI 环境中运行时，您需要提供一个身份验证令牌：
SANITY_AUTH_TOKEN=<token> sanity schema deploy[!NOTE] 架构部署需要 Sanity CLI 版本 3.88.1 或更新版本。
获取您的 API 凭证
项目 ID
数据集名称
具有适当权限的 API 令牌
此 MCP 服务器可与任何支持模型上下文协议 (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桌面配置文件 |
光标 | 工作区或全局设置 |
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 – 转换文档内容，同时保留格式和结构，非常适合文本替换和样式更正
翻译文档——将文档内容翻译成另一种语言，同时保留格式和结构
query_documents – 执行 GROQ 查询来搜索和检索内容
document_action – 执行文档操作，例如发布、取消发布或删除文档
list_releases – 列出内容发布，可选择按状态过滤
create_release – 创建新的内容发布
edit_release – 更新现有版本的元数据
Schedule_release – 安排在特定时间发布
release_action – 对发布执行操作（发布、存档、取消存档、取消计划、删除）
create_version – 为特定版本创建文档版本
discorn_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 服务器使用创建专用令牌
安全存储令牌 - 它只显示一次！
所需权限：
根据您的使用情况，令牌需要适当的权限
对于基本的读取操作： viewer角色就足够了
对于内容管理：建议editor或developer角色
对于高级操作（如管理数据集）：可能需要administrator角色
数据集访问：
公共数据集：未经身份验证的用户可读内容
私有数据集：需要正确的令牌认证
草稿和版本化内容：只有经过身份验证且拥有适当权限的用户才能访问
安全最佳实践：
对不同的环境（开发、准备、生产）使用不同的令牌
永远不要将令牌提交到版本控制
考虑使用环境变量进行令牌管理
定期轮换代币以确保安全
服务器支持两种用户角色：
开发人员：访问所有工具
编辑器：无需项目管理的以内容为中心的工具
Node 版本管理器用户须知：如果您使用
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然后，创建必要的符号链接（选择您的操作系统）：
在 macOS/Linux 上：
sudo ln -sf "$(which node)" /usr/local/bin/node && sudo ln -sf "$(which npx)" /usr/local/bin/npx虽然使用
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 版本时记得更新符号链接
您可以创建一个 shell 别名或脚本来自动执行此操作：
# 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.
