🔥 TML — LLM-Optimized API Schemas

Make APIs understandable for LLMs — fewer tokens, fewer mistakes, better tool calls.

Used to test tool selection across real APIs (GitHub, Stripe, NASA, Slack, and more)

---

LLMs don’t fail because they’re not smart enough.

They fail because we describe tools in ways they can’t reason about.

TML fixes that.

---

🎥 See it in action (30s)

---

⚡ The Problem

AI agents need tool descriptions to call APIs.

Today’s formats are:

• too verbose
• too nested
• full of noise

👉 Result:

• wrong tool selection
• hallucinated parameters
• wasted tokens

At scale, this gets expensive fast:

• ~15,000 tokens for ~20 tools (just schema overhead)

---

💡 The Idea

TML is a minimal format for describing APIs focused only on what models actually need:

• endpoint
• intent
• parameters
• output

Nothing else.

Unlike traditional schemas, TML is optimized for how LLMs reason, not how systems validate.

#oatr1|My API|https://api.example.com
users.list|GET /users|page:i=1,limit:i=10|{users:[{id,name,email}]}|users list
users.get|GET /users/{id}|id:s!|{id,name,email,role}|users get profile

Two tools. One file. Works with Claude, GPT-4, Gemini, Gemma, Llama — any model that reads text.

---

💥 What you get

• ✅ Better tool selection
• ✅ Less hallucination
• ✅ Smaller context usage
• ✅ Easier debugging

---

⚡ Two formats

api.tml  → human-friendly (write & edit)
api.min  → model-friendly (send to LLM)

👉 Same tools. Less noise. Better reasoning.

---

📊 Why it matters

Format	Tokens (3 tools)	Accuracy
OpenAPI JSON	769	100%
MCP JSON-RPC	765	100%
OpenAI Schema	522	100%
TML .min	174	100%

Token counts measured from Claude API input_tokens. Full methodology: benchmarks/

---

🧩 How it works

API → TML → .min → LLM → Tool Call → API

👉 You send .min to the model — everything else is for humans.

---

🚀 Try it in 60 seconds

🏠 Local (no API key)

winget install Ollama.Ollama
ollama pull gemma4:latest
ollama serve

cd studio && npm install && node server.js

☁️ Cloud (Anthropic Claude)

cd studio
npm install
echo "ANTHROPIC_API_KEY=your-key" > .env
node server.js

Switch providers anytime from the dropdown in the top bar.

👉 From API → working AI agent in under a minute

---

🔌 LLM Support

• Claude
• GPT-4 / OpenAI
• Gemini
• Gemma / Ollama (local)
• Llama / Mistral / any text model

👉 No special integration required — just text.

---

🛠️ CLI

Compile TML → .min

node cli/tml-to-min.cjs tools.tml

Convert from OpenAPI

Already have an OpenAPI spec? Convert it directly:

node cli/index.js convert openapi.json                  # outputs TML + .min
node cli/index.js convert openapi.json --min            # .min only
node cli/index.js convert https://api.example.com/openapi.json

Write .min by hand

For simple APIs, skip TML Source entirely:

#oatr1|My API|https://api.example.com
users.list|GET /users|page:i=1,limit:i=10|{users:[{id,name,email}]}|users list

---

📦 Examples

30+ ready-to-use registries: Open-Meteo, PokeAPI, GitHub, Stripe, Slack, YouTube, Gmail, SpaceX, Rick and Morty, and more.

Browse them in examples/ and examples/generated/.

---

⚠️ What this is NOT

• Not a replacement for API specs
• Not a replacement for MCP
• Not a validation system
• Not a framework

👉 It’s a reasoning layer for LLMs

---

❓ FAQ

Is TML a replacement for MCP? No. MCP is a live protocol for connecting agents to tool servers. TML is a static file format for describing APIs that already exist. They complement each other.

Do I need to run a server? No. A .min file is just text — drop it in any system prompt and the LLM reads it.

What if I already have an OpenAPI spec? Convert it with one command: node cli/index.js convert openapi.json --min

Can I use it fully offline? Yes. Run Studio with Ollama and pick any local model. No API key, no outbound requests.

Does this work with private/authenticated APIs? Yes. TML supports auth declarations (bearer, API key, OAuth2). The agent handles authentication at call time.

---

🚧 Status

Experimental (v0.1)

---

⭐ If this is interesting

Give it a star 🙌

License

Apache 2.0 — Matias Fernandez