acri

Agent Capability Resolution Interface

DNS resolves a name to an address. acri resolves an intent to the right tools.

You don't hand a browser all 300 million domains. You shouldn't hand a model all 300 tools.

The problem

Tool selection degrades as your toolset grows. Anthropic's own documentation puts the cliff at 30–50 tools: past that, the model starts picking the wrong one.

The fix is to stop sending every schema on every request, and send only the few that matter for the current turn. Anthropic ships this as tool search. OpenAI ships an equivalent.

Gemini does not. Ollama does not. vLLM does not. Your 8B local model does not.

acri is that layer, for everyone else — one import, no gateway, no daemon, no framework to adopt.

What acri is

A client-side, provider-agnostic capability resolver. It sits between your code and the LLM API, and decides which tools the model gets to see this turn.

What acri is not

• Not an MCP replacement. MCP defines how tools connect. acri decides which of them the model sees. Your existing MCP servers work unchanged.
• Not a framework. No orchestration, no graph, no agent loop. It is a function you call. Use it inside LangGraph, inside the raw SDK, or inside nothing.
• Not a proxy or gateway. No process to run, no port to open, no network hop added.
• Not a model. Bring your own key. acri never calls an LLM you didn't ask for.

The system

acri
├── corpus    the capability index — MCP servers, OpenAPI, plain functions,
│             indexed into one searchable body
├── compass   the resolver — intent in, the right k tools out           ← the core
├── router    the tier picker — cheap/strong model, chosen once, before generating
├── port      provider adapters — gemini · openai-compatible (OpenAI, vLLM, Ollama, ...)
├── config    acri.yaml — declares capabilities and limits, never control flow
├── daemon    the OpenAI-shaped request handler — acri.run(), nothing more
├── server    `acri up` — binds it: stdlib http.server, SSE, localhost by default
├── gate      the necessity check — does this turn need a tool at all?  (advisory)
├── press     the compactor — big payloads to short digests + a handle
├── sandbox   CPU/memory/network/volume limits on stdio MCP servers, via docker
├── ledger    the decision trace — what was chosen, skipped, and what it cost
├── studio    `acri studio` — read-only dashboard over acri.yaml + the ledger, own process/port
└── assay     the proving ground — the only place a benchmark number may come from

examples/     end-to-end scripts against a real MCP server — not part of the installed package
rust/         minimal Rust port of corpus + compass, v0.1 scope only
typescript/   minimal TypeScript port of corpus + compass, v0.1 scope only

Status

Pre-alpha — API not yet stable (v0.x, see docs/decisions.md). corpus + compass + port + ledger + assay + an exact-match cache + a pre-generation router all exist, are tested, and back every claim below with a script or a test file. daemon (acri up) exists too, ahead of its own gate — see the v1.0 roadmap row for what that means.

pip install pyacri

Distribution name is pyacri, not acri — PyPI blocks names within edit-distance-1 of an existing package (acris, acr, and acre already exist, all unrelated). import acri and the acri command are unaffected, since PyPI's distribution name and the Python import name are separate settings. Published via .github/workflows/publish.yml (OIDC trusted publishing, triggered by the v0.4.0 GitHub Release). To install extras or work on acri itself, clone and:

pip install -e ".[dev]"

import acri

tools = acri.from_callables([get_weather, get_stock_price, merge_pull_request])
corpus = acri.index(tools)          # build once, reuse across the whole task

result = acri.run("what's the weather in Tokyo?", corpus, my_openai_client)
print(result.tool_calls)            # [{"name": "get_weather", "arguments": '{"city": "Tokyo"}'}]

acri.run() resolves, calls the provider, and — if you pass ledger=acri.Ledger() — records the trace. Prefer to drive the pieces yourself? acri.resolve(query, corpus, k=5) returns the ranked tools; acri.gemini / acri.openai_compatible take it from there.

Read docs/architecture.md for the full design, the prior art it builds on, and the claims it explicitly refuses to make. Read docs/decisions.md for every capability that was proposed and cut, with the evidence that decided it.

First numbers

Measured on a synthetic 100-tool corpus spanning 20 domains (github, postgres, stripe, aws_ec2, jira, zendesk, ...) with realistic cross-domain confusability, and 50 hand-written queries phrased the way someone would actually type them, not as paraphrases of the tool descriptions. Reproduce: pip install -e ".[dev]" then python -m assay.recall. Fixtures and script: assay/fixtures.json, assay/recall.py.

Both adversarial queries (no correct tool exists in the corpus) correctly resolve to nothing, at every k. The k=5 row moved from 86% to 100% (assay/recall.py) after a small query-side synonym table was added to compass.py — _ALIASES, 10 entries, each traced to a real miss, not guessed (pr → pull, request; rain → weather; text → sms, message; and so on). It expands the query only, never the indexed tool text, so a tool's own description can't start quietly matching a synonym it never claimed.

Recall says the right tool is available to the model in a much smaller set — not that the model picks it. That's a separate, live-model question: assay/accuracy.py, naive (all 100 tools) vs. acri (top 5), same 50 queries, real gemini-2.5-flash calls, no mocking.

