Sanity의 AI 기반 도구로 콘텐츠 운영을 혁신하세요. 선호하는 AI 기반 편집기에서 자연어 대화를 통해 콘텐츠를 제작, 관리 및 탐색하세요.
Sanity MCP 서버는 모델 컨텍스트 프로토콜을 구현하여 Sanity 프로젝트를 Claude, Cursor, VS Code와 같은 AI 도구와 연결합니다. 이를 통해 AI 모델이 콘텐츠 구조를 이해하고 자연어 명령을 통해 작업을 수행할 수 있습니다.
🤖 콘텐츠 인텔리전스 : AI가 콘텐츠 라이브러리를 탐색하고 이해하도록 하세요
🔄 콘텐츠 운영 : 자연어 지침을 통해 작업 자동화
📊 스키마 인식 : AI는 콘텐츠 구조 및 검증 규칙을 존중합니다.
🚀 릴리스 관리 : 콘텐츠 릴리스를 손쉽게 계획하고 구성하세요
🔍 의미 검색 : 키워드가 아닌 의미에 따라 콘텐츠를 검색합니다.
Related MCP server: Context Bridge
MCP 서버를 사용하려면 다음이 필요합니다.
스키마 매니페스트를 사용하여 Sanity Studio 배포
MCP 서버가 효과적으로 작동하려면 콘텐츠 구조에 액세스해야 합니다. 다음 방법 중 하나를 사용하여 스키마 매니페스트를 배포하세요.
지엑스피1
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 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 – 특정 릴리스에 대한 문서 버전을 만듭니다.
discard_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 ) | ❌ |
[!경고] > 프로덕션 데이터세트에 AI 사용 프로덕션 데이터세트에 대한 쓰기 권한이 있는 토큰으로 MCP 서버를 구성하는 경우, AI가 콘텐츠 생성, 업데이트 또는 삭제와 같은 파괴적인 작업을 수행할 수 있다는 점에 유의하십시오. 읽기 전용 토큰을 사용하는 경우에는 문제가 되지 않습니다. 현재 가드레일을 적극적으로 개발하고 있지만, 쓰기 권한이 필요한 AI 작업을 테스트할 때는 개발/스테이징 데이터세트를 사용하는 것이 좋습니다.
MCP 서버가 제대로 작동하려면 적절한 API 토큰과 권한이 필요합니다. 다음 사항을 숙지하세요.
로봇 토큰 생성 :
프로젝트 관리 콘솔로 이동하세요: 설정 > API > 토큰
"새 토큰 추가"를 클릭하세요
MCP 서버 사용을 위한 전용 토큰을 생성하세요
토큰을 안전하게 보관하세요. 토큰은 한 번만 표시됩니다!
필요한 권한 :
토큰에는 사용에 따라 적절한 권한이 필요합니다.
기본 읽기 작업의 경우: viewer 역할이면 충분합니다.
콘텐츠 관리의 경우 editor 또는 developer 역할 권장
고급 작업(데이터 세트 관리 등)의 경우 administrator 역할이 필요할 수 있습니다.
데이터 세트 접근 :
공개 데이터 세트: 인증되지 않은 사용자가 콘텐츠를 읽을 수 있습니다.
개인 데이터 세트: 적절한 토큰 인증이 필요합니다.
초안 및 버전 관리된 콘텐츠: 적절한 권한이 있는 인증된 사용자만 액세스할 수 있습니다.
보안 모범 사례 :
다양한 환경(개발, 스테이징, 프로덕션)에 대해 별도의 토큰을 사용하세요.
토큰을 버전 제어에 커밋하지 마십시오.
토큰 관리를 위해 환경 변수 사용을 고려하세요
보안을 위해 정기적으로 토큰을 회전하세요
서버는 두 가지 사용자 역할을 지원합니다.
개발자 : 모든 도구에 액세스
편집기 : 프로젝트 관리 없이 콘텐츠 중심 도구
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이를 통해 사용 가능한 도구를 검사하고 테스트할 수 있는 웹 인터페이스가 제공됩니다.
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.
