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 field's findings.
- `papers` — the most relevant papers, with abstract snippets. Summarise what
  they cover; do not present them as the field's most important work, since they
  are ranked by relevance to the query rather than by influence.

## Never

- Read percentages from a small corpus as proportions of a research area. Exact
  arithmetic over six papers still prints as "33%". When `notes` flags a small
  corpus, describe the individual papers instead.
- Compare two topics' totals without saying whether both were matched the same
  way. A `full_text` total against a `title_and_abstract` total is not a
  comparison.
- Add papers, counts, or trends from memory. Everything reported must come from
  the response.
- Call the tool repeatedly to page through a field. One survey covers the whole
  corpus; more calls only re-count it.

## Reporting

1. **Size** — the total, what it was matched on, and the years covered.
2. **Trajectory** — the trend, with the recent versus prior three-year counts
   behind it and the peak year.
3. **Composition** — sub-areas, then the disciplines and countries producing the
   work, then where it is published and how much is peer reviewed.
4. **What to read** — the returned papers, grouped by what they address.
5. **Caveats** — the corpus definition and any small-corpus or retraction note.

## Related workflows

- To measure one paper's influence rather than a field's size, use
  `trace-citation-impact`.
- To check a specific reference the user already has, use `verify-citations`.

Referenced files: 2

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 cover N
  citing papers") and flags an absent citer or reference list. Quote the sample
  size whenever you quote a percentage.

## Never

- Equate citation count with quality or correctness. It measures attention.
  Retracted papers accumulate citations too, so check `seed.is_retracted`.
- Report a decline when `trend` is `unreliable`.
- Say a paper is uncited when `notes` reports that no citers were indexed — a
  recent paper and an unindexed one look identical from here, and the note
  distinguishes them.
- Infer a lab's research agenda, a company's product plans, or an author's
  opinion from a single citation.
- Compare two papers' raw citation totals across different years or fields
  without saying that both vary by publication age and field size.

## Reporting

1. **The paper** — canonical title, authors, year, venue, total citations, and
   any retraction.
2. **Trajectory** — accelerating, steady, declining, or unreadable, with the
   three-year counts and peak year behind it.
3. **Where it spread** — the citing fields, calling out any far from the paper's
   own subfield.
4. **Who is citing** — the institution mix, then the leading citing authors.
5. **What to read next** — the most-cited citing papers, and the references if
   the user asked what it was built on.
6. **Sample size and caveats** — how many citers the breakdowns cover.

## Related workflows

- To size the whole field rather than one paper's reach, use
  `survey-a-research-field`.
- To confirm a reference exists and is not retracted, use `verify-citations`.

Referenced files: 2

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`.

Referenced files: 2