Corrected twice, both times in public. The first published number here claimed acri roughly doubles accuracy: naive ~24%, acri ~53% (commit history on assay/accuracy.py). That was a broken benchmark: every one of the 100 fixture tools had an empty parameter schema, so a well-behaved model correctly declined to fabricate a ticket ID or a SQL string it was never given, and that correct caution was scored as a tool-selection failure. Fixing the schemas and the obviously under-specified queries produced a second number: naive 72%, acri 74% (assay/accuracy.py), that this README called modest and honest. It was honest, but still not fully clean: a live diagnostic pass (assay/diagnose.py) surfaced 9 more queries that satisfied their tool's declared required fields but still left a genuinely necessary value unstated — "bump it up a size" with no target size, "point [domain] at the new server" with no address, an opportunity referenced by company name instead of ID. Full list and reasoning: docs/decisions.md. Fixed the same way as the first round — supply the missing value, or mark the field required if the action is meaningless without it — never by rewording toward the answer. Third run, current:

An 8-point gap this time, not noise — for scale, naive's own score moved 2 points between the previous two runs with zero code changes on its side, so 2 points is this benchmark's rough noise floor at n=50; 8 is well outside it. assay/diagnose.py confirms resolver_miss=0 — every remaining acri miss is the model's, not compass's — and all four share one shape: the model declines to act (picked: None, not a wrong tool) on a write/mutating request — refund a charge, launch a server, send an email, book a meeting — even once every required field is present. That reads as the model being conservative about consequential actions specifically, not a resolver or benchmark defect, and it is left unpatched on purpose: supplying more certainty than a real caller would have crosses from fixing the benchmark into fixing the test until it passes. This is still a single run at each stage; repeat runs would firm up the interval and are a natural next step, not yet taken. Reproduce: GEMINI_API_KEY=... python -m assay.accuracy --provider gemini, or via Vertex AI / ADC: GOOGLE_APPLICATION_CREDENTIALS=... GOOGLE_CLOUD_PROJECT=... python -m assay.accuracy --provider vertex.

What this means for the project's claims: recall — the context-window reduction — remains the number that survived every round unaffected (BM25 never reads a tool's parameters, so none of the query-completeness fixes could have moved it; only the synonym layer did, on purpose). The accuracy claim is now both real and no longer small, but it took three corrected rounds to get a benchmark that measures tool selection instead of measuring whether the fixtures gave the model enough to work with — a fact worth remembering before trusting the next number this project publishes, including from this project's own authors.

Also verified against a real MCP server, not a mock: assay/mcp_live.py spawns the official @modelcontextprotocol/server-filesystem over stdio, ingests its live tools/list response through acri.adapters.from_mcp_tools(), resolves a query against the real 14-tool corpus, and executes the top-ranked tool through an actual tools/call. list_directory was the top match for "what files are in this directory" (score 1.000 of 14 candidates), and its live result contained a marker file planted before the run specifically to prove the pipeline is real. Run: python -m assay.mcp_live <a-directory> "<query>" (needs Node.js on PATH).

compass.resolve() itself, over 1,040 calls against the same 100-tool corpus: p50 0.040ms, p95 0.087ms (assay/latency.py). Not headlined on purpose — see docs/decisions.md for why resolver latency is beside the point against a network call measured in hundreds of milliseconds.

Does it hold up at scale?

assay/scale.py reruns recall@k and latency against assay/fixtures_500.json — the same 100 tools and 52 gold queries above, plus ~400 more tools across ~40 new domains (gitlab and bitbucket alongside github, discord and telegram alongside slack, and so on), so corpus size is the only thing that changed. It isn't: recall@5 drops from 100% to 92%, recall@1 from 74% to 60% — assay/scale.py. Latency stays fast — p50 0.179ms, p95 0.285ms at 504 tools, still nothing against a network call. The context-window case gets stronger, not weaker, at this scale: 5 of 504 tools shown is a 99% reduction — assay/scale.py, the same arithmetic the 100-tool table above already uses. Recall genuinely degrades, though, and that's the metric that matters more than either latency or the reduction percentage.

The honest reason, checked query by query rather than assumed: BM25 has no semantic understanding, so once a real lexical competitor exists it can win. "Is PR 42 on the acme/webapp repo merged" now out-scores github_get_pull_request with bitbucket's own pull-request tools, because neither tool's description names its own platform and the query doesn't say which host it means — a gap the original 100-tool corpus never had to close, since no second git host existed to be confused with. Not patched: rewording the query toward the answer or adding an alias here would be tuning the benchmark, not fixing the resolver — see docs/decisions.md's "Corrected twice, both times in public" for why that line gets held. Reproduce: python -m assay.scale.

Diagrams

Both are static SVGs generated from the numbers above, nothing more — no simulator, no live trace, no feature these diagrams show that isn't already shipped and linked to the script that measured it. If a future version adds studio (the real trace visualizer — see docs/decisions.md), it replaces these; until then, these are it.

Roadmap

The claims policy

This project makes no performance claim it cannot reproduce.

No number appears in this repository — README, docs, paper, or commit message — unless a script in assay/ regenerates it from a public benchmark, and the run is committed alongside it. Estimates are labelled as estimates. Projections are labelled as projections.

If you find a number here without its receipt, that is a bug. Please open an issue.

Prior art

acri stands on published work and does not pretend otherwise:

• RAG-MCP — retrieval over tool schemas to cut prompt bloat
• When2Call — when (not) to call tools
• Anthropic tool search and context editing — the same idea, shipped provider-side

acri's contribution is placement: the same capability, client-side and provider-agnostic, for the models that don't have it natively.

License

MIT — see LICENSE.

Built by Piyush Sharma under INERATE, alongside Atelier.