🤖 AI & Agents · 9 min read

agent-tools.json: How an AI Agent Finds Out What Your Site Can Do

agent-tools.json is a file at a site root that lists the actions the site offers, the page each one lives on, whether sign-in is needed, and what the caller has to supply. An agent reads it instead of guessing a site's abilities from page text.

It is not an official standard. We wrote the one on this site, and we check it against the live pages rather than trusting it. The check we ran while writing this found four entries that resolve to a real tool and one that an anonymous agent cannot reach at all. Both parts are below, because the second is the more useful half.

Why a reading list is not enough

Three files now sit at the root of a site that wants to be legible to machines, and they answer different questions.

• robots.txt says what may be fetched. It is a request about access, and RFC 9309 is explicit that it is not a form of authorization. We covered the AI crawler tokens in the robots.txt guide.
• llms.txt says what is worth opening. The convention is documented at llmstxt.org, and ours is 11,004 bytes of grouped links with a line of description each. What it does not say is what the site can do.
• WebMCP is the browser API that lets a page hand tools to an agent. Chrome documents two forms: the declarative API, where a form carries toolname and tooldescription, and the imperative API, where a script registers a tool with a typed input schema. We wrote about the whole layer in What Is WebMCP?

The gap is timing and reach. A WebMCP declaration is only visible once a capable browser has opened the page. An agent deciding where to send a user, or an agent running in a browser without the trial flag switched on, has nothing structured to read. A static index of actions covers that case, and the name we and a few others use for it is agent-tools.json.

What our file contains

The file we measured today is 7,142 bytes, served as application/json, stamped spec_version 1.1 and dated 19 September. It opens with a publisher block and a short section of notes for agents, then one object per action:

{
  "spec_version": "1.1",
  "updated": "2026-09-19",
  "publisher": { "name": "NoCodeCSV", "url": "https://nocodecsv.com" },
  "notes_for_agents": [
    "All tools run in the user's browser...",
    "The /dashboard workspace requires a signed-in user."
  ],
  "tools": [
    {
      "name": "split_large_csv",
      "webmcp_toolname": "splitLargeCsv (declarative) | splitCsvText (imperative)",
      "intent": "Split a CSV that is too large for Excel into smaller files.",
      "page": "https://nocodecsv.com/tools/csv-splitter",
      "requires_auth": false,
      "steps": [
        { "action": "upload_file", "selector": "#toolFileInput" },
        { "action": "set_value", "selector": "input[type=number]" },
        { "action": "submit", "selector": "button[type=submit]" }
      ]
    }
  ]
}

Fields that earn their place: requires_auth, so a caller knows whether sign-in is part of the job; steps with real selectors, so an agent does not have to infer the interface; and webmcp_toolname, so the static entry and the in-page declaration can be matched to each other. That last field is what makes the file testable, which is where the next section comes from.

What we measured against the live pages

A declaration file is only as good as the pages under it. We loaded each page in a Chromium build launched with the WebMCP testing flag, awaited navigator.modelContext.getTools() and compared the result with what the JSON claims.

Four of five entries hold up. The one that does not is instructive: the dashboard entry is marked requires_auth: true, and when we loaded /dashboard without a session the browser landed on /sign-in?redirect_url=... with zero forms, zero file inputs and zero tools registered. So the declaration is accurate about the requirement, and an agent following it still cannot do the task. A list of capabilities is not a grant of access.

The remaining gap is the file input. On a tool page whose only input is a file picker, the tool appears in the list with an empty parameter set. That is why two entries in our file are imperative tools that take the CSV or JSON as text: splitCsvText accepts csvText plus an optional rowsPerFile, and convertJsonCsvText accepts text and direction. Both were introduced for exactly that reason, and the file records it so the next person editing it does not remove them as duplicates.

The 200 that is not your file

Here is a check worth copying if you publish anything at a static path. On one of our other sites, a request to /agent-tools.json returns 200 with content type application/json and 8,223 bytes. A request to a path that does not exist returns 200 with content type text/html and 28,843 bytes, because the host falls back to the single-page app shell for unknown routes.

Two different results, same status code. A curl that prints only %{http_code} cannot tell them apart, and neither can a monitoring check that watches for a 404. Print the type as well:

curl -s -o /dev/null -w "http=%{http_code} type=%{content_type} " 
  https://example.com/agent-tools.json

The check has already caught one real problem for us. On 19 September the same request against that site returned text/html for the path, which meant the file was not published and the agent on the other end would have received a web page. On 20 September it returns application/json. Nothing about the status code changed in between, which is the point.

How to keep it from drifting

1. One entry per action, with a page URL. If two pages do the same job, the file should say which one callers should use.
2. Test the auth flag signed out. We only know the dashboard entry behaves as documented because we loaded it without a session.
3. Record the exact tool name the page declares, then re-run the check after any UI change. A rename in a form is silent otherwise.
4. Point steps at markup that exists. Our selectors name file inputs that are in the DOM at load time, not inputs created when a button is clicked.
5. Mark links as links. One of our five entries has no tool behind it: webmcp_toolname is null and a note explains that the page is a landing page. Implying a tool where there is only a page is the fastest way to make the file useless.
6. Stamp it and re-verify the stamp. The updated field is only worth reading if someone re-runs the check on that date.

What still does not work

Two limits we hit ourselves, both worth stating rather than leaving for a reader to discover. A file picker does not become a tool parameter, so any action that begins with "upload your spreadsheet" is out of reach for a browser agent today; the workaround is a text-shaped tool, which is not always possible. And an authenticated tool is invisible to an unauthenticated agent, so the parts of a product behind a login are declared but not usable. Neither limit is a reason to skip the file. Both are reasons to describe the site accurately instead of optimistically.

If your site publishes tools, the order that worked for us was robots.txt first, then llms.txt, then this file, then the WebMCP declarations themselves. Each one is checkable, and the checks are one command each.

Frequently asked questions

I build this layer for other sites — llms.txt, agent-tools.json, WebMCP declarations — and verify each one against the live pages. Details at /agent-ready.