Skip to main content
Glama

essay.revise

Records review feedback on an existing essay after research or Word confirmation, gated by a two-step confirm. Use it to capture revision notes without creating a new .docx or replacing Word edits.

Instructions

Essay: essay.revise (Confirm two-step). The essay id is a sequence id. Records feedback on this same essay after research or Word confirm. Does not write a new .docx and does not replace the Word confirm. Invented citations in the note are refused. Local Word edit. A changed Word upload leaves the parent sequence in place and rolls forward onto the next sequence.

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>",
      "message": "<message>"
    },
    "name": "essay.revise"
  }
}

Input Schema

NameRequiredDescriptionDefault
packNo
messageYes
essay_idYes
confirmPhaseNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.3.1

TDQS

C2.7/5.0
Behavior3/5

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

With zero annotations, the description carries the full behavioral burden and does disclose some meaningful traits: invented citations in the note are refused, no new .docx is written, the Word confirm is not replaced, and a changed Word upload keeps the parent sequence and rolls forward. That is real value. It stops short on who may call it, whether the feedback record is reversible, and what a refused citation does to the call — gaps that matter for a mutation with no annotation cover.

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?

It opens by restating the name and title, then strings together short fragments ('Local Word edit.') that each add words without resolving referents. The most load-bearing constraint, that citations are refused, is buried mid-paragraph rather than front-loaded. The piece is not long, but it is not structured for scanning.

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

Completeness2/5

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

A four-parameter mutation tool with no annotations, no output schema, and 0% schema description coverage needs a far more complete description. Return behavior, the meaning of confirmPhase, and the pack object are absent. What is present — sequence semantics and citation refusal — is genuinely useful but not enough to call it correctly end to end.

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 coverage is 0%, so the description must define all four parameters and does not. 'The essay id is a sequence id' is a useful hint for essay_id, and 'the note' loosely maps to message. Neither pack nor confirmPhase is explained beyond the unexplained phrase 'Confirm two-step'. Two of four parameters remain opaque.

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 does state a concrete action — 'Records feedback on this same essay after research or Word confirm' — which is a real verb+resource pair. But it is wrapped in fragments like 'Essay: essay.revise (Confirm two-step)' and 'Local Word edit', so the agent has to reconstruct what the tool actually does. It only partially separates itself from siblings by negating ('does not write a new .docx and does not replace the Word confirm') rather than naming the alternative.

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?

'after research or Word confirm' and 'Confirm two-step' imply a prerequisite ordering, which is genuine context. However, no sibling tool is named as the alternative path, and the exclusions are phrased negatively ('does not replace the Word confirm') rather than as 'use X instead when…'. The guidance is implied, not explicit.

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