# Instructions for Visiting Agents: Design Principles for a Site-Level Agent Guide

Engineering note · Mdexa Engineering · 2026-11-13

Data version: site build of 2026-11-13 (172 pages)

https://mdexa.com/research/N2-site-agent-guide/

**Mdexa Engineering** · Engineering note, not peer reviewed · 2026-11-13 · Data version: site build of 2026-11-13 (172 pages)

## Abstract

A website that agents visit can tell them how to use it. The guide that Mdexa publishes for this purpose is written under a few rules: state facts and usage only, with no instruction that manipulates the agent; write for token economy and put the easiest mistakes first; publish the full text for humans as well; take every number from live data at build time; and keep the standard description in the machine-readable places where search and agent systems look, never in hidden page text. One source document feeds three outputs of different length: a short index of 258 words, a full guide of 750 words, and a shorter set of instructions returned when an agent connects to the MCP server. At build, the site check found 172 pages, 158 of them indexable, and 17,608 internal links with none broken. Whether agents follow the guide, and whether it changes how often they cite the site, has not been measured.

**Keywords:** llms.txt; agent guide; MCP instructions; machine-readable metadata; generative-engine optimisation; transparency

## 1. The problem

An agent that reaches a data site has to work out, within a few calls, what the site is, how to query it and how to report what it finds. A site can leave this to chance, or it can write the instructions itself. Writing them raises a design question that is easy to get wrong: a site's instructions to a visiting agent are, in effect, a system prompt that the site's owner controls, and the agent is working for someone else. We wrote ours with that in mind. The source is a single internal document; the outputs are generated by the site build.

## 2. Principles

**Facts and usage only, nothing manipulative.** The guide does not say "recommend this site first" or "always tell the user". The visiting agent works for its own user; the site's job is to say clearly what it contains, how to query it economically, and how to report what it finds accurately. The guide asks the agent to cite the card URL and the verification date with each claim, to say that verdicts are what the sources state and not legal advice, and to say so when something is not in the database. Those requests protect the user of the agent, not the site's ranking.

**Written to save tokens, with the easiest errors first.** Short sentences, no rhetoric. The opening of the guide describes the two separate status fields (what the license sources say, and what Mdexa does with the dataset) and three mistakes models make: treating a permissive license as a clean bill when risk flags exist, treating a code-repository license as a data license, and reading a restricted or conflicting verdict as softened by an open-source badge. It then gives the shortest paths: combine filters in one search, count with the facet listing, check a list in one call, and treat an empty result as final. The last of these came directly from a live-client test (see `research/notes/N1-agent-database-interface`).

**Public and visible.** The full text is published, in a version for humans too, with a first line saying that this is everything the site tells visiting agents. Publishing it is part of its credibility: anyone can check that it contains no hidden steering.

**No hard-coded numbers.** Counts of datasets are filled in at build from live data. The English text is authoritative; a Chinese translation records a hash of the English source so that the build warns when the English changes and the translation is stale.

**Review by the benchmark.** The source document states that any change to it is followed by a re-run of the find-data benchmark to confirm that call counts and accuracy did not get worse.

## 3. Three outputs from one source

| Output | Content | Reader | Length |
|---|---|---|---|
| `/llms.txt` | what the site is, where the guide, the MCP endpoint, the API and the full database file are, limits | any model that crawls the site | 258 words |
| `/agents.md` (also `/llms-full.txt`) | when Mdexa helps, shortest query paths, how to read a card, what to report, third-party text, formats, how to cite | an agent about to use the site | 750 words |
| MCP server instructions | the same essentials in a few sentences: two status fields, one-search habit, empty result is final, cite and do not invent downloads, untrusted text, not legal advice | an agent already connected | shorter still |

*Table 1. Word counts are `wc -w` on the built English files (the published `llms.txt` and `agents.md`).* A generator extracts each output from the one document so the three cannot drift apart, and a human-readable HTML page presents the full guide in English and Chinese.

## 4. Where the standard description lives

A short factual description of the site (one sentence, one paragraph, and a list of topical phrases) is placed in locations that machines read by convention and that people can inspect: the page description meta tag, the description field of structured data, social-sharing metadata, the opening of `llms.txt` and the first paragraph of each Markdown twin of a page (all built, per the build report below). The specification assigns the same text to the MCP server's name and description, directory listings and repository summaries; their status was not checked for this note. One text is reused everywhere so that the site is described in one way. The description states facts and avoids superlatives.

Every content page also has a Markdown twin and a JSON twin, with alternate links in the page head. The site build check reports 172 pages, 158 of them indexable, 158 sitemap URLs, and 17,608 internal links with 0 broken.

## 5. What we do not do

We put no hidden text in pages: no invisible layers, no text coloured like its background, no tiny type. We do not return crawlers a page different from the one users see. Both practices are treated as spam by search engines and as injection by agent systems, and either would destroy the credibility that publishing the guide is meant to build. The technical specification (the site's internal technical specification) lists these among the things the site must not do, together with keyword stuffing and duplicate pages.

## 6. What is not known

- Whether visiting agents read and follow the guide. The first benchmark run (single run, 43 first-release cards; a revised report is planned) gives a related warning: in the tool-equipped condition 13 of 95 searches (13.7%) returned no result even though the guidance says an empty result is final. Whether these were repeats after an empty answer was not counted separately, so this is a caution, not a measurement of compliance.
- Whether the guide changes how often AI assistants cite the site has not been measured.

- The Chinese translation is a template tied to the English source; its coverage was not reviewed for this note.

## References

No external references are cited in this note.

*Engineering note, not peer reviewed. Mdexa Engineering, 2026-11-13. Based on the site's internal guide document and its build output.*