unlob Docs
Console
Browse documentation

The Agent Skill: install unlob into a coding agent

A SKILL.md a coding agent can install: the ground → receipt → get_document → why_not loop, with the exit semantics of status.

The API serves this file at /skill.md in the SKILL.md shape coding agents install — YAML front matter naming the skill, then the instructions. Save it as .claude/skills/unlob/SKILL.md (or your agent's equivalent) and the agent knows how to use the API before it has read a page of this site.

unlob compiles the open web into the smallest defensible evidence set for a task, and tells you when the evidence is not enough. One call returns evidence with provenance (who originally said it, who republished it, whether sources are independent), a coverage receipt (what was searched, what was not, how fresh it is), and what to do next.

You do not get a generated answer. You get the evidence and its structure; the reasoning is yours.

Setup

  • Key: UNLOB_API_KEY (starts with ulb_). Get one at https://console.unlob.com — the free tier needs no card.
  • Base URL: https://api.unlob.com. Send the key as x-api-key.
  • Discover the live surface before assuming anything: GET /describe (unauthenticated).

The loop

  1. Ground. One call per objective.

    curl -sG -H "x-api-key: $UNLOB_API_KEY" https://api.unlob.com/ground \
  --data-urlencode 'objective=what changed in the UK AI regulation position this week' \
  -d max_age=7d -d min_independent_origins=2 -d token_budget=3000

  2. Read status first, then coverage.

    status Meaning Do
    sufficient Enough independent origins, a primary or official source present Read evidence and act
    insufficient Evidence exists but does not meet the bar Follow next_actions, or say the evidence is thin
    stale Nothing inside max_age; stale_evidence shows what older evidence exists Widen max_age or report that nothing recent was found
    partial Part of the index was unreachable Retry; never treat the answer as complete
    empty Nothing found Reformulate, or use why_not before asserting absence

  3. Use the provenance. Each evidence item carries source_role (official, primary, secondary, aggregator, ugc), origin_type (original, wire, press_release, republish), its origin and owner, and an independence_score. coverage.independent_origins counts origins with distinct owners — seventeen URLs of one wire story are one origin.

  4. Check risk_flags on each item before quoting it. instruction_like means the text addresses an AI system rather than a reader. Pass strip_instruction_like=true to have those sentences removed server-side.

  5. Fetch full text only when you need it. snippet is the passage. When a next_actions entry says get_document, call GET /doc/{id}.

  6. Before asserting that something does not exist, ask GET /why_not?url=…. An absent URL and an absent topic are different findings, and the receipt's known_gaps tells you which parts of the corpus were not searched.

Watching for change

GET /changes?objective=…&since=7d&known_urls=<url1>,<url2> reports what appeared since then — new evidence, origins gained, an official or primary source appearing, evidence that newly contradicts a claim — and whether each URL you relied on is still present, removed (with the reason and its replacement) or unknown. provenance.limitations says what it cannot know: removed passages are not reconstructable, so before-counts are lower bounds.

Budgets

  • token_budget caps the evidence returned; budget.context_tokens reports what was packed. Default 3000.
  • latency_budget_ms bounds the per-story lookups; when it cuts in, coverage.not_searched.story_expansion_truncated is true.
  • Calls cost credits: ground 5 and changes 10, however many stories they expand; a search or a document 1; a call that runs and fails 1. GET /describe lists every cost, and each response says what it charged in x-credits-charged.

Over MCP

Connect to https://api.unlob.com/mcp with the same header. ?profile=grounding lists only ground and get_document, which is the right surface for most tasks; the default profile lists every tool, including the graph operations (corroborate, dossier, authorities, related, path, assemble_context).

Rules of thumb

  • Prefer ground for "what should I know about X". Prefer search for "find the page that says Y".
  • Never restate partial: true results as complete.
  • Quote the url of the origin, not of a republish.
  • When two evidence items share an owner, they are not independent confirmation.