doiget

WHEN TO USE: Attach or clear a freeform annotation / note on a stored paper for local knowledge-base organisation (#294). INPUTS: ref (DOI or arXiv id); text (string — the annotation; omit or set to null to clear); clear (bool, default false — explicitly clear the annotation). OUTPUTS: { ok: true, ref, annotation } OR { ok: false, error }. COSTS: 0 network requests; one store read + write. SIDE EFFECTS: Overwrites [doiget].annotation in <store>/.metadata/<safekey>.toml. LIMITS: Entry must already exist in the store. Setting text overrides any existing annotation.

WHEN TO USE: User wants to fetch many papers in one call (up to 100). INPUTS: refs (array of up to 100 DOIs / arXiv ids), dry_run (optional bool), force (optional bool: ask again even if this session was just answered on the ref; without it such a repeat is replayed as ok:false with replayed:true, #507). OUTPUTS: { ok: true, results: [{ref, ok, ...}] } OR { ok: true, dry_run: true, plans: [{ref, plan, rate_limit_budget}] } OR { ok:false, error }. COSTS: 1-3 s per ref, bounded by the 5/sec global rate cap. SIDE EFFECTS: Writes PDFs / metadata TOMLs to the store (unless dry_run). Appends one provenance row per attempt. LIMITS: Max 100 refs per call (TOO_MANY_REFS otherwise). Per-ref errors are reported in `results` and do NOT fail the whole call.

WHEN TO USE: User has a Zotero / Mendeley CSL-JSON export and wants to fetch all OA-resolvable entries. INPUTS: path (absolute path to .bib / .csl / .json), format ("auto" | "csl-json" | "bibtex" | "refs", default "auto"), strict (bool, default false), force (optional bool, as for doiget_batch_fetch). OUTPUTS: { ok: true, summary:{total,ok,failed,parse_errors}, results: [{entry_key, ref, ok, ...}] } OR { ok:false, error }. COSTS: Same as batch_fetch — 1-3 s per entry, bounded by the 5/sec global rate cap. SIDE EFFECTS: Writes PDFs / metadata TOMLs to the store. Appends one provenance row per attempt. LIMITS: bibtex parsing is not yet shipped (re-export as CSL-JSON). Per-entry parse errors are reported in results unless strict=true.

WHEN TO USE: Resolve multiple free-form bibliographic citation strings in batch. INPUTS: queries (array of query strings), limit (maximum number of candidates per query, default: 5). OUTPUTS: { ok: true, results: [ { query, candidates: [ { doi, title, author, year, score, confidence, matched, source } ] } ] } OR { ok: false, error }. COSTS: 1-2 s round-trip per query. SIDE EFFECTS: none. LIMITS: Returns candidates with similarity score >= 0.5. At most 50 queries per call. BRANCH ON confidence, NOT score: the score is token overlap against your query string and 0.5 is the FLOOR, so the worst candidate this tool can emit still looks like a positive number. confidence is exact (every query token matched), probable (four in five), or weak (cleared the floor and no more) - for a known-item lookup a weak candidate is a near-miss, not a match, so verify it with doiget_resolve_paper before citing. matched lists which of your tokens were found, which is how you see whether the author and the journal were among them.

WHEN TO USE: Export already-fetched entries as BibTeX (one or many). INPUTS: refs (array of DOI / arXiv id strings, 1..=200). OUTPUTS: { ok: true, entries: [{ ref, safekey, bibtex }] } — bibtex is null when the entry is not in the store; a per-ref { ref, error } element is emitted for an invalid ref or a store read error. OR { ok:false, error } for a store-open failure. COSTS: <10 ms per entry, local read. SIDE EFFECTS: none. LIMITS: Entry must already have been fetched (bibtex:null otherwise — NOT an error). At most 200 refs per call.

WHEN TO USE: Determine which sources the running doiget instance is allowed to use. INPUTS: none. OUTPUTS: { oa_enabled, metadata_sources, tdm_enabled, tdm_elsevier, tdm_aps, tdm_springer, rate_limit_per_sec } (plus additive ok, tier_1, tier_2, tier_3, tdm_ieee). COSTS: <1 ms. SIDE EFFECTS: none. LIMITS: none.

WHEN TO USE: Export already-fetched entries as CSL JSON 1.0 (one or many). INPUTS: refs (array of DOI / arXiv id strings, 1..=200). OUTPUTS: { ok: true, entries: [{ ref, safekey, csl }] } — csl is a 1-element CSL JSON array, or null when the entry is not in the store; a per-ref { ref, error } element is emitted for an invalid ref or a store read error. OR { ok:false, error } for a store-open failure. COSTS: <10 ms per entry, local read. SIDE EFFECTS: none. LIMITS: Entry must already have been fetched (csl:null otherwise — NOT an error). At most 200 refs per call.

WHEN TO USE: Expand a DOI's citation neighborhood via OpenAlex BFS. INPUTS: ref (DOI), depth (optional 1-3, default 3), total (optional 1-100, default 100), per_paper (optional 1-20, default 20). OUTPUTS: { ok: true, ref, seed_work_id, nodes, edges, truncated, total_visited } OR { ok:false, ref, error }. COSTS: O(total) OpenAlex requests; expect 1-30 s for a depth-3 walk. SIDE EFFECTS: Emits one provenance row per consulted Work under Capability::Metadata. NEVER writes to the store. NEVER fetches PDF. LIMITS: ADR-0010 hard caps applied regardless of inputs: depth<=3, total<=100, per_paper<=20. Requires DOIGET_ENABLE_OPENALEX in env. Returns NOT_IMPLEMENTED when this binary was built without the `citation` Cargo feature.

WHEN TO USE: User wants to download a paper PDF given a DOI or arXiv id. INPUTS: ref (DOI or arXiv id), dry_run (optional bool), force (optional bool: ask again even if this session was just answered on the ref; without it such a repeat is replayed as ok:false with replayed:true, #507). OUTPUTS: { ok: true, ref, source, path, license, size_bytes, schema_version, pdf, attempts } OR { ok: true, dry_run: true, ref, plan, rate_limit_budget } OR { ok:false, ref, error }. READ `pdf.status` — `ok: true` does NOT mean a PDF landed. `fetched` = PDF on disk; `no_oa_url` = metadata only, no free copy exists; `blocked` = a free copy EXISTS but was refused. ON `blocked`: do not report the paper as unavailable. `pdf.remediation` lists the config changes that would lift it, narrowest first — `additional_host` entries go under [[network.additional_hosts]] in the config file, a `trust_flag` is a [network] boolean. Show them to the user and let them choose; both widen the trusted download surface. `attempts` says which other sources were consulted and which were never asked (`consulted: false` + `detail` naming the env var to set). Use it before concluding a paper is not indexed anywhere. COSTS: 1-3 s network call (or 0 when dry_run). May fail if not Open Access. SIDE EFFECTS: Writes PDF (or metadata-only TOML) to the store. Appends a row to the provenance log (unless dry_run). LIMITS: Max 5 fetches/sec (global). Use doiget_batch_fetch for >5 refs.

WHEN TO USE: Operational sanity check for the doiget MCP server. INPUTS: none. OUTPUTS: { ok: true, version, schema_version, store_writable, build: { version, channel, binary, method, manifest, manifest_matches, update, check } }. `build` says which binary answered and how to update it; compare `version` with the latest release only if the user asks (`build.check`). COSTS: <1 ms; no network. SIDE EFFECTS: none. LIMITS: store_writable is a best-effort probe of the nearest existing ancestor; it never creates the store.

WHEN TO USE: Inspect a stored entry's metadata locally; the entry must already have been fetched. INPUTS: ref (DOI or arXiv id). OUTPUTS: { ok: true, ref, safekey, metadata: <object>|null } OR { ok:false, ref, error }. COSTS: <10 ms local read. SIDE EFFECTS: none. LIMITS: A missing entry surfaces as { ok: true, metadata: null } — NOT an error envelope. Check `metadata !== null` to confirm presence; call doiget_fetch_paper first when `metadata` is null.

WHEN TO USE: Given a published DOI, find whether the same work has a free arXiv preprint (to read it, or to dedup a preprint vs the journal version). INPUTS: ref (a DOI, e.g. "10.1103/PhysRevB.1"). OUTPUTS: { ok: true, doi, arxiv, openalex_id, title } (arxiv is null when no preprint) OR { ok:false, error }. COSTS: 1 OpenAlex request. SIDE EFFECTS: Emits a Metadata provenance row. NEVER writes the store; NEVER fetches a PDF. LIMITS: DOI input only (arXiv → DOI is a follow-up; an arXiv/invalid ref → INVALID_REF). A DOI with no OpenAlex work → NOT_FOUND.

WHEN TO USE: List the most-recently fetched entries in the local store. INPUTS: limit (optional integer, default 50, max 200). OUTPUTS: { ok: true, count, entries: [{ safekey, title, year, fetched_at }] } OR { ok:false, error }. COSTS: <100 ms for a few thousand entries. SIDE EFFECTS: none. LIMITS: Returns at most `limit` entries (capped at 200).

WHEN TO USE: User wants metadata for a DOI / arXiv id without paying for or being noticed by a PDF download. INPUTS: ref (DOI or arXiv id), dry_run (optional bool), include_oa_location (optional bool). OUTPUTS: { ok: true, ref, source, license?, oa_url, oa_status, metadata } OR { ok: true, dry_run: true, ref, plan, rate_limit_budget } OR { ok:false, error }. COSTS: 1-2 s metadata round-trip (or 0 when dry_run; roughly doubled when include_oa_location). SIDE EFFECTS: Appends a 'metadata-only' provenance row (unless dry_run). Writes the metadata TOML to the store. Never fetches PDF. LIMITS: Subject to the same rate cap as fetch_paper (5/sec). The OA URL is reported but never followed. Crossref alone cannot supply an oa_url, because its link[] entries are scoped to a licensed programme (Similarity Check / TDM / syndication) rather than being general-purpose. A null oa_url is therefore NOT evidence that the work is closed. oa_url is null on the default path whenever Crossref answered, which is nearly every DOI. It can be non-null WITHOUT the flag in one case: Crossref failed and Unpaywall answered instead, and then source is unpaywall rather than crossref - so source tells you which happened. With include_oa_location set, oa_status says which answer you got: closed means the lookup completed and found no OA location, null means the lookup did not complete.

WHEN TO USE: Locate the local PDF file for a stored entry (returns a path, NOT the PDF bytes). INPUTS: ref (DOI or arXiv id). OUTPUTS: { ok: true, ref, safekey, path: string|null, pdf_exists: bool, origin: string|null ("user-supplied" for a PDF added with doiget add; null when doiget fetched it), license: string|null } OR { ok:false, ref, error }. COSTS: <10 ms local read. SIDE EFFECTS: none. NEVER reads or transmits PDF bytes. LIMITS: Both 'no metadata entry' and 'metadata exists but PDF file missing' surface as { ok: true, path: null, pdf_exists: false } — call doiget_info to distinguish the two cases. Returns an ok:false envelope only on invalid ref / store-open failure.

WHEN TO USE: Discover papers on a topic via external OpenAlex search, abstract-first, before fetching any PDF. INPUTS: query (string); optional limit (1-200, default 25), from_year, to_year, oa_only (bool), min_citations, min_fwci (impact floor), min_percentile (0-100, top-X% in cohort), author, venue, publisher (names — resolved to OpenAlex ids), sort (relevance only — use min_fwci/min_percentile/from_year as filters, #290). OUTPUTS: { ok: true, scope: "external", query, total_results, count, results: [{ doi, openalex_id, arxiv, title, authors, year, venue, abstract, cited_by_count, oa_status, source }] } OR { ok:false, error }. COSTS: 1 OpenAlex request, plus 1 per supplied author/venue/publisher name to resolve. SIDE EFFECTS: Emits Metadata provenance rows. NEVER writes the store. NEVER fetches a PDF. LIMITS: Tier-1, always-on (no DOIGET_ENABLE_OPENALEX gate). An ambiguous author/venue/publisher name → AMBIGUOUS (candidates listed); no match → NOT_FOUND. ZERO RESULTS ARE NOT EVIDENCE OF ABSENCE: OpenAlex free-text matching degrades sharply past roughly 8 terms and returns nothing rather than a partial match. On total_results: 0, retry with 3-5 distinctive terms before concluding the work is not indexed; the envelope carries a `hint` saying so.

WHEN TO USE: Fetch the raw LaTeX source of an arXiv paper — more reliable than `doiget_paper_text` (ar5iv) for papers not yet processed by LaTeXML. INPUTS: ref (arXiv id, e.g. "arxiv:2401.12345"); optional max_chars (cap; omit for full source). OUTPUTS: { ok: true, arxiv_id, main_file, tex_source, char_count, truncated, retrieved_from } OR { ok:false, error }. COSTS: 1 arXiv source API request (gzip'd tar download); large papers can be sizeable — use max_chars to bound. SIDE EFFECTS: Emits an OA provenance row. NEVER writes the store; NEVER opens a PDF blob. LIMITS: arXiv only (a DOI → NOT_IMPLEMENTED; pass the arXiv id). PDF-only submissions → TEXT_UNAVAILABLE.

WHEN TO USE: Read a paper's full text (arXiv only) without an external pdf-to-text tool — the 'read' step after discovery/fetch. INPUTS: ref (arXiv id, e.g. "arxiv:2401.12345"); optional max_chars (cap; omit for full text). OUTPUTS: { ok: true, arxiv_id, source: "ar5iv", title, sections: [{ heading, text }], char_count, truncated, retrieved_from } OR { ok:false, error }. COSTS: 1 ar5iv HTTP request (HTML), then parse; large papers can be sizeable — use max_chars to bound. SIDE EFFECTS: Emits an OA provenance row. NEVER opens the PDF blob; NEVER writes the store. LIMITS: arXiv only (a DOI → NOT_IMPLEMENTED; pass the arXiv id). A paper not converted by ar5iv → NOT_FOUND. Best-effort extraction (truncation flagged on `truncated`).

WHEN TO USE: Resolve a free-form bibliographic citation string (e.g. 'Onsager 1944') to ranked DOI candidates. INPUTS: query (bibliographic citation query string), limit (maximum number of candidates to return, default: 5). OUTPUTS: { ok: true, query, candidates: [ { doi, title, author, year, score, confidence, matched, source } ] } OR { ok: false, error }. COSTS: 1-2 s round-trip. SIDE EFFECTS: none. LIMITS: Returns candidates with similarity score >= 0.5. BRANCH ON confidence, NOT score: the score is token overlap against your query string and 0.5 is the FLOOR, so the worst candidate this tool can emit still looks like a positive number. confidence is exact (every query token matched), probable (four in five), or weak (cleared the floor and no more) - for a known-item lookup a weak candidate is a near-miss, not a match, so verify it with doiget_resolve_paper before citing. matched lists which of your tokens were found, which is how you see whether the author and the journal were among them.

WHEN TO USE: User wants metadata for a DOI / arXiv id with no local persistence (audit log row only). INPUTS: ref (DOI or arXiv id), include_oa_location (optional bool). OUTPUTS: { ok: true, ref, source, resolver_profile, license?, oa_url, oa_status, metadata, schema_version } OR { ok:false, ref, error }. COSTS: 1-2 s metadata round-trip (roughly doubled when include_oa_location). SIDE EFFECTS: Appends one provenance row per consulted resolver. NEVER writes a metadata TOML to the store. NEVER fetches PDF. LIMITS: Subject to the same rate cap as metadata_only (5/sec). The OA URL is reported but never followed. Crossref alone cannot supply an oa_url, because its link[] entries are scoped to a licensed programme (Similarity Check / TDM / syndication) rather than being general-purpose. A null oa_url is therefore NOT evidence that the work is closed. oa_url is null on the default path whenever Crossref answered, which is nearly every DOI. It can be non-null WITHOUT the flag in one case: Crossref failed and Unpaywall answered instead, and then source is unpaywall rather than crossref - so source tells you which happened. With include_oa_location set, oa_status says which answer you got: closed means the lookup completed and found no OA location, null means the lookup did not complete. dry_run is not supported; use metadata_only with dry_run for a preview.

WHEN TO USE: Find stored entries whose title / authors / venue / publisher contain a query substring (case-insensitive). INPUTS: query (string), limit (optional integer, default 50, max 200). OUTPUTS: { ok: true, scope: "local", query, count, results: [{ safekey, title, year, fetched_at }] } OR { ok:false, error }. COSTS: O(N) over the local store; <100 ms for a few thousand entries. SIDE EFFECTS: none. LIMITS: Returns at most `limit` entries (capped at 200).

WHEN TO USE: Add or remove tags / collections on a stored paper entry for local knowledge-base organisation (#294). INPUTS: ref (DOI or arXiv id); add (array of tags to add, optional); remove (array of tags to remove, optional); collection_add (array of collections to join, optional); collection_remove (array of collections to leave, optional). OUTPUTS: { ok: true, ref, tags, collections } OR { ok: false, error }. COSTS: 0 network requests; one store read + write. SIDE EFFECTS: Overwrites [doiget].tags / [doiget].collections in <store>/.metadata/<safekey>.toml. LIMITS: Entry must already exist in the store. Tags are case-sensitive; idempotent add/remove.