Skip to main content
Glama
Sign In
showntell

showntell

by rahimnathwani
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

Start walkthrough

start_walkthrough

Starts a narrated slide walkthrough from a title and opening, returning a playable link immediately so viewers can watch while you add more slides.

Instructions

Create a narrated walkthrough. Pass its opening in opening: the reply then comes once that is voiced, with the handle, the playable link and the full authoring guide. Send the link to the user at once, in a message, before your next tool call; they watch while you add the body with add_slides. Without opening, the reply is short and your first add_slides call must carry the opening instead.

Input Schema

NameRequiredDescriptionDefault
frameNoSlide shape: landscape (default, 1280×720), square (960×960) or portrait (720×1280, for phones).landscape
speedNoSpeech rate from 0.8 to 1.3; 1.0 is normal.
themeNoColour theme: dark (default), light, paper (warm light), night (indigo and pink), ocean (teal and coral), studio (bright, violet) or contrast (high contrast). Pick one that suits the subject. Omit to use the project's showntell.theme.json or the default. Viewers can switch it.
titleYesWalkthrough title, shown on the title slide and in the player. Lead with the subject's keywords; under about 50 characters fits the title slide.
voiceNoEnglish Kokoro voice id. Omit for the default. Voices: af_heart, af_bella, af_nicole, af_aoede, af_kore, af_sarah, af_nova, af_sky, af_alloy, af_jessica, af_river, am_michael, am_fenrir, am_puck, am_echo, am_eric, am_liam, am_onyx, am_adam, bf_emma, bf_isabella, bf_alice, bf_lily, bm_george, bm_fable, bm_lewis, bm_daniel.
openingNoThe opening in Markdown, voiced before this call returns: a `#` title heading, an optional `>` subtitle line, then one or two short spoken sentences as a plain paragraph. Nothing more; the body goes in add_slides. Example: # How the retry loop works > Backoff in the HTTP client A failed request can be sent up to four times. We'll follow one through the client.
descriptionNoOne or two sentences on what the walkthrough covers and for whom, up to 200 characters. Shown in the list and gallery and written into exported files as metadata; never spoken or shown on a slide.
project_dirNoAbsolute path of the project. Code blocks with file= and image paths are read from it and must stay inside it. Defaults to the client's root, then the server's working directory.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changedv0.1.6
    • addedInput schema / properties / description
      Added value: +{
+  "default": "",
+  "description": "One or two sentences on what the walkthrough covers and for whom, up to 200 characters. Shown in the list and gallery and written into exported files as metadata; never spoken or shown on a slide.",
+  "title": "Description",
+  "type": "string"
+}
    • changedInput schema / properties / title / description
      Previous value: -"Walkthrough title, shown on the title slide and in the player."New value: +"Walkthrough title, shown on the title slide and in the player. Lead with the subject's keywords; under about 50 characters fits the title slide."
  2. Changed2 schema fields changedv0.1.5
    • changedInput schema / properties / theme / description
      Previous value: -"Colour theme: dark (default), light, paper (warm light) or contrast (high contrast). Omit to use the project's showntell.theme.json or the default. Viewers can switch it."New value: +"Colour theme: dark (default), light, paper (warm light), night (indigo and pink), ocean (teal and coral), studio (bright, violet) or contrast (high contrast). Pick one that suits the subject. Omit to use the project's showntell.theme.json or the default. Viewers can switch it."
    • changedInput schema / properties / theme / enum
      Previous value: -[
-  "",
-  "dark",
-  "light",
-  "paper",
-  "contrast"
-]New value: +[
+  "",
+  "dark",
+  "light",
+  "paper",
+  "contrast",
+  "night",
+  "ocean",
+  "studio"
+]
  3. Changed1 schema field changedv0.1.4
    • addedInput schema / properties / theme
      Added value: +{
+  "default": "",
+  "description": "Colour theme: dark (default), light, paper (warm light) or contrast (high contrast). Omit to use the project's showntell.theme.json or the default. Viewers can switch it.",
+  "enum": [
+    "",
+    "dark",
+    "light",
+    "paper",
+    "contrast"
+  ],
+  "title": "Theme",
+  "type": "string"
+}
  4. First observedv0.1.0

TDQS

A4.6/5.0
Behavior5/5

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

Annotations already say readOnly=false, destructive=false, idempotent=false, but the description adds behavior annotations cannot express: the call blocks until the opening is voiced, and the reply contains the handle, playable link and authoring guide — and the result differs depending on whether `opening` was supplied. That latency and reply-shape disclosure materially changes how an agent sequences its calls.

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 action and no wasted sentences — every clause conveys a constraint. It is dense, however: the ordering rule, reply contents and the omitted-`opening` fallback are packed into two long sentences that could be split for faster parsing.

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, so the description carries the return-value burden and does: handle, playable link, full authoring guide, plus the shorter reply when `opening` is omitted. Combined with the sequencing rule, an agent has everything needed to call this and know what comes back.

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 coverage is 100%, and the schema already documents every parameter in detail — including frame geometry, theme options, voice ids and the Markdown structure of `opening`. The description's only added parameter meaning is the consequence of supplying vs. omitting `opening`, which is close to what the schema field already says, so baseline 3 applies.

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?

The opening sentence is a specific verb plus resource — 'Create a narrated walkthrough' — and the rest immediately distinguishes it from its sibling by naming add_slides as the way the body is added. An agent knows this is the entry point of a multi-step authoring flow, not the slide editor.

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

Usage Guidelines5/5

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

It states both branches explicitly: pass `opening` here, or omit it and let the first add_slides call carry it. It also gives a hard ordering rule — send the link to the user immediately, before the next tool call — which is exactly the when/when-not guidance an agent needs in a multi-tool flow.

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

Deploy Server

Other Tools