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

> Discover the Reasonix tool schema contract and how DeepSeek-Reasonix enforces provider-visible capabilities. Learn about compile-time generation, build-time consistency, and runtime validation for robust tool interfaces.

- Repository: [YHH/DeepSeek-Reasonix](https://github.com/esengine/DeepSeek-Reasonix)
- Tags: deep-dive
- Published: 2026-08-08

---

**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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/schema.generated.json) file

Additional baseline tests in [`internal/boot/golden_baseline_test.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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.

```go
// 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:

```go
// 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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/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.