# Citation System Reference

## Citations

AgentDock verifies and formats citations automatically. You provide a DOI or
URL inline in your writing, and the server resolves it — fetching the real
title, authors, journal, and year from academic databases. No hallucinated
citations. You never need to format references yourself.

### How to Cite (Primary — inline in your writing)

Write your content normally. When you want to cite a source, include the
identifier inline using `{{cite:...}}` syntax:

```markdown
Crop yields declined by 6% {{cite: doi=10.1038/s41586-024-1234}}.

AI funding hit record levels {{cite: url=https://techcrunch.com/2026/article}}.

The treatment showed promise {{cite: pmid=39847562}}.

{{cite: doi=10.1038/... format=narrative}} found significant results.
```

Pass this content to `write_document`. The server resolves each identifier,
verifies the source exists, and places the formatted citation inline. The
document owner sees proper "(Smith et al., 2024)" citations, not your raw
identifiers.

### How to Find Sources

If you don't know what to cite, search first:

```
search_citations(query: "climate change agriculture")
→ [{ doi: "10.1038/...", title: "Global Crop Yields", year: 2024, ... }]
```

Then use the returned DOI in your writing.

### Citation Tools

#### search_citations
Search for papers to cite. Returns verified sources from real databases.

- `query` (required) — search text
- `limit` (optional, 1-10, default 5)
- `yearFrom` / `yearTo` (optional) — publication year range
- Returns: array of citation candidates with DOI, title, authors, year, journal

#### add_citation
Add a citation to an existing document. The citation is placed inline at the
end of the specified paragraph — not as a separate block.

- `id` (required) — document UUID
- `identifier` (required) — DOI, URL, "pmid:12345", or "arxiv:2301.07041"
- `paragraphIndex` (optional) — which paragraph to cite (0-based). Default: last paragraph.
- `style` (optional) — citation style (apa, mla, chicago, harvard, ieee, ama, vancouver)
- `format` (optional) — `"parenthetical"` = (Smith, 2024), `"narrative"` = Smith (2024)
- `saveToLibrary` (optional, boolean, default false) — also save this citation to your personal library for reuse across documents
- Returns: `{ citation: { id, formattedText, title, authors, year, doi, savedToLibrary } }`

#### list_citations
See what's already cited in a document.

- `id` (required) — document UUID
- Returns: array of `{ id, title, authors, year, doi, formattedText }`

#### remove_citation
Remove a citation from a document.

- `id` (required) — document UUID
- `citationId` (required) — citation ID (from list_citations)
- Returns: `{ success: true }`

### Supported Identifiers

| What you have | How to write it |
|--------------|----------------|
| DOI | `{{cite: doi=10.1038/s41586-024-1234}}` |
| Publisher URL | `{{cite: url=https://nature.com/articles/...}}` |
| News/blog URL | `{{cite: url=https://techcrunch.com/...}}` |
| PubMed ID | `{{cite: pmid=39847562}}` |
| arXiv ID | `{{cite: arxiv=2301.07041}}` |

### Workflow: Write a Research Article

```
1. search_citations(query: "climate change crop yields")
   → [{ doi: "10.1038/...", title: "Global Crop Yields" }]

2. create_document(title: "Impact Analysis")
   → { id: "abc-123" }

3. write_document(id: "abc-123", content: "# Impact Analysis\n\n
   Crop yields declined by 6% {{cite: doi=10.1038/s41586-024-1234}}.
   This has significant implications for food security.")

4. list_citations(id: "abc-123")
   → [{ formattedText: "(Smith et al., 2024)", title: "Global Crop Yields" }]
```

### Workflow: Add Citations to Existing Document

```
1. search_citations(query: "neural network efficiency")
   → [{ doi: "10.1145/...", title: "Efficient Networks" }]

2. add_citation(id: "abc-123", identifier: "10.1145/3512345")
   → { citation: { formattedText: "(Chen et al., 2023)" } }
```

## Citation Library

Your personal citation library stores citations for reuse across documents.
When you find a useful source, save it once and insert it into any document
later. All 7 citation styles (APA, MLA, Chicago, Harvard, IEEE, AMA,
Vancouver) are pre-formatted automatically.

### citation_library_list
List citations from your personal library.

- `limit` (optional, 1-100, default 50)
- `sortBy` (optional) — `"recent"` (default), `"usage"`, or `"title"`
- Returns: `{ citations: [...], count }`

### citation_library_save
Save a citation to your personal library. Automatically formats in all 7
citation styles.

- `title` (required) — citation title
- `authors` (required) — array of `{ firstName, lastName }`
- `year` (optional) — publication year
- `citationType` (optional) — CSL type (default: article-journal)
- `metadata` (optional) — additional fields (doi, journal, volume, etc.)
- Returns: `{ citation: { id, title, formattedApa } }`

### citation_library_get
Read a single citation from your library by ID.

- `citationId` (required) — citation UUID
- Returns: `{ citation: { ... } }`

### citation_library_search
Search your personal citation library using full-text search.

- `query` (required) — search text
- `limit` (optional, 1-50, default 20)
- Returns: `{ citations: [...], count }`

### citation_library_delete
Delete a citation from your personal library.

- `citationId` (required) — citation UUID to delete
- Returns: `{ success: true }`

### citation_format
Format a citation in a specific style without saving to your library. Useful
for previewing how a citation will look before saving or inserting.

- `title` (required) — citation title
- `authors` (required) — array of `{ firstName, lastName }`
- `year` (optional) — publication year
- `style` (required) — apa, mla, chicago, harvard, ieee, ama, or vancouver
- `format` (optional) — `"parenthetical"` (default) or `"narrative"`
- `doi` (optional) — DOI
- `journal` (optional) — journal name
- Returns: `{ formattedText, style }`

## Citation Collections

Collections are folders for organizing your citation library. Create
collections by topic, project, or any other grouping.

### citation_collection_list
List your citation collections.

- `counts` (optional, boolean) — include citation counts per collection
- Returns: `{ collections: [...] }`

### citation_collection_create
Create a new collection.

- `name` (required) — collection name
- `description` (optional) — collection description
- `parentId` (optional) — parent collection UUID (for nested collections)
- Returns: `{ collection: { id, name } }`

### citation_collection_add
Add a citation from your library to a collection.

- `citationId` (required) — citation UUID
- `collectionId` (required) — collection UUID
- Returns: `{ success: true }`

### citation_collection_remove
Remove a citation from a collection. The citation remains in your library.

- `collectionId` (required) — collection UUID
- `citationId` (required) — citation UUID to remove
- Returns: `{ success: true }`

### citation_collection_delete
Delete a collection. Child collections are deleted recursively. Citations
in the collection are not deleted from your library.

- `collectionId` (required) — collection UUID to delete
- Returns: `{ success: true }`

### Workflow: Build a Research Library

```
1. citation_collection_create(name: "Climate Research")
   → { collection: { id: "col-1" } }

2. search_citations(query: "climate change agriculture")
   → [{ doi: "10.1038/...", title: "Global Crop Yields" }]

3. add_citation(id: "doc-1", identifier: "10.1038/...", saveToLibrary: true)
   → { citation: { id: "cit-1", savedToLibrary: true } }

4. citation_collection_add(citationId: "cit-1", collectionId: "col-1")
   → { success: true }

5. citation_library_list(sortBy: "recent")
   → Your saved citations, ready for any document
```