CEP-15 Common Tool Schemas

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:

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

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{ "kinds": [11317], "#i": ["a7f3d9c2b1e8..."] }

Find all ContextVM common tool schemas:

{ "kinds": [11317], "#k": ["io.contextvm/common-schema"] }

Browse candidates by category (best-effort):

{ "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:

{
  "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:

{
  "_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:

{
  "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

{
  "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:

{ "kinds": [11317], "#i": ["f8e7d6c5b4a3..."] }

Or browse by category (best-effort):

{ "kinds": [11317], "#t": ["weather-forecast"] }

4. User invokes tool

{
  "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
• NIP-73: External Content IDs
• RFC 8785: JSON Canonicalization Scheme (JCS)
• MCP Specification: Tools
• MCP Specification: _meta field