The Renyi toolchain as an MCP server: learn the language, inspect and check a project, run and test programs, and track what changed.
cheat_sheet: read the whole Renyi language on one page before writing code.
library_lookup: find standard library declarations by name or words, with signature, effects and purpose.
project_map: the project map — one record per module/definition (signature, purpose, effects, failures, edges, metrics, hash), filtered by module, as text or JSON.
definition: one definition's record and source text by qualified name.
effects: the transitive effect and failure graph under a definition, down to library primitives.
check: parse, type-check and effect-check a file or inline source, returning diagnostics.
format: canonical layout of Renyi source text.
run: check and run a program's main on the VM with arguments, narrowed by deny/allow-host/allow-read/allow-write/at-most, optionally replayed or explained.
run_tests: run every example: line and test block, replaying recorded tests, with strict and explain.
diff: what changed since a saved map or git revision, per definition, plus the version bump it forces.
chunks: the project (or the language's own docs and library) as JSON Lines chunks for embedding-based retrieval.
Renyi is the scripting language of AI agents: the agent writes it, you review it at a glance, and the program can only do what it declares.
Agents now write most of the code that runs on your behalf. The code they write in today's languages has to be read line by line, or run blind. Renyi is designed around that division of labour: the agent writes, the person reviews, and the language makes the review a glance.
What a program may do is in its signature. Every function declares
its effects (needs filesystem.read("data"), network.http("api.example")),
scoped to a path or a host, budgeted (at most 60 per minute) and
guarded (only to). The compiler refuses what is not declared; the
runtime admits only that, for the program's dependencies too. The
signature of main is the whole program's grant.
Every run is evidence. A run can be recorded, replayed offline and
reproduced under its manifest (toolchain, code hash, dependencies,
grant, arguments, outcome); --explain narrates it in the words the
program's author wrote. You know what a run did, as data.
Dependencies cannot widen what you allowed. A package's effects are computed from its sources, never written by hand; an update that would let the program do more is refused, not noticed later.
The tooling an agent needs is built in. The project map, the
semantic diff and the chunks for retrieval by embedding are commands
(renyi index, --diff, --chunks), the toolchain is an MCP server
(renyi mcp), documentation is syntax (purpose:), and every error
carries a fix, so the agent's next attempt is right.
Read in one pass, by anyone. Regular English with one spelling per concept, one canonical layout, no exceptions, no null, no anonymous functions, no operator overloading. A reviewer who has never seen Renyi reads what a program touches from its signature.
public function active_adult_emails(path: Path)
returns List of Email
or fails with FileError or JsonError
needs filesystem.read
purpose: Read users from a JSON file and return the e-mails of active users who are at least 18.
let text be filesystem.read_text(path) otherwise fail
let users: List of User be json.parse(text) otherwise fail
let emails be
for each user in users
where user.is_active and user.age is at least 18
sorted by user.name
collect user.email
return emails
endRenyi is a general-purpose language; its first users are people who run
automation with Claude Code, Codex and their like, and will not run an
agent's Python blind. The design record is
docs/design/08-positioning.md (decisions AH1 to AH4).
Related MCP server: core-agent-mcp
Each row is a claim the implementation keeps and the conformance suite tests. The other languages were built for other jobs and do them well; the comparison is for one job, a program an agent wrote and a person must trust.
For a program an agent wrote | Renyi | Python | TypeScript / Deno | Rust | Shell |
What it may do, visible before it runs | in every signature, scoped and budgeted, checked by the compiler | not declared; a sandbox limits the whole process |
| not declared; the type system is about memory, not effects | not declared |
Its dependencies' effects | computed from their sources, locked, refused when they widen | not declared | not declared | not declared | not declared |
What a run did | recorded, replayed, reproduced by the runtime | external tooling | external tooling | external tooling |
|
What an error means | a fix on every diagnostic, by rule | a traceback | a message | a good message, for a programmer | an exit code |
Reviewable without training | regular English, one spelling per concept | familiar to programmers | familiar to programmers | expert reading | terse |
Speed on integer loops | machine code in the process | CPython | V8 | native, the fastest | n/a |
Python and TypeScript are the languages agents write best today, and nothing in them says what a script will touch before it runs. Rust gives guarantees about memory and data races at a cost in time and expertise that a script does not repay, and says nothing about effects. Shell is what agents reach for first, and it is the hardest to review of all.
Between "the agent wrote it" and "I ran it" there is a review that nobody has time for. Sandboxes bound the process from outside and tell you nothing about the program; type systems check shapes, not effects; recordings and audit trails are bolted on afterwards, if at all. Renyi closes that gap inside the language: the effects are types, the grant is a signature, the run is data, and the syntax exists so that a person can check all three in the time it takes to read a function header. That is the whole design; everything else follows from it.
Source files use the .renyi or .ry extension; the two are equivalent.
Every release (decisions AI1 to AI4; v0.1.0 is the first) carries
binaries for Linux (x86_64), macOS (Apple silicon) and Windows (x86_64).
On Linux and macOS:
curl -fsSL https://raw.githubusercontent.com/renyi-lang/renyi/main/install.sh | shOn Windows, in PowerShell:
irm https://raw.githubusercontent.com/renyi-lang/renyi/main/install.ps1 | iexBoth verify the archive's checksum; RENYI_VERSION=v0.1.0 picks a
version and RENYI_INSTALL_DIR a directory. With a Rust toolchain,
cargo install renyi builds the same binary from crates.io, and cargo install --git https://github.com/renyi-lang/renyi renyi from the
repository. The VS Code extension (syntax highlighting and the client of
the language server, renyi lsp; editors/vscode/) is attached to every
release as a .vsix. docs/RELEASE.md is the
release procedure, and the documentation site is
https://renyi-lang.org. An agent starts from starter/ (decision AI3): a
skill file, the MCP configuration and five workflows that do real work,
with their tests and recordings. The MCP registry lists the toolchain
as mcp-name: org.renyi-lang/renyi.
The design is complete (M0); the front end (M1), the type and effect
checker (M2), the project map (renyi index), the VM (M3) and packages
(the first slice of M4, decision AC1) exist. What exists:
docs/design/01-decisions.md: every design decision taken so far, with the
reasoning.
docs/design/02-syntax-sketch.md: the concrete surface those decisions
produce; docs/design/04-stdlib-sketch.md: the prelude and the standard
library modules, which also exist as declaration files under
library/std/.
docs/design/03-readability-test.md: how LLM comprehension of the grammar is
measured (the grammar is frozen by decision V11); the harness and the rounds are under
tests/readability/.
docs/design/05-agent-tooling.md: the project map (renyi index) and the
renyi mcp server for agents, both of which exist; docs/design/06-runtime-guarantees.md:
recorded and replayable runs, budgets in grants, provenance guards;
docs/design/07-system-design.md: the trade-offs the language claims to
resolve, capability-safe packages, reproducibility, in-process sandboxing
and checked live update.
docs/cheatsheet.md: the whole language on one page, kept under 3000 tokens
(python3 tools/count_tokens.py).
docs/grammar.ebnf: the formal grammar of the syntax level, W3C EBNF over
the lexer's tokens; a test in the syntax crate interprets it and checks that
it accepts exactly what the parser accepts.
docs/reference.md: the language reference, normative: one section per
construct with the grammar excerpt, the meaning, the static rules with their
diagnostic codes and the run-time behaviour; a test holds its excerpts to
the grammar file and its list of diagnostic codes to the crates.
examples/: thirty example programs, checked by
python3 tools/lint_examples.py.
compiler/: the compiler written in Renyi itself, run by the Rust VM:
the syntax tree as Renyi types (whose derived JSON is what renyi parse --json prints), the lexer, the parser, the type and effect checker and
the bytecode emitter; renyi run compiler/parse.ry <file> prints the
same tree and the same diagnostics as renyi parse --json <file>,
byte for byte on every program of the corpus, the conformance suite,
the library and the compiler itself, renyi run compiler/checker.ry --json <file> prints
the same diagnostics as renyi check --json <file>, with and without
--strict, on every program of the corpus, the conformance suite and
the compiler itself, and renyi run compiler/compile.ry --to <file.ryc> <file> writes the same bytecode file as renyi compile,
byte for byte, on the same programs; a test holds all three pairs
equal.
crates/: the Rust toolchain. renyi check reports lexer, parser, type,
effect and layout diagnostics as text or JSON, each with a suggested fix;
renyi format rewrites files in the canonical layout; renyi tokens and
renyi parse [--json] dump the token stream and the syntax tree;
renyi index [--json] prints the project map: one record per definition
with its signature, purpose, declared and transitive effects and
failures, edges, metrics and content hash, renyi index --diff <map or revision> what changed since a saved map or a git revision, per
definition, with what each change reaches and the version bump it
forces, renyi index --chunks the map's modules and definitions as
chunks for retrieval by embedding (JSON Lines: an id that changes
exactly when the text does, the text, the metadata); renyi run checks a program
and runs its main on the bytecode VM under the grant main declares,
narrowed by --deny, --allow-host, --allow-read, --allow-write
and --at-most, and inside each function by that function's own
needs (the grant stack of decision Q1); renyi record writes a
recording of every effect of a run with the run manifest in its header
(--redact keeps a secret out of it), renyi run --replay re-executes
one offline, renyi reproduce replays one under its manifest and
compares the outcome and the output, --explain narrates a run
through the purpose: clauses it passes, and --profile reports where
its time went; renyi serve --watch runs a service and, when a file
of its project changes and the program checks clean, runs main
again between two requests with the listening socket kept open
(decision AO1); renyi run --sandbox grant.json runs a program under
a grant narrower than its main declares, with a memory budget, and a
Rust host loads a module the same way through renyi::Sandbox and
calls its public functions (decision AP1), and a C host, or a Python
one through bindings/python/renyi.py, through the library renyi_c
with the values as JSON texts (decision AW46; the guide is
docs/embedding.md); the VM generates machine code for the hot code
objects inside the binary (decision AG1: integer loops run in
registers, an Integer that leaves the machine word goes back to the
interpreter, which has the big ones), and --interpret keeps a run
on the interpreter; renyi test
runs every example: line and test block, a replays test from its
recording (--strict, --refresh); renyi compile writes a program
as a bytecode file (.ryc, the derived JSON of the types of
compiler/bytecode.ry), which run, record, test and
reproduce load in place of the source; renyi bind <header.h> --module <name> --library <names> writes a foreign module from a C
header (decision AF1) and renyi bind --python <package> a Python
module from a package (decisions AM1 and AM2); renyi add, update [--accept-effects], audit, fetch and publish manage a project's
dependencies (decision AC1: renyi.json names them and a registry,
a directory or a URL; renyi.lock.json pins each version's hash;
every package's files are verified against their hashes and its
effect manifest recomputed from its sources, so a package cannot
understate what it does, and a version whose effects widen is never
taken silently). Every example checks cleanly, is in
canonical form, and its examples and tests pass, the five that reach
the network and the one on SQLite from recordings under
examples/fixtures/; the ten programs with a reference output print
it. The VM covers the whole library: the
prelude, console, environment, time, random, filesystem, JSON, CSV,
regular expressions, the HTTP client (ureq), the HTTP server (over
std::net), SQLite (rusqlite, compiled in) and other programs
(std.process, decision AE1), the screen a frame loop draws on
(std.screen, decision AW31), C libraries through foreign modules
(decision AF1; renyi bind writes one from a header) and Python
modules through the bridge (decisions AJ2, AJ3 and AL1 to AL4; renyi bind --python writes one from a package, AM1 and AM2; the guide is
docs/python.md); run concurrently
runs its tasks one after the other (decision S2); the binary
allocates through mimalloc (decision X6). bench/ holds six
benchmarks, four of them with CPython twins, and tools/bench.py
times them (decision AG4; CI prints the numbers).
cargo build
./target/debug/renyi check examples/hello.ry
./target/debug/renyi check --json examples/hello.ry
./target/debug/renyi format --check examples/*.ry
./target/debug/renyi index examples
./target/debug/renyi index --diff HEAD examples # what changed since the last commit, and the version bump
./target/debug/renyi run examples/hello.ry Renyi
./target/debug/renyi run --explain examples/statistics.ry 2 4 4 4 5 5 7 9
./target/debug/renyi run --profile compiler/parse.ry compiler/parser.ry # where the VM's time goes
./target/debug/renyi run --interpret bench/primes.ry # the interpreter alone; by default the hot code runs as machine code
python tools/bench.py target/debug/renyi # the benchmarks of bench/, with --interpret, from their images and against CPython
./target/debug/renyi record --to hello.json examples/hello.ry Renyi
./target/debug/renyi run --replay hello.json examples/hello.ry
./target/debug/renyi reproduce hello.json
./target/debug/renyi test examples/invoice.ry
./target/debug/renyi compile --to hello.ryc examples/hello.ry && ./target/debug/renyi run hello.ryc Renyi # from the bytecode file
./target/debug/renyi mcp examples # the toolchain for an agent host, over standard input and output
(cd tests/conformance/packages/project && ../../../../target/debug/renyi audit) # a dependency's effects against every main
./target/debug/renyi run compiler/parse.ry examples/hello.ry # the parser written in Renyi, on the VM
./target/debug/renyi run compiler/checker.ry --json examples/hello.ry # the checker written in Renyi, on the VM
./target/debug/renyi run compiler/compile.ry --to hello.ryc examples/hello.ry # the compiler written in Renyi, on the VM
cargo testRelease 0.4.0 (2026-10-15) is the stable version (decision AW67): the
effects of a function value where it is bound, stored or returned (AW60,
AW61), a type in parentheses (AW62, AW63), the memory budget written in
the program (AW64 to AW66), the liveness walk's residue on both sides
(AW67) and the C archive's static library without the bitcode of fat
LTO. Release 0.3.0 (2026-10-15) adds the C API (decisions AW46 to AW48:
the crate renyi_c, the Python binding and a library archive per
target) and fixes a Windows path in the embedding API. Release 0.2.1
(2026-10-14) fixes the scope of the current directory,
filesystem.read("."), which refused every relative path, and lists the
toolchain on the MCP registry. Release 0.2.0 is out (2026-10-13; the
procedure in docs/RELEASE.md, decisions AI1 to AI5 and AW36; the
extension is on the Visual Studio Marketplace and Open VSX as renyi- lang.renyi). Between 0.1.0 (2026-10-07) and it came the registration
API for Rust natives (decisions AJ1 and AK1 to AK4;
docs/extensions.md), the Python bridge (decisions AJ2, AJ3 and AL1 to
AL4; docs/python.md), the resident world, the language server with
completion, references and rename, the watch of serve and the
embedding API (M5, decisions AN1 to AP2, AW38, AW39 and AW44), the
rounds on the VM's speed and the front end's (decisions AQ to AU, AW1 to
AW27), the toolchain for the browser with the play page and the showcase
game (decisions AW29 to AW37), and the chunks for retrieval by embedding
(decisions AW40 to AW43). docs/ROADMAP.md is the map of every stage,
numbered and grouped by track, with what comes next (the C API of
decision A5 is the next stage of AW28's order, not opened).
CLAUDE.md holds the conventions for Claude Code sessions and
docs/HANDOFF.md the current state and next steps; start there.
Apache-2.0. See LICENSE.
The whole Renyi language on one page (docs/cheatsheet.md): syntax, types, effects and the library. Read it before writing Renyi.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It discloses the underlying artifact path (docs/cheatsheet.md), implying a read-only documentation fetch, but does not confirm read-only behavior or describe the return shape. For a zero-parameter doc reader the behavior is largely self-evident, so this is adequate rather than rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, zero waste. The identity of the resource is front-loaded ahead of the prescriptive usage hint, and every clause earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no parameters, no output schema, and no annotations, the definition is nearly self-sufficient: it says what the tool is and when to reach for it. The only unaddressed detail is the exact return format, which is minor for a static doc fetch.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so per the baseline there is nothing for the description to disambiguate. Schema coverage is reported at 100% with an empty property set, and the description correctly adds no spurious argument guidance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a concrete resource (the entire Renyi language cheatsheet at docs/cheatsheet.md) and enumerates its coverage: syntax, types, effects, and the library. This is clearly distinguished from the narrower sibling `library_lookup` by scope, though it does not explicitly contrast with `effects` or `definition`.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
"Read it before writing Renyi" gives a clear, actionable trigger for invoking the tool. There is no explicit when-not or named alternative, but the directive is unambiguous for an agent starting Renyi work.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Parse, type-check and effect-check a program and report its diagnostics as renyi check --json prints them (an empty list is clean). Give path, a file under the served directory, or source, the text of a module (with path naming the file it would be, so that its imports resolve).
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | a file under the served directory | |
| source | No | the text of a module |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It does disclose the return shape ('diagnostics as `renyi check --json` prints them (an empty list is clean)'), which is valuable. It does not state that the program is not executed, whether the path must already exist, or the permissions/scope required, so key behavioral context is missing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two dense sentences, front-loaded with the operation ('Parse, type-check and effect-check...') and followed by the parameter guidance. No filler, and the most decision-relevant information comes first.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
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 explains that results are JSON-style diagnostics with an empty list meaning clean. Both parameters are covered and their interaction is explained. It stops short of covering execution semantics or error behavior, but it is adequate for a two-parameter read-only tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning: it clarifies that the two parameters are alternative inputs and that `path` doubles as the module name for import resolution when `source` is given. That relationship is not evident from the schema alone, so it exceeds the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States specific verbs and resource: 'Parse, type-check and effect-check a program and report its diagnostics.' That is far more specific than the bare name 'check' and implies a static-analysis operation, distinguishing it in spirit from siblings like run and format. It stops short of explicitly contrasting itself with siblings such as effects or run_tests, so it is clear but not fully differentiated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives concrete guidance for choosing between `path` and `source`, including that `path` names the file for import resolution when `source` is supplied. However, it never says when to use this tool rather than alternatives like `run`, `run_tests`, or `effects`, which are the likely confusions given static-checking versus execution. Usage is implied rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The served project as chunks for retrieval by embedding, as renyi index --chunks writes them: JSON Lines, a first line with the project, the revision, the toolchain and the counts, then one object per module and per definition with id (the SHA-256 of its text, which changes exactly when the text does), text (a header from the record, then the canonical source) and metadata (the map's id and text hash, module, package, kind, effects, edges, location). The host embeds; the toolchain only writes. module narrows it to one module; language gives the language's own documents instead (the cheat sheet's and the reference's sections, the library's modules and public declarations, the same shape), for a host that embeds the language beside the project.
| Name | Required | Description | Default |
|---|---|---|---|
| module | No | a module name, to give only that module's chunks (with `language`: a library module such as `std.http`, or `cheatsheet` or `reference`) | |
| language | No | true for the language's documents and library instead of the served project |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does substantial work: it discloses the JSON Lines format, the header line's contents, the per-object shape (id/text/metadata), the SHA-256 stability guarantee of `id`, and the key split that the host embeds while the toolchain only writes. It omits error behavior, size limits, and permissions, keeping it short of a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The content is dense inside a single sprawling run-on sentence with nested parentheses, so the essential fact (JSON Lines chunks of the project, host embeds) is buried rather than front-loaded. Every clause is informative, but the structure makes it hard to parse and would benefit from being split.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no output schema and no annotations, the description adequately covers the return format and parameter behavior. What is missing is the routing context needed to pick it among eleven siblings, which is a real gap for an agent deciding between this, `project_map`, and `definition`.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents both parameters, including the `language`-plus-`module` interaction. The description restates that `module` narrows to one module and that `language` switches to language documents, adding reassurance but no syntax or format detail beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a concrete resource and scope: the served project emitted as chunks for embedding, in the exact form `renyi index --chunks` produces. That is specific enough to separate it from `project_map` or `definition`, though it never names a sibling to sharpen the contrast and the opening is a noun phrase rather than a verb phrase.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no when-to-use guidance and no comparison with alternatives like `project_map`, `definition`, or `library_lookup`, which an agent must choose between. The only usable signal is the `--chunks` CLI parity note and the two narrowing flags, which describe mechanics rather than selection criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One definition's record and its source text, by qualified name: module.name, module.Type.method, module.Ability for Target, module.test:name; a bare name works when it is unique in the project.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | the qualified name |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses that a bare name resolves only when unique in the project, which is a useful resolution rule, but it never states that this is a read-only lookup, nor what happens on ambiguity or unknown names.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence, front-loaded with what is returned and then the accepted identifier forms. Every clause carries information; nothing is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter, no-output-schema lookup, the description covers what comes back (record plus source text) and how to address it. Only failure behavior for ambiguous or missing names is absent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the schema says only 'the qualified name,' so the baseline would be 3. The description adds genuine meaning beyond it: concrete qualified-name forms (`module.Type.method`, `module.Ability for Target`, `module.test:name`) and the bare-name uniqueness fallback.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific resource ('One definition's record and its source text') and the qualifier that selects it, so the agent knows exactly what it retrieves. It does not, however, distinguish itself from siblings like library_lookup or chunks, which an agent must infer.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains valid name formats but never says when to reach for this tool versus the ten siblings (library_lookup, project_map, chunks, etc.), nor any when-not condition. Nothing guides tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
What changed in the served project since a base: a saved map (a file renyi index --json or project_map with json wrote) or a git revision such as HEAD or v1.2.0. One entry per changed definition with the changes (added, removed, renamed, signature, visibility, effects, failures, body), the definitions each change reaches, and the version bump the changes force (the same as renyi index --diff).
| Name | Required | Description | Default |
|---|---|---|---|
| base | Yes | a saved map file under the served directory, or a git revision | |
| json | No | true for the JSON shape; the text form by default |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full load and does so well: it discloses the return shape (one entry per changed definition, the change categories, the definitions each change reaches, the forced version bump) and notes equivalence to `renyi index --diff`. It does not mention auth, permissions, or rate limits, but for a read-style diff that is a minor gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The core purpose is front-loaded in the first clause, and every subsequent clause adds information rather than filler. It is dense and heavily nested with parentheses, which costs some readability, but no sentence is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description must describe return values, and it does so thoroughly (changed definitions, change categories, reached definitions, version bump). An agent has everything needed to call it and interpret the result.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it clarifies what a 'saved map' is (output of `renyi index --json` or project_map with `json`) and gives concrete git revision examples (HEAD, v1.2.0) beyond the schema's generic wording.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: it computes what changed in the served project since a base, and it enumerates the exact output (one entry per changed definition, the changes, reached definitions, forced version bump). There is no ambiguity about what the tool produces versus a sibling like project_map or definition.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explains how to supply the base (saved map file or git revision) but never states when to reach for diff versus alternatives such as check, project_map, or definition. Usage is implied by the tool's obvious diff semantics rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The transitive effect and failure graph under a definition: every project definition it reaches, each with its declared and reachable effects and failure types, and the library primitives at the leaves with their declarations.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | the qualified name |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden, and it does disclose the shape of the result (declared vs. reachable effects, failure types, library primitives at the leaves). However, it says nothing about whether this is a pure read, its cost on large graphs, caching, or error behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single dense sentence that front-loads the subject (the effect/failure graph) and lists its contents without padding. It is long but every clause contributes meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter analysis tool with no output schema, the description conveys the conceptual return contents reasonably. It still omits the practical essentials: how the graph is represented, whether absence of effects is signaled, and how this differs from sibling lookup tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the single parameter is documented as 'the qualified name'. The phrase 'under a definition' loosely ties the parameter to a definition name but adds no format, scoping, or resolution details beyond the schema, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description is a verbless noun phrase naming the resource: a transitive effect and failure graph under a definition. The returned content is fairly clear, but it never states the action the tool performs and gives no differentiation from siblings like definition, project_map, or check.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no indication of when to reach for this tool, what kinds of questions it answers, or how it relates to alternatives such as definition or project_map. The agent gets no routing guidance at all.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The canonical layout of Renyi source text, what renyi format writes; the parse diagnostics when it does not parse.
| Name | Required | Description | Default |
|---|---|---|---|
| source | Yes | the text of a module |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full behavioral burden. It usefully discloses the dual return mode (formatted text on success, parse diagnostics on failure), which is real context beyond the schema. But it never clarifies whether the tool writes to disk or the source is mutated—'what `renyi format` writes' is ambiguous about side effects and reversibility, a notable gap for a mutation-ambiguous tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One tight sentence with a semicolon splitting the success and failure behavior—no wasted words and the primary behavior leads. It is efficient, though the elliptical phrasing trades a little clarity for brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter transformer with no output schema, the description does explain what comes back in both success and failure cases, which is the key missing structured info. It still leaves side-effect semantics and any usage context unaddressed, so it is adequate but not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for the single 'source' parameter, so the schema already documents it. The description adds no syntax, format, or size constraints beyond the term 'Renyi source text'. Baseline 3 applies when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description identifies the tool's output (the canonical Renyi layout, plus parse diagnostics on failure), so an agent can infer it is a formatter. However, it is phrased as a noun clause rather than a verb+resource statement and never says explicitly that it formats source code, nor does it differentiate itself from parse-adjacent siblings like check or definition.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no when-to-use guidance and no mention of any alternative tool. The only hint is the assumed equivalence to the `renyi format` command, which the agent must already know. Nothing tells the agent when to reach for format vs check.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find standard library declarations by name or by a few words (case-insensitive; every word must occur in the module name, the signature or the purpose). Each match is given with its signature, effects and purpose. Use it before calling a library function, so that names and arguments are not invented.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | a name or a few words, such as `get_with` or `read file` |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does reasonably well: it discloses the match algorithm (case-insensitive, every word must appear in module name, signature or purpose) and the shape of each result (signature, effects, purpose). It omits ranking, result limits, and search scope beyond 'standard library', which keeps it below a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with what is found and how matching works, then the usage cue. The parenthetical earns its place by defining the match rule; nothing is redundant.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter lookup with no annotations and no output schema, the description covers scope, matching semantics, returned fields, and intended workflow. Only secondary details such as result ordering or match limits are missing, which is acceptable here.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the schema already supplies examples ('get_with', 'read file'), so the baseline would be 3. The description goes further by explaining how the query string is interpreted (multi-word AND across name/signature/purpose, case-insensitive), which is genuine semantics the schema does not convey.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Find') and a specific resource ('standard library declarations'), plus the matching rule. It is clearly distinguishable from action siblings like run/format/check, though it never contrasts itself with the plausibly overlapping `definition` or `cheat_sheet` siblings, so it stops short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives an explicit trigger: 'Use it before calling a library function, so that names and arguments are not invented.' That is actionable context, but there are no exclusions or alternatives named (e.g. when to prefer `definition` or `cheat_sheet` instead).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The project map of the served directory: one record per module and per definition with signature, purpose, effects, failures, edges, metrics and content hash. module narrows it to one module; json gives the JSON shape of renyi index --json instead of the one-line-per-definition text.
| Name | Required | Description | Default |
|---|---|---|---|
| json | No | true for the JSON shape; the text form by default | |
| module | No | a module name, to show only that module |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are absent, so the description carries the full behavioral burden. It discloses the output structure (one record per module/definition, fields, text vs JSON) but says nothing about read-only safety, side effects, authentication, performance, or rate limits. For a query tool this is adequate but incomplete.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the output contract then parameter behavior. No filler; every clause carries information and the structure is efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description must explain returns, and it does list the record contents and format options. It lacks details on nested field shapes, but for a 2-parameter read-only map tool the coverage is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and both parameters are documented. The description adds useful context: json yields the JSON shape of `renyi index --json` versus the default one-line-per-definition text, and module narrows to one module. This goes beyond the schema's terse descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names the artifact ('project map of the served directory') and enumerates the per-definition fields it returns (signature, purpose, effects, failures, edges, metrics, content hash), giving a specific scope. It does not explicitly contrast with siblings like definition or effects, but the breadth of records distinguishes it as the whole-project map.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No when-to-use guidance or alternatives are offered. The second sentence only explains parameter effects (module narrowing, json shape), not when to choose this tool over definition, effects, or chunks.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check a program and run its main on the VM with the arguments, under the grant it declares narrowed by the options (the same as renyi run). Answers with what the program printed and how it ended. Its effects really happen unless replay names a recording.
| Name | Required | Description | Default |
|---|---|---|---|
| deny | No | capabilities to refuse, such as `network`; the run does not start when any function needs one | |
| path | Yes | the program, a file under the served directory | |
| replay | No | a recording to answer every effect from; nothing is written or sent | |
| at_most | No | budgets to add, `<capability>=<count>/<unit>`, such as `network.http=10/run` | |
| explain | No | narrate the run: purposes, arguments, results and effects | |
| arguments | No | the command-line arguments | |
| allow_host | No | hosts `network.http` is narrowed to | |
| allow_read | No | path prefixes `filesystem.read` is narrowed to | |
| allow_write | No | path prefixes `filesystem.write` is narrowed to |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does disclose the critical trait: effects really happen unless `replay` names a recording, which is the key safety fact. It also explains the grant-narrowing model and that the response reports program output and exit. It stops short of error/failure behavior or any permission prerequisites beyond the grant.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tight sentences that front-load what the tool does before the grant and effect caveats. The backticked jargon ('grant', 'narrowed', `replay`) is dense but every sentence carries information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 9-parameter execution tool with no annotations and no output schema, the description covers the essentials: it runs `main`, it returns printed output and termination status, and side effects are real unless replayed. Remaining gaps are failure modes and timing/resource limits, which are secondary here.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description goes beyond the schema by framing `deny`/`allow_*`/`at_most` as narrowing the program's declared grant, and by clarifying that `replay` substitutes for every effect so nothing is written or sent — conceptual meaning the per-field descriptions do not tie together.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource: run a program's `main` on the VM and return what it printed and how it ended. It anchors to `renyi run`, but that is an external CLI reference rather than a sibling tool, so differentiation from `check`, `effects`, or `run_tests` is left implicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit when-to-use guidance or exclusion against neighbors like `check` or `run_tests`. The phrase 'Check a program and run its main' ambiguously reuses a sibling's name, so the agent must infer that this tool actually executes rather than statically checks.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run every example: line and test block of a program, replays tests answered from their recordings (the same as renyi test), and answer with the report.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | the program, a file under the served directory | |
| strict | No | a recorded call a test never reaches fails it | |
| explain | No | narrate each test |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses that all example:/test blocks run and that recorded tests are replayed from recordings, which is useful behavioral context, but it says nothing about side effects, whether recordings are written or mutated, or failure semantics beyond `strict` in the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence, front-loaded with the verb and the scope of what runs. It is dense but every clause contributes; the parenthetical backtick jargon ('replays tests answered from their recordings') is slightly opaque but brief.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema and no annotations, so the description should say more about the report it returns. 'Answer with the report' gestures at the return but leaves an agent guessing at structure and pass/fail signal for a 3-parameter test runner.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so path/strict/explain are already fully documented in the schema. The description adds no parameter-level meaning (e.g., what 'strict' or 'explain' change in the report), so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (Run) and resource (every `example:` line and `test` block of a program), and ties itself to the `renyi test` behavior. It is distinguishable from format/check siblings, though it never explicitly contrasts with them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is only implied: you run this to execute tests. The equivalence note ('the same as `renyi test`') hints at behavior but names no alternative or condition for choosing this over `check` or `run`. No when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.2.1cheat_sheetcheckchunksdefinitiondiffeffectsformatlibrary_lookupproject_maprunrun_testsScored across 11 tools
Each tool targets a distinct capability: language reference, stdlib lookup, project overview, single-definition detail, effect graph, static checking, formatting, execution, testing, change diff, and embedding chunks. Overlaps (e.g., project_map vs chunks) are clearly separated by their descriptions and output formats, so an agent can reliably select the right tool.
All names use snake_case, but the set mixes noun-based names (cheat_sheet, project_map, definition, effects, chunks) with verb-based names (check, format, run, diff) and one verb_noun (run_tests). There is no single predictable pattern like verb_noun throughout, though the names remain readable and descriptive.
11 tools is well-scoped for a language toolchain, covering documentation, inspection, checking, formatting, execution, testing, diffing, and embedding without obvious redundancy. Each tool earns its place and the count sits comfortably in the ideal 3–15 range.
The surface covers the core lifecycle: reference, stdlib lookup, project map, definition detail, effect graph, check, format, run, test, diff, and chunks. Minor gaps remain, such as no project-wide search by name (one must scan project_map) and no direct file editing or scaffolding, but agents can work around these.
214 tools for AI agents over one MCP endpoint: image, video, audio, 3D, data, storage, mail, GPUs.
AI-native git hosting — repos, PRs, issues, CI gates, and AI code review over MCP (60 tools).
Architecture compiler for AI code. 11 tools, 92 actions, 872 Lean4 proofs, 100/100 self-cert.
Package intelligence MCP for AI agents — 22 tools, 19 ecosystems, AGPL SDK, free.
