Reasonix Tool Schema Contract: How DeepSeek-Reasonix Enforces Provider-Visible Capabilities

The Reasonix tool schema contract is a compile-time generated, canonical JSON-Schema definition paired with immutable metadata that enforces tool interfaces through build-time consistency tests and runtime JSON-Schema validation.

The DeepSeek-Reasonix repository implements a strict Reasonix tool schema contract to define every built-in capability in a machine-readable format. This contract ensures that tool interfaces remain stable, versioned, and safe across the entire ecosystem by combining immutable schema definitions with dual-layer enforcement mechanisms.

What Is the Reasonix Tool Schema Contract?

At its core, the contract is an in-code representation defined by the ContractEntry struct in internal/tool/contract.go. Each entry captures a tool's canonical interface through four immutable fields:

• Name: The unique identifier for the tool
• ReadOnlyHint: A boolean flag indicating whether the tool modifies state
• Description: A human-readable explanation of the tool's purpose
• Schema: Raw bytes containing the canonical JSON-Schema definition

The canonical schema for all tools resides in internal/extension/protocol/schema.generated.json. This file is generated at compile time and serves as the single source of truth, eliminating drift between documentation and implementation.

How the Contract Is Enforced

The system employs a dual-layer enforcement strategy that validates contract integrity both during the build process and at runtime.

Build-Time Verification

The test suite in internal/tool/contract_test.go guarantees contract consistency through automated checks that run on every CI build. These tests verify that:

1. Every built-in tool appears in the docs/TOOL_CONTRACT.md documentation table
2. Each tool has a non-empty description
3. The ReadOnlyHint boolean matches the source code implementation
4. The canonical schema bytes exactly match the generated schema.generated.json file

Additional baseline tests in internal/boot/golden_baseline_test.go ensure that runtime boot-strapping respects the contract definitions. This compile-time enforcement guarantees that any modification to a tool's interface is explicitly reflected in the contract documentation.

Runtime Validation

When the host registers a tool, the runtime loads the canonical schema and performs JSON-Schema validation on every incoming request before invoking the tool's implementation. If the payload fails validation, the call is rejected with a schema_mismatch error code.

This mechanism guarantees that the executor never receives malformed data, preserving safety and backward compatibility across sessions.

Accessing Contract Entries at Runtime

The tool.BuiltinContractEntries() function provides a deterministic snapshot of all available contracts. This helper is used by both the runtime registry to expose schemas to the host and by the test suite to verify consistency.

// Example: List all built‑in tool contracts at runtime
import "github.com/esengine/DeepSeek-Reasonix/internal/tool"

func ListToolContracts() {
    for _, entry := range tool.BuiltinContractEntries() {
        fmt.Printf("Tool: %s\n", entry.Name)
        fmt.Printf("Read‑only: %t\n", entry.ReadOnlyHint)
        fmt.Printf("Description: %s\n", entry.Description)
        // The schema is a []byte containing the canonical JSON schema
        fmt.Printf("Schema size: %d bytes\n", len(entry.Schema))
    }
}

Validating Tool Calls Against the Contract

Providers can validate incoming requests using the canonical schema bytes stored in each ContractEntry. The following example demonstrates how to perform JSON-Schema validation using the contract's schema:

// Example: Validate an incoming tool request against the contract
import (
    "encoding/json"
    "github.com/xeipuuv/gojsonschema"
    "github.com/esengine/DeepSeek-Reasonix/internal/tool"
)

func ValidateToolCall(name string, request json.RawMessage) error {
    // Find the contract entry for the requested tool
    var contract *tool.ContractEntry
    for _, e := range tool.BuiltinContractEntries() {
        if e.Name == name {
            contract = &e
            break
        }
    }
    if contract == nil {
        return fmt.Errorf("unknown tool %s", name)
    }

    // Use the canonical JSON schema to validate the payload
    schemaLoader := gojsonschema.NewBytesLoader(contract.Schema)
    documentLoader := gojsonschema.NewBytesLoader(request)
    result, err := gojsonschema.Validate(schemaLoader, documentLoader)
    if err != nil {
        return err
    }
    if !result.Valid() {
        return fmt.Errorf("schema_mismatch: %v", result.Errors())
    }
    return nil
}

Stability Guarantees and Versioning

Because the contract is immutable once compiled, the system prompt, memory prefix, and tool schema remain constant throughout a running session. The contract defines a stable schema hash that hosts can cache; any schema change forces a cache refresh without interrupting ongoing sessions.

The ReadOnlyHint field specifically influences scheduling decisions. For example, a read-only sub-agent may be allowed to invoke tools marked with ReadOnlyHint: true without additional approval steps, enabling safer parallel execution.

Summary

• The Reasonix tool schema contract consists of the ContractEntry struct and a canonical JSON-Schema file generated at compile time.
• Build-time enforcement via internal/tool/contract_test.go ensures documentation, code metadata, and generated schemas remain synchronized.
• Runtime enforcement validates every tool call against the canonical schema, rejecting malformed requests with schema_mismatch errors.
• The BuiltinContractEntries() function provides deterministic access to all tool contracts for both runtime registries and test suites.
• Immutable contracts and stable schema hashes enable safe caching and version control across the Reasonix ecosystem.

Frequently Asked Questions

What happens when a tool call fails schema validation?

When an incoming request does not conform to the canonical JSON-Schema defined in the tool's ContractEntry, the runtime rejects the call before execution begins. The system returns a schema_mismatch error code with specific validation details, preventing malformed data from reaching the tool implementation and preserving system integrity.

How does the ReadOnlyHint field affect tool execution?

The ReadOnlyHint boolean in ContractEntry indicates whether a tool modifies persistent state. This metadata influences scheduling decisions, allowing the system to grant read-only sub-agents permission to execute read-only tools without additional approval workflows. It serves as a safety hint rather than an access control mechanism.

Where is the canonical schema stored and maintained?

The canonical schema resides in internal/extension/protocol/schema.generated.json. This file is auto-generated at compile time and should never be hand-edited. Human-readable documentation is generated in docs/TOOL_CONTRACT.md, which draws from the same schema source to ensure documentation always matches the runtime definition.

How is contract consistency verified during development?

The internal/tool/contract_test.go file contains comprehensive tests that run during every CI build. These tests verify that every built-in tool appears in the markdown documentation, that descriptions are non-empty, that read-only flags match the implementation, and that the embedded schema bytes match the generated file exactly.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}