How to Implement the ARD Specification: A Step-by-Step Guide for SaaS Companies

Summary

• Agentic Resource Discovery (ARD) is the new standard for making SaaS tools and APIs discoverable to AI systems through a crawlable ai-catalog.json file.
• Key steps for implementation include creating the catalog file, adding an Agentmap to robots.txt, and updating your website's HTML head with a link tag.
• Your representativeQueries are crucial for ranking in agent registries, as they directly map your tool's capabilities to an agent's task-based searches.
• ARD is a foundational step, but a complete strategy is needed to ensure AI agents select and use your tools. Synscribe helps companies build and execute a full-stack approach to agentic discovery.

Google's Agentic Resource Discovery (ARD) specification went live on June 17, 2026. If you run a SaaS product, this is the new standard for making your tools, APIs, and agents discoverable to AI systems at runtime. This guide walks you through exactly what to do — from publishing your first catalog file to getting indexed by Google's Agent Registry.

No prerequisites beyond being able to host a JSON file and edit your robots.txt.

If you've been searching for a clear submission process and keep hitting walls, you're not alone. This guide is written for the publisher side: SaaS companies that need to publish their capabilities into the ecosystem, not teams building the registries themselves.

What You're Actually Publishing: ARD from the SaaS Publisher's View

As a publisher, your job is simple in concept: host a single JSON file that describes your capabilities. That file is ai-catalog.json, and it lives at /.well-known/ai-catalog.json on your domain.

Here's what happens after you publish it:

