DEV Community: Viren Tanti

The spec required a dot. Every tool-calling API rejects it.

Viren Tanti — Wed, 05 Aug 2026 18:59:15 +0000

We shipped a specification with a rule that made it unusable for the single thing
almost everyone would want to do with it. It took an HTTP 400 to notice.

Here is the error, from a request built directly out of a conformant manifest:

HTTP 400
{"error":{"code":"invalid_request_error",
          "message":"tool function names must match ^[a-zA-Z0-9_-]{1,64}$",
          "param":"tools[0].function.name"}}

Nothing was malformed. The manifest validated. The capability name was exactly
what the specification required it to be. That was the problem.

Two rules that cannot both be satisfied

The Agent Discovery Specification defines capability names as namespacedName:

^[A-Za-z][A-Za-z0-9-]{0,63}(\.[A-Za-z][A-Za-z0-9-]{0,63})+$

The trailing + is the whole story. It makes at least one dot mandatory.
com.example.lookupOrder is conformant. lookupOrder is not.

OpenAI's Chat Completions API constrains tools[].function.name to:

^[a-zA-Z0-9_-]{1,64}$

No dot. Anthropic's tools[].name and Google's functionDeclarations[].name
impose equivalent restrictions, and every OpenAI-compatible endpoint inherits
the first one — in practice that means OpenRouter, Together, Groq, and most
self-hosted gateways.

These rules are not merely awkward together. They are mutually exclusive. The
specification requires the character the tool APIs forbid. No conformant
capability name could ever be passed to a tool-calling API.

This is not one vendor's quirk, and it is not something to wait out. It is the
industry's settled convention, and we wrote a spec that could not meet it.

The part that is worse than the 400

An error at the boundary is the good case. You see it immediately and you fix it.

The real damage was quieter. Any client can cope — stripping a namespace is
trivial. But the specification never said how, so every client invented its own
mapping, and clients that agreed perfectly on the manifest stopped agreeing the
moment they built tools from it.

Given com.example.orders.get:

Strategy	Resulting tool name
Take the last segment	`get`
Replace dots with hyphens	`com-example-orders-get`
Take the last two segments	`orders-get`

Three clients, one manifest, three different tool names. A model trained or
prompted against one client's names does not transfer to another's.

Then it gets sharper. Consider a manifest advertising both:

com.example.orders.get
com.example.refunds.get

Under the last-segment strategy, both become get. The two capabilities collapse
into one identifier, silently. The model sees a single tool where two were
advertised, and which one actually executes depends on how the client happened to
build its dictionary. No error is raised. Nothing validates as broken. A refund
runs where an order lookup was intended.

There is also a length trap that has nothing to do with dots. namespacedName
permits 64-character segments with no limit on segment count, so a perfectly
conformant name can exceed the 64-character tool-name ceiling on its own, before
any transformation is applied.

What ADS-2 changed

The fix is deliberately small. ADS-2
adds one optional field, invocationName, and — more importantly — makes the
derivation rule normative so clients stop diverging.

{
  "name": "com.example.shop.orders.get",
  "invocationName": "orders-get",
  "version": "1.0.0"
}

invocationName must match ^[A-Za-z][A-Za-z0-9_-]{0,63}$ and must be unique
across the manifest. Note that underscores are permitted here and prohibited in
name — the two fields have genuinely different jobs, and no single string could
have done both.

When it is absent, a client that needs a constrained identifier must derive
one by replacing every . with -, and must not derive one by truncating to
a subset of segments.

Truncation is prohibited rather than discouraged, and that distinction was the
main thing worth arguing about. Discouraging it would have left the orders.get
/ refunds.get collision legal. The failure it produces is silent, produces a
wrong action rather than an error, and is invisible in the manifest — so it has
to be a MUST NOT.

If the derived identifier still exceeds 64 characters, the client must treat the
capability as not invocable through that interface and should say why, rather
than truncating to fit. Failing loudly beats guessing.

One decision we are fairly confident about: invocationName carries no identity.
name remains the sole identifier. Two manifests describing the same capability
must agree on name; they need not agree on invocationName. Presentation
concerns should not become identity, or you get two competing identifiers and the
same divergence problem one layer up.

Every manifest valid under 0.2.0 remains valid under 0.3.0. The field is
optional, and the derivation rule describes what careful clients were already
doing.

What this looks like in practice

Our reference implementation serves 14 capabilities, each carrying both:

com.example.cheelashop.cart-add-item     →  cart-add-item
com.example.cheelashop.cart-clear        →  cart-clear
com.example.cheelashop.cart-remove-item  →  cart-remove-item

