What can you do with this server?

The server provides tools for AI agents to manage TNL (Typed Natural Language) contracts — structured English feature contracts governing how code changes are proposed, approved, and implemented. * get_impacted_tnls: Retrieve TNL units whose declared paths: overlap with code files the agent intends to edit. Repo-wide TNL units are always included. * retrieve_tnl: Fetch the full verbatim content of one or more TNL contracts by their IDs. Unmatched IDs are reported in a notFound list. * propose_tnl_diff: Stage a batch of proposed TNL creates or updates for human review, returning a diff_id for later approval. Nothing is written to disk until approved. * approve_tnl_diff: Commit a staged proposal — writes tnl/ .tnl files to disk, regenerates sidecar metadata, and clears the staging record. * verify: Run structural and test-binding integrity checks on TNLs impacted by a set of code paths, returning a structured JSON report suitable for CI gates. * trace: Record or read session-scoped events documenting how TNL was used during an agent session, useful for audit trails and observability.

Which integrations are available for this server?

Uses Markdown-based TNL files to define per-feature contracts with a fixed schema, reviewed and approved before implementation.

de en es ja ko ru zh

TNL

by janaraj

Overview Schema Source Related Servers Discussions Admin

TypeScript

Local

TNL — Typed Natural Language

AI coding agents make design decisions silently, drift from what was planned, and lose context at session end. TNL (Typed Natural Language) is the fix: a per-feature English contract with a fixed schema — proposed by the agent, approved by you, implemented against, saved on disk, and read by every future session. If you've used plan mode in Claude Code, this is the same discipline made compact, persistent, and machine-checkable.

The schema

The schema is seven fields:

id / title — what this feature is
scope — feature or repo-wide
paths — which files the change is allowed to touch
surfaces — named external surfaces (CLI commands, routes, MCP tools)
behaviors — numbered MUST / SHOULD / MAY clauses; the contract proper
non-goals — what's explicitly out of scope
rationale — the why, for future readers

You approve this once, before any code runs. The agent implements against each MUST clause and self-attests at the end — for every MUST, naming the file or test that satisfies it.

No new tool, no new agent, no new workflow. TNL slots into whatever agent you already use. Claude Code, Codex, Gemini, and Cursor get first-class tnl init with stanza + hooks + MCP. Any agent that reads a Markdown instruction file adopts with a two-step manual copy — the minimum product is a stanza in your instruction file plus a tnl/ directory. tnl verify, the PreToolUse hook that re-surfaces the contract mid-edit, and the MCP server are optional layers on top.

Related MCP server: MCP SDD Server

A TNL file looks like this

