DADL is on purpose narrower than e.g. OpenAPI. It describes only the tool surface that an agent is allowed to call - not the full API contract that humans, SDK generators, gateways, docs and mocks need. In practice this means fewer parts to think about: method, path, parameters, access class, descriptions, and policy metadata. The point is to make the allowed actions explicit and small enough to actually review.

Every MCP project I have seen wraps APIs imperatively - custom code per backend. DADL is the only declarative format I know of that makes the allowed surface reviewable in a PR diff. That is a deliberate trade-off: less flexibility, more auditability.

Why YAML? Because humans really read and edit it. I wanted something small enough to review in a PR, diff cleanly, easy for LLMs to generate AND to write by hand when needed. In practice this is more important than maximum expressiveness.

What DADL can do: describe HTTP tools with typed parameters, declare auth requirements, attach policy metadata and caller constraints, provide a compact tool surface to the model - and attach a simple 'access' badge to each tool that flags it as read-only or dangerous. And errors come back in a form the LLM can reason about, not as crashes that break the flow.

What DADL is not trying to do: replace OpenAPI, capture every edge case of complex APIs, or be a full SDK generation format.

A few questions I get often:

Does this work for every API? No. APIs with very stateful flows, weird auth handshakes, streaming edge cases or messy responses still need custom handling. Some APIs map cleanly to DADL, some do not - but for those that do not, you can still plug in an existing MCP server through ToolMesh, and Code Mode applies to it too.

Why not generate from OpenAPI? OpenAPI is a great source material. You point an LLM to the DADL specification, to the OpenAPI definition - and you get a valid DADL that usually only needs optimisation.

So far there are 20 DADLs in the public registry covering 1,833 tools (GitHub, Cloudflare, GitLab, DeepL, Hetzner Cloud and more). If there is a specific API you would want to see as DADL, just ask - I am happy to add it.

If you want to try before cloning: https://demo.toolmesh.io is a public instance with the HN APIs loaded (login dadl/toolmesh). Works with Claude.ai, Claude Desktop, Claude Code, and ChatGPT - setup takes 30 seconds: https://toolmesh.io/demo

In Code Mode the model sees only two tools by default: list_tools(pattern) and execute_code(code). list_tools takes a regex and returns TypeScript signatures for matching tools. execute_code runs JavaScript that calls them.

So when the model actually needs the GitHub API for example, it calls list_tools("github.*pull") - it gets back just the typed signatures for those endpoints, and then writes code against them. Your second hypothesis is the mechanism: a meta-tool that queries on demand. The typed signatures (first hypothesis) are what the model reasons over once it has them.

That is what really brings the cost down. A large API as MCP tool definitions is easily 40-50k tokens upfront. The same API via list_tools + execute_code is ~1k for the two tool descriptions, plus only the signatures the model pulls per query.