Pendar

View saved version →

---
name: survey-a-research-field
description: Size and characterise a research area from exact publication counts — how many papers exist, whether output is growing or fading, which sub-areas and disciplines it divides into, which countries and institutions produce it, where it is published, and what to read first. Use when the user asks how large, how active, or how crowded a field is, wants an overview of a topic's literature, or is deciding whether to enter an area.
metadata:
  short-description: Measure a research field by exact publication counts
---

# Survey a research field

Describe a body of literature by counting it. `survey_literature` returns exact
counts over every paper matching the topic — not a sample — so the answer can
state how many papers exist, how that number moved year by year, and who
produced them.

The counts are the substance here. A list of relevant papers comes back too, but
it is the smaller half of the answer, and leading with it wastes what the tool is
for.

## Quick start

1. Reduce the user's question to a **short noun phrase of two to six words**.
   "How much work has been done on solid-state electrolytes for lithium metal
   batteries?" becomes `solid state electrolytes lithium metal`.
2. Call `survey_literature` once. Add `year_from` or `year_to` only if the user
   asked about a period.
3. Read `corpus.total_papers` together with `corpus.matched_on` before saying
   anything about size — the second changes what the first means.
4. Lead with size and trend, then composition, then the reading list.
5. Repeat every caveat in `notes` that bears on what you claim.

## Choosing the query

The search requires **every** word to appear, so each extra word shrinks the
corpus, and question words are stripped before searching.

- Drop question framing, verbs, and articles: keep the subject.
- Keep the phrase specific enough to mean one field and no more.
- If `total_papers` is 0 or in the low single digits, the terms were too narrow.
  Retry once with the two or three most central words, and tell the user you
  broadened it and to what.
- If the number looks implausibly large for the subject, the terms were too
  generic. Retry with the distinguishing term restored.

Never present a retry as a different question. State which phrase produced the
numbers you are reporting; `corpus.searched_for` shows what was actually
searched after stripping.

## Reading the result

- `corpus.total_papers` with `corpus.matched_on`:
  - `title_and_abstract` — a conservative count. Papers that mention the topic
    only in passing are excluded.
  - `full_text` — too few papers had the topic in title or abstract, so the
    corpus was widened to anything whose full text mentions it. Report the total
    as an **upper bound**, because passing mentions are now included.
- `corpus.trend` — `interpretation` is already written from the exact per-year
  counts; use it rather than recomputing a trend from `papers_by_year`. Treat
  `too_new` as insufficient history, not as a lack of growth. The current year is
  partial, so never describe a field as declining on the strength of the latest
  bar alone.
- `corpus.topics` versus `corpus.disciplines` — topics are the **sub-areas the
  work divides into**; disciplines are the **fields whose researchers produce
  it**. Keep them apart. A topic list answers "what is this field about", and a
  discipline list answers "who works on it".
- `corpus.countries` and `corpus.institutions` — shares overlap and total well
  above 100%, because a paper written across four institutions counts once in
  each. Say so if you quote them.
- `corpus.venues` — preprint servers and repositories rank here beside journals.
  A repository near the top is a finding: the field circulates before peer
  review.
- `corpus.work_types` — a large preprint share means a fast-moving field where
  the published record lags.
- `corpus.retracted_papers` — mention any retractions if the user intends to rely
  on the fie

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 2 — file references are metadata, not package contents.

View saved version →

---
name: trace-citation-impact
description: Trace who has built on a specific paper — whether its citations are accelerating or fading, which research fields picked it up, whether universities or industry or hospitals are citing it, and which authors cite it most. Use when the user asks how influential a paper is, whether it is still relevant, where a method spread, which labs are working on it, or what it was built on.
metadata:
  short-description: Follow who has built on a paper, and where it spread
---

# Trace citation impact

Take one paper and report how the literature has used it: the exact per-year
citation history, the fields the citing work comes from, the kinds of institution
doing the citing, and the authors citing it most. `graph_hopper` resolves the
paper, walks one hop forward to its citers and one hop back to its references,
and returns counts over the citing set.

The value is in *who* cited it, not how many did. A citation total is available
anywhere; the composition of the citing set is what says whether a method
travelled beyond its home field and who is carrying it.

## Quick start

1. Call `graph_hopper` with the paper as a DOI, title, or full citation string.
   A `paper_id` from an earlier Pendar result also works and resolves exactly.
2. Leave `direction` as `both` unless the user asked only about influence
   (`forward`) or only about foundations (`backward`).
3. Leave `analyze_citers` at 50, or raise it toward 100 for a heavily cited
   paper. It widens the breakdowns at almost no cost, since they come back as
   counts.
4. Keep `papers_per_direction` small — 10 is usually enough. The breakdowns
   already summarise the rest.
5. Set `include_graph: true` **only** when the user wants a diagram of the
   neighbourhood. It is large and adds nothing the breakdowns do not cover.

If `found` is false, present `candidates` and ask which paper was meant. Do not
analyse a paper the user did not ask about.

## Reading the result

