Essay Writer

Overview Schema Source Related Servers Discussions Admin

essay.setup

Initialize the writing workspace and research search settings with a two-step confirmation, creating cloud folders or saving named local paths.

Instructions

Essay: essay.setup (Confirm two-step). Say the reply to the user. File work does not own this chat. Draft writes nothing. Confirm creates the app folder, the KB1 vault, and the door folders later doors read (Essay-writer, uploads, unassigned) on the cloud computer when called with no paths. A named pair of paths saves on this computer. Only a path you name on this computer is accepted. Documents is not a fallback and is not labelled as the cloud. A Consensus key and an Unpaywall email are collected on the secret card and are not repeated. A Consensus key turns Consensus on for the search. No key leaves Consensus off and the search stays on OpenAlex. The Consensus key is for academic research search: it finds papers for the research step. Consensus's help center says the API is how a tool programmatically searches academic research and retrieves relevant papers: https://help.consensus.app/en/articles/16516328-the-consensus-api

Create that key with Consensus's own steps from that page. Click the profile icon in the bottom-left corner, select API & MCP Dashboard, open the Keys and Clients tab, click New key, give the key a name so you can tell what it is for, then create it and copy it somewhere secure. The full key is shown once. If it is lost, revoke it and create a new one. The same path is on https://docs.consensus.app/api-plans-and-access : profile icon, then API & MCP Dashboard, then Keys and clients, then New key. The dashboard named from get-started is https://consensus.app/api-mcp

Ask which Consensus plan they have. Free stores ESSAY_WRITER_CONSENSUS_PAID as 0. Pro stores it as 1. Teams, Deep, and Enterprise use 1, the same paid flag as Pro. Do not add another flag. The published limits are only those on https://docs.consensus.app/api-plans-and-access : Free includes 30 calls a month and the maximum with additional usage is 30; Pro includes 500 and the maximum with additional usage is 1,000. Max papers per request is 20 on Free and 300 on Pro. Pagination past the first page is no on Free and yes on Pro. Full-text excerpts are no on Free and yes on Pro. The rate limit is 1 request per second on Free and 1 request per second on Pro.

The email is for Unpaywall free-PDF lookup. Unpaywall's API docs say a request must include the email as ?email=YOUR_EMAIL, and they ask for at most 100,000 calls a day: https://unpaywall.org/products/api . OpenAlex, from the same team, asks for an email where they can contact you if a script goes wrong, and says that approach is copied from Crossref: https://github.com/ourresearch/openalex-docs/blob/main/how-to-use-the-api/rate-limits-and-authentication.md . Crossref's REST API FAQ answers "Will you spam me with marketing bumf once you have our contact info?" with "No. We will only use it to contact you about problems with your scripts." https://github.com/CrossRef/rest-api-doc/blob/master/README.md . Say that limit, attributed to the Crossref FAQ by way of OpenAlex. Do not say that Unpaywall's own page promised never to email.

If the user skips the Consensus key, the Unpaywall email, or both, show the warning before the skip is accepted. Consensus is not used when the key is missing. Unpaywall free PDF lookup will not run when the email is missing. OpenAlex still runs. After an explicit yes to that warning, call essay.setup with confirmPhase draft, acknowledge_skipped_searches true, and the same other arguments. Show that result. After another explicit yes, call essay.setup with confirmPhase confirm and those same arguments. A confirm that skips without acknowledge_skipped_searches writes nothing.

Do not ask the user to edit a .env file. Do not repeat the key or the email. The file-work host is stored once and defaults to agent --version at setup. Pass the alternate only when the user asks for grok version instead. Change it only by running setup again. The version check matches that choice. This door reports that version. It does not install grok and does not install on the Mac. Does not write notes.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "essay.setup"
  }
}

Input Schema

Name	Required	Description	Default
`app_path`	No
`kb1_path`	No
`confirmPhase`	No
`consensus_plan`	No
`unpaywall_email`	No
`mid_office_shell`	No
`consensus_api_key`	No
`install_grokbuild`	No
`acknowledge_skipped_searches`	No

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.3.1Nov 4, 2026

TDQS

B3.1/5.0

Behavior3/5

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

With no annotations, the description carries the full burden and does disclose useful traits: cloud-vs-local path behavior, that draft writes nothing, that the version check matches the stored host choice, and that it does not install grok or write notes. However it omits failure modes, idempotency on re-run, and the shape of the result. It also creates ambiguity by offering an install_grokbuild parameter while asserting the door "does not install grok."

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?

Roughly 600 words for a setup call, with multiple external URLs, a full pricing/limit table, and step-by-step instructions for creating a third-party API key that do not help an agent invoke this tool. The two-step confirm rule — the most decision-relevant content — is placed near the end, after the digressions.

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 9-parameter, annotation-free, output-schema-free setup tool the description does cover the important behavioral and sequencing facts. What is missing is a mapping from prose to parameter names, plus any description of the return payload an agent must relay to the user.

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

Parameters3/5

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

Schema description coverage is 0% across 9 parameters, so the description must compensate and it partially does: it explains the null-path/cloud vs named-path/local semantics, the draft/confirm phases, the plan-to-flag mapping (Free=0; Pro/Teams/Deep/Enterprise=1), and the host/version choice. But it never names the parameters, and install_grokbuild, mid_office_shell, and app_path vs kb1_path pairing remain inferential rather than explicit.

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 core purpose is stated — "Confirm creates the app folder, the KB1 vault, and the door folders later doors read ... on the cloud computer when called with no paths" — which is a specific verb+resource+scope. But it is buried under long digressions about Consensus API key creation, plan limits, and Unpaywall email policy, so an agent must excavate the actual operation. Nothing distinguishes it from siblings such as essay.intake or essay.sequence.new.

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

Usage Guidelines4/5

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

The two-step confirm flow is spelled out explicitly: draft first with acknowledge_skipped_searches true after a warning, then confirm after another explicit yes, and "A confirm that skips without acknowledge_skipped_searches writes nothing." Skip conditions and their consequences (Consensus off, Unpaywall lookup not running, OpenAlex still running) are also given. It lacks any statement of when to call this versus the sibling setup-ish tools.

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