# Discovery files for AI agents

Use these public files to find the right GEDCOM Tools page without loading a private tree:

- [tools.json](https://gedcom.tools/tools.json): the tool catalogue and capability metadata.
- [llms.txt](https://gedcom.tools/llms.txt): a short index of tools, guides and agent documentation.
- [llms-full.txt](https://gedcom.tools/llms-full.txt): an expanded product summary with tool descriptions and guide summaries.
- [API reference](/api): public discovery and authenticated hosted endpoints, scopes and limits.
- [MCP connection guide](/for-agents/mcp): public discovery, seven hosted operations and their REST equivalents.

These files describe the site. Fetching them does not run a tool, return findings from your GEDCOM or give an agent permission to read or change your files.

## Choose the resource for the task

| You need | Read |
|---|---|
| Tool URLs, inputs and described data flow | `tools.json`, then the current tool page. |
| A short list to choose a tool or guide | `llms.txt`. |
| More product context in one request | `llms-full.txt`. It contains summaries, not the complete text of every guide. |
| Step-by-step instructions | The relevant [how-to guide](/how-to). Append `.md` to its URL for Markdown. |
| A research methodology for your own agent | The canonical [genealogy-research skill on skills.sh](https://www.skills.sh/sliday/genealogy-research) or [GitHub](https://github.com/sliday/genealogy-research). See [the skill guide](/for-agents/skill). |
| MCP tools for public discovery | Connect to `/mcp` to search tools and read guides without authentication or private file processing. |
| Private hosted analysis through MCP or REST | Complete [hosted onboarding](/hosted-access) and create a scoped agent key in [the vault](/vault). See [connection instructions](/for-agents/mcp) for uploads, deterministic analysis, reports and deletion. |

Hosted operations require `Authorization: Bearer <AGENT_TOKEN>` with the required `read`, `write` or `delete` scope. Obtain explicit consent for upload and retention. We retain private originals and reports until deletion; cleanup retries can continue without a finite deadline. Hosted operations make no paid AI calls, but your agent's provider can receive results. Keep owner keys out of agent configuration and credentials out of URLs and tool arguments.

A bundled skill catalogue or saved index can become stale. Refresh the manifest and relevant page before choosing a route, quoting limits or describing what leaves the browser.

## Read capability metadata as guidance

The manifest includes `requires`, `data_flow`, `sends`, `mutates`, `output_fields`, `result_may_be_capped`, `runs_before`, `runs_after`, `trigger_phrases` and `prompt`.

Use those fields to plan the work, then verify the page's current controls and notices. The generator combines tool definitions, maintained metadata and a source scan for model calls. That process does not prove the completeness of a payload description or dependency rule.

Keep disclosure and mutation separate. The current catalogue marks 21 tools browser-local and three with optional model calls. Research Gap Planner does not mutate the GEDCOM, but its model feature sends the first 25 eligible plan gaps, independent of display filters. Descriptions can name people and include place, year-range and source metadata. Read `sends` before invoking a model feature. An external agent can also disclose page text or screenshots to its own provider during a browser-local check.

A `mutates: false` flag is not permission to inspect an unrelated file or send its contents elsewhere. A `mutates: true` flag describes changed-file or determination output, not a request to apply it. Follow the user's scope and review genealogical changes before mutation. [The overview](/for-agents/overview) explains these boundaries.

Treat general product claims in a discovery summary as context, not proof that a particular repair is lossless, an inverse will survive another program, or a validation establishes historical truth.

## What the current build lists

The catalogue contains 24 browser tools, 22 how-to guides and five agent documents. API and MCP endpoints do not add HTML tool pages. Use the fetched catalogue for the deployed list and the sitemap for public page routes.

`llms.txt` groups tools by tier and links to guides and agent documents. `llms-full.txt` gives tool descriptions, guide summaries and broader product context. Neither contains a selected file, tool results or a user's research notes.

Tool pages also provide rendered HTML without JavaScript execution, including headings and empty states. Browser-tool findings require a file selected in the browser; hosted findings require an authorized document and an analysis call. Tool-page Markdown such as `/gedcom-validator.md` is not supported, and an `Accept: text/markdown` header does not enable it.

The how-to index has a Markdown version at `/how-to.md`. Agent documents use addresses such as `/for-agents/overview.md` and `/for-agents/skill.md`.

## Where the files come from

For repository maintainers, `scripts/discovery.ts` generates the public discovery assets from tool definitions, maintained tool facts and compiled content. It also writes the generated data-flow list used by the interface.

```sh
bun run discovery
```

Run the content-generation workflow before discovery when authored guides change. Review the output and run the repository's checks; generation alone is not verification. Do not edit the generated public files as a substitute for updating their sources.

## What these files do not establish

The llms.txt convention offers a readable discovery format. Its presence does not prove that a crawler fetched it, an AI system used it or a search result improved. This page makes no traffic or citation-lift claim.

The site's robots and content-signal declarations concern access to public pages. They do not grant permission to disclose a user's GEDCOM, living-person details or private source documents.

For a copyable starting instruction, use [the prompt collection](/for-agents/prompts). A copied prompt still needs the user's scope, granted access and privacy choices.