# Ricorsa — for agents

Ricorsa (https://www.ricorsa.com) is a governed orchestration platform: a person (or an agent acting for them) states an outcome in natural
language; Ricorsa resolves identity, purpose and context, matches a Playbook, expands the capabilities the outcome needs,
resolves the governed implementations available to that workspace, checks authority and the account's allowance, executes
through enforcement points, and returns the result with an execution receipt. Models are one capability inside the plan,
never the centre of it.

## Connect this agent to Ricorsa

1. Sign in at https://www.ricorsa.com → account menu → **Connected accounts & capabilities** → **Agent access** → *Create key*.
   The key is shown once. It acts as you, inside your workspace, under your plan.
2. MCP endpoint (Streamable HTTP, JSON-RPC 2.0): `POST https://www.ricorsa.com/mcp` with header `Authorization: Bearer <key>`.
   Claude Desktop / Claude Code / Cursor: add a remote MCP server with that URL and header.
3. Every call is receipted and visible to you in Ricorsa; side effects (saving lists, sending) go through the same review
   gate and confirmation as in the app. Revoke the key at any time from the same panel.

## Tools

- `ricorsa_playbooks_list` — the built-in Playbooks (lead generation: Discover · Identify · Verify · Plan · Execute · Analyze),
  what each needs from you, which capabilities it uses and whether they are live in your workspace.
- `ricorsa_playbook_resolve { text, answers? }` — resolve a natural-language request into a governed plan: intent, Playbook,
  inputs (and the one question if something required is missing), steps with implementations and authority decisions,
  usage estimate and whether it fits your allowance. Nothing executes.
- `ricorsa_playbook_run { planId }` — execute a resolved plan. Returns companies / people / verification labels with sources,
  the executions, proposals written to Ricorsa Leads (review gate — nothing committed), the receipt id.
- `ricorsa_capabilities` — the Capability Graph projection for your workspace (live · declared · connectable · provisionable).
- `ricorsa_domain_search { company | domain, limit?, seniority?, department? }` — people at a company with the addresses the
  provider returned (verified contact data; Ricorsa Pro).
- `ricorsa_email_find { first, last, company | domain }` — one person's address, or nothing (never a guessed pattern).
- `ricorsa_email_verify { email }` — the provider's label: valid · accept_all · unknown · invalid.
- `ricorsa_discover { query? | filters… }` — companies matching a plain-language brief and/or structured filters (headcount,
  industry, city, state, country, technology, keywords, company_type, year_founded, similar_to) — verified contact data.
- `ricorsa_company_find { domain }` — a company's firmographic profile from its domain (verified contact data).
- `ricorsa_person_find { email }` — the professional profile behind a business address (verified contact data).
- `ricorsa_combined_find { email }` — person + company in one call (verified contact data).
  These give an agent the full verified contact-data surface — through Ricorsa's identity, allowance,
  receipts and rules: business-level fields only, nothing guessed, credits reported on every result.
- `ricorsa_cap_answer_search { provider: "serpapi.google_ai_mode" | "serpapi.google_gemini", args: { q, conversationToken?, location?, gl?, hl?, imageUrl? } }` —
  an AI answer engine's referenced answer (text blocks, references, places, products, follow-ups) with a token to continue
  the conversation; the engine's text is returned as returned.

## Every governed capability is a tool (one Ricorsa key federates every provider key)

Besides the named tools above, `tools/list` returns one tool per capability in your workspace's Capability Graph, named
`ricorsa_cap_<capability id with dots as underscores>` — for example `ricorsa_cap_market_quote`, `ricorsa_cap_news_search`,
`ricorsa_cap_ads_library_search`, `ricorsa_cap_travel_flight_search`, `ricorsa_cap_search_engine` (the SerpApi engine
registry: Google Search · Shopping · Scholar · Patents · Trends · Images · Maps · Local · News · Finance · Flights · Hotels ·
Events · Jobs · Play · Books · Ads Transparency Center, Bing, DuckDuckGo, Yahoo!, Baidu, Naver, Yandex, Amazon, Walmart,
eBay, Target, Home Depot, Zillow, Airbnb, Booking.com, Tripadvisor, OpenTable, Yelp, Apple Maps, App Store, Flightradar24,
YouTube, Instagram, Facebook Pages, Meta Ad Library — pass `provider: "serpapi.<engine>"`). Each takes
`{ provider?: string, args: object, confirmToken?: string }`. The vendor keys live sealed in the workspace; your Ricorsa key
is the only credential you hold, and every call is receipted against it. A capability whose provider is not configured answers
with the exact requirement (which key, which door) instead of a guess. A side effect (booking, room, product update) answers
first with a preview and a `confirmToken`; call again with the token within five minutes to execute.

## The API Registry (hundreds of APIs, one orchestrator)

`ricorsa_api_registry { q? | id? }` lists every third-party API the workspace can reach through Ricorsa — built-in manifests
(SEC EDGAR, FRED, BLS, EIA, Census, SAM.gov, FEC, Congress.gov, openFDA, ClinicalTrials, PubMed, Crossref, OpenAlex,
CoinGecko, Frankfurter, Open-Meteo, Nominatim, Mapbox, OpenCage, Google Places, Yelp, OpenCorporates, Companies House, People
Data Labs, HubSpot, Pipedrive, Airtable, Notion, Slack, Stripe, Resend, GitHub, Twilio Lookup, …) plus manifests the
workspace adds as data. `ricorsa_api_call { provider: "api.<id>", operation, args }` runs one documented operation through
the broker: arguments validated against the manifest, the workspace's sealed key injected at the edge, the provider's own
answer returned (records, total, source URL, docs), usage metered, receipt written. An API that needs a key the workspace
has not added answers with the key's name and where to get it. Adding an API needs no deploy: an admin posts a manifest
(https host, auth by secret NAME, typed operations) from Workspace runtime.

## Capability contracts (v1.20)

Every Advanced Tool (Create Image · Create Logo · Translate · Process Doc · Search on Web · Summarize Webpage · Code · Analyze Web)
runs under a capability manifest: the request is compiled into an execution specification (QUALITY KERNEL + specialist profile +
specification), executed, evaluated privately against the capability's rubric, repaired once when it fails, and delivered with the
scores, the attempt count and a runtime fingerprint in the receipt. `GET /api/quality/manifests` lists the contracts;
`POST /api/quality/compile` and `POST /api/quality/evaluate` are the runtime; `GET /api/quality/performance` is the
deterministic outcome ledger per implementation (pass rate · repair rate · latency · cost · dimension means).

## Rules every tool follows

- Ricorsa never fabricates a company, a person or an address. If a provider is not configured for your workspace the tool says
  which one and how a reviewer adds it; it does not fill the gap with a guess.
- Writes (lead lists, sequences) are proposals or require confirmation; an agent cannot commit or send by itself.
- Vendor (credit-metered) providers are a Ricorsa Pro entitlement; usage is metered as fuel and reported on each result.
- The decision priority when instructions conflict: trust kernel · tenant policy · explicit authority · purpose · resource
  permissions · Playbook invariants · your instructions · workspace preferences · capability defaults · model judgment.

## Also

- Web: https://www.ricorsa.com (sign in with your Ricorsa account). Health: https://www.ricorsa.com/healthz.
- WebMCP bridge for sites: https://www.ricorsa.com/webmcp-bridge.js