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

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-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, 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 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:

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 (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:

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 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 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) and is validated by the documentation test:

{
  "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-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-v2/internal/tool/tool.go)	Tool implementations and canonical schema generation
[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-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.

• Schema compliance is enforced through compile-time Go struct generation, automated documentation tests in internal/tool/contract_test.go, and runtime verification in 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 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 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 would detect the contract violation.

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