- `momentum.trend` is one of `accelerating`, `steady`, `declining`, `too_new`,
  `unreliable`, or `unknown`.
  - **`unreliable` means report no trend at all.** The paper's own per-year
    history contradicts itself, which happens when duplicate records for one
    paper are merged or split and most of its citations follow the other copy.
    Say the citation record for this paper appears damaged and that a trend
    cannot be read from it. Do not describe such a paper as declining — that is
    the artefact talking, and it will be wrong about famous papers in particular.
  - `too_new` means too little history, not lack of impact.
  - Use `momentum.interpretation` as written; it is derived from the exact
    histogram. `recent_3y_citations` against `prior_3y_citations` is the evidence
    behind it.
- `field_mix` — the research areas the citing papers belong to, from a standard
  discipline taxonomy. Name both `subfield` and `field`. Subfields far from the paper's
  own are the interesting part: they are where the work crossed over. Do not
  reduce this to a single "interdisciplinarity" figure; field boundaries are
  administrative and such a number would mislead.
- `institution_mix` — universities, industry, hospitals, government labs. An
  industry or hospital share is the signal that research became practice.
  `representative_institutions` are examples from that bucket, not the full list,
  so do not present them as the only ones.
- `top_citing_authors` — the corresponding authors citing the work most, ranked
  by their own citation totals. These are the people building on it: useful for
  finding collaborators, reviewers, or labs to approach. They are **not**
  co-authors of the seed paper, and citing a paper does not imply endorsing it.
- `cited_by` and `references` — the most-cited individual papers in each
  direction. Abstracts are omitted; call `verify_paper` on one if the user wants
  its full record.
- `notes` — carries the sample size behind the breakdowns ("breakdowns 

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 2 — file references are metadata, not package contents.

View saved version →

---
name: verify-citations
description: Check whether cited papers actually exist, are described correctly, and have not been retracted. Use when the user pastes a bibliography, reference list, or citations from a draft, asks whether a paper is real, or wants references from an AI-generated answer checked before relying on them.
metadata:
  short-description: Confirm papers exist, match their citation, and are not retracted
---

# Verify citations

Confirm each cited paper exists in the published record, that the citation
describes it accurately, and that it has not been retracted.

A citation that cannot be found is the finding. Report it as unverified and stop
there — never substitute the closest real paper, and never fill in a missing
DOI, year, or venue from memory. A confidently wrong reference is worse than an
acknowledged gap, because the user will submit it.

## Quick start

1. Split the input into individual citations. One `verify_paper` call per
   citation, never several at once in one string.
2. Pass whatever the user gave: a DOI, a bare title, or a full citation string
   all work. A `paper_id` from an earlier Pendar result also resolves exactly.
3. Classify each result — verified, ambiguous, retracted, or not found — using
   the rules below.
4. Report every citation in the order given, then a one-line tally.

## Reading the result

- `found: false` — the paper could not be resolved. Say so plainly and quote
  `reason`. Do not offer a different paper as though it were the one cited. If
  the user wants alternatives, offer to search the literature instead, as a
  separate step they asked for.
- `candidates` non-empty — the citation was too ambiguous to resolve. List the
  candidates with year, venue, and author so the user can choose. Ask which one
  they meant. Do not pick the top candidate silently.
- `match_confidence` below about 0.8 — the match is uncertain even though a
  paper came back. Show the resolved `title`, `year`, and `authors` next to what
  the user wrote so they can judge it themselves.
- `retraction_warning` non-empty, or `paper.is_retracted: true` — lead with the
  retraction. Say the paper is retracted before saying anything about its
  findings, and advise against citing it as standing evidence.
- `paper.work_type` of `preprint` — flag that it has not been peer reviewed. The
  user may have cited it as a journal article.
- Metadata that disagrees with the user's citation — a different year, venue, or
  author list — report the discrepancy and give the canonical values from
  `paper`. Do not quietly correct it; the user needs to know their source was
  wrong.

## Never

- Invent or guess a DOI, a `paper_id`, or a URL. Use `paper.doi` and
  `paper.landing_url` as returned, or say they are unavailable.
- Claim a paper is retracted unless `is_retracted` is true.
- Treat `found: false` as proof of fabrication. It means the paper is not in the
  indexed record, which is strong evidence for a mainstream journal article and
  weak evidence for a book chapter, thesis, technical report, or very recent
  preprint. Say which case you think it is.
- Report `citation_count` as a measure of quality. It measures attention, and a
  recent paper has had less time to accumulate any.

## Reporting

Give one line per citation, in the user's order, each with a clear verdict:

- **Verified** — canonical title, authors, year, venue, DOI.
- **Retracted** — the same, with the retraction stated first.
- **Ambiguous** — the candidates, and the question of which was meant.
- **Not found** — what was searched for, and why it may be missing.

Close with the tally: how many verified, how many retracted, how many
unresolved. If anything was retracted or unresolved, say explicitly that the
draft needs those references fixed before submission.

## Related workflows

- To measure a paper's influence rather than its existence, use
  `trace-citation-impact`.
- To find what else exists on the subject, use `survey-a-research-field`

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 2 — file references are metadata, not package contents.