# What Is the Tool Contract in DeepSeek-Reasonix and How It Enforces Schema Compliance

> Understand the Tool Contract in DeepSeek-Reasonix. Learn how it defines tools and enforces schema compliance via compile-time generation, doc tests, and runtime checks.

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

---

**The Tool Contract in DeepSeek-Reasonix is a provider-visible specification that defines every built-in tool's name, description, read-only flag, and canonical JSON schema, with compliance enforced through compile-time generation, documentation tests, and runtime verification.**

DeepSeek-Reasonix uses a **Tool Contract** to guarantee that the model's built-in tools remain consistent across documentation, code, and runtime behavior. This contract serves as the single source of truth for tool availability and schema structure, enabling reliable request validation and permission checks by the host. Understanding how this system works is essential for anyone extending Reasonix or integrating it into provider environments.

## Where the Tool Contract Is Defined

The contract documentation lives in [[`docs/TOOL_CONTRACT.md`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/docs/TOOL_CONTRACT.md)](https://github.com/esengine/DeepSeek-Reasonix/blob/main-v2/docs/TOOL_CONTRACT.md), where lines 5-10 explain that the document "records the provider-visible contract for Reasonix compile-time built-in tools"【/cache/repos/github.com/esengine/DeepSeek-Reasonix/main-v2/docs/TOOL_CONTRACT.md#L5-L10】.

This Markdown file contains a table listing every available tool with:

- **Tool name** (e.g., `bash`, `read_file`, `edit_file`)
- **Read-only flag** indicating whether the tool modifies state
- **Description** of the tool's purpose
- **Reference to the canonical JSON schema**

The human-readable format ensures providers can audit tool capabilities without reading source code.

## Canonical Schema Source and Generation

The **canonical JSON schemas** are not hand-written. They are generated from Go struct definitions in the `tool.BuiltinContractEntries` package.

In [`internal/tool/tool.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/tool/tool.go), each built-in tool implementation defines a Go struct that gets marshaled into JSON schema. This compile-time generation ensures the schema always reflects the actual code structure.

The test file [`internal/tool/contract_test.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/tool/contract_test.go) validates this pipeline. Lines 17-20 contain `TestBuiltinToolContractDocumentation`, which verifies that every built-in tool has a documented row and that the generated schema matches the documentation【/cache/repos/github.com/esengine/DeepSeek-Reasonix/main-v2/internal/tool/contract_test.go#L17-L20】.

Run this test to validate contract documentation:

```bash
go test ./internal/tool -run TestBuiltinToolContractDocumentation

```

## Runtime Registration and Verification

When Reasonix boots, it registers built-in tools on the provider-visible surface. The test `TestBootToolContractMatchesProviderVisibleSurface` in [`internal/boot/boot_test.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/boot/boot_test.go) (lines 18-22) cross-checks this runtime registry against the contract, ensuring the host sees identical tool names and read-only flags【/cache/repos/github.com/esengine/DeepSeek-Reasonix/main-v2/internal/boot/boot_test.go#L18-L22】.

Execute this verification with:

```bash
go test ./internal/boot -run TestBootToolContractMatchesProviderVisibleSurface

```

This dual-layer testing (documentation + runtime) prevents mismatches between what the contract promises and what the system delivers.

## Three-Layer Schema Compliance Enforcement

DeepSeek-Reasonix enforces **Tool Contract** compliance through three interconnected mechanisms:

1. **Compile-time generation** — Go structs in [`internal/tool/tool.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/tool/tool.go) define the schema source of truth; any API change must update the implementation first.

2. **Documentation test** — `TestBuiltinToolContractDocumentation` reads generated schemas and fails if [`TOOL_CONTRACT.md`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/TOOL_CONTRACT.md) lacks matching entries (verified against lines 33-39 of the contract)【/cache/repos/github.com/esengine/DeepSeek-Reasonix/main-v2/docs/TOOL_CONTRACT.md#L33-L39】.

3. **Runtime test** — `TestBootToolContractMatchesProviderVisibleSurface` confirms the exposed tool surface exactly matches contract specifications for names and flags.

Because these tests run automatically, schema drift is impossible. A pull request that changes a tool's arguments, renames a tool, or modifies read-only status without updating all three layers will fail CI.

## Example: Generated Schema Structure

Below is an excerpt of the canonical JSON schema that `tool.BuiltinContractEntries` produces for the `edit_file` tool. This schema appears in the contract table (line 16 of [`TOOL_CONTRACT.md`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/TOOL_CONTRACT.md)) and is validated by the documentation test:

```json
{
  "name": "edit_file",
  "description": "Replace an exact string in a file with another.",
  "parameters": {
    "type": "object",
    "properties": {
      "path": { "type": "string", "description": "File to edit" },
      "old_string": { "type": "string", "description": "Exact text to replace" },
      "new_string": { "type": "string", "description": "Replacement text" }
    },
    "required": ["path", "old_string", "new_string"]
  },
  "readOnly": false
}

```

The `readOnly: false` flag signals to hosts that this tool performs mutations, enabling appropriate permission checks.

## Key Files for Tool Contract Analysis

| File | Purpose |
|------|---------|
| [[`docs/TOOL_CONTRACT.md`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/docs/TOOL_CONTRACT.md)](https://github.com/esengine/DeepSeek-Reasonix/blob/main-v2/docs/TOOL_CONTRACT.md) | Human-readable contract with tool registry and schema references |
| [[`internal/tool/tool.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/tool/tool.go)](https://github.com/esengine/DeepSeek-Reasonix/blob/main-v2/internal/tool/tool.go) | Tool implementations and canonical schema generation |
| [[`internal/tool/contract_test.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/tool/contract_test.go)](https://github.com/esengine/DeepSeek-Reasonix/blob/main-v2/internal/tool/contract_test.go) | Documentation consistency validation |
| [[`internal/boot/boot_test.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/boot/boot_test.go)](https://github.com/esengine/DeepSeek-Reasonix/blob/main-v2/internal/boot/boot_test.go) | Runtime surface verification |

## Summary

- The **Tool Contract** is DeepSeek-Reasonix's provider-visible specification for all built-in tools, documented in [`docs/TOOL_CONTRACT.md`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/docs/TOOL_CONTRACT.md).

- **Schema compliance** is enforced through compile-time Go struct generation, automated documentation tests in [`internal/tool/contract_test.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/tool/contract_test.go), and runtime verification in [`internal/boot/boot_test.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/boot/boot_test.go).

- Any tool API change must propagate through all three layers; otherwise tests fail and the build breaks, guaranteeing contract integrity.

- The `readOnly` flag in each contract entry enables hosts to enforce permission policies without inspecting implementation details.

## Frequently Asked Questions

### What happens if a developer changes a tool's schema without updating the contract?

The build fails. `TestBuiltinToolContractDocumentation` detects the mismatch between the generated schema and the Markdown table, and `TestBootToolContractMatchesProviderVisibleSurface` catches runtime surface discrepancies. Both tests must pass for CI to succeed.

### How does the contract help external providers integrate with DeepSeek-Reasonix?

Providers read [`docs/TOOL_CONTRACT.md`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/docs/TOOL_CONTRACT.md) to discover available tools, their parameters, and mutation capabilities. The canonical JSON schemas enable automatic request validation and permission gating without requiring providers to parse Go source code.

### Can custom tools be added to the Tool Contract?

The contract specifically covers **compile-time built-in tools** as documented in [`TOOL_CONTRACT.md`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/TOOL_CONTRACT.md) lines 5-10. Custom tools loaded at runtime would need separate registration mechanisms outside this contract system.

### Why is the `readOnly` flag significant for schema compliance?

The `readOnly` flag determines whether a tool can modify system state. Hosts rely on this contract field to enforce sandboxing policies. If a tool incorrectly reports `readOnly: true` while performing mutations, the verification test in [`internal/boot/boot_test.go`](https://github.com/esengine/DeepSeek-Reasonix/blob/main/internal/boot/boot_test.go) would detect the contract violation.