id: user-rate-limiter
title: Per-user API rate limiter
scope: feature
owners: [@jana]
paths: [src/middleware/rate-limit.ts]
surfaces: [POST /api/*]

intent:
  Cap requests per user at 60/min; exceeding users get 429 with
  Retry-After. Prevents abuse on the public write endpoints.

behaviors:
  - The middleware MUST track request counts per user in a sliding window of 60 seconds.
  - When a user exceeds 60 requests in the window, the middleware MUST return HTTP 429.
  - [test: tests/rate_limit.test.ts::returns_429_on_exceeded] The 429 response MUST include a `Retry-After` header.
  - [semantic] The middleware SHOULD log the user ID and request path on every 429, without leaking the request body.

non-goals:
  - Per-IP rate limiting — authenticated surface only.
  - Distributed rate state — in-memory per instance for now.

Three zones: machine (id, paths, surfaces), contract (behaviors with RFC 2119 keywords and [semantic] / [test: …] prefixes), human (intent, non-goals, rationale).

The workflow

Every feature request — new or modification — runs through 7 steps:

Scope — agent scans tnl/ for files whose paths: overlap the request. If one exists, the output is an edit; if not, a new TNL.
Clarify — ambiguous request? Agent asks questions before proposing anything.
Propose — agent outputs the full TNL content inline in chat. Nothing on disk yet.
Wait for approval — you review, push back, approve. Nothing is written until you say go.
Save — agent writes the approved TNL to tnl/<slug>.tnl.
Implement — agent writes code + tests against the contract. paths: bounds the change.
Self-attest — agent lists every MUST clause and where it was satisfied. Silent omission counts as a miss.

For follow-up work, step 1 returns "edit the existing TNL" — and the next session reads the already-approved contract as context, rather than rediscovering design decisions from the code.

What you get over plan mode

Structure. Seven fixed fields. Reviewers scan the same things every time. Agents produce the same shape every session.
Persistence. Plan mode's output is a chat message — gone when the session ends. A TNL is a file on disk alongside your code. The next session reads the contract instead of re-analysing source.
Enforcement. Every MUST clause maps to a file or test at self-attestation time. tnl verify checks paths exist and test bindings resolve. The PreToolUse hook re-injects the contract on every Edit/Write so the agent can't drift silently.
Incremental adoption. No bulk migration. Your next feature gets a TNL; the rest of the repo stays as-is. The knowledge base accumulates as the work accumulates.

Does it actually work?

We ran a controlled A/B. Baseline condition: four working principles — think before coding, simplicity first, surgical edits, goal-driven — written as prose in the project's CLAUDE.md / AGENTS.md. TNL condition: the same four plus two more (match existing conventions; exhaustive end-of-task self-attestation) encoded as tnl/workflow.tnl, plus a per-feature TNL. Same agent, same project context; only the contract step differs.

Headline task: add event-driven triggers to a 16KLOC Python codebase. 35 behavioural scenarios covering config, cycle prevention, cron coexistence, CLI surfaces.

Agent	Run	TNL	Baseline	Gap
Claude Code Opus 4.7	1	35/35	29/35	+6
Claude Code Opus 4.7	2	31/35	27/35	+4
Claude Code Opus 4.7	3	30/35	25/35	+5
Codex GPT-5.4 high	1	32/35	26/35	+6
Codex GPT-5.4 high	2	31/35	26/35	+5
Codex GPT-5.5	1	32/35	29/35	+3
Codex GPT-5.5	2	— ¹	30/35	—

¹ Second GPT-5.5 baseline has no paired TNL run; averaged baseline across the two GPT-5.5 runs is 29.5/35.

TNL was ahead of baseline in every paired cell across models. Gap ranges +3 to +6 scenarios.

Model scaling. The gap narrows as the underlying agent gets stronger: baseline on the same task jumped from 26/35 (Codex GPT-5.4, avg of 2 runs) to 29.5/35 (Codex GPT-5.5, avg of 2 runs) with no change to the codebase or prompt. The contract step still helps, but it helps less when the agent already writes disciplined code on its own.

Other signals:

Contracts retained. TNL runs encoded 15–38 explicit MUST clauses in the per-feature TNL before any code was written. Baseline produced 0 by construction — there's no contract step. On the cross-session retention question ("did the next session re-use the contract or re-read code?"), the TNL agent opened and edited the existing TNL on every follow-up task we measured; baseline re-read source.
Follow-up work reused the contract. On round-2 tasks in the same worktrees, TNL agents edited the existing TNL file rather than creating a new one (4/4 samples). The baseline agent had to re-read the code each time.

Caveats up front. Small sample (2–3 per cell), LLM sessions are noisy, and we built the tool. Every script, prompt, raw JSON, and session transcript is committed so you can rerun anything.

Full eval report →

Built with TNL

We built this tool using its own workflow — the minimal form (CLAUDE.md stanza + tnl/, no hooks or MCP). The baseline rules live in tnl/workflow.tnl and every feature has its own TNL in tnl/. In practice: faster turnaround, few rework cycles, each next change edits the spec instead of re-analysing code. One project's worth of evidence, but the meta-test isn't nothing.

What TNL builds on

Two of Andrej Karpathy's observations framed the problem we're solving:

"Agents make wrong assumptions silently" — coding agents don't manage confusion, don't seek clarification, don't surface tradeoffs. Prompting norms help but they're vibes, not gates.
"The LLM is the programmer, the wiki is the codebase" — structured Markdown the model can reason over directly beats fuzzy RAG for mid-sized bodies of knowledge.

TNL is our answer: a concrete contract format with a fixed schema, a review workflow, and enforcement plumbing that turns both observations into a daily practice.

Install

# One-off, no install
npx -y typed-nl <command>

# Or install globally
npm install -g typed-nl
tnl <command>

Requires Node 20 or later.

Other agents (manual install)

If your agent reads a markdown instruction file but isn't in tnl init's native list, the minimum adoption is two copies:

Copy tnl/workflow.tnl from this repo into tnl/workflow.tnl in your project.
Paste the TNL workflow stanza (the block under  that tnl init --agent claude would emit into CLAUDE.md) into your agent's instruction file.

That's it — the workflow fires from the stanza, contracts live in tnl/. The hook, MCP server, and CI action are all optional and agent-specific; they can be added later if your stack supports them.

Quickstart

1. Start minimal

Begin with just the baseline TNL scaffold — no MCP, no hooks, no CI. The agent follows the workflow from the appended CLAUDE.md stanza alone.

cd /path/to/your/repo
npx -y typed-nl init --agent claude --minimal

This writes only:

tnl/ — where your TNL contracts will live
tnl/workflow.tnl — baseline session principles
CLAUDE.md — TNL workflow stanza appended (or file created if missing)

For Codex: --agent codex (writes AGENTS.md). For Gemini: --agent gemini (writes GEMINI.md). For Cursor: --agent cursor (writes AGENTS.md + .cursor/mcp.json).

2. Author your first TNL

Start a Claude Code (or Codex / Gemini / Cursor) session and ask for any feature. The agent, guided by the workflow stanza, will:

Scope the request — check for existing TNLs that cover it.
Clarify ambiguous requirements by asking questions.
Propose a TNL inline in chat as a fenced code block.
Wait for your approval — nothing is written to disk yet.
Save the approved TNL to tnl/<slug>.tnl.
Implement against the approved TNL (modifying only files listed in paths:).
Self-attest — list each MUST clause and where it was satisfied.

3. Verify

npx -y typed-nl verify

Runs tier 1 (paths and dependencies exist) and tier 2 (test-binding integrity — each [test:] annotation names a test that still exists). Exits 2 on any failure; CI uses this gate.

4. Add capabilities as you need them

You can always re-run tnl init to layer on more. Each step is independent and safe to re-run (idempotent):

# Full install: MCP server + PreToolUse hook + CI workflow
npx -y typed-nl init --agent claude

# Everything except CI
npx -y typed-nl init --agent claude --no-ci

# Everything except the PreToolUse hook
npx -y typed-nl init --agent claude --no-hook

# Claude only: add the /tnl-feature slash command
npx -y typed-nl init --agent claude --with-skill

What each capability gives you:

Capability	Added by default (omit `--minimal`)	What it does
MCP server	yes	Registers `tnl` in `.mcp.json` / `.codex/config.toml` / `.gemini/settings.json` / `.cursor/mcp.json`. Agent gains 6 tools: retrieve, propose, approve, verify, impacted, trace.
PreToolUse hook	yes (Claude)	`.claude/settings.json` hook auto-injects impacted TNLs as context on every `Edit` / `Write`.
CI workflow	yes	`.github/workflows/tnl-verify.yml` runs `tnl verify` on push + PR.
`/tnl-feature` skill	no (opt-in via `--with-skill`)	Claude Code slash command for explicit invocation.

Commands

tnl init [flags]          # scaffold TNL in a project
tnl verify [paths...]     # check structural + test-binding integrity
tnl resolve [id...]       # regenerate sidecar meta (hashes, classification)
tnl impacted <paths...>   # list TNLs whose paths: overlap with given code paths
tnl diff <file>           # show clause-level diff of a TNL vs HEAD
tnl test-plan <id>        # list test-backed clauses for a unit

`tnl init` flags

Flag	Default	Behavior
`--agent claude\|codex\|gemini\|cursor`	auto-detect	Target one agent; overrides detection
`--minimal`	off	Scaffold only `tnl/` + instruction-file stanza; skip everything below
`--no-ci`	off	Skip `.github/workflows/tnl-verify.yml`
`--no-mcp`	off	Skip MCP server registration
`--no-hook`	off	Skip Claude PreToolUse hook
`--with-skill`	off	(Claude only) Install `/tnl-feature` slash command
`--local-install`	off	(Dev-only) Rewrite configs to absolute local `node dist/...` paths

Without --agent, init auto-detects targets (.claude/ → Claude; AGENTS.md → Codex; GEMINI.md → Gemini; .cursor/ → Cursor). Re-running tnl init is safe — existing files are detected and upgraded when the bundled template evolves.

MCP integration

tnl init auto-registers the TNL MCP server with supported agents. Once registered, the agent gains six tools:

Tool	Purpose
`get_impacted_tnls`	Return TNLs whose `paths:` overlap with given code paths
`retrieve_tnl`	Return the verbatim contents of one or more TNLs by id
`propose_tnl_diff`	Validate and stage a batch of create/update diffs
`approve_tnl_diff`	Commit a staged diff to disk, regenerate sidecars
`verify`	Run the verifier over given paths, return structured JSON
`trace`	Record / retrieve session-scoped agent-initiated events

Running MCP manually:

npx -y -p typed-nl tnl-mcp-server   # stdio JSON-RPC server

TNL file format

Machine zone fields (see tnl/workflow.tnl for a working example):

Field	Required	Notes
`id`	yes	Kebab-case slug matching the filename
`title`	yes	Short human label
`scope`	yes	`repo-wide` or `feature`
`owners`	yes	List of `@handles`
`paths`	scope=feature only	Files this TNL governs
`surfaces`	optional	Named external surfaces (CLI commands, routes, tools)
`dependencies`	optional	Other TNL ids this couples with
`intent`	yes	One-paragraph plain English
`behaviors`	yes	Numbered clauses using MUST / SHOULD / MAY
`non-goals`	yes	Explicit scope fences
`rationale`	optional	Tradeoffs, gotchas, why-behind-choices

RFC 2119 keywords:

MUST / MUST NOT — hard requirement
SHOULD / SHOULD NOT — strong preference
MAY — permission

Clause prefixes:

[semantic] — judgment needed to verify (not structural)
[test: <file>::<name>] — binds the clause to a named test; tnl verify checks the test still exists

Development

git clone https://github.com/janaraj/tnl.git
cd tnl
npm install
npm run build
npm test           # parser, resolver, verifier, CLI, MCP suites
npm run typecheck

Every new feature follows the TNL workflow this tool enforces. See CLAUDE.md for session guidance and tnl/ for the contracts governing this repository's own development.

License

MIT. See LICENSE.

Available Tools

6 tools

approve_tnl_diffApprove TNL diffA

DestructiveIdempotent

Apply a staged proposal: write each tnl/.tnl, regenerate its sidecar, and remove the staging record.

ParametersJSON Schema

Name	Required	Description	Default
`diff_id`	Yes	The diff_id returned by propose_tnl_diff.

TDQS

A4.6/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations indicate destructive and idempotent; description explicitly lists file writes, sidecar regeneration, and staging removal—adding concrete behavioral specifics beyond annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single 15-word sentence, no redundancy, every word carries meaning.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given single param, no output schema, and rich annotations, description sufficiently covers actions and prerequisite. Minor omission: no mention of return value or error cases.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema covers diff_id with description, but description adds valuable origin context ('returned by propose_tnl_diff'), helping agent understand where the parameter comes from.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description uses specific verb 'Apply' and resource 'staged proposal', enumerating exact actions (write, regenerate sidecar, remove staging record). Clearly distinguishes from sibling tool propose_tnl_diff which creates the proposal.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Implies prerequisite of having a staged proposal from propose_tnl_diff, but does not explicitly state when not to use or alternatives. Sibling context helps but could be more direct.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_impacted_tnlsGet impacted TNLsA

Read-only

Return TNL units whose declared paths overlap with any of the given code paths. Repo-wide units are always included.

ParametersJSON Schema

Name	Required	Description	Default
`paths`	Yes	Code paths the agent intends to edit.

TDQS

A3.8/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate readOnlyHint=true, and the description adds the specific behavior that repo-wide units are always included. No contradictions. Could mention limits or error handling but fine for a simple retrieval.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, no redundancy, front-loaded with the action verb 'Return'. Every word adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the simplicity (1 param, no output schema), the description covers the essential behavior and scope. Minor gap: no mention of return format or pagination, but acceptable for a straightforward list tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema has 100% coverage with clear parameter description. The tool description reinforces that paths are for overlap but adds no new semantic information beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly specifies the tool returns TNL units based on overlapping code paths, and always includes repo-wide units. This distinguishes it from siblings like retrieve_tnl or trace.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance on when to use this tool vs alternatives like retrieve_tnl or trace. The description implies usage for determining impacted TNLs before edits but lacks when-not-to-use or alternative recommendations.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

propose_tnl_diffPropose TNL diffA

Stage a proposed TNL change (batch of creates and updates) for human review. Returns a diff_id for later approve_tnl_diff.

ParametersJSON Schema

Name	Required	Description	Default
`intent`	Yes	Plain-English description of what the proposal is for.
`changes`	Yes	Ordered list of creates/updates.

TDQS

A3.8/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate it is not read-only, not destructive, not idempotent. The description adds that it returns a diff_id for later approval, but does not disclose side effects or required permissions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, front-loads the purpose, and includes the key return value and next step. No extraneous content.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description usefully mentions the returned diff_id. However, it could clarify that changes are staged but not applied immediately.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Both parameters (intent, changes) are fully described in the input schema. The tool description adds no additional parameter-level information beyond the schema's descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's action ('Stage a proposed TNL change') and resource ('batch of creates and updates'), and distinguishes it from sibling tools like approve_tnl_diff by noting the returned diff_id.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies the tool is used before approve_tnl_diff for human review, but does not explicitly state when not to use it or provide alternatives like get_impacted_tnls.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

retrieve_tnlRetrieve TNLA

Read-only

Return the verbatim content of TNL units identified by id. Ids with no matching file are listed in notFound.

ParametersJSON Schema

Name	Required	Description	Default
`ids`	Yes	TNL unit ids to fetch.

TDQS

A3.8/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description adds value beyond annotations by explaining that missing ids result in a 'notFound' list. Annotations already indicate readOnlyHint=true, and the description complements this by detailing the behavior for nonexistent ids.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences, front-loaded with the primary action. No extraneous text; every sentence adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple retrieval tool with one parameter and no output schema, the description covers the key behavior: returning verbatim content and listing missing ids. It provides sufficient context for an agent to understand the response structure.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with the description 'TNL unit ids to fetch.' The description does not add further detail about the parameter format or constraints beyond what the schema provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Return the verbatim content of TNL units identified by id,' specifying the action and resource. It distinguishes from sibling tools like approve_tnl_diff or propose_tnl_diff, which are mutation-oriented.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives. For instance, no mention of when to use get_impacted_tnls instead. The description only states functionality without usage context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

traceTrace TNL usageA

Record or read session events documenting how TNL was used. Pass event to record; omit it to read.

ParametersJSON Schema

Name	Required	Description	Default
`session_id`	Yes	Opaque session identifier chosen by the caller.
`event`	No	If present, append this event to the session log. Server overwrites any caller-supplied timestamp.

TDQS

A4.7/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the annotations (which indicate the tool is not read-only, not destructive, and not idempotent), the description adds that the server overwrites any caller-supplied timestamp. This is a key behavioral detail for the agent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence that front-loads the core functionality and wastes no words. It is maximally concise while still being informative.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

While the description covers the core behavior and parameter usage, it omits information about the return value when reading events. For a tool with no output schema, this is a gap: the agent doesn't know what the read operation returns.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 100% schema coverage, the description still adds value by explaining the conditional semantics of the `event` parameter: its presence triggers recording, absence triggers reading. The description clarifies the dual role beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's dual purpose of recording or reading session events related to TNL usage. It uses specific verbs ('record' and 'read') and a specific resource ('session events'), and it distinguishes itself from sibling tools like approve_tnl_diff or retrieve_tnl.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit guidance on when to use each mode: pass `event` to record, omit it to read. This tells the agent exactly how to invoke the tool for the desired action.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

verifyVerify TNLsA

Read-only

Verify the TNLs impacted by a set of code paths. Returns a structured report; verify failures are data, not isError.

ParametersJSON Schema

Name	Required	Description	Default
`paths`	Yes	Code paths the agent intends to edit.

TDQS

A3.6/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description adds a key behavioral trait beyond the readOnlyHint annotation: 'verify failures are data, not isError.' This tells the agent that failures are returned as data rather than errors, which is crucial for correct handling. It also notes the return of a structured report, providing useful context for tool invocation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise, consisting of two sentences: the first clearly states the purpose, and the second provides a crucial behavioral note. Every word earns its place, with no unnecessary information or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (one parameter, no output schema, annotations present), the description is sufficiently complete. It covers the tool's purpose, parameter, and a key behavioral aspect. However, it could be more complete by explicitly stating that it is a read-only verification tool and how it relates to sibling tools, but the current level is adequate.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 100% coverage with a description for the 'paths' parameter: 'Code paths the agent intends to edit.' The tool description does not add any additional meaning or clarification beyond what is already in the schema, so it meets the baseline for high coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Verify the TNLs impacted by a set of code paths.' It specifies the verb (verify) and resource (TNLs impacted by code paths), and mentions the return of a structured report. However, it does not differentiate from siblings like 'get_impacted_tnls' which also deals with TNLs, slightly reducing clarity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool over alternatives such as 'get_impacted_tnls' or 'propose_tnl_diff'. It lacks explicit when-to-use or when-not-to-use conditions, leaving the agent to infer usage context from the name alone.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

6 tool updatesv0.1.0Apr 24, 2026
- First observedapprove_tnl_diff
- First observedget_impacted_tnls
- First observedpropose_tnl_diff
- First observedretrieve_tnl
- First observedtrace
- First observedverify

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.2/5.0

Scored 2026-05-10 12:10 across 6 tools

Disambiguation5/5

Each tool has a distinct purpose: proposal staging, approval, impact analysis, retrieval, tracing, and verification. No overlap.

Naming Consistency5/5

All tools follow a consistent verb_noun pattern using snake_case, making them predictable and easy to understand.

Tool Count5/5

With six tools, the server covers the core workflow for TNL management without being too sparse or overburdened.

Completeness4/5

The set covers proposing, approving, retrieving, verifying, and tracing. Missing a list or delete operation, but the core lifecycle is well-represented.

Maintenance

ActivityInactive

ResponsivenessNo issues

Resources

Need Help?

Related Servers

Related MCP Connectors

mcp-serverOAuth
com.niftypm
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Project Management Communication File Systems
2
strata
ai.klavis
MCP server for progressive tool usage at any scale (see https://klavis.ai)
Agent Orchestration Autonomous Agents Developer Tools
25,748
DevSpeak
io.github.juanjaragavi
Official DevSpeak MCP server — translate technical text into formal specs from any AI IDE or agent
Developer Tools AI & Machine Learning Documentation Access
2
microservices.sh
sh.microservices
MCP server for AI agents to plan, verify, and deploy Cloudflare-native apps.
Cloud Platforms Agent Orchestration Developer Tools
21

Related MCP Servers

JSON Contractsofficial
Developer Tools Code Analysis
json-contracts
A
license
A
quality
C
maintenance
JSON Contracts is a local MCP server for transforming natural language into Git-controlled JSON contracts, JSON Schema validation, and structured LLM/agent outputs.
Updated 4 months ago (2026-05-05 17:17 UTC)
8
25 npm
1
Apache 2.0
MCP SDD Server
Developer Tools Software Architecture Code Analysis
yi-john-huang
A
license
C
quality
A
maintenance
An MCP server implementing Spec-Driven Development workflows for AI-agent CLIs and IDEs like Claude Code and Cursor, enabling spec-first development with automated workflow guidance and quality checks.
Updated 2 months ago (2026-07-25 06:01 UTC)
16
12 npm
52
MIT
openai-mcp
Coding Agents Developer Tools AI & Machine Learning
iflow-mcp
F
license
Not graded
quality
D
maintenance
A versatile MCP server that enables natural language software development tasks using multiple LLM providers (OpenAI, Anthropic) with real-time visualization, cost management, and a comprehensive tool suite.
Updated 10 months ago (2025-11-27 04:17 UTC)
-
uacos
Code Analysis Coding Agents
caotiensinh
A
license
Not graded
quality
B
maintenance
Local-first code intelligence and safety layer for AI coding agents. MCP server exposes dependency graph, impact analysis, and AST-compressed repo context, backed by typed local memory, patch-scope safety gates, and git-independent transaction rollback.
Updated 24 days ago (2026-08-26 14:52 UTC)
1
MIT

TNL — Typed Natural Language

The schema

A TNL file looks like this

The workflow

What you get over plan mode

Does it actually work?

Built with TNL

What TNL builds on

Install

Other agents (manual install)

Quickstart

1. Start minimal

2. Author your first TNL

3. Verify

4. Add capabilities as you need them

Commands

tnl init flags

MCP integration

TNL file format

Development

License

Available Tools

Tool Schema Changelog

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

JSON Contractsofficial

`tnl init` flags