Use GEDCOM Tools with your AI agent
Ask your agent to choose a browser tool, interpret a report or plan source-backed research.
content/agents/index.md
index.md, 11,999 characters. The same bytes answer at /for-agents/overview.md.
Ask your agent to choose a browser tool, interpret a report or plan source-backed research. GEDCOM Tools supplies 24 browser tools and 22 how-to guides, plus optional private hosted storage, deterministic checks and HTML reports. Your external agent supplies its own model, browser controls and file access; this site does not grant those capabilities.
For the research workflow, use Sliday's canonical genealogy-research skill on skills.sh or GitHub. Read the skill guide for installation boundaries. The skill can guide archive research and document analysis through your agent. The browser toolbox checks and repairs the file you load; it does not acquire new archive records.
Choose how to work
| Your setup | What you can do |
|---|---|
| You use the browser yourself | Select your GEDCOM, run a check and review the report. Share only the findings you want the agent to see. |
| Your agent supports remote MCP or REST | Discover tools and guides without a key. With a scoped agent key and consent, upload a GEDCOM, inspect, validate, audit relationships and create reports. |
| You want private hosted access | Complete hosted onboarding, open the vault and save your owner key before creating a scoped agent key. We retain private files and reports until deletion. |
| Your agent controls a browser and can select local files | Authorize the file and task, then let it inspect the relevant page. Page text and screenshots can enter its model context. |
| Your agent has no browser controls or hosted access | Ask it to choose a tool and give you the URL and instructions. Fetching a page does not execute a file analysis. |
| You work in this repository | Inspect the tool's run(doc, opts, ctx) and supporting modules, then call local code under the repository's development rules. No published remote API exposes that function. |
Start with File Inspector and GEDCOM Validator when the problem is unclear. Review encoding and structural findings before choosing a repair. The parser can continue through malformed input; recovery is not a prerequisite for every other check.
Read current capability information
tools.json lists the published tools and URLs. It combines definitions, maintained metadata and a source scan for model calls. Generation connects the catalogue to the source; it does not prove that every description or ordering rule is complete.
| Field | How to use it |
|---|---|
requires | Check that the agent has the required browser and file access. |
data_flow, sends | Identify optional model calls and the described payload. Read the page's send notice before disclosing data. |
mutates | Identify changed-file or determination output. The flag does not authorize a change. |
output_fields, result_may_be_capped | Preserve available locators, totals, shown counts and omissions. Do not invent fields a finding lacks. |
runs_before, runs_after | Read suggested dependencies and their rationale. Apply them when the findings and task warrant that order. |
trigger_phrases, prompt | Choose a starting prompt, then adapt it to the user's scope and privacy choices. |
Use the current manifest and page when an older skill catalogue or copied prompt lists different tools, routes or limits.
Keep the privacy boundaries separate
The current manifest marks 21 browser tools browser-local and three sends-to-model. Loading a file into a browser-local check does not send the GEDCOM to the site's model endpoint.
Hosted uploads have a separate boundary: obtain explicit consent before sending the file for private retention and deterministic checks. We retain originals and reports until document or vault deletion. Storage cleanup can remain pending after deletion; the MCP guide explains retries without a finite deadline. Hosted operations make no paid AI calls, but your agent's provider can receive the results. Upload consent grants no training or secondary-use permission.
Three optional model features send tool-specific data through the site's Worker to OpenRouter:
| Feature | Data to review before sending |
|---|---|
| Merge Conflict Arbitration | The two records, linked relatives' identifying details, matching signals and existing pair determinations. |
| Note Structurer | A separate request for each collected note, with its full text and context such as language and shared-note status. Names inside a note remain part of that text. The button does not send only a selected note. |
| Research Gap Planner | The first 25 eligible plan gaps, independent of display filters. Gap descriptions can name people; requests also include place, year-range and source metadata. |
Read the current sends description and on-page notice before pressing a model button. Complete the model-access challenge yourself when required. A read-only tool such as Research Gap Planner can still disclose information through its model feature.
Your external agent creates a separate disclosure boundary. Attachments, pasted GEDCOM, screenshots and page snapshots can expose information to its provider even during a browser-local check. Agree on what it may see before it reads private records. Minimize living-person details and consider Living Person Privatiser, then review the output. Redaction is not proof that no identifying information remains.
Review changes before applying them
Run read-only checks within the user's request and granted access. For a changed file or determination, explain the proposed change, evidence, uncertainty and known losses. Get review of relationship changes, merges, deletions and conflict resolutions before applying them, unless the user has already authorized that exact change.
Some pages build an output preview on load. A preview does not overwrite the input or establish acceptance. Preserve the original, review selections and hidden-row limits, then download the chosen output. Recheck that downloaded file before the next repair.
Do not promise universal undo. Tree patches may omit encoding metadata, and other programs can drop determination carriers. Recovery byte accounting does not prove semantic preservation. Validation and confidence scores do not establish genealogical truth or guarantee that a destination will import each field.
Interfaces available now
| Resource | Purpose and limits |
|---|---|
| API reference | Public discovery and authenticated hosted REST operations, with scopes, limits and privacy boundaries. |
| Remote MCP setup | Streamable HTTP at /mcp for unauthenticated discovery and seven authenticated hosted operations, with REST parity. |
| Hosted access, vault and scoped keys | Complete onboarding, save your owner key, manage scoped agent keys and delete retained files. |
| tools.json | JSON catalogue, not executable tool bindings. |
| llms.txt, llms-full.txt | Discovery summaries, without findings from your file. |
| Use with AI, prompt collection | Instructions and prompts. They cannot supply missing browser or file access. |
| How to | Task guides. Append .md to an article URL for its source; the index is at /how-to.md. |
| GEDCOM Validator and other tool pages | Rendered HTML with an empty state before file selection. Analysis requires browser execution and a selected file. |
| Feedback | A challenge-protected form for a report the user chooses to send. Avoid private GEDCOM content. |
| API health | Worker status and the configured model name, not proof that a model call or file analysis succeeded. |
The public discovery API offers GET /api, GET /api/tools, GET /api/tools/{id}, GET /api/guides and GET /api/guides/{id}. Remote MCP exposes search_tools, get_tool, list_guides and read_guide through POST /mcp over the same public data. These public discovery operations do not process GEDCOM files. The same MCP endpoint provides authenticated hosted operations; their REST equivalents use /api/v1. Read GET /api/v1/config for limits and GET /api/v1/documents for your document list.
The Worker also publishes these protected application endpoints. Keep them separate from public discovery:
| Method and path | Purpose |
|---|---|
GET /api/health | Service status and configured model. |
GET /api/feedback/config | Feedback challenge settings and input limits. |
GET /api/ai/config | Model-access challenge settings. |
POST /api/feedback | Submit feedback through the protected form. |
POST /api/ai/capability | Obtain model access after the browser challenge. |
POST /api/ai/v1 | Run one of the three typed model actions with a valid capability. |
POST /api/ai | Legacy endpoint; returns status 426 and the current endpoint address. |
Fetch discovery documents without loading a private file:
curl --fail https://gedcom.tools/tools.json
curl --fail https://gedcom.tools/api
curl --fail https://gedcom.tools/api/tools/a1-validator
curl --fail https://gedcom.tools/llms.txt
The current build provides static page routes and 404 responses for unknown paths. A nonexistent API address is not a hidden tool. Tool-page Markdown such as /gedcom-validator.md is not supported. An Accept: text/markdown header does not turn that tool page into Markdown.
Hosted operations and remaining limits
Hosted MCP offers list_documents, upload_gedcom, get_document, analyze_gedcom, create_report, get_report and delete_document, with equivalent REST routes under /api/v1. Analysis methods are inspect_gedcom, validate_gedcom and audit_relationships. Results default to summaries. Originals remain unchanged; hosted operations do not search archives, repair a GEDCOM or invoke paid AI.
Use Authorization: Bearer <AGENT_TOKEN> with the required read, write or delete scope. Keep owner keys out of agent configuration and credentials out of URLs and tool arguments. Uploads require contentBase64 and consent: true after approval. For owner-key replacement, save the client-generated replacement before sending it as newOwnerKey to POST /api/v1/owner-key. The MCP guide covers setup, limits, REST parity and deletion.
The site's /api/ai/v1 serves three typed model-assisted actions through the browser workflow. It uses origin checks, a challenge-issued capability and request limits. It is not an arbitrary chat proxy or GEDCOM-processing API. /api/ai returns an upgrade response, not a second service. Do not forge origin headers, bypass challenges or retry through quota errors.
Report evidence and limits
Name the file and settings used, the tool, totals and omitted results. Include record identifiers, lines, severity, confidence and rationale where the report supplies them; some header findings have no record or line. Distinguish observed findings, proposed repairs and research interpretations.
If missing access, a file, permission or model quota prevents the check, state that limit. Do not substitute a plausible report for an executed one.
More documentation
This overview is available at /for-agents/overview and /for-agents/overview.md. The other documents use /for-agents/<name> and /for-agents/<name>.md.