Skip to main content
Glama

essay.research.full

Runs essay topic research with a draft-then-confirm workflow; confirmation writes one Word file per paper to critical-reviews.zip.

Instructions

Essay: essay.research.full (Confirm two-step — draft then confirm; never silent). The draft reply returns cardDigest. Send confirmPhase confirm with the same arguments plus that cardDigest; a confirm without it, or with a different digest, is refused and the step is shown again. confirmPhase and topic are required. clarify_context needs objective, background, issues, and guidance, each an answer or leave_open true. leave_open is the human's choice, never the model's default. packs is optional, at most two names from essay.health local_packs; never invent one. exclude_section_ids, industry, and host_voice are optional. Clarify answers, industry, host_voice, and a named pack are not evidence. Confirm writes one Word file per paper in critical-reviews.zip. Draft writes neither. The files are the same for either mid-office pick.

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>",
      "topic": "<topic>"
    },
    "name": "essay.research.full"
  }
}

Input Schema

NameRequiredDescriptionDefault
packsNo
topicYes
claimsNo
reviewsNo
sourcesNo
essay_idYes
industryNo
cardDigestNo
host_voiceNo
confirmPhaseNo
clarify_contextNo
exclude_section_idsNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.9.0
    • addedInput schema / properties / cardDigest
      Added value: +{
      +  "anyOf": [
      +    {
      +      "type": "string"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "default": null,
      +  "title": "Carddigest"
      +}
  2. First observedv0.3.1

TDQS

B3.4/5.0
Behavior4/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 substantial work: it discloses the two-step confirmation, that a missing or mismatched digest is refused and the step re-shown, that confirm writes Word files into critical-reviews.zip while draft writes neither, and that leave_open is a human-only choice. It omits permissions, idempotency, and what happens if a confirm targets an essay already confirmed, but the mutation profile is unusually well surfaced for an unannotated tool.

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

Conciseness3/5

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

The critical constraint (two-step, digest-bound confirm) is front-loaded, which is correct. But the text is a dense run of parenthetical fragments, and the closing line 'The files are the same for either mid-office pick' introduces undefined jargon that does not visibly earn its place. Information-dense yet hard to parse on a first read.

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 12-parameter, unannotated tool with no output schema, the description covers the confirm flow, the side effects, and roughly half the parameters, but leaves essay_id, claims, reviews, and sources undefined and never describes what the draft returns beyond cardDigest. It is more complete than typical for its complexity, yet still leaves gaps an agent would need before a correct first call.

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

Parameters4/5

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

Schema coverage is 0%, so the description must compensate, and it explains cardDigest's provenance, confirmPhase's role and requirement, clarify_context's four sub-fields and the answer/leave_open structure, and packs' limit of two names drawn from essay.health local_packs with an explicit 'never invent one'. It even adds epistemic semantics ('clarify answers, industry, host_voice, and a named pack are not evidence'). essay_id, claims, reviews, and sources remain unexplained, keeping this from a 5.

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 the two-phase draft/confirm protocol and that confirm writes 'one Word file per paper in critical-reviews.zip', which obliquely reveals what the tool produces. However, it never plainly states what 'full research' actually does (what papers, from what inputs) and offers no differentiation from siblings such as essay.research.summary. The purpose must be inferred from side-effect statements rather than stated directly.

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?

It gives strong invocation discipline for the confirm step (cardDigest must come from the draft, mismatches are refused) and states which parameters are required vs optional. It does not say when to choose this tool over essay.research.summary, essay.dig, or other research paths, nor what preconditions the essay must satisfy. Usage is implied through the protocol rather than through explicit tool selection guidance.

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