1. Your file lists your capabilities — MCP servers, A2A agents, APIs, skills.
2. ARD-compliant registries (including Google's Agent Registry) crawl this file and index your capabilities.
3. When an AI agent queries a registry ("find me a payment processing tool"), your tool surfaces if it matches.

Think of it like sitemap.xml for the agentic web. You publish it, crawlers find it, your capabilities become discoverable. No manual "submit your agent" button required — the discovery is automatic and federated by design.

The most important field you'll write: representativeQueries. This is the functional equivalent of keywords for the agentic web. Registries use it to build semantic vector embeddings for search ranking. Write it wrong, and agents won't find you. Write it right, and you surface for the exact tasks your tool solves.

A 7-Step Guide to Implementing ARD for Your SaaS

This process involves creating your catalog file, hosting it correctly, and adding discovery tags to your site. Follow these steps to ensure registries can find and index your tools.

Step 1: Create Your ai-catalog.json File

Start with this minimal working example for a SaaS MCP server, then swap in your own details:

{
  "specVersion": "1.0",
  "host": {
    "displayName": "Your Company Name",
    "identifier": "did:web:yourcompany.com"
  },
  "entries": [
    {
      "identifier": "urn:ai:yourcompany.com:server:main",
      "displayName": "YourProduct API",
      "type": "application/mcp-server+json",
      "url": "https://api.yourcompany.com/mcp.json",
      "description": "One-sentence description of what your tool does.",
      "representativeQueries": [
        "send a transactional email to a customer",
        "track an email delivery event",
        "create an email template"
      ],
      "capabilities": ["SendEmail", "TrackDelivery", "ManageTemplates"],
      "tags": ["email", "transactional", "notifications"]
    }
  ]
}

Field-by-field annotation:

• specVersion: The version of the ARD spec you're conforming to. Use "1.0" for the current release.
• host.displayName: Your company's human-readable name as it will appear in registries.
• host.identifier: A DID Web identifier anchored to your domain. Format: did:web:yourcompany.com.
• identifier (entry-level): A globally unique, stable URN for this specific capability. Must follow the format urn:ai:<your-domain>:<namespace>:<name>. Domain-anchored, so it stays stable even if your infrastructure changes. See the URN naming guide in the ARD repo for details.
• displayName: Human-readable name for this specific capability or product.
• type: The MIME type of the resource. Common values:
  • application/mcp-server+json → MCP servers
  • application/a2a-agent-card+json → A2A agents
  • application/ai-skill → discrete skills
• url vs. data: Use url to point to a remote artifact (preferred for MCP servers — keeps your catalog file small). Use data to embed the artifact inline, only appropriate for small, static definitions.
• description: One sentence. What does this tool do? Agents and humans both read this.
• representativeQueries: The strategic heart of your entry (see Step 6 for the full breakdown). 2–5 natural language queries representing how an agent would ask for your tool.
• capabilities: Specific tool/function names within your server (e.g., SendEmail, TrackDelivery). Allows registries to filter without fetching the full artifact at url.
• tags: Additional keywords for filtering and categorization.

Step 2: Host It at the Well-Known URI

Upload your file to this exact path:

https://yourdomain.com/.well-known/ai-catalog.json

Server configuration requirements:

• Must be publicly accessible — no authentication, no login wall.
• Must be served with the HTTP header Content-Type: application/json.

Verify it's working:

curl -sL https://yourdomain.com/.well-known/ai-catalog.json | python -m json.tool

If this prints your formatted JSON without errors, you're good. If it errors, check your server's CORS and content-type settings first.

Step 3: Add the Agentmap Directive to Your robots.txt

ARD defines three discovery mechanisms. This is the second. Registry crawlers read your robots.txt for the Agentmap directive, similar to how traditional crawlers read the Sitemap directive.

Add this to your robots.txt:

# robots.txt
User-agent: *
Disallow:

Agentmap: https://yourdomain.com/.well-known/ai-catalog.json

This ensures any ARD-compliant crawler that reads your robots.txt can find your catalog — even if it never visits your homepage.

Step 4: Add the HTML Link Tag to Your Website's <head>

The third discovery mechanism: a <link> tag in your HTML head. Crawlers that parse your website's HTML will detect this and follow it to your catalog.

Add this inside the <head> of your main website pages:

<link rel="ai-catalog" href="https://yourdomain.com/.well-known/ai-catalog.json">

Implement all three mechanisms (well-known URI, Agentmap, HTML link tag) for maximum coverage across different registry implementations.

Step 5: Validate Your Manifest with the Official Conformance Tool

Before going live, validate your manifest. Schema errors are a known pain point and hard to debug after the fact — the ARD spec repository ships an official conformance testing CLI for exactly this reason.

# Clone the official ARD specification repository
git clone https://github.com/ards-project/ard-spec

# Validate a live, hosted manifest
./conformance/bin/conformance-test manifest https://yourdomain.com/.well-known/ai-catalog.json

# Or validate a local file before publishing
./conformance/bin/conformance-test manifest path/to/ai-catalog.json

Run this before and after every edit. The conformance tool will flag issues with URN formatting, missing required fields, and invalid MIME types — catching problems that would otherwise silently prevent your tool from being indexed.

Step 6: Write representativeQueries Strategically (The Most Important Step)

This deserves its own section because it's where most implementations fail.

representativeQueries is not a description field. Registries use it to build semantic vector embeddings for search ranking. When an agent queries a registry, the registry runs a semantic similarity search against these embeddings. Your queries determine which agent tasks return your tool — and which don't.

The core strategy: think like an agent, not a marketer.

The key to showing up in AI-mediated search is writing in the language of real user (or agent) intent — not the language of your marketing site. This is a core principle in modern Generative Engine Optimization (GEO), where tools like Synscribe's Reddit Social Listening are used to mine real conversations for the exact phrasing and pain points that drive search.

Agents search for tasks, not products. Apply these four rules:

Rule	Bad	Good
Task-oriented	"email API integration"	"send a transactional email to a customer"
Outcome-focused	"cryptocurrency data"	"get the current Bitcoin price"
Imperative voice	"support ticket creation"	"create a support ticket for a billing issue"
Distinct use cases	5 variations of "send email"	sending, tracking, templating, scheduling, unsubscribing

Bad examples (feature-oriented, how a marketer thinks):

• "email API integration"
• "SMTP service"
• "email sending platform"

Good examples (task-oriented, how an agent thinks):

• "send a transactional email to a newly registered user"
• "check if an email was delivered or bounced"
• "create a reusable email template for order confirmations"

Cover 2–5 distinct use cases — not 5 variations of the same use case. Each query should unlock a different category of agent task. Think about the breadth of jobs your tool can do, and write one query per job.

Step 7: Add a trustManifest for Enterprise-Grade Discovery (Optional, but Important)

If your product serves enterprise, fintech, or healthcare customers, this step is not optional in practice. Enterprise AI agents are built to filter registries for compliant tools — and if your trust metadata isn't declared in the catalog, you're invisible to them.

As developers building for regulated industries have noted: "plan for policy + audit around tool calls early; retrofitting it later is pain." The trustManifest is how you front-load that signal — before an agent even calls your tool.

Add this block inside your entry object:

"trustManifest": {
  "identity": "spiffe://yourcompany.com/api/main",
  "identityType": "spiffe",
  "attestations": [
    {
      "type": "SOC2-Type2",
      "uri": "https://trust.yourcompany.com/reports/soc2.pdf"
    }
  ]
}

Field annotation:

• identity — A SPIFFE identifier for your service. This is a cryptographically verifiable identity standard used in zero-trust architectures.
• identityType — Set to "spiffe" for SPIFFE-based identities.
• attestations — An array of compliance attestations. Each object needs a type (e.g., "SOC2-Type2", "HIPAA", "ISO27001") and a uri pointing to the actual report or certification.

How enterprise agents use this: An agent querying a registry with a compliance filter like {"trustManifest.attestations.type": ["SOC2-Type2"]} will only surface tools that declare this attestation. If yours isn't there, you don't show up — full stop.

Advanced ARD: Handling Multiple Products and Nested Catalogs

If your company ships more than one product or service, here's how to structure your catalog correctly.

Multiple entries in a single catalog: Add multiple objects to the entries array. Each gets its own identifier, type, representativeQueries, and capability set.

"entries": [
  {
    "identifier": "urn:ai:yourcompany.com:payments:invoicing",
    "displayName": "Invoicing API",
    ...
  },
  {
    "identifier": "urn:ai:yourcompany.com:crm:contacts",
    "displayName": "CRM Contacts API",
    ...
  }
]

Nested catalogs for grouped capabilities: If a product has many sub-capabilities, point to a dedicated catalog file instead of listing everything inline. Use type: "application/ai-catalog+json" with a url pointing to the nested file:

{
  "identifier": "urn:ai:yourcompany.com:payments:catalog",
  "type": "application/ai-catalog+json",
  "url": "https://yourcompany.com/.well-known/payments-catalog.json"
}

Separate subdomains for distinct business units: If your products are genuinely separate surfaces (e.g., payments.yourcompany.com and crm.yourcompany.com), host a separate ai-catalog.json at each subdomain's /.well-known/ path. Each subdomain's robots.txt and HTML <head> should point to its own catalog.

URN namespace conventions: Use the namespace segment of your URN to logically separate capabilities by department or product:

• urn:ai:yourcompany.com:payments:invoicing
• urn:ai:yourcompany.com:payments:subscriptions
• urn:ai:yourcompany.com:crm:contacts
• urn:ai:yourcompany.com:crm:pipeline

This makes your catalog readable for both machines and the humans on your team who maintain it.

Getting Listed: How ARD Connects You to Google's Agent Registry

The question everyone is asking: "How do I actually submit to Google's registry?"

Here's the honest answer: ARD is designed for automated discovery, not manual submission. By implementing the three mechanisms above (well-known URI, Agentmap, HTML link tag), you make your tools discoverable by any ARD-compliant registry — including Google's — without clicking through a console or waiting for an approval queue.

This is a deliberate design choice that solves the exact pain developers have with AWS AgentCore, where, as one developer pointed out, users can't find a public submission entry point and can't tell if agents can self-register or require human intervention. ARD's federated, crawl-based architecture sidesteps that bottleneck entirely.

Current status of Google's Agent Registry: Native ARD support in Google's Agent Registry (part of the Gemini Enterprise Agent Platform) is rolling out "in the coming months" per the June 17 announcement. The infrastructure for automated crawling is the thing to watch.

Where to monitor for updates:

• Official spec site: The official ARD spec
• Official GitHub repo: The official GitHub repo — watch this repo for releases and registry submission procedures as they're published.

The Reality Check: What ARD Alone Won't Do for Agentic Discovery

ARD is a real and meaningful step forward for agentic discoverability. But it's important to be clear about what it actually covers — and what it doesn't.

ARD makes you discoverable to agents that are actively querying registries. That's valuable. But it doesn't cover the rest of the discovery stack:

• It doesn't make agents search for you in the first place. Most AI agents answer from their training data by default. That data is typically 5+ months stale. An agent confident it knows how to use your API may be using a deprecated endpoint — and won't query a registry because it doesn't know it needs to.

• It doesn't guarantee selection even when you're surfaced. In the web search and fetch layer that many agents use, only around 6% of surfaced domains actually get opened and read. Getting indexed is not the same as getting used.

• It doesn't write you into agent configuration files. Files like AGENTS.md and CLAUDE.md — environment-level instructions that developers embed in their repos — represent the highest form of tool preference. When present, these produce near-complete selection flips in testing. ARD doesn't touch this layer.

• It doesn't fix incorrect usage patterns. If an agent has learned an outdated version of your API from training data, it will confidently call the wrong endpoints even after finding you via a registry. ARD solves discoverability, not behavioral accuracy.

ARD is just one component of a complete agentic discovery strategy. A full-stack approach requires influencing agent training data, optimizing for web search and fetch, and engineering inclusion in configuration files. Synscribe's SEO & GEO AI Agent automates this entire process, from discovery to selection and accurate usage. For the complete strategy, see our agentic discovery playbook.

Your ARD Implementation Checklist

Use this as your go/no-go checklist before calling your implementation done:

• Published ai-catalog.json at https://yourdomain.com/.well-known/ai-catalog.json
• File is publicly accessible with no authentication and Content-Type: application/json
• Added Agentmap directive to robots.txt
• Added <link rel="ai-catalog"> to website <head>
• Written 2–5 task-oriented representativeQueries per capability entry (imperative voice, outcome-focused, covering distinct use cases)
• Validated manifest with the conformance-test CLI from the official ARD spec repo
• Added trustManifest with relevant attestations (required if targeting enterprise, fintech, or healthcare buyers)
• Monitoring the official ARD website and the ARD GitHub repo for registry submission updates

Master Your Agentic Discovery Strategy

ARD is a critical first step for agentic discovery. Implement it now — the window to establish early index position in emerging registries is open. To master the full 11-play stack beyond ARD, read Synscribe's complete agentic discovery playbook.

Frequently Asked Questions

What is the Agentic Resource Discovery (ARD) specification?

ARD is a standard for making your company's tools, APIs, and agents discoverable to AI systems. It allows AI registries, like Google's Agent Registry, to automatically find and index your capabilities by crawling a simple ai-catalog.json file that you host on your website. This makes your tools available for AI agents to use at runtime when they need to perform a specific task.

Why is implementing ARD important for my SaaS product?

Implementing ARD is crucial for future-proofing your product's visibility in the age of AI agents. It ensures that when AI systems look for a tool to solve a problem (e.g., "send a transactional email"), your product can be discovered and surfaced as a solution. Without ARD, your tools will be invisible to this emerging, automated channel for user and agent discovery.

How do I submit my tools to Google's Agent Registry?

There is no manual submission process for Google's Agent Registry. ARD is designed for automated, crawl-based discovery. By correctly implementing the three discovery mechanisms—hosting ai-catalog.json at the well-known URI, adding the Agentmap directive to robots.txt, and including the HTML link tag—you make your tools discoverable by any ARD-compliant crawler, including Google's.

What is the most critical field in the ai-catalog.json file?

The representativeQueries field is the most critical for successful discovery. This field is used by registries to create semantic vector embeddings for search. Writing clear, task-oriented queries that reflect how an agent would ask for your tool is essential. Poorly written queries will prevent your tool from being found, while strategic queries will ensure you surface for relevant tasks.

How is ai-catalog.json different from sitemap.xml?

While both are for discovery, sitemap.xml tells search engines about the web pages on your site for human readers. In contrast, ai-catalog.json describes the functional capabilities of your tools and APIs specifically for AI agents and registries. It details what your tools do (e.g., "send an email"), not just what your web pages are about.

What should I do if my API or tool capabilities change?

You should update your ai-catalog.json file immediately whenever your capabilities change. Since ARD registries periodically re-crawl your catalog file, any changes you publish—such as adding new tools, updating representativeQueries, or removing deprecated capabilities—will be automatically indexed. This ensures that AI agents always have an accurate, up-to-date understanding of what your tools can do.