Essay Writer

Overview Schema Source Related Servers Discussions Admin

essay.dig

Search and download open-access papers for an essay with explicit confirmation; save valid PDFs and generate a dig card, annotation notes, and a missing-links list.

Instructions

Essay: essay.dig (Confirm two-step). Draft writes nothing. Confirm writes a local dig-card.json and dig-card.md on the sequence. OpenAlex runs without a key. Unpaywall runs only when an email is already stored; skipping the email is fine. A Consensus key turns Consensus on for the search. No key leaves Consensus off and the search stays on OpenAlex. ESSAY_WRITER_CONSENSUS=0 turns Consensus off. ESSAY_WRITER_CONSENSUS=1 turns it on when a key is present. Consensus Free or Pro is the tier the look-up returns. Confirm downloads an open copy only when the response is a real PDF (content-type and %PDF- magic). An HTML abstract page, a 404, a paywall, or an empty file is not a paper and is written to download-list.docx. Valid PDFs are kept. The same failed address stops after 3 tries. The path also stops when more than 10 minutes pass with no new PDF. Confirm then writes annotation.docx and the download list from the files already saved, and names what is still missing. The annotation Word file is for the chat. download-list.docx is Word. The reply includes a links card with a title and a URL for each file that was not saved. A saved PDF is not on that card. The papers zip contains real PDFs only. Do not retry a stopped address. invent-forbid: hits are look-up records only. Do not invent a paper.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "essay_id": "<essay_id>",
      "query": "<query>"
    },
    "name": "essay.dig"
  }
}

Input Schema

Name	Required	Description	Default
`query`	Yes
`essay_id`	Yes
`confirmPhase`	No

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.3.1Nov 4, 2026

TDQS

B3/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations at all, the description carries the full burden and does substantial work: it discloses credential requirements per source (OpenAlex keyless, Unpaywall needs a stored email, Consensus needs a key), the env-var overrides, PDF validation by content-type and %PDF- magic, the 3-try cap per failing address, the 10-minute no-progress stop, and which artifacts get written. What it omits are side effects on the server/reply shape beyond the links card and whether existing files are overwritten.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness2/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The text is a wall of short declaratives with no grouping, so the operational 'how' is front-loaded ahead of the purpose and the reader must assemble the model themselves. There is also redundancy ('The annotation Word file is for the chat. download-list.docx is Word.') that spends words without adding information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a complex, mutable, key-gated, multi-artifact tool with no annotations and no output schema, the description is unusually thorough on failure handling and file outputs, and it does mention what the reply contains (links card). It still leaves the core intent and all three parameter meanings underspecified, so an agent could invoke confirm blindly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate and it largely does not: 'query' is never explained (search string? syntax?) and 'essay_id' is never tied to a project or sequence. The most important gap is 'confirmPhase' — the draft/confirm phrasing hints at values but the literal strings, the null default, and whether omission means draft are never stated, leaving an ambiguous mutation switch.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description conveys a great deal about mechanics (writes dig-card.json/dig-card.md, runs OpenAlex/Unpaywall/Consensus look-ups, downloads open PDFs), but never front-loads a single sentence saying what the tool is for. 'Essay: essay.dig (Confirm two-step)' is close to a restatement of the name, and 'dig' is not a self-explanatory verb, so the agent must reconstruct the purpose from the operational detail that follows.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The draft/confirm two-step is implied ('Draft writes nothing. Confirm writes...'), which gives some when-to-use signal, and two exclusions are stated explicitly ('Do not retry a stopped address', 'Do not invent a paper'). However, none of the 23 sibling tools (e.g. essay.research.full, essay.research.summary, essay.download.leftovers) are named or contrasted, so routing between this and overlapping research/download tools is left to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.