# Tscg

> TSCG — Deterministic tool-schema compiler for LLM agents. 50-72% token savings, 50 tools in 2.4ms. Phi-4 recovers from 0% to 90% accuracy. 459 tests, zero dependencies, MIT.

- **Type:** MCP server
- **Install:** `agentstack add mcp-skzl-ai-tscg`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [SKZL-AI](https://agentstack.voostack.com/s/skzl-ai)
- **Installs:** 0
- **Category:** [Developer Tools](https://agentstack.voostack.com/c/developer-tools)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [SKZL-AI](https://github.com/SKZL-AI)
- **Source:** https://github.com/SKZL-AI/tscg
- **Website:** https://github.com/SKZL-AI/tscg#readme

## Install

```sh
agentstack add mcp-skzl-ai-tscg
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# TSCG -- Tool-Schema Compression Grammar

[](https://www.npmjs.com/package/@tscg/core)
[](https://www.npmjs.com/package/@tscg/mcp-proxy)
[](https://www.npmjs.com/package/@tscg/tool-optimizer)
[](LICENSE)
[]()
[]()

**Deterministic tool-schema compiler that reduces LLM tool-definition overhead by 50--72% while *improving* accuracy.**

1,200 LOC TypeScript. Zero dependencies. Sub-millisecond. 23KB ESM bundle.

## Paper 2: Agentic RAG Enablement (May 2026)

### 6,566-Call Agentic RAG Benchmark

TSCG enables agentic RAG under constrained context budgets. We evaluate 14 models (1.5B--32B local models plus one frontier API model) across 6,566 API calls at three context budgets (8K, 16K, 32K) with 28 tool definitions:

| Condition | JSON EM | TSCG EM | Delta |
|-----------|---------|---------|-------|
| 8K, 28 tools (avg 8 models) | 2.6% | 23.1% | **+20.5pp** |
| HotpotQA (Phi-4, 8K) | 0% | 48% | **+48pp** |
| 32K ceiling control | -- | -- | 4 of 5 models: \|Delta\| $30,000/month**.

Worse: small models (4B--14B) cannot parse JSON-format tool schemas reliably at scale -- achieving **0--49% accuracy** with >15 tools. This locks agentic capabilities behind expensive frontier APIs.

## Key Results

### Pareto Dominance: Better Accuracy AND Fewer Tokens

BFCL ([Berkeley Function Calling Leaderboard](https://gorilla.cs.berkeley.edu/leaderboard.html)) validation -- the industry standard for tool-calling evaluation:

| Model | Without TSCG | With TSCG | Improvement | Token Savings |
|-------|-------------|-----------|-------------|---------------|
| Claude Sonnet 4 | 85.7% | 93.2% | +7.5pp | 46.8% |
| **GPT-4o** | **31.7%** | **57.4%** | **+25.7pp (181% ARR)** | 2.6% |
| GPT-5.2 | 61.9% | 89.4% | +27.5pp (144% ARR) | 8.3% |

Every model *improves*. TSCG achieves **108--181% Accuracy Retention Rate** -- it doesn't just retain accuracy, it increases it.

### Small Model Enablement

| Model | JSON Baseline (20 tools) | With TSCG | Recovery |
|-------|------------------------|-----------|----------|
| Phi-4 14B | 0% | 84.4% | **+84.4pp** |
| Mistral 7B | 35% | 80.1% | **+45.1pp** |
| Gemma 3 4B | 49.9% | 67.0% | +17.1pp |

Seven small models (4B--14B) that achieve 0--49% accuracy on JSON tools recover to **65--90%** with TSCG. The root cause: JSON format, not model capacity (R^2 = 0.88 against JSON baselines, collapses to 0.03 against text -- **97% of variance is format sensitivity**).

### Full Benchmark Summary

From **~19,000 API calls** across **12 models** (4B--32B + 3 frontier APIs), 5 scenarios:

| Finding | Detail |
|---------|--------|
| Token savings | 50--72% on tool schemas |
| BFCL validation | 108--181% Accuracy Retention Rate |
| Formal guarantee | >=51% savings on any well-formed schema (Theorem 3.1) |
| Predictive model | R^2 = 0.88 predicts TSCG benefit from single baseline measurement |
| Speed | 50 tools in 2.4ms (Node.js v24, commodity hardware) |
| Cost at scale | >$30,000/month savings at 100K calls/day |

### Verified Performance (Fresh Install)

Independent reproduction on `@tscg/core` from npm:

| Metric | Measured |
|--------|----------|
| 5 realistic tools (Claude target) | 59.5% token savings |
| 50 tools | 66.6% savings in 2.4ms |
| Compression time (5 tools) | 0.9ms |
| Unit tests | 108 passing (core 47 + proxy 61) |
| Bundle | 34.7KB (11.7KB gzipped) |
| Dependencies | 0 |

## What TSCG Does

TSCG applies 8 formally-defined transforms grounded in how causal transformers process tokens:

| Principle | Full Name | What It Does |
|-----------|-----------|-------------|
| **TAS** | Tokenizer-Aligned Syntax | Optimizes for BPE boundaries |
| **CFL** | Constraint-First Layout | Exploits the attention sink at position 0 |
| **CFO** | Causal-Flow Ordering | Orders operations into causal chains |
| **SDM** | Semantic Density Maximization | Removes 104+ filler patterns |
| **DRO** | Delimiter-Role Optimization | Converts verbose phrases to compact delimiters |
| **CCP** | Closure-Context Preservation | Appends closure block for recency bias |
| **CAS** | Causal Access Scoring | Scores and reorders by parameter fragility |
| **SAD-F** | Selective Anchor Duplication | Budget-constrained anchor duplication |

## Quick Start

All three `@tscg/*` packages use umbrella versioning -- same version number, released together.

```bash
npm install @tscg/core                # Core compression engine
npm install @tscg/mcp-proxy           # Transparent MCP middleware
npm install @tscg/tool-optimizer      # LangChain / Vercel AI SDK integrations
```

```typescript
import { compress } from '@tscg/core';

const tools = [
  {
    type: 'function',
    function: {
      name: 'get_weather',
      description: 'Get the current weather for a location',
      parameters: {
        type: 'object',
        properties: {
          location: { type: 'string', description: 'City name or coordinates' },
          units: { type: 'string', enum: ['celsius', 'fahrenheit'] },
        },
        required: ['location'],
      },
    },
  },
];

const result = compress(tools, { model: 'claude-sonnet' });
console.log(result.compressed);
console.log(`Saved ${result.metrics.tokens.savingsPercent}% tokens`);
// => "get_weather(location:str units?:str[celsius|fahrenheit])|Get current weather"
// => "Saved 62.3% tokens"
```

### Result Object

```typescript
const result = compress(tools, { model: 'claude-sonnet', profile: 'balanced' });

result.compressed                        // string — compressed tool definitions
result.metrics.tokens.original           // number — original token count
result.metrics.tokens.compressed         // number — compressed token count
result.metrics.tokens.savingsPercent     // number — e.g. 62.3
result.metrics.compressionTimeMs         // number — e.g. 0.9
result.appliedPrinciples                 // string[] — e.g. ['SDM', 'CAS', 'DRO', 'TAS']
result.metrics.perTool                   // { name, originalTokens, compressedTokens, savingsPercent }[]
```

### Options

```typescript
compress(tools, {
  model: 'claude-sonnet',   // Target model: 'claude-sonnet' | 'gpt-4o' | 'gpt-4' | ...
  profile: 'balanced',      // Profile: 'conservative' | 'balanced' | 'aggressive' | 'auto'
});
```

### Description-Only Mode (v1.4.0)

Compress only `.description` fields while preserving the full JSON Schema structure -- compatible with native tool-calling APIs (OpenAI, Anthropic, Google):

```typescript
import { compressDescriptions } from '@tscg/core';

const result = compressDescriptions(tools, { model: 'claude-sonnet' });
console.log(result.tools);              // Tools with compressed descriptions
console.log(result.metrics.descriptions.savingsPercent); // ~25-40% description savings
```

### Auto Profile (v1.4.0)

The `auto` profile selects compression principles based on catalog size. At >=30 tools, CFL/CFO are automatically disabled (they become harmful at scale per our 100-tool benchmark findings):

```typescript
compress(tools, { model: 'claude-sonnet', profile: 'auto' });
```

## Packages

| Package | Description | Install |
|---------|-------------|---------|
| [`@tscg/core`](packages/core/) | Core compression engine (8 operators) | `npm i @tscg/core` |
| [`@tscg/mcp-proxy`](packages/mcp-proxy/) | MCP stdio proxy -- transparent TSCG compression for any MCP server | `npm i @tscg/mcp-proxy` |
| [`@tscg/tool-optimizer`](packages/tool-optimizer/) | LangChain, MCP, Vercel AI SDK integrations | `npm i @tscg/tool-optimizer` |

## CLI

```bash
# Compress tool schemas
npx tsx cli/tscg.ts compress --input tools.json --model claude-sonnet --profile balanced

# Run benchmarks
npx tsx cli/tscg.ts benchmark --model claude-sonnet

# Show compression info
npx tsx cli/tscg.ts info
```

## MCP Proxy

`@tscg/mcp-proxy` sits between Claude Code (or any MCP client) and your MCP tool servers, transparently compressing tool schemas:

```bash
# Opus 4.7 -- 57-63% savings, +2.5 to +7.5pp accuracy
npx @tscg/mcp-proxy --target=claude-opus-4-7 --server=

# Sonnet 4 -- 57-63% savings, robust accuracy
npx @tscg/mcp-proxy --target=claude-sonnet-4 --server=
```

Setting `--target` automatically enables the full compression pipeline validated by our 720-call benchmark. No other flags required.

**Legacy mode** (backward compatible with v1.0.x):
```bash
npx @tscg/mcp-proxy --server=
```

## Integrations

**LangChain:**
```typescript
import { withTSCG } from '@tscg/tool-optimizer/langchain';
const optimizedAgent = withTSCG(agent);
```

**Vercel AI SDK:**
```typescript
import { tscgMiddleware } from '@tscg/tool-optimizer/vercel';
```

## TSCG vs Other Approaches

| Property | TSCG | LLMLingua-2 | DSPy / SAMMO |
|----------|------|-------------|-------------|
| Accuracy effect | **Improves** (108--181% ARR) | Degrades (-5 to -20%) | Degrades |
| Speed | **2.4ms / 50 tools** | ~42s (GPU) | Minutes |
| Dependencies | **None** | GPU + ML framework | API calls |
| Deterministic | **Yes** | No | No |
| Formal guarantees | **>=51% savings** | None | None |
| Bundle size | **34.7KB** | Requires PyTorch | Full stack |
| Works offline | **Yes** | GPU required | API required |

## Who Benefits

- **Claude Code / Cursor / Windsurf users**: ~35K fewer tokens per subprocess
- **Local LLM users (Ollama)**: 7B models become functional tool-use agents with 50+ tools
- **Production API deployments**: >$30,000/month savings at 100K calls/day
- **Multi-agent orchestration**: Savings multiply per sub-agent in the chain
- **Edge / Mobile / Privacy**: EU AI Act compliant local deployment becomes viable

## Project Structure

```
packages/
  core/             # @tscg/core — compression engine (8 operators, 47 tests)
  mcp-proxy/        # @tscg/mcp-proxy — stdio proxy for MCP servers (61 tests)
  tool-optimizer/   # @tscg/tool-optimizer — LangChain, Vercel AI SDK integrations
paper/              # LaTeX source (arXiv version)
cli/                # Unified CLI (compress, benchmark, analyze, info)
benchmark/          # TAB benchmark harness, analysis code, raw data
integrations/       # Framework integration examples
docs/               # Technical documentation
```

## Development

```bash
git clone https://github.com/SKZL-AI/tscg.git
cd tscg
npm install
npm run build
npm test          # 459 tests
npm run typecheck # Type checking
```

## Papers

### Paper 1: TSCG -- Deterministic Tool-Schema Compilation for Agentic LLM Deployments

Furkan Sakizli ([ORCID: 0009-0009-5975-5014](https://orcid.org/0009-0009-5975-5014)). April 2026.

[TSCG-paper.pdf](./TSCG-paper.pdf) -- arXiv preprint (full version, 12 models, ~19,000 API calls, 4-class taxonomy)

LaTeX source is available in [`paper/`](paper/).

### Paper 2: Tool-Schema Compression Enables Agentic RAG Under Constrained Context Budgets

Furkan Sakizli ([ORCID: 0009-0009-5975-5014](https://orcid.org/0009-0009-5975-5014)). May 2026.

[TSCG-RAG-Benchmark-Paper.pdf](./TSCG-RAG-Benchmark-Paper.pdf) -- 14 models, 6,566 API calls, binary enablement at 8K

## Citation

```bibtex
@article{sakizli2026tscg,
  title={TSCG: Deterministic Tool-Schema Compilation for Agentic LLM Deployments},
  author={Sakizli, Furkan},
  year={2026},
  note={arXiv preprint},
  orcid={0009-0009-5975-5014}
}

@article{sakizli2026tscgrag,
  title={Tool-Schema Compression Enables Agentic RAG Under Constrained Context Budgets},
  author={Sakizli, Furkan},
  year={2026},
  note={arXiv preprint},
  orcid={0009-0009-5975-5014}
}
```

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, code style, and PR guidelines.

## License

[MIT](LICENSE)

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [SKZL-AI](https://github.com/SKZL-AI)
- **Source:** [SKZL-AI/tscg](https://github.com/SKZL-AI/tscg)
- **License:** MIT
- **Homepage:** https://github.com/SKZL-AI/tscg#readme

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** yes
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-skzl-ai-tscg
- Seller: https://agentstack.voostack.com/s/skzl-ai
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.