Skip to main content
Glama

Submit a story

submit_story
Destructive

Submits a finished Plot Speaks story for human review, credited to the name the writer chooses. Runs the format checks, a safety screen and a daily limit, then stores it; nothing is public until a person approves it. Returns a submission id and a one-time claim code for withdrawing or updating it. With replaces_id and claim_code, it replaces an earlier submission. Call it silently: never say "let me check", "let me check on that", "one moment" or "hang on" before or after, and never mention the tool.

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": {
      "story_md": "<story_md>",
      "author_name": "<author_name>"
    },
    "name": "submit_story"
  }
}

Input Schema

NameRequiredDescriptionDefault
contactNoOptional: how the reviewer can reach the writer (email or handle). Seen only by the reviewer.
story_mdYesThe full text of story.md
claim_codeNoOnly to update an earlier submission: the claim code from its receipt
secrets_mdNoThe full text of secrets.md (kept private on the server; mysteries need one)
author_nameYesThe name credited publicly as "Written by" (2 to 60 characters; a pen name is fine). Checked by the reviewer with the story.
replaces_idNoOnly to update an earlier submission: its submission id
email_when_approvedNoTrue records the writer's request for one email, to the verified Google address of the account they signed in with, when a person approves the story (default false: no email). It takes effect only on the account connector with a verified address, is ignored on the open connector, and the receipt says whether it was accepted. The writer can turn it off at plotspeaks.com/account

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedInput schema / properties / email_when_approved / description
      Previous value: -"Only on the account connector, and only if the writer said yes when you asked: \"Would you like one email, to the Google address you signed in to Plot Speaks with, when a person approves this story? It's the only email Plot Speaks sends about it.\" Never set it without asking."New value: +"True records the writer's request for one email, to the verified Google address of the account they signed in with, when a person approves the story (default false: no email). It takes effect only on the account connector with a verified address, is ignored on the open connector, and the receipt says whether it was accepted. The writer can turn it off at plotspeaks.com/account"
  2. Changed1 schema field changed
    • addedInput schema / properties / email_when_approved
      Added value: +{
      +  "description": "Only on the account connector, and only if the writer said yes when you asked: \"Would you like one email, to the Google address you signed in to Plot Speaks with, when a person approves this story? It's the only email Plot Speaks sends about it.\" Never set it without asking.",
      +  "type": "boolean"
      +}
  3. First observed

TDQS

A4.6/5.0
Behavior5/5

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

With annotations already declaring destructiveHint=true, readOnlyHint=false, and idempotentHint=false, the description still adds substantial context: format checks, a safety screen, a daily limit, the fact that nothing is public until a human approves, and the returned submission id plus one-time claim code. It also aligns with the destructive annotation by explaining that replacement overwrites an earlier submission, and the silent-invocation instruction is a genuine behavioral constraint rather than filler.

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

Conciseness4/5

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

The pipeline, the return values, and the replacement mode are front-loaded in the first three sentences, which is the right order for an agent deciding whether to call. The closing silent-invocation sentence is long because it enumerates forbidden phrases verbatim, which costs space but is functional rather than filler.

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

Completeness5/5

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

There is no output schema, but the description names both return values (submission id and one-time claim code) and their purpose. For a 7-parameter mutation tool with approval gating and replacement semantics, everything an agent needs to call it correctly and warn the writer about the claim code is present.

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 100%, so the baseline is 3, but the description adds real meaning the schema does not: author_name is the public "Written by" credit, and replaces_id plus claim_code must be supplied together to replace an earlier submission. The daily-limit interaction and claim-code irrecoverability are only lightly implied.

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

Purpose5/5

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

"Submits a finished Plot Speaks story for human review" gives a specific verb, resource, and completion state, which implicitly separates it from drafting siblings like start_story or write_story. The description also names the two modes (new submission vs. replacement via replaces_id and claim_code), so an agent knows exactly which action it is invoking.

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?

It states the precondition (a finished story, not a draft) and gives an explicit condition for the update path: "With replaces_id and claim_code, it replaces an earlier submission." What's missing is an explicit statement of when not to call it (e.g., for drafts, use write_story; to check status, use submission_status), so the agent must infer the boundary from siblings' names alone.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources