---
title: CEP-15 Common Tool Schemas
description: Standard for defining and discovering common tool schemas using MCP _meta fields and ContextVM announcements
---
# Common Tool Schemas
**Status:** Draft
**Type:** Standards Track
**Author:** @Contextvm-org
## Abstract
This CEP establishes a standard for defining and discovering common tool schemas in ContextVM.
It enables interoperability by allowing multiple servers to implement the same standardized MCP tool interface that clients can recognize and use consistently. Using MCP's `_meta` field, RFC 8785 for deterministic hashing, and CEP-6 announcements for discovery, this creates a marketplace where users can choose between multiple providers implementing the same common tool schema.
## Motivation
This CEP enables a **marketplace for common services** in ContextVM. When servers implement similar functionality (e.g., translation, weather, search), clients currently cannot:
1. Discover equivalent services across providers
2. Switch providers without code changes
3. Compare offerings based on quality, cost, or trust
4. Build specialized UIs for standard tool types
Common tool schemas enable provider competition, user choice, client optimization, and seamless interoperability.
## Specification
### 1. Schema identity and hash calculation
A common tool schema is identified by a **deterministic hash** of its tool name and normalized JSON Schemas.
To ensure compatible tool definitions produce the same cryptographic fingerprint even when providers use different documentation text, this specification defines a schema-normalization step before applying **RFC 8785 (JSON Canonicalization Scheme — JCS)** for deterministic JSON serialization.
#### 1.1 Hash payload boundary
The schema hash is computed from a payload that contains only:
1. `name`
2. normalized `inputSchema`
3. normalized `outputSchema` (if present)
All other top-level MCP tool fields are excluded from the hashed payload.
This keeps schema identity focused on the portable structural contract of the tool rather than tool-level documentation or server-specific metadata.
#### 1.2 Schema normalization
Before hashing, implementations **MUST** normalize `inputSchema` and `outputSchema` (if present) as follows:
1. If the schema uses `$ref`, produce a self-contained schema representation before hashing.
2. Recursively traverse each JSON Schema object
3. Remove the following annotation and metadata keywords at every nesting level when present:
- `title`
- `description`
- `examples`
- `default`
- `deprecated`
- `readOnly`
- `writeOnly`
4. Remove vendor-extension fields whose keys begin with `x-` at every nesting level
5. Preserve all other keywords exactly as provided
This normalization applies only to the JSON Schemas included in the hash payload. It does **not** modify the actual tool definition returned by `tools/list`.
This CEP defines deterministic structural identity for common tool schemas. It does **not** attempt to define full JSON Schema semantic equivalence.
#### 1.3 `$ref` handling
If `inputSchema` or `outputSchema` uses `$ref`, implementations **MUST** hash a self-contained schema representation rather than the unresolved `$ref` strings alone.
For hash calculation:
- implementations **MUST NOT** depend on live network resolution of remote references
- schemas used for hashing **MUST** be self-contained
- `$ref` values, if present in the hashed representation, **MUST** resolve within that self-contained representation
- implementations **MAY** preserve local references within the self-contained representation so long as the representation remains deterministic and complete for hashing
Implementations SHOULD bundle schemas into a self-contained representation before applying the normalization rules above and RFC 8785 canonicalization.
#### 1.4 Hash construction
The schema hash is calculated as:
```javascript
schemaHash = sha256(JCS({
name: string,
inputSchema: normalizeSchema(JSONSchema),
outputSchema?: normalizeSchema(JSONSchema)
}))
```
**Important**: The hash includes the tool name to ensure interoperability. Since MCP tool invocations use the tool name in requests, including it in the hash guarantees that clients can use the same tool name across all servers implementing the common schema.
**Important**: If `outputSchema` is present, it **MUST** be included in the hashed payload.
**Note**: Top-level tool fields other than `name`, `inputSchema`, and `outputSchema` are intentionally excluded from the hash. Within JSON Schema content, documentation, annotation, and vendor-extension fields listed in the normalization rules are removed before hashing. This allows implementers freedom in how they document or annotate their service while maintaining schema compatibility.
**Note (output schema omission)**: Servers that do not provide an `outputSchema` will naturally share a hash with other servers that also omit `outputSchema` but use the same `name` and `inputSchema`. This is not inherently unsafe, but it can reduce specificity when clients want to distinguish between tools that return structured output vs. tools that return unstructured output.
### 2. Tool metadata (`_meta`) in `tools/list`
Servers that implement a common tool schema MUST include the schema hash in the MCP tool definition using MCP's `_meta` field.
**Multi-tool servers**: Common schemas are defined **per tool**. A server that exposes multiple tools MUST include the appropriate `schemaHash` in each tool entry it wants treated as a common schema. Tools that do not include this `_meta` field are simply treated as non-common (bespoke) tools.
#### 2.1 Tool definition in `tools/list` response
```json
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"tools": [
{
"name": "translate_text",
"description": "Translate text between languages using AI models",
"inputSchema": {
"type": "object",
"properties": {
"text": {
"type": "string",
"description": "Text to translate"
},
"source_language": {
"type": "string",
"description": "Source language code (ISO 639-1)"
},
"target_language": {
"type": "string",
"description": "Target language code (ISO 639-1)"
}
},
"required": ["text", "target_language"]
},
"outputSchema": {
"type": "object",
"properties": {
"translated_text": {
"type": "string",
"description": "The translated text"
},
"detected_language": {
"type": "string",
"description": "Detected source language if not provided"
}
},
"required": ["translated_text"]
},
"_meta": {
"io.contextvm/common-schema": {
"schemaHash": "a7f3d9c2b1e8..."
}
}
}
]
}
}
```
### 3. Public announcements (CEP-6) for discovery
Servers MAY publish CEP-6 public announcements to advertise which common tool schemas they implement.
This CEP uses NIP-73 compliant `i` and `k` tags to enable schema discovery and ecosystem integration (e.g., NIP-22 comments, NIP-25 reactions, voting on schemas). Schema identity comes solely from `schemaHash`.
Because a CEP-6 tools announcement reuses the same underlying `tools/list` payload in the event `content`, common-schema references SHOULD be carried consistently in both delivery paths: direct `tools/list` responses transported over ContextVM events and CEP-6 tools announcements. In practice:
- tool entries in the shared `content` payload SHOULD include the same common-schema metadata in `_meta`
- the enclosing ContextVM event SHOULD include the corresponding `i` and `k` tags in both a direct `tools/list` response and a CEP-6 tools announcement
This keeps the direct-response path and the public-announcement path semantically aligned while preserving the same schema identity across both.
#### 3.1 Implemented schema marker (NIP-73 `i` and `k` tags)
Servers implementing a common tool schema include `i` and `k` tags:
```json
{
"kind": 11317,
"pubkey": "<server-pubkey>",
"tags": [
["i", "a7f3d9c2b1e8...", "translate_text"],
["k", "io.contextvm/common-schema"]
]
}
```
**Tag format**:
- `["i", "<schema-hash>", "<tool-name>"]` — NIP-73 identifier for the common schema
- `["k", "io.contextvm/common-schema"]` — NIP-73 kind identifier (one per event)
The `i` tag contains the schema hash as the identifier, with the tool name as the optional third item. The `k` tag specifies the identifier kind, matching the namespace used in the `_meta` field.
**Multi-tool servers**: A server MAY announce multiple implemented common schemas by including multiple `i` tags in the same event (one per tool schema hash), with a single `k` tag. For example:
```json
{
"kind": 11317,
"pubkey": "<server-pubkey>",
"tags": [
["i", "a7f3d9c2b1e8...", "translate_text"],
["i", "f8e7d6c5b4a3...", "get_weather"],
["k", "io.contextvm/common-schema"]
]
}
```
This keeps schema discovery hash-indexable while allowing a single server announcement to represent a server with many tools.
#### 3.2 Optional category tags (`t` tags)
To support lightweight discoverability and curation, servers MAY include one or more `t` tags that categorize the server's tool offerings.
These tags are **not part of the schema contract** and are **not enforced**. They are hints for browsing and filtering.
Example:
```json
{
"kind": 11317,
"pubkey": "<server-pubkey>",
"tags": [
["i", "a7f3d9c2b1e8...", "translate_text"],
["k", "io.contextvm/common-schema"],
["t", "translation"],
["t", "traduccion"]
]
}
```
**Recommendation**: Servers SHOULD include at least one canonical, English, slug-style category tag (e.g., `translation`, `weather-forecast`, `web-search`) to reduce fragmentation across languages and synonyms.
### 4. Discovery and verification flow
#### 4.1 Server discovery
**Find all implementers of a schema hash:**
```json
{ "kinds": [11317], "#i": ["a7f3d9c2b1e8..."] }
```
**Find all ContextVM common tool schemas:**
```json
{ "kinds": [11317], "#k": ["io.contextvm/common-schema"] }
```
**Browse candidates by category (best-effort):**
```json
{ "kinds": [11317], "#t": ["translation"] }
```
Recommended client behavior is a two-step flow:
1. Browse/search using `t` tags (optional, best-effort)
2. For interoperable provider switching, rely on `schemaHash` by:
- extracting the hash from announcements and/or `tools/list`, and
- querying `#i` by hash to find other implementers
#### 4.2 Verification process
Clients SHOULD verify schema conformance before treating a tool as an implementation of a common schema.
1. Receive a `tools/list` payload, either from a direct response or from a CEP-6 tools announcement
2. Extract tool `name`, `inputSchema`, and `outputSchema` (if present)
3. If the schema uses `$ref`, produce a self-contained representation without live remote resolution
4. Normalize schemas by removing the annotation, metadata, and `x-*` fields.
5. Compute hash from a payload containing only `name`, normalized `inputSchema`, and normalized `outputSchema` (if present): `sha256(JCS({ name, inputSchema: normalizeSchema(inputSchema), outputSchema?: normalizeSchema(outputSchema) }))`
6. Compare with `_meta["io.contextvm/common-schema"].schemaHash`
7. If event-level `i` tags are present, clients MAY additionally verify that the advertised hash matches the corresponding per-tool `_meta` value
8. If hashes match, the tool conforms to the common schema
#### 4.3 Client tool invocation
Clients invoke tools using the standard name:
```json
{
"method": "tools/call",
"params": {
"name": "translate_text",
"arguments": { "text": "Hello!", "target_language": "es" }
}
}
```
Works identically across all implementing servers for the same schema hash.
### 5. The `_meta` field structure
Servers implementing a common tool schema MUST provide:
```typescript
{
"_meta": {
"io.contextvm/common-schema": {
"schemaHash": string // SHA-256 hash
}
}
}
```
### 6. Versioning
Common tool schemas do **not** have independent versions. Version information comes from the server, following MCP's design where servers have versions, not individual tools.
Breaking changes naturally produce a new `schemaHash` (because the hashed payload changes). In practice, schema evolution can be handled by:
1. Defining a new tool with a different name (e.g., `translate_text_v2`)
2. Or updating the tool schema in a new server version (clients relying on hash-based common schemas will treat it as a different schema hash)
The server version in initialization responses indicates the overall API version.
## Backward Compatibility
Fully backward compatible:
- Existing clients ignore `_meta` and use tools normally
- Existing servers work without `_meta` fields
- `_meta` is part of the MCP specification
- CEP-6 tags are additive
## Security Implications
### Schema verification
**Risk**: A malicious server could claim to implement a common schema but provide different, potentially harmful schemas.
**Mitigation**:
- Clients MUST verify the schema hash before trusting a common schema claim
- Clients SHOULD display clear warnings if hash verification fails
### Discovery does not imply trust
**Risk**: Users might discover and connect to untrusted servers implementing common schemas.
**Mitigation**:
- Clients SHOULD implement server reputation systems
- Clients SHOULD allow users to maintain allowlists of trusted servers
- Discovery doesn't equal trust—users must explicitly authorize connections
## Implementation Considerations
### For server developers
**Implementing a common schema**:
- Choose a clear tool name (it is part of the hash)
- Design `inputSchema` and (optionally, but strongly recommended) `outputSchema`
- Ensure schemas are self-contained for hashing and do not rely on live remote `$ref` resolution
- Normalize schemas using the rules in Section 1.2
- Compute `schemaHash` from `{ name, inputSchema, outputSchema? }` using normalized schemas, JCS, and SHA-256
- Include `schemaHash` in `_meta["io.contextvm/common-schema"].schemaHash`
- When delivering the tool list over ContextVM events, include matching `i` and `k` tags on the enclosing event
- Publish CEP-6 tools announcements with the same tool payload and matching `i` and `k` tags (NIP-73 compliant)
- Optionally include `t` tags for categorization
### For client developers
**Discovery**:
- Query Nostr for `i` tags to find providers for a known `schemaHash`
- Optionally support browsing via `t` tags, then refine by hash
**Verification**:
- Always verify schema hashes
- Show clear indicators for verified schemas and warnings on failures
**UX**:
- Build specialized UIs for common schemas
- Enable provider switching by grouping providers by `schemaHash`
- Cache verified schemas
## Example: Weather service marketplace
### 1. A server implements the weather schema
The `tools/list` response includes the schema hash in the tool entry and the corresponding common-schema discovery tags on the enclosing ContextVM event:
```json
{
"kind": 25910,
"pubkey": "<server-pubkey>",
"content": {
"jsonrpc": "2.0",
"id": 1,
"result": {
"tools": [
{
"name": "get_weather",
"inputSchema": {
"properties": {
"location": { "type": "string" }
},
"required": ["location"]
},
"outputSchema": {
"properties": {
"temperature": { "type": "number" }
},
"required": ["temperature"]
},
"_meta": {
"io.contextvm/common-schema": {
"schemaHash": "f8e7d6c5b4a3..."
}
}
}
]
}
},
"tags": [
["e", "<tools-list-request-event-id>"],
["i", "f8e7d6c5b4a3...", "get_weather"],
["k", "io.contextvm/common-schema"]
]
}
```
### 2. The server announces it implements the schema
```json
{
"kind": 11317,
"pubkey": "<server-pubkey>",
"content": {
"tools": [
{
"name": "get_weather",
"inputSchema": {
"properties": {
"location": { "type": "string" }
},
"required": ["location"]
},
"outputSchema": {
"properties": {
"temperature": { "type": "number" }
},
"required": ["temperature"]
},
"_meta": {
"io.contextvm/common-schema": {
"schemaHash": "f8e7d6c5b4a3..."
}
}
}
]
},
"tags": [
["i", "f8e7d6c5b4a3...", "get_weather"],
["k", "io.contextvm/common-schema"],
["t", "weather-forecast"]
]
}
```
### 3. Client discovers providers
Find implementers:
```json
{ "kinds": [11317], "#i": ["f8e7d6c5b4a3..."] }
```
Or browse by category (best-effort):
```json
{ "kinds": [11317], "#t": ["weather-forecast"] }
```
### 4. User invokes tool
```json
{
"method": "tools/call",
"params": {
"name": "get_weather",
"arguments": { "location": "San Francisco" }
}
}
```
Works identically across all providers implementing the same schema hash.
## Dependencies
- [CEP-6: Public Server Announcements](/spec/ceps/cep-6)
- [NIP-73: External Content IDs](https://github.com/nostr-protocol/nips/blob/master/73.md)
- [RFC 8785: JSON Canonicalization Scheme (JCS)](https://tools.ietf.org/html/rfc8785)
- [MCP Specification: Tools](https://modelcontextprotocol.io/specification/2025-11-25/server/tools)
- [MCP Specification: \_meta field](https://modelcontextprotocol.io/specification/2025-11-25/basic#json-schema-usage)