Skip to content

AI Agent Discovery

FirmaDB ships a complete set of machine-readable discovery files so that AI agents — and the frameworks they're built on — can integrate without a human reading a docs page first. Point your agent at the right URL and it has everything it needs: capabilities, endpoints, pricing, error semantics, and behavioural rules.

Discovery file inventory

File URL Spec Purpose
llms.txt https://api.firmadb.com/llms.txt llmstxt.org Plain-Markdown agent brief: instructions, endpoints, errors, pricing
Agent Card https://api.firmadb.com/.well-known/agent-card.json A2A Structured capability declaration: skills, endpoints, security, pricing
AGENTS.md https://api.firmadb.com/AGENTS.md Linux Foundation agents.md Long-form integration guide: workflows, idempotency, attribution
OpenAPI https://api.firmadb.com/openapi.yaml OpenAPI 3.1 Single source of truth for endpoints, schemas, errors
MCP server https://mcp.firmadb.com/mcp Model Context Protocol Six dedicated tools, JSON-RPC over Streamable HTTP

All five are public and require no authentication to read.

llms.txt — the agent brief

llms.txt is the entry point. It follows the llmstxt.org spec: a single Markdown file with a description, an instructions block, an endpoint catalog, and links to deeper resources.

curl https://api.firmadb.com/llms.txt

The structure:

# FirmaDB API
> European company data from official government registries...

## Instructions
- Prefer exact lookup over search when you have a registry ID...
- Always pass `country` when searching...
- ...

## Quick start
Base URL: https://api.firmadb.com/v1
Auth: Bearer token in Authorization header

## Endpoints
### GET /v1/companies/{country}/{registry_id}
Look up one company by exact country code and registry ID...

## Errors
All errors follow RFC 9457 (Problem Details for HTTP APIs)...

## Pricing
| Tier | Monthly | Included results | Overage |
| ...

The Instructions block is normative

Every rule in the Instructions block is something we've seen agents get wrong in production. Cache leading zeros, don't treat unknown as active, read correction on errors. Following the instructions is the difference between an agent that works and one that quietly hallucinates.

Agent Card (A2A)

/.well-known/agent-card.json is the A2A standard capability declaration. Agent frameworks discover it automatically and register the skills, endpoints, and security schemes without any human touch.

curl https://api.firmadb.com/.well-known/agent-card.json

Key fields:

  • name, description, provider — basic identity
  • endpoints — REST, MCP, OpenAPI, llms.txt URLs
  • securitySchemes — bearer token (and OAuth in future)
  • skills — what FirmaDB can do, in agent-skill terms
  • x-firmadb-pricing — concrete EUR amounts per tier (vendor-namespaced because A2A doesn't have a standard pricing field as of 2026-05)
  • x-firmadb-coverage — country list and record counts
  • x-firmadb-compliance — GDPR roles, source provenance

AGENTS.md — long-form guide

AGENTS.md follows the Linux Foundation agents.md format. It's the place to look when you need detail beyond the brief: rate-limit headers, cache windows by tier, the idempotency contract, attribution requirements, error recovery patterns.

curl https://api.firmadb.com/AGENTS.md

The same content lives across these docs (in Rate Limits, Cost Estimation, MCP Setup) — AGENTS.md is the single concatenated version that an agent can ingest in one fetch and ground on for the rest of a session.

OpenAPI — the source of truth

https://api.firmadb.com/openapi.yaml is the OpenAPI 3.1 spec. Every endpoint, schema, error type, and example is defined there. Generators turn it into:

  • Interactive docs (API Reference)
  • Client SDKs (forthcoming)
  • MCP tool descriptions
  • Function-calling manifests for OpenAI / Anthropic / Vertex

If a fact in this documentation contradicts the OpenAPI spec, the spec wins. File a docs bug.

MCP server — direct tools

For agents that speak Model Context Protocol, https://mcp.firmadb.com/mcp exposes six tools (firmadb_get_company, firmadb_search_companies, firmadb_verify_status, firmadb_enrich_companies, firmadb_check_coverage, firmadb_estimate_cost). See MCP Setup for full configuration.

Building on FirmaDB as an agent

The minimum viable integration:

  1. Fetch and embed llms.txt in your system prompt, or its summary in your tool description. The Instructions block is the contract.
  2. Use MCP if you can. It saves you from writing function-calling glue and gives you typed inputs/outputs for free. See MCP Setup.
  3. Otherwise, use the OpenAPI spec. Generate function-calling manifests directly from it.
  4. Always pass country on search. The single biggest free-tier waste pattern is unscoped searches.
  5. Estimate before batching. Call firmadb_estimate_cost for any job over ~10 records and respect human_approval_recommended. See Cost Estimation.
  6. Cache per your tier. Free 24h, Solo 7d, Team 30d, Scale 90d. Use If-None-Match with ETag for free conditional requests. See Rate Limits & Caching.
  7. Recover from correction and suggested_request. Errors are designed to be machine-actionable — don't surface "company not found" to your user without first trying the suggested correction. See Errors.
  8. Preserve source_url and data_freshness end-to-end. Auditors and end users need the provenance chain.
  9. Use restricted (rk) keys. Never embed a secret (sk) key in agent context.

Discovery from a single URL

If your framework only takes one URL to onboard a new tool, give it the agent card:

https://api.firmadb.com/.well-known/agent-card.json

It links out to everything else — llms.txt, AGENTS.md, OpenAPI, MCP — so a single fetch primes the agent for the full integration.

Versioning

All discovery files are versioned with the API. v1 files are stable; breaking changes ship as v2 at a separate URL. Never assume an undocumented field is permanent — read the changelog before upgrading.

Why both llms.txt and an Agent Card?

The two specs solve adjacent but distinct problems:

  • llms.txt is for language models. It's plain Markdown that fits in a system prompt and reads like a one-page brief. Agents that don't speak A2A or MCP can still get everything they need by ingesting it.
  • Agent Card is for agent frameworks and runtimes. It's structured JSON with declared skills, security schemes, and pricing — built for automated discovery and cataloguing.

Most production agents end up using both: the framework reads the Agent Card to register the integration, and the model loads llms.txt (or its summary) into prompt context to ground its tool-use behaviour.

Bootstrapping checklist

Use this as a one-time setup checklist when adding FirmaDB to a new agent:

Step Action
1 Fetch https://api.firmadb.com/.well-known/agent-card.json and register the skills
2 Fetch https://api.firmadb.com/llms.txt and embed it (or its summary) in the system prompt
3 Configure MCP at https://mcp.firmadb.com/mcp with a restricted (rk) bearer key
4 Set a daily spend cap and call firmadb_estimate_cost for any job over ~10 records
5 Test against firmadb_get_company for FR/552120222 (SOCIETE GENERALE) — known-good smoke test

What's next