The left column is identity, stable and namespaced. The right column is what
gets handed to a model. They are related by an explicit rule rather than by each
client's guess.

The lesson we would like to have had earlier

A discovery format is not consumed in isolation. It is consumed by something,
and that something has its own constraints — which are not negotiable just
because your specification is elegant.

We validated our names against our own schema. We did not validate them against
the API that the overwhelmingly common use of a discovered capability leads
straight to. The schema was correct and the design was wrong, and no amount of
internal validation would have caught it. It took building a client and getting
a 400.

If you are writing a spec, the question is not only "is this internally
consistent." It is "what will the first person to use this pipe it into, and what
will that thing say."

ADS is MIT-licensed and open to
proposals.
If you think the derivation rule is wrong, or you have a case where prohibiting
truncation causes more harm than it prevents, that is exactly the kind of
disagreement the process exists for.

If you want to try the spec end to end, implementing agent discovery takes about
ten minutes.

Implement agent discovery in 10 minutes

Viren Tanti — Wed, 05 Aug 2026 18:59:01 +0000

Implement agent discovery in 10 minutes

By the end of this page you will have served a valid ADS manifest, validated it
against the normative schema, and made one capability callable from an LLM
tool-calling API. Ten minutes, a text editor, and Python — which you almost
certainly already have.

This is a quickstart for the Agent Discovery
Specification, an open,
MIT-licensed, vendor-neutral spec. Nothing here requires a product, an account,
or a signup. If you want the reasoning behind any of it, the two deep dives
linked at the bottom are where it lives — but read them after this works.

Current spec version: 0.3.0 (released as v0.3.1). If you have seen an ADS
example declaring 0.1.0, it predates two releases. Copy from here instead.

Step 1 — serve the smallest legal manifest

Five fields. That is the entire requirement.

mkdir -p ads-demo/.well-known && cd ads-demo

Create .well-known/agent-discovery.json:

{
  "specVersion": "0.3.0",
  "id": "com.example.bookshop",
  "name": "Example Bookshop",
  "provider": { "name": "Example Inc." },
  "capabilities": []
}

An empty capabilities array is valid. "I speak ADS and I currently expose
nothing" is a real, useful answer — it is how a client tells the difference
between a system that has no capabilities and a system that has never heard of
discovery.

Serve it:

python3 -m http.server 8000

In a second terminal, fetch it the way a client would:

curl -i http://localhost:8000/.well-known/agent-discovery.json

You should see Content-type: application/json in the response headers. The spec
requires it, and Python's dev server gets it right for free.

Why http:// and not https://? The spec says a client MUST NOT fetch
a manifest over plaintext HTTP — a manifest names endpoints an agent will
subsequently call and the auth it will present, so over a rewritable channel it
is a redirection primitive. The single exception is loopback (localhost,
127.0.0.0/8, [::1]) during local development, where there is no network
attacker. You are inside that exception. Everywhere else, use TLS.

You have just performed agent discovery. A GET to a predictable path. That is
genuinely the whole mechanism.

Step 2 — validate it against the real schema

This is where you find out whether your file is correct instead of hoping.

pip install jsonschema requests

Save as validate.py:

import json, requests
from jsonschema import Draft202012Validator

SCHEMA_URL = (
    "https://raw.githubusercontent.com/Cheela-Labs/"
    "agent-discovery-spec/v0.3.1/spec/schema/manifest.schema.json"
)

schema = requests.get(SCHEMA_URL).json()
manifest = json.load(open(".well-known/agent-discovery.json"))

errors = sorted(Draft202012Validator(schema).iter_errors(manifest),
                key=lambda e: list(e.path))

if not errors:
    print("✅ Valid manifest")
else:
    for e in errors:
        location = " → ".join(str(p) for p in e.path) or "(root)"
        print(f"❌ {location}: {e.message}")

python3 validate.py

That URL is pinned to a tag on purpose. Pointing a validator at main means the
thing you validate against can change under you between two runs; pin the
version you are targeting and upgrade deliberately.

There is no official ads-validate CLI yet. Thirty lines of jsonschema is the
whole tool, which is roughly the point of keeping the schema small.

Step 3 — add a capability that does something

An empty manifest is legal but boring. A capability needs three things: name,
version, endpoint.

Replace the file:

{
  "specVersion": "0.3.0",
  "id": "com.example.bookshop",
  "name": "Example Bookshop",
  "description": "Search the catalogue and check stock.",
  "provider": { "name": "Example Inc.", "url": "https://example.com" },
  "capabilities": [
    {
      "name": "com.example.searchBooks",
      "invocationName": "search_books",
      "version": "1.0.0",
      "description": "Search the catalogue by title or author.",
      "inputSchema": {
        "type": "object",
        "properties": { "query": { "type": "string" } },
        "required": ["query"]
      },
      "endpoint": {
        "transport": "http",
        "address": "https://api.example.com/v1/books/search",
        "auth": "none"
      }
    }
  ],
  "discovery": { "cacheTtlSeconds": 3600 }
}

