Skip to main content
Glama
rahimnathwani

showntell

by rahimnathwani
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

Add slides

add_slides

Append Markdown slides to a narrated walkthrough, adding spoken explanations and visuals slide by slide so coding agents can build guided code explanations.

Instructions

Append slides to a walkthrough, written in Markdown.

Calls:

  • Opening: normally sent in start_walkthrough's opening (see its example). Only if it was not sent there, the first call carries it and nothing more: the title slide and one or two short spoken sentences. That call returns when the link is playable, with the full guide; send the link to the user then, before anything else.

  • All other calls: first one short slide alone, then one to three whole slides. Never resend earlier Markdown. Never split a slide or its code block across calls.

  • Replies list problems: fix them in later slides, or replace a broken slide with revise_slide.

Format:

  • Slide: each #, ## or ### heading starts one. Optional attributes: ## Title {#id .build}; .build reveals parts as cues reach them.

  • Narration: plain paragraphs are spoken, each voiced separately. Put identifiers in backticks; [text]{say="spoken"} fixes pronunciation.

  • Shown text: > lines are shown, never spoken; under the first heading, one is the subtitle.

  • Visual: at most one per slide: fenced code, diff, mermaid diagram, math formula, pipe table, list, or image alt.

  • Code from disk, with an empty body and the file's own line numbers in the gutter:

Inline code may set start=10.

  • Diff: python old then python new blocks; diff with -/+ lines, one hunk per slide; or diff file=path rev=A (against the working tree) or rev=A..B.

  • List: - **Title**: text {#id}; without {#id}, the id is the title, lowercased and hyphenated. 1. items are steps; .cards on the heading shows cards.

  • Cues are links in narration. The pointer moves when the label's first word is spoken, within the current slide only. label line 12 | #L12-18 a range | label only that text on line 12 | #-L5 old side, #+L7 new side of a diff | #id a list item, card or Mermaid node | #row-2 the second table row, or a {#id} ending its last cell | # the whole visual; label finds that text in it.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
handleYesHandle from start_walkthrough.
markdownYesSlides in Markdown: one to three whole slides, nothing already sent. Only when the opening was not sent with start_walkthrough: the first call carries just the title slide and one or two spoken sentences.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.8/5.0
Behavior5/5

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

Annotations only declare the generic mutation profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false, openWorldHint=false), but the description adds real behavioral context beyond them: the first call returns when the link becomes playable, replies may list problems, and content is append-only ('Never resend earlier Markdown'). These traits are not derivable from the annotations.

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 description is long but front-loaded and organized under 'Calls:' and 'Format:' headings, and nearly every line is load-bearing specification for the Markdown DSL that the agent cannot infer elsewhere. It is dense rather than padded, though the volume is close to the limit of what belongs inline.

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?

With no output schema, the description compensates by explaining return timing and error behavior, and it covers sequencing across sibling tools, content formats, and cue syntax. An agent has everything needed to invoke the tool correctly on the first try.

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% and both parameters are documented in the schema, so the baseline is 3. The description goes further by spelling out what the `markdown` payload must contain in terms of DSL structure, ordering, and the special-case opening call, which materially improves how the agent constructs the argument.

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?

Opens with a specific verb+resource+format: 'Append slides to a walkthrough, written in Markdown.' The Calls section further distinguishes its role from start_walkthrough (which carries the opening) and revise_slide (which replaces broken slides), so an agent can route between siblings without opening the schema.

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?

Explicitly states when to use this call vs. alternatives: the opening normally belongs in start_walkthrough's `opening`, and only if omitted does the first add_slides call carry it. It also names revise_slide as the remedy for a broken slide and specifies batch sizing (one short slide, then one to three).

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