Guide

Writing representativeQueries

The only field in an ARD manifest that says what a resource is for, and the one most manifests get wrong.

What the field is

An ARD manifest describes each resource with an identifier, a display name, a type and a location. Those say what a thing is. One field says what it is for:

Entries SHOULD include representativeQueries: example natural-language requests that the resource is well suited to answer.

ARD specification v0.91, the entry schema agenticresourcediscovery.org

That is the whole of the normative guidance. Three lines for the field that decides whether a conformant manifest is ever returned to anybody.

It matters because of what happens on the other side. An agent does not search for type=mcp-server. It has a task in words, and it hands those words to a registry. The registry has to decide which of many entries is the best answer to a sentence it has never seen. Your representativeQueries are the only sentences you have contributed to that comparison.

The four failure modes, with fixes

1. The category label

By far the most common. The field gets filled with the noun phrase from the marketing page.

The test that catches all three: does it contain a verb, and could you say it out loud to a colleague without them asking what you mean? A category label fails both.

2. The query you wish you ranked for

The second most common, and the more expensive. A query is written because it is valuable, not because the resource answers it. A note-taking tool claims manage my entire business.

This is worse than useless. A registry may well return you, and then the agent connects, reads your tool list, finds nothing that does the thing, and leaves. You have spent the one impression you were given proving you were the wrong answer. Retrieval systems that observe outcomes will learn that faster than you can edit the file.

Write fitness, not demand. The query should describe something the resource is genuinely one of the better answers to. If that is a small, dull, specific thing, say the small, dull, specific thing.

3. Eight near-identical rephrasings

send an sms, send SMS, send a text message, sms sending api. This is keyword stuffing wearing a new hat, and it does not work the way its author hopes: the entries collapse to nearly the same match, so eight slots have bought roughly one query's worth of coverage.

Spend the slots on different situations instead: send an sms, send a one-time passcode to a phone number, notify a customer their delivery is late, send a text to a list of numbers from a spreadsheet. Same capability, four genuinely different requests, four chances to be the answer.

4. The internal name

use the configuration webhooks endpoint is a real example of the shape, and it is what happens when the field is generated from API reference headings. It is precise, correct, and matches nothing, because the only people who phrase it that way already know your product and do not need to discover it.

How to write them, in four steps

1. List the jobs, not the features. For each resource, write down what somebody had actually been trying to do in the five minutes before they needed you. Not "invoice API" but "chase an unpaid invoice".
2. Say each one out loud as a request. Start it with a verb. If it sounds like a heading rather than a sentence, it is still a category label.
3. Cut anything you are not genuinely good at. The cost of a wrong query is paid at the moment an agent arrives and leaves.
4. Split the resource if the list will not converge. If you need fifteen unrelated queries, you have several resources sharing one entry. Entries are free. Fifteen queries across three focused entries outperforms fifteen on one vague one.

What this looks like in a manifest

{
  "identifier": "urn:air:example.com:mcp:invoicing",
  "displayName": "Example Invoicing",
  "type": "application/mcp-server-card+json",
  "url": "https://api.example.com/mcp",
  "representativeQueries": [
    "issue an invoice and record the payment",
    "chase an invoice that is thirty days overdue",
    "turn a signed quote into an invoice",
    "find every unpaid invoice for one customer"
  ]
}

Four sentences, four different situations, each one something the resource genuinely answers. That is the whole technique.

How to check your own

Two things worth doing, in this order.

Read them cold. Take your list to somebody who does not know the product and ask what they think it does. If the answer is vague, the queries are labels.

Then run them. Send each of your own queries to a registry that indexes you and see whether you come back, and who comes back above you. The result is the only feedback that is not a guess. Every public ARD registry accepts a search over HTTP:

curl -X POST https://neuronto.com/search \
  -H "Content-Type: application/json" \
  -d '{"query": {"text": "chase an invoice that is thirty days overdue"}}' 

If you are not in the results for a query you wrote about yourself, that is not a registry bug. It is the field telling you the sentence does not describe you as clearly as you thought.

Questions

curl -X POST https://neuronto.com/submit \
  -H "Content-Type: application/json" \
  -d '{"url": "https://yourdomain.com"}'

Last reviewed 2026-09-05. Checked against ARD v0.91 (Proposal, 2026-08-26).