ppt-generator

Overview Schema Source Related Servers Discussions Admin

prepare_slide_edit

Prepares a single slide addition or update without changing project files, returning the prompt, schema, and edit context required to generate and ingest the slide spec.

Instructions

Prepares to add or update ONE slide without changing project files.

No LLM call. Returns the slide generation prompt, response_schema, and an immutable edit_context. Generate the slide spec JSON, then call ingest_slide_edit with the SAME action, slide_index, and edit_context.

For narrow single-element tweaks, use prepare_modify_component instead.

Args: project_id: Target project ID (required). action: "add" | "update". slide_index: 1-based position. add: insertion point (-1 = end). update: target. title: Slide title (required for add; required for update on imported projects). content_summary: Content description (required for add; required for update on imported). component_hint: Layout hint (default: "bullets"). slide_type: "title" | "content" | "closing" | "agenda" (default: "content"). speaker_notes: Optional speaker notes. color_theme: Color theme ("dark" or "light").

Returns: JSON with prompts, response_schema, action, project_id, edit_context.

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": {
      "project_id": "<project_id>",
      "action": "<action>"
    },
    "name": "prepare_slide_edit"
  }
}

Input Schema

Name	Required	Default
`title`	No
`action`	Yes
`project_id`	Yes
`slide_type`	No	content
`color_theme`	No	dark
`slide_index`	No
`speaker_notes`	No
`component_hint`	No	bullets
`content_summary`	No

Output Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.7.0Jul 10, 2026

TDQS

A4.7/5.0

Behavior4/5

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

With no annotations, the description carries the full burden, and it does most of it: no LLM call, no mutation of project files, and an `edit_context` that is explicitly immutable and must round-trip unchanged into the ingest call. What it omits is failure behavior (what happens if edit_context is stale or the project is locked) and any concurrency/expiry guidance.

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 workflow contract in bold before the parameter list, and every Args line carries information the schema lacks. The trailing Returns block mildly duplicates the existing output schema, which is the only wasted space.

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 9-parameter, zero-schema-coverage, two-step tool, this covers the pairing invariant, all parameter meanings, and the return contract (output schema exists, so return values needn't be re-explained). The only unresolved detail is how an agent identifies an "imported project," which is a minor omission against an otherwise complete definition.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0% with 9 parameters, so the description must do all the work — and it does: it defines the 1-based index, the -1 = append convention, target-vs-insertion semantics per action, the add-only vs imported-project-conditional requirements for title/content_summary, and enumerates values for action, slide_type, and color_theme that the schema leaves as bare strings.

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?

States a specific verb and resource ("prepares to add or update ONE slide") and immediately bounds it with "without changing project files." It distinguishes itself from both `ingest_slide_edit` (the paired step) and `prepare_modify_component` (the narrower alternative), so an agent can route correctly without opening any 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?

Explicit sequencing rule: generate the slide spec JSON, then call `ingest_slide_edit` with the SAME action, slide_index, and edit_context. Plus an explicit exclusion — "For narrow single-element tweaks, use `prepare_modify_component` instead." Both when-to-use and when-not-to-use are stated.

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