Skip to main content
Glama

Publish a spec

publish_spec

Publishes a spec on Spekkr under the signed-in person's username, as username/name, or publishes a new version of one of theirs. Send the text of spekkr.json and every file it lists. A small text file goes in files with its content. Any other file (an image, a PDF, a video, a long document) goes in files with its size in bytes and no content: the answer then gives an address to upload those files to with HTTP PUT, and once they are uploaded you call publish_spec again with the same arguments. Nothing is listed until a call answers with published. A listed spec names the member who published it. A published version never changes: to update a spec, raise the version, add a changelog entry and list every file again. A file that has not changed goes in files with keep set to true and nothing else, and Spekkr takes it from the version listed now, so a screenshot need not be uploaded again. In this version a published spec is free. If anything has to change first, the answer names every problem. This tool needs sign-in. Ask the person before you call it: publishing makes the files public.

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": {
      "manifest": "<manifest>",
      "files": "<files>"
    },
    "name": "publish_spec"
  }
}

Input Schema

NameRequiredDescriptionDefault
filesYesEvery file the manifest lists, every file inside a folder it lists, and every screenshot under demo.screenshots. Leave out spekkr.json, BUILD.md and spekkr.inputs.json. Each file has a path and one of content, bytes or keep.
manifestYesThe whole text of the spec's spekkr.json. Its id is username/name, with the signed-in person's username, and its author.id is that username.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.6/5.0
Behavior5/5

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

Annotations only say it is a non-idempotent, non-destructive, open-world write; the description adds the material context an agent actually needs: sign-in required, files become public, a listing appears only after a call answers "published", publish is free, and published versions are immutable so updates need a raised version and changelog. It also explains the two-phase conflict-free upload protocol, which no annotation conveys.

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?

Front-loaded with the core action and naming form, then the file-sending rules, then the upload loop, then the warning about asking the person. Nearly every sentence carries operational content, though the manifest/file enumeration is dense and could be tightened slightly.

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?

For a non-trivial two-phase publish with no output schema, the description discloses the shape of every response an agent must react to (an upload address, a "published" confirmation, a list of problems). An agent has enough to complete or correctly abandon the operation.

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 per-field meanings are already carried by the schema. The description still adds the selection rule tying fields together: small text goes as content, anything else as bytes with no content, unchanged files as keep=true and no content. That linkage and the call-again cycle go beyond what the schema states.

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?

Specific verb and resource ("Publishes a spec on Spekkr") plus the exact naming form ("username/name") and the second mode ("publishes a new version of one of theirs"). Named operations like check_spec, get_spec and unpublish_spec are clearly distinct from this publish action without any of them being read.

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?

Gives concrete when-and-how guidance: send the manifest plus every listed file, re-call publish_spec after the PUT uploads, and raise the version to update ("A published version never changes"). Also gives a precondition ("Ask the person before you call it") and a retry rule when the answer names problems. No explicit routing to sibling tools is given, so it stops just short of a 5.

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