python3 validate.py

✅ Valid manifest.

Three fields there are worth understanding, because they are the ones people get
wrong.

name must contain a dot. It is a reverse-DNS identifier, and the schema
enforces it. Drop the namespace and you get:

❌ capabilities → 0 → name: 'searchBooks' does not match
   '^[A-Za-z][A-Za-z0-9-]{0,63}(\.[A-Za-z][A-Za-z0-9-]{0,63})+$'

The namespace is what stops your searchBooks and someone else's searchBooks
from colliding the moment two manifests are merged into one agent's tool list.

invocationName must not contain a dot. This is the newest part of the
spec (ADS-2,
landed in 0.3.0) and it exists because of a genuine collision: OpenAI, Anthropic,
Google and every OpenAI-compatible endpoint constrain tool function names to
^[a-zA-Z0-9_-]{1,64}$. A dot is rejected outright. So a conformant ADS name
could never be passed to any of them.

invocationName is the identifier to use where name cannot be. It is
presentation only — name remains the sole identity. If you omit it, a client
that needs a constrained identifier must derive one by replacing dots with
hyphens, and is now forbidden from truncating to a subset of segments. That
prohibition is not pedantry: two capabilities in one manifest can share a leaf
segment, and a client that truncates maps both to the same tool name silently.

endpoint.auth is required, even when it is "none". Delete the line and
the validator says so:

❌ capabilities → 0 → endpoint: 'auth' is a required property

Making "no auth" an explicit statement rather than an omission is deliberate — a
missing field is indistinguishable from a forgotten one, and an agent should
never have to guess whether it needs a credential.

Break each of those three on purpose and run the validator. Ninety seconds,
and you will remember the rules for good. Then put them back.

Step 4 — hand it to an LLM

Here is the payoff, and the reason invocationName exists. This turns a manifest
into a tool list an LLM API will actually accept:

import json

manifest = json.load(open(".well-known/agent-discovery.json"))

def tool_name(cap):
    # ADS-2: prefer invocationName; otherwise dots → hyphens. Never truncate.
    return cap.get("invocationName") or cap["name"].replace(".", "-")

tools = [
    {
        "name": tool_name(cap),
        "description": cap.get("description", ""),
        "input_schema": cap.get("inputSchema", {"type": "object"}),
    }
    for cap in manifest["capabilities"]
    if cap["endpoint"]["transport"] == "http"      # skip what you can't speak
    and not cap.get("deprecated")
]

print(json.dumps(tools, indent=2))

[
  {
    "name": "search_books",
    "description": "Search the catalogue by title or author.",
    "input_schema": {
      "type": "object",
      "properties": { "query": { "type": "string" } },
      "required": ["query"]
    }
  }
]

That array can be passed straight to a tool-calling API. You went from a URL to a
usable tool list without knowing anything in advance about the system behind it.

Note the transport filter. The rule is skip what you do not understand, never
reject the whole manifest. A client that raises on an unrecognised transport
breaks the first time anyone adds a capability it does not support — and per the
spec, that is the client's bug, not the manifest's.

You are done

You have a valid, current, tool-callable manifest. To put it in production:
serve the same document at /.well-known/agent-discovery.json over TLS, send
Access-Control-Allow-Origin: * if browser clients should see it, and keep
specVersion honest when you upgrade.

Where to go next

The reasoning — Agent Discovery Spec: a .well-known for AI agents is the deep dive: worked examples, the versioning model, how ADS differs from MCP and OpenAPI.
The gentler route — How AI agents find out what other systems can do covers the same ground assuming less.
The normative text — the spec itself, seven documents, all short.

Now change it

The most useful thing you can do next is disagree with something here.

ADS is a 0.x draft. It is small, young, MIT-licensed with no CLA, and governed
through a public proposal process modelled on Ethereum's EIPs — which makes it an
unusually good first standards contribution. invocationName exists because
someone hit the dot problem and wrote it up. Ambiguity in the spec is a
spec-bug issue.
A change to how it works is a
proposal.
Both doors are open, and the second one is less intimidating than it sounds.

If you serve a manifest anywhere public, open an issue and say so. A spec with
one implementer is a design document; the implementations are what make it a
standard.

Cheela is the first production implementer of ADS —
its runtime registry publishes conformant manifests for every registered
runtime. The spec does not depend on it, and nothing in this quickstart used it.