This server provides deterministic tools for SCGJ educational content: generating course storyboards, planning and outputting module video scripts with slide decks, and reading Participant Handbook units verbatim, along with source retrieval, timing validation, and DOCX/PPTX rendering.
Course storyboarding: create drafts pre-filled with structure and timing, write content module-by-module, validate traceability and timing, render to DOCX using the track's template.
Module content packages: plan the 3-minute video (18 segments) and 9-minute slide deck (14 slides), set a story bible, submit segments/slides, validate coverage and continuity, export script (.txt), subtitles (.srt), and deck (.pptx/.txt).
Exact handbook reading: resolve a unit heading and return the unit's text verbatim, with no generation or summarization.
Source retrieval and citation: BM25 search scoped by course/document/chapter/module, fetch chunks verbatim, get document pages, and ensure every generated field cites real chunks.
Timing and crosswalk: parse and validate the Timing Allocation Document, get authoritative durations and module-to-chapter/NOS mappings.
Template analysis: inspect storyboard DOCX templates for structure, fields, and formatting; get content specifications.
Guided flow: start a session with a menu, step through choices (programme → subject → module), with shortcuts for topic-based starts and back/restart.
Video transcript generation (legacy/unit-level): plan and submit scene-based transcripts for a single unit, validate word budgets and citations.
Assessment authoring: set the assessment blueprint and question bank with citations, weightage tables, and validation.
Versioning and rollback: all artifacts keep append-only version histories; rollback to earlier versions.
Validation and enforcement: mechanical checks for citations, timing arithmetic, template conformance, unit coverage, continuity, and grounding; refuses invalid outputs unless explicitly allowed.
File exports: write storyboard DOCX, module PPTX, script/subtitle/deck files to disk and return paths for the client to attach.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@CVC Storyboard MCP plan module content for the networking basics module"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A deterministic tool layer for SCGJ educational content: course storyboards as DOCX, 2.5-3 minute AI info video scripts per module, and exact Participant Handbook readings.
This server contains no AI model and no AI API key. It executes operations and returns structured results. All reasoning, orchestration and content generation happen in the connected client.
Antigravity IDE / Gemini CLI / Claude Code
│ reasoning, orchestration, content generation
▼ MCP (stdio)
Storyboard MCP
│
▼
Deterministic tools
source retrieval (BM25) timing parsing + validation
template analysis module crosswalk
storyboard state + versions DOCX clone + insert + export
handbook outline + reading video profile + character lock
scene planning + word budgets script validation + prompt compositionClient (Gemini / Antigravity) | This server | |
Which tools to call | ✔ | |
In what order | ✔ | |
What content to write | ✔ | |
How to fix validation errors | ✔ | |
Scoped source retrieval | ✔ | |
Authoritative durations | ✔ | |
Template fidelity | ✔ | |
Validation findings | ✔ | |
DOCX generation | ✔ | |
Scene budgets, self-containment and presenter consistency | ✔ |
They are kept strictly apart. A session records which flow it is in, and the tools of one flow cannot produce the output of another.
start_flow ← "hi", "start", "can we start", "let's get started"
│
┌───────────────┼───────────────────────────┐
▼ ▼ ▼
1 Storyboard 2 Video Script 3 Handbook Reading
│ │ │
▼ ▼ ▼
programme course subject
Entrepreneur Entrepreneur │
Orientation Orientation ▼
CDR │ module
│ ▼ │
▼ subject ▼
subject │ unit
│ ▼ │
│ module ▼
│ │ reading_complete
│ ▼
│ video type
│ │
│ ▼
│ presenter ×5 in one answer
│ │
│ ▼
│ background
│ │
▼ ▼
storyboard_ready video_script_ready
generation begins generation beginsThe menu is three lines and nothing else: what each option produces is answered by the step that follows it, and explaining them up front made the first thing a user saw a wall of text about choices they had not made yet.
Only the storyboard asks which programme, and it asks first, because the three tracks are genuinely different documents — a different template, different sources, different module routing — and everything after that answer depends on it. The video flow asks its own course question over a different list — two options, not three, because CDR has no Participant Handbook and a video is built from one. The reading flow does not ask at all: a subject carries its own track.
The subject is the storyboard's last question. Nothing is asked about length, modules, format or confirmation, because none of it is open: the course's module count comes from its timing document, the shape from its template, and the loop that fills it runs without the user.
The flow asks only what it cannot work out. There is no "would you like to type or browse" question and no course-type question: a topic typed at any step is resolved to the unit that holds it, and course type is a label on each subject.
The video flow stops at the background question. Everything below it is settled: 150-180 seconds, 15-18 scenes of ten seconds, and which slice of which unit each scene introduces. No duration question is asked because there is nothing to choose — the four hard rules fix it. A scene shorter than ten seconds cannot hold twenty-two words, so every scene is ten; 150-180 seconds of those is 15-18 scenes.
Reading goes one level deeper than the module, to the unit, and returns its verbatim text. No generation step exists on that path.
What a video is. One 150-180 second introduction covering the whole module, as 15-18 scenes, each a separate generation:
Structure | opening → what the topic is (×2) → turn to learning → 9-12 learning-area scenes → consolidation → hand-over |
Scene seconds | every scene exactly 10s. 15 scenes = 150s, 18 = 180s |
Narration | 22-25 words per scene, ~150 wpm, at most 3 sentences |
Breathing | 0.3-0.5s between sentences, 0.5s of silence before the cut |
Self-contained | every sentence begins and ends inside its own scene |
Unit coverage | each learning area gets 2-3 consecutive scenes, each with its own slice of that area's text |
Each scene carries | purpose, location, visual, presenter action, camera framing and movement, teaching visuals, narration, citations |
The server adds | the presenter, attire, voice, pace, pauses and speak-once directives — identically, every scene |
Output | the script inline and a |
The presenter comes from a saved video profile — gender, age, skin tone, demographic appearance, attire, background — asked once and reused, so a learner taking several modules of a course meets the same instructor.
Say restart at any step, finished ones included, to clear the session and go
back to the menu. back changes the previous answer. start_flow opens an
independent session whenever you want one.
Shortcut. A user who names a topic skips the menus: read_ph_unit takes a
heading, and plan_video_script takes a subject and a module directly.
Subjects. Nine across three programmes. Each reports exactly what it is waiting for, and the flow offers only the ones it can serve.
Entrepreneur | Orientation | CDR |
Solar Photovoltaic ✅ | ESG — Environmental, Social and Governance | CDR Biochar |
Bio-Energy (Biofuels) ✅ | GHG — Greenhouse Gas | |
Green Hydrogen ✅ | GL — Green Logistics | |
Agri-Residue Aggregator ✅ | BG — Biogas |
✅ means a storyboard builds today: four approved documents on disk and a reviewed crosswalk. All four Entrepreneur subjects qualify. The Orientation subjects have their documents but no reviewed crosswalk yet; CDR's is blocked on its rewritten master file (see Known gaps).
Adding a subject: drop the PDFs in and pick it from the menu. Put ph.pdf
(and qp.pdf, fg.pdf, timing.pdf for storyboards) into
courses/<track>/<subject>/, and name that path in the course's directory in
src/courses/course-config.ts. A handbook that is
present but not yet indexed shows in the menu as a normal choice and is indexed the
first time it is picked, which takes a few seconds once. Modules and units are
derived from the handbook itself, so nothing about its structure is declared in
code.
The folder need not be named for the course_id — Solar's documents arrive in
courses/entrepreneur/solar while the course is solar-pv — because directory
states the path outright. That is preferred to renaming the folder, because the
folder is the thing that keeps arriving.
Templates are per track. Each track renders to templates/<track>/, and the
template is chosen from the subject rather than passed in, so a course cannot be
built to another track's document. The Entrepreneur and Orientation templates are
not interchangeable: Orientation's carries an Instructional Design and Behavioral
Analytics section that Entrepreneur's does not, and the table of contents is
derived from whichever template is in use rather than assumed.
Module titles come from the handbook's own chapter headings where it prints them.
A handbook that jumps straight to its first unit leaves modules titled Module 3;
the menu then lists each module's unit titles, rather than inventing a title the
handbook never gave. Filling in chapter_titles for that course replaces them.
(A storyboard additionally needs a reviewed crosswalk.)
Related MCP server: marp-agent-mcp
Requires Node 22.13+ (for the built-in node:sqlite). No native compilation,
no API keys.
npm install
cp .env.example .envThen index the course documents once:
npm run ingest -- solar-pvAdd this to your Antigravity MCP configuration:
{
"mcpServers": {
"storyboard": {
"command": "npx",
"args": ["tsx", "src/mcp/server.ts"],
"cwd": "C:\\cvc-mcp"
}
}
}For a compiled server, run npm run build and use
"command": "node", "args": ["dist/src/mcp/server.js"].
The same config works for Gemini CLI and Claude Code — all three speak MCP over stdio.
Courses and documents
Tool | Purpose |
| Registered courses and the status of their four approved documents |
| Course metadata plus the module crosswalk |
| Extract, chunk and index the PDFs (idempotent) |
| BM25 search, scoped by course / document / chapter / NOS |
| Re-read one chunk verbatim by |
| Every chunk on one PDF page, in reading order |
Timing and crosswalk
Tool | Purpose |
| Map timing module → handbook chapter + NOS code |
| Authoritative module and unit durations, with citations |
| Check the timing document's internal arithmetic |
Template
Tool | Purpose |
| Derived table shapes, headers, slide counts, styles |
| Which fields you write, which are read-only, citation rules |
Storyboard
Tool | Purpose |
| Skeleton with structure and timing pre-filled |
| Read state, optionally one module |
| One whole module to write, with its sources attached once |
| Write a whole module; commits one version, returns the next |
| Three-level mechanical validation |
| Populate the template and export |
| Versions and change log |
| Restore a version as a new version |
| Refuses changes that conflict with the timing document |
Guided flow
Tool | Purpose |
| The two-option menu; returns a |
| Answer the current step; also |
| Re-render the current step (resume after a restart) |
Handbook navigation
Tool | Purpose |
| Course types, subjects, and what each unavailable one needs |
| The handbook's own modules and units, derived from the document |
| Resolve a unit heading the user typed, across subjects |
| A unit's text split into citable blocks, for writing |
Video script (two calls from plan to finished script)
Tool | Purpose |
| The saved presenter and background, or the six questions to ask |
| The scenes, their seconds and word bands, what each must achieve, the handbook text behind them, the locked presenter, and the writing rules — all in one call |
| All the scenes at once: validates, composes each scene's generation prompt, commits a version, writes the file |
| Read state and versions |
Exact reading
Tool | Purpose |
| The unit's own text, verbatim. Takes no generation parameters |
Storyboard — three answers from the user, then a loop the client runs alone:
start_flow → flow_choose ×3 (menu → programme → subject; stops there)
→ create_storyboard_draft → artifact_id
→ storyboard_next_module → WRITE_THIS + one module, sources attached once
→ loop: storyboard_submit_module → commits one version, returns the next module
until READY_TO_RENDER (one call per module: 6–10 for a course)
→ validate_storyboard → render_storyboard_docx → give the user the .docxThe older hand-driven path still works and is what the task loop runs underneath:
list_courses → ingest_course_documents → get_course_manifest
→ get_timing_allocation → analyze_storyboard_template
→ get_storyboard_field_spec → create_storyboard_draft
→ per module: search_course_content → storyboard_submit_module
→ validate_storyboard → render_storyboard_docxVideo script — five answers from the user, then two calls:
start_flow → flow_choose ×5 (menu → course → subject → module → type,
then the presenter and background questions)
→ plan_video_script scenes, budgets, handbook text, presenter, rules
→ submit_video_script validates, composes the prompts, writes the fileExact reading:
find_ph_unit → read_ph_unit returned unchanged; nothing else runsA storyboard is written by a model over many calls, so what governs how long it takes and what it costs is how many times the client is asked, not how fast the server answers. Every MCP round trip re-sends the tool list and the whole conversation so far and buys back one answer, so the number of calls multiplies everything.
The build loop was originally one call per row, which for a six-module course was 130 calls. Measured on Green Hydrogen:
per row (before) | per module (now) | |
Round trips for a 6-module course | 132 | 10 |
Tool-result payload | ~300K tokens | ~110K |
Client arguments | ~29K tokens | ~16K |
Source text sent | ~178K tokens | ~70K |
Chunk sends / distinct chunks | 774 / 228 (3.4× each, worst 24×) | 293 / 293 (1.00×) |
Versions written | 130, each rewriting the whole state | 7 |
Conversation history re-sent | 130 times, growing | 10 times |
Three things were being paid for repeatedly:
The asking. Per-row batching bought a few fields per call. A module is the natural batch — it is what the template repeats, what the crosswalk scopes, and what one writer can hold in mind at once — so the loop now hands out a whole module and takes it back in one call.
The same source text, again and again. Sources were retrieved per row, so a chunk was re-sent for every row whose wording happened to match it. A module's material is now retrieved once, deduplicated, and sent once.
Re-describing the tools. 54 tool schemas went out with every one of those 130 calls. The surface is now 44 tools, and the loop that uses them is 10 calls rather than 130.
Server-side work is not the bottleneck and never was — a complete course builds in 1.3–1.7s of server time — but two things there were genuinely wrong and are fixed:
Retrieval was scoped after the fact. The scope was a WHERE clause, so SQLite
matched a query's terms against every chunk of every course, ranked all of them
with bm25(), and only then discarded the out-of-scope 99% — and because a query
is an OR of its terms, it matched 2494 of 2530 chunks. Cost grew with the whole
corpus, so indexing a second course slowed retrieval for the first. The scope is
now carried as indexed tokens inside the FTS index and ANDed into the MATCH, so
postings lists intersect: 12.4 ms → 1.8 ms, and independent of how many other
courses exist.
A module could not see the end of its own chapter. Scope listings were capped at the search limit of 50, and handbook and guide chunks interleaved, so a module whose chapter ran to 145 chunks got the first fifty of a mixed set — the material its last units are written from was simply absent. Sources are now budgeted per unit: every Part A row is a unit and gets its own slice, so coverage is guaranteed per row and the total scales with how many units a module has rather than with how long its chapter happens to be. A test asserts every row has source material about its own unit.
Tuning, if a course needs it: MODULE_CHUNKS_PER_UNIT (default 6) and
MODULE_CONTEXT_CHUNKS (default 10) set how much source a module carries.
These are structural, not advisory — the client cannot route around them.
Course isolation. Every retrieval query carries a mandatory course_id
predicate. There is no code path that returns a chunk from another course, and an
unregistered course_id throws rather than falling back.
The scope is carried inside the full-text index rather than applied to its
output. Each chunk is indexed with opaque tokens naming its course, document,
chapter, unit and NOS (see
src/documents/scope-tokens.ts), and a query
ANDs the ones it needs into the MATCH expression. As a WHERE clause the scope
could only be applied after the fact: SQLite ranked every chunk of every course —
a typical query, being an OR of its terms, matched 98% of the corpus — joined each
one, and then discarded almost all of them. Cost therefore grew with the size of
the whole corpus, so indexing a second course slowed retrieval for the first.
Intersecting postings lists instead made a scoped query roughly seven times
faster, and made it independent of how many other courses are indexed.
Timing is read-only. Durations are parsed from the Timing Allocation Document
and carry a page citation. The build loop cannot write a duration.
modify_storyboard_timing refuses any value that disagrees with the document and
explains the conflict.
Parts B and C are spent out of the module's own time. They are fixed at 15 minutes each, so Part A is the module total less half an hour — a three-hour module gives Part A 2.5 hours. That is the template's own arithmetic: every Part A heading in it reads "(2.5 hours)" under the three-hour modules it states. Handing Part A the whole module made its heading disagree with the template and made the three parts sum to half an hour more than the module lasts.
The two tables agree about an activity by construction. An LMS Technical Mapping row's Unit and Activity Type are copied from that unit's Part A row rather than written again, because both tables describe the same activity. They are read from the state as just written, not from the work order — the work order is computed before the call, when Part A is still blank, so taking them from it left the Activity Type column empty in every module.
The table of contents is rebuilt as a field, from the document produced. The
template's contents is a live TOC field: each entry is a hyperlink to a _Toc…
bookmark, a right-aligned tab with a dot leader, and a PAGEREF. Rewriting those
entries as plain text destroyed all three -- the output carried zero TOC fields, so
w:updateFields had nothing to refresh, no page number or leader could ever appear,
and the bare run left behind still carried the Hyperlink character style, so it
rendered as blue underlined text. The renderer now discards the template's entries
and emits one per Heading1 and Heading2 in the finished body, bookmarking each
heading as it goes. Levels come from the heading styles, so a course with a
different module count, and the glossary, are carried without a second list to keep
in step.
The field is written \o "1-2", matching what the template's contents actually
shows. Its own field instruction says "1-3", which disagrees with its cached
entries -- there are ten Heading3 question-group headings and none is listed -- so
refreshing under "1-3" would add eleven lines the reference document does not
have.
The cover keeps its page break. It ends with one, in the same paragraph as the
strapline, and that is what puts the contents on page two. Replacing a paragraph's
text discarded every run in it, the page break included, so the contents rode up
onto the cover. setParagraphText now carries page-break runs across the rewrite.
The template formats within a paragraph, and so does the output. A question stem
is a bold green "1. " followed by a bold stem; an explanation is a bold-italic
"Explanation: " followed by italic text; a Part A cell is a bold activity name
followed by a plain description; a script cell is a bold speaker followed by plain
dialogue. Each is one paragraph holding two differently-formatted runs.
setParagraphText keeps only the first run's properties, so every one of those came
out uniformly bold -- the label's formatting spread across the whole line.
setParagraphParts maps part N onto run N instead, and inside table cells the
split is read off the prototype: a cell whose first run is bold and whose later runs
are not is a label-and-body cell, and its text is divided at the first ": ". The
decision stays in the template rather than being repeated per column.
Every storyboard closes with a glossary. Terms and abbreviations are gathered a module at a time, from the sources that use them, so each carries that module's citations; the renderer merges them into one alphabetical Glossary of Terms and Abbreviations, deduplicated by term, and lists it in the contents. It renders as an Abbreviation / Full Form / Definition table built from the template's own three-column table, so its header fill, borders, padding, fonts and column widths are the template's. It is the only thing in the output that the template does not already contain -- a formatting diff of a generated storyboard against the template reports the glossary table and nothing else.
One folder per subject, holding one document. A render writes
artifacts/<course_id>/<course_id>-storyboard.docx and removes any earlier render
beside it. Version history stays in the database, which is where it is queryable;
what is on disk is the deliverable, and there is exactly one of it. Naming the
folder for the artifact and the file for the version meant every draft made a new
directory and every render added a file.
The module crosswalk. The source documents disagree about module numbering. The client-authored timing document renumbers the SCGJ chapters:
Timing module | PH / FG chapter | NOS |
1 Entrepreneurship & Biomass Basics (3h) | 1 | SGJ/N4102 |
2 Financial Budget & Business Plans (6h) | 2 | SGJ/N4103 |
3 Sales, Supply & Marketing (3h) | 3 | SGJ/N4103 |
4 Compliance (3h) | 4 | SGJ/N4104 |
5 Pellet Manufacturing, Elective 1 (3h) | 7 | SGJ/N4105 |
6 Small Biogas Plant, Elective 2 (6h) | 8 | SGJ/N4106 |
7 HSE (3h) | 5 | SGJ/N4050 |
8 Employability Skills (3h) | — none — | DGT/VSQ/N0102 |
Pass module_number to search_course_content and the crosswalk is applied for
you. Getting this wrong yields content about the wrong subject under a
correct-looking citation, so validate_storyboard also rejects any citation whose
chunk belongs to the wrong chapter.
Template fidelity. The DOCX is never built from scratch. styles.xml (345 KB),
theme1.xml, numbering.xml, header1.xml, footer1.xml and sectPr are carried
over as untouched package parts, and every paragraph, row and table in the output
is a clone of a real element from the template with only its <w:t> text replaced.
Formatting is preserved by construction; a test asserts those parts are
byte-identical.
Traceability. Every generated educational field must cite a chunk_id.
Validation confirms each citation resolves to a real chunk, in the right course and
chapter, and measures lexical overlap between the field and the text it cites.
Insufficient source. Where the approved documents cannot support content, the
result is INSUFFICIENT_SOURCE_CONTENT, never invented material.
The outline is the handbook's own contents. Modules and units are read from the indexed handbook, and unit titles are taken from its table of contents, which is the one place every title is printed complete. Every module the handbook declares is listed — including one that has no units, like Biofuels module 6 (Employability Skills), which the handbook defers to an external DGT workbook. It is shown with its reason and cannot be selected. A test asserts the outline matches the contents page unit for unit.
A video's shape is arithmetic with one answer. Four rules are fixed — 150-180 seconds, no scene over 10 seconds, 22-25 words a scene, no sentence crossing a scene boundary — and a scene shorter than ten seconds cannot hold twenty-two words. So every scene is exactly ten seconds and the video is 15-18 of them. Six are the frame and the other 9-12 go to the units, two or three apiece, which is what makes it a complete module introduction rather than a teaser. A scene outside its word band is a validation error: over the band the generator cuts the last words off mid-sentence, which is not recoverable after rendering.
Every scene finishes what it starts. Each scene is a separate generation and may be
watched with a beat between clips, so a sentence spanning two of them does not merely
read awkwardly — it breaks. Validation rejects narration that ends without terminal
punctuation, ends on a word that promises a continuation (and, so, which, to,
…), or contains a fragment. At most three sentences a scene, because the breath between
them and the half-second before the cut need somewhere to fit.
The pace follows from the word count, not the other way round. Twenty-two to twenty-five words inside ten seconds, with a breath between sentences and a beat of silence at the end, is about 150 wpm — not the 120-130 an earlier brief asked for. The word count and the scene length are the mandatory rules, so the pace is derived from them and stated in every prompt. Asking a generator for 130 wpm and 25 words in one clip simply produces a clip whose last words are cut off.
The presenter is the same person by construction, not by discipline. Each scene is a separate generation and the generator remembers nothing between calls, so a presenter described afresh per scene comes back as a different face, in different clothes, with a different voice. The description is therefore written once from the saved profile and the identical text is stamped into every scene prompt by the server — along with the voice, the delivery pace, the 0.5-1 second speech lead-in and the speak-this-line-once audio directive. The client is told not to write any of them, and validation reports those checks as guaranteed rather than sampled, because they cannot fail.
On-screen text is spelled out, enumerated and fenced. Misspelled burned-in text
is the commonest way a finished clip comes back unusable — the shot looks right, the
audio is right, and a learner sees CALORIFC VALUE in a training video. Every scene
prompt therefore carries an ACCURACY block that names the exact strings permitted
(the caption, character for character; the teaching visual's labels), forbids all other
text including invented background lettering on walls, packaging and equipment, pins
every number and unit to the value given, and — the escape hatch that matters — tells
the generator that if text cannot be rendered cleanly it should render none, because
missing text is recoverable and misspelled text is not. It appears on every scene,
including scenes with no text at all, since those are exactly where invented signage
slips through. The block adapts to the scene: a scene with a labelled diagram is never
told "no text may appear", because a prompt that contradicts itself is resolved by the
generator however it likes.
The prompt forecloses the errors rather than hoping. Each composed prompt is
labelled blocks and a numbered eight-point audio contract, not prose: the spoken line
quoted in full and marked as the entire audio, the pauses given in seconds, and an
explicit DO NOT list (no second person, no music, no captions, no slow motion, no
cutting away, no restyling the presenter). A generator does not infer — it fills gaps
with whatever is statistically nearby, and every gap is a defect waiting to be rendered.
The topic is the hero. This is an LMS introduction, not a short film. The spec that ships with the plan rules out backstory, character development, drama, conversation and cinematic set pieces, and the composed prompt says so to the generator too. The presenter holds, points at and demonstrates things; that is the whole of their role.
A video script never mentions its source. No handbook, page, figure, table, unit
number, module number, QR code or qualification code may appear in narration, on-screen
text, the visual description, the location or the presenter's action — the viewer has
none of those in front of them. It is an error, not a warning, and citations stay in
each scene's sources.
Every teaching scene is grounded in its own allocation. A roadmap scene must cite chunk_ids, they must resolve in that subject's handbook, and they must belong to the units allocated to that scene — a citation borrowed from another part of the module is an error. The framing scenes cite nothing, because they speak about the module rather than from a passage of it.
A duplicated word is caught before it is spoken. "the the" in a narration line is what a stuttering generation sounds like, and written into the script it is guaranteed rather than likely, so it is an error.
One script per module, not one per request. The store is keyed on course, module and video type, so answering the flow twice for the same module continues the script that exists. The previous feature keyed on nothing and left a hundred empty rows behind.
The reading mode cannot generate. read_ph_unit takes a subject and a unit and
nothing else — no length, no style, no audience. There is no parameter through which
a summary could be requested, and the result carries a fidelity_note stating the
only two mechanical differences from the printed page (removed running headers and
folio numbers, removed indexing overlap).
Unit resolution refuses to guess. When a typed heading matches two units closely,
find_ph_unit reports confident: false and the flow asks which was meant rather
than picking one — reading out the wrong unit answers a question nobody asked.
Generation is two calls, deliberately. Every MCP round trip re-sends the tool list and the whole conversation and buys back one answer, so a feature that fetches a spec, then the source, then submits, then validates, then renders, then exports costs six times what a 90-second video needs. Everything the writer needs travels with the plan, and everything the server does with the result happens inside the submit.
Module 8 (Employability Skills, 3 of 30 hours) has no source content. Neither the Participant Handbook (p.292) nor the Faculty Guide (p.106) contains it — both defer to an external DGT workbook, and a keyword sweep of the 311-page handbook for the DGT/VSQ/N0102 topics returns nothing. The module renders as a flagged stub. Supply the DGT/VSQ/N0102 Employability Skills workbook as a fifth approved document and it will generate like any other module.
Validation grounding is lexical, not semantic. Without a model, the server can
confirm a citation resolves, is correctly scoped, and shares wording with the field
citing it. It cannot judge whether a sentence is a fair paraphrase — that
assessment belongs to the client, and low_grounding_overlap is reported as a
warning rather than an error to reflect that.
Page numbers need Word, and are resolved at generation time. The contents is a
real TOC field with a PAGEREF per entry, and both are computed from where text
falls on the page -- a layout pass this server cannot do. So the renderer emits the
fields with an empty cached result and then hands the finished file to Word once,
via COM, to update them and save. The numbers are in the file from that point, so a
viewer that shows cached field results rather than resolving them displays them too.
That step is the one place the pipeline reaches outside itself, and it is
deliberately last and soft: the byte-faithful document is already on disk before it
runs, and a machine without Word gets a warning and a document whose page numbers
fill in the first time it is opened in Word. Set REFRESH_FIELDS=false to skip it.
Word rewrites the package when it saves, so the byte-identity check against the
template applies to what the renderer wrote, before this runs -- which is what the
suite asserts, with the refresh switched off.
Orientation has documents but no crosswalk. All four Orientation subjects have
their PDFs on disk, so the reading flow serves them today. A storyboard
additionally needs a reviewed crosswalk and chapter-title map in
src/courses/course-config.ts, which is left empty
for them rather than guessed at: an inferred crosswalk produces a storyboard about
the wrong chapter under citations that look valid. The storyboard menu lists them
and says so.
CDR's master file has been rewritten. courses/cdr-biochar/master.docx now
declares five modules rather than seven, states each duration on the line after the
module heading rather than on it, and names its reference documents by their
on-disk filenames. src/cdr/master-file.ts still expects the previous shape and
finds no module headings at all, so the CDR track cannot build and its generation
tests are skipped with that reason. Nothing else depends on it.
npm run typecheck
npm test # 155 tests
npm run flow # walk the guided flow by hand in the terminal
npm run flow -- "<heading>" # the shortcut flow, from a unit heading
npm run parse-timing -- biofuels
npm run analyze-template
npx tsx scripts/render-skeleton.ts biofuelsnpm test covers timing parsing and arithmetic, chapter attribution, FTS query
escaping, run-preserving paragraph replacement, course isolation, crosswalk
scoping, citation validation, question-bank numbering and rejection rules, version
conflicts, rollback, and byte-identical preservation of the template's formatting
parts. The handbook suite covers overlap-free unit reassembly, heading resolution
and its refusal to guess, and the guided flow's step machine. The video suite covers
the scene arithmetic (every scene ten seconds, seconds summing exactly, contiguous
timecodes, the fixed 22-25 word band, every unit given two or three consecutive
scenes with a distinct slice each), each validation rule against a script written to
break it — including narration left open, ending on a dangling word, holding a
fragment, or holding more sentences than the breaths fit — the identity of the
presenter block across every composed prompt, and the flow's five questions
including the five-in-one presenter answer.
src/
mcp/server.ts stdio MCP server
mcp/tools/index.ts the registry: assembles the lists below and dispatches
mcp/tools/flow.ts start_flow, flow_choose, get_flow -- the entry point
mcp/tools/storyboard.ts feature 1, the storyboard's course, timing and render tools
mcp/tools/storyboard-build.ts feature 1's build loop: one module out, one back
mcp/tools/video-script.ts feature 2, the 2.5-3 minute info video: plan and submit
mcp/tools/reading.ts feature 3, read_ph_unit
mcp/tools/catalog.ts handbook navigation
catalog/ course types, subjects, and their readiness
courses/ course registry, crosswalk, chapter titles
documents/ PDF extraction, chunking, ingestion, BM25 retrieval
documents/ph-outline handbook structure, verbatim reading, heading resolution
flow/ the guided step machine, persisted per session
timing/ timing parser and arithmetic validator
docx/ OOXML helpers, template analyzer, renderer
storyboard/ skeleton builder, module work order, three-level validator
videoscript/ profile and character lock, scene planning, prompt
composition, validation, rendering, store
reading/ plain-text rendering of a handbook unit
storage/ SQLite schema, artifact and version store
courses/<track>/<subject>/ qp.pdf ph.pdf fg.pdf timing.pdf
templates/<track>/ that track's storyboard template
scripts/timing/ author a Timing Allocation Document for a new course
scripts/cdr/ regenerate the CDR course definitions from a master file
artifacts/<course_id>/ the finished storyboard, one document per subject
artifacts/video-scripts/<script_id>/ the finished video script, one file per versionInspects the storyboard DOCX template and returns its derived structure: per-module table shapes, exact column headers, slide counts, paragraph styles and the assessment section. Read this before generating content so the content you produce matches the shapes the template requires. Formatting is preserved automatically by the renderer; you never need to specify fonts, colours or layout.
| Name | Required | Description | Default |
|---|---|---|---|
| template_version | No | Defaults to "v1". |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the transparency burden. It discloses that the tool 'inspects' (implying read-only) and returns a specific derived structure. It also adds useful behavioral context about the renderer preserving formatting, telling the agent not to worry about fonts/colours/layout. However, it does not mention potential edge cases, errors, or any non-obvious behaviors.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, each carrying essential information: the action and output, the when-to-use, and a practical reassurance about formatting. No redundant words or filler; it is front-loaded with the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (one optional parameter, no output schema), and the description fully compensates by listing exactly what the returned structure includes (table shapes, column headers, slide counts, paragraph styles, assessment section). It also explains the tool's role in the generation pipeline, making it contextually complete for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already documents the only parameter (template_version, defaults to 'v1') with 100% coverage. The description adds no further meaning or usage nuance for this parameter, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Inspects' and identifies the resource as the 'storyboard DOCX template', then details the derived structure (per-module table shapes, exact column headers, slide counts, paragraph styles, assessment section). This clearly distinguishes it from sibling tools like render_storyboard_docx or set_storyboard_content by positioning it as a structural analysis tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit timing guidance: 'Read this before generating content so the content you produce matches the shapes the template requires.' It does not name alternative tools or list when-not-to-use cases, but gives a clear context and a prerequisite role in the content generation flow.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Creates a new storyboard artifact as version 1, pre-populated with everything derivable from the approved documents: modules, unit codes and titles, authoritative durations with provenance, correlation NOS codes, and empty rows/slides of the correct shape. Content fields are left blank for you to fill via set_storyboard_content. Modules the sources cannot support are marked INSUFFICIENT_SOURCE_CONTENT rather than invented.
| Name | Required | Description | Default |
|---|---|---|---|
| note | No | ||
| modules | No | Restrict to these module numbers. Defaults to all. | |
| course_id | Yes | ||
| timing_strategy | No | How Part A durations derive from the timing document. Defaults to part_a_verbatim, which copies stated unit minutes unchanged. | |
| template_version | No | Defaults to "v1". |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does well: it discloses behavior (creates version 1, prepopulates derivable data, blanks content, marks unsupported modules as INSUFFICIENT_SOURCE_CONTENT) and explicitly avoids fabrication. It could be clearer on side effects like overwriting existing drafts or expected return, but it is quite transparent for a create operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise, well-structured sentences convey purpose, scope, and behavior without fluff. Front-loaded with the main action and efficiently explains what is prefilled, what is left blank, and how unsupported modules are handled.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex creation tool with no annotations or output schema, the description covers the essential workflow: what is created, what is left for later, and the marking convention. It could mention implications for existing storyboards or completion/return values, but it gives sufficient context for an agent to invoke it correctly in a multi-step process.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description does not directly elaborate on individual parameters; it stays at a high level. Since schema coverage is 60%, some parameters have descriptions in the schema, but the description itself adds minimal parameter-level nuance beyond the schema. The behavior around modules and timing is implied but not mapped to parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates a new storyboard artifact as version 1 and enumerates exactly what is prepopulated (modules, unit codes, durations, NOS codes, empty rows/slides). It uses a specific verb-resource combination and distinguishes itself from sibling tools like set_storyboard_content by explaining what it does not do (fill content).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on when to use this tool (before content population) and explicitly references set_storyboard_content as the follow-up, giving a workflow hint. However, it does not explicitly state when not to use this tool or mention alternatives beyond the one sibling.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Writes every deliverable for a finished package and returns their paths: the video script as .txt, the subtitle track as .srt, the deck as .pptx and as .txt. Call this whenever a module has been generated, and ATTACH THE RETURNED FILES so the user can download them from the conversation rather than copying a long script out of it. Refuses by default if validation has errors; pass allow_invalid to export a draft anyway.
| Name | Required | Description | Default |
|---|---|---|---|
| version | No | ||
| package_id | Yes | ||
| allow_invalid | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and does well by disclosing that the tool writes files, returns paths, and refuses by default if validation errors exist. It also explains the allow_invalid escape hatch for draft exports, which is important behavioral context an agent needs before invoking.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences and every sentence earns its place: one lists deliverables and return value, one gives direct usage guidance with a practical rationale, and one explains error behavior and the fallback parameter. It is front-loaded with the most decision-critical information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no annotations, the description provides enough context for the core export behavior, expected file types, and validation gate. It could be more complete by clarifying version semantics, but the overall description is sufficient for a straightforward export invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, so the description must compensate. It meaningfully explains allow_invalid ('pass allow_invalid to export a draft anyway') and package_id is implied by context, but it does not explain the optional version parameter or its role in selecting which package version to export.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action: 'Writes every deliverable for a finished package and returns their paths,' enumerating exactly which files are produced (.txt, .srt, .pptx, .txt). It distinguishes this from sibling tools like get_module_package or validate_module_package by describing a side-effecting export action rather than a read-only fetch or validation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use guidance: 'Call this whenever a module has been generated,' and even explains why the returned files should be attached so users can download instead of copying a long script. It does not name alternative tools, but the context is clear enough for an agent to decide when this export action is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Resolves a unit heading the user typed to the unit, the module and the subject that holds it, searching every indexed Participant Handbook. This is the entry point for both shortcut flows: "make a video script for " and "what does actually say". Ranking is deterministic term matching. When confident is false the top candidates are close -- ask the user which they meant rather than picking one.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| track | No | Restrict to one course type. | |
| heading | Yes | The unit heading or topic the user named, in their words. | |
| subject | No | Restrict to one subject, when the user named one. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden, and it does meaningful work: it reveals that the search covers every indexed Participant Handbook, that ranking is deterministic, and that a low-confidence result should trigger user disambiguation. It does not detail auth requirements or response edge cases, but the important decision behavior is accurately disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three dense sentences, each earns its place: the first defines the tool's core resolution behavior, the second places it within concrete user flows, and the third explains ranking and disambiguation. There is no filler, repetition of the schema, or boilerplate.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that there is no output schema and no annotations, the description provides enough context about what the tool returns conceptually (unit, module, subject) and about the important confidence behavior. It could be slightly more explicit about candidate count, limit behavior, or response shape, but it is complete enough for an agent to select and invoke the tool sensibly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already describes heading, track, and subject, so schema coverage is 75%. The description adds useful framing for heading ('in their words') and clarifies the global search scope, but it does not add meaning for the 'limit' parameter, which is the least documented parameter. Overall the extra description is helpful but not extensive.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Resolves') and clearly states the resource: a user-supplied unit heading is mapped to the unit, module, and subject across all indexed Participant Handbooks. It also positions this tool as the entry point for two named shortcut flows, which distinguishes it from sibling lookups like read_ph_unit and get_ph_unit_source.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear usage context by identifying the shortcut flows that should enter through this tool. It also tells the agent what to do when confidence is low: ask the user rather than selecting a candidate. However, it does not explicitly name alternatives or state when to choose search_course_content or get_module_units instead.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Applies the user's answer to the step a session is on and returns the next step, with its prompt and options. Pass what the user actually said. Each step accepts its option values, and the menu also accepts 1, 2 or 3. An answer that matches no option is tried as a topic name before it is rejected, so a user who types "quality control of biomass pellets" at the subject or module step is taken straight to the unit that holds it. An answer that matches neither re-asks the same step with an explanation rather than guessing. Two answers work everywhere, finished steps included: "back" changes the previous answer, and "restart" clears the session and returns to the menu. Follow the step's next_action exactly; when a step reports done, everything it needed has been asked, so generate without further questions.
| Name | Required | Description | Default |
|---|---|---|---|
| choice | Yes | What the user said: an option value ("module_content", "biofuels", "7", "7.1"), the menu number 1-3, a topic name, or "back" / "restart". | |
| session_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully carries the burden of behavioral disclosure. It richly describes edge-case handling: topic-name fallback, re-asking on mismatch, behavior of 'back' and 'restart', and the instruction to generate without further questions when done. This exceeds typical descriptions and provides substantial behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but each sentence adds essential information: main purpose, parameter guidance, fallback behavior, global commands, and next_action handling. It is front-loaded with the primary function, then explains special cases. It could be slightly more concise, but given the tool's complexity, the length is justified.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description explains what the tool returns ('the next step, with its prompt and options'), covers all special command behavior, and instructs on handling 'done' states. It lacks detail on session_id semantics, which is a missing piece. However, for a tool with no output schema, it provides thorough guidance overall.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers 50% of parameters: 'choice' has a detailed description including accepted values, but 'session_id' has none. The description adds some meaning to 'choice' by explaining how answers are processed, but it does not illuminate 'session_id' at all. Since schema coverage is moderate, the description partially compensates but leaves a gap for session_id.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action: 'Applies the user's answer to the step a session is on and returns the next step.' This specific verb+resource combination distinguishes it from siblings like start_flow (initiates) and get_flow (retrieves), making its purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use the tool ('Pass what the user actually said' and 'Follow the step's next_action exactly') and provides context for special commands like 'back' and 'restart'. It does not explicitly mention alternatives or when not to use it, but given the sibling set, the usage context is clear enough for an agent to infer appropriate invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Full manifest for one course: metadata, approved document status, and the module crosswalk. The crosswalk is essential -- it maps each Timing-Allocation module number to the Participant Handbook / Faculty Guide chapter and the NOS code that hold its content. These numbers disagree (timing module 5 is handbook chapter 7), so always scope retrieval using the crosswalk rather than the module number.
| Name | Required | Description | Default |
|---|---|---|---|
| course_id | Yes | Course identifier, e.g. "biofuels". |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Since no annotations are provided, the description must convey behavior. It clearly warns about the discrepancy between timing module numbers and handbook chapters, and instructs to use the crosswalk for retrieval. This adds meaningful behavioral guidance beyond the tool's name and parameters.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief yet packed with relevant information. It front-loads the main content and then provides a crucial caveat about the crosswalk in two sentences. No unnecessary fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the single parameter and no output schema, the description adequately covers what the tool returns and highlights a critical usage detail (the crosswalk). It doesn't describe return format, but that's not required without an output schema. The description is sufficient for an agent to know when and how to use it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter course_id is well-described in the schema ('Course identifier, e.g. "biofuels"'), so the description adds little beyond that. The description does imply that the manifest is for a single course, but it doesn't elaborate on the parameter syntax or format. With 100% schema coverage, a score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it returns a full course manifest with metadata, approved document status, and the module crosswalk. It uses specific nouns and distinguishes itself as a comprehensive overview tool, especially by highlighting the crosswalk component.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides concrete usage advice: 'always scope retrieval using the crosswalk rather than the module number' and explains the mismatch between module numbers and chapters. However, it does not explicitly contrast with sibling tools like get_module_crosswalk, though the emphasis on full manifest implies when to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns every chunk on one PDF page of one approved document, in reading order. Use it to widen context around a search hit, or to read a page a citation points at.
| Name | Required | Description | Default |
|---|---|---|---|
| pdf_page | Yes | 1-based index within the PDF file, not the printed page number. | |
| course_id | Yes | ||
| document_type | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses constraints like 'approved document' and 'in reading order', which imply read-only behavior. However, it does not mention error cases or limitations (e.g., what happens if the page is out of range), leaving some gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences, front-loaded with the core action and then the usage context. Every word adds value with no redundant detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a moderately simple read tool with no output schema, the description covers the purpose, usage, and key constraints. It could be slightly more detailed about the chunk format or error behavior, but it is sufficiently complete for typical use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 33% (only pdf_page has a description). The description does not add any information about course_id or document_type, which are required parameters. Given the low coverage, the description should compensate but fails to explain these parameters or their roles.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'returns' and names the exact resource ('every chunk on one PDF page of one approved document') and scope ('in reading order'). This clearly distinguishes it from sibling tools like get_source_chunk, which likely returns a single chunk, and search_course_content, which searches.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states two concrete use cases: 'to widen context around a search hit' and 'to read a page a citation points at'. This provides clear guidance on when to use the tool, though alternatives are not named explicitly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Re-renders the step a session is on, with its prompt, options and selections so far. Use it to resume after a gap. It advances nothing.
| Name | Required | Description | Default |
|---|---|---|---|
| session_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. The phrase 'It advances nothing' clearly discloses that the tool is read-only and non-mutating, which is exactly the side-effect information an agent needs. It could have added more on state or errors, but this is solid.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, each earning its place: purpose first, then usage trigger, then a key side-effect note. Perfectly front-loaded with no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter tool with no output schema, the description covers purpose, output content, when to use, and non-mutation—more than sufficient. Slightly more detail on the parameter or return format could push it to a 5.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, and the description never mentions session_id, its purpose, or where to obtain it. The description was expected to compensate for the lack of schema documentation but does not, even though the parameter is simple and self-explanatory.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('re-renders') and resource ('step a session is on') and details the content (prompt, options, selections), clearly distinguishing it from siblings like start_flow and flow_choose. It leaves no ambiguity about its function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states 'Use it to resume after a gap,' giving a clear trigger for when to invoke. It doesn't name alternatives or exclusions, but the context is actionable enough for the agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
What to write into each video segment and each slide, what is fixed by the plan, and the standard the output is held to. Read this before submit_module_video or submit_module_slides.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, description carries full burden. It conceptually describes the tool as a read-only resource ("Read this before...") and explains what information it returns (content specs, fixed by plan, standards). However, it does not explicitly state safety, auth, or limitation details naturally expected without annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the core purpose, and ends with actionable guidance ('Read this before...'). No fluff, every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no parameters and no output schema, the description adequately covers what the spec contains and when to read it. It doesn't enumerate specific fields, but that's likely acceptable for a spec retrieval tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters)Skip, and the schema has no fields. The description doesn't need to explain parameters, but the baseline for 0 params is 4. It does not add parameter info because there is none.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: it specifies what to write into video segments and slides, what is fixed, and the standard. It distinguishes from siblings like submit_module_video (which actually submits) and get_module_video_script (which retrieves script) by focusing on field specifications.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs to read before submit_module_video and submit_module_slides, providing clear context for when to use. However, it does not mention alternative tools or when NOT to use it, so it lacks a full when/not-when comparison but is still strong.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Resolves Timing-Allocation module numbers to the PH/FG chapter and NOS code that hold their source content, and flags modules the approved documents cannot support. Omit module_number for the whole table.
| Name | Required | Description | Default |
|---|---|---|---|
| course_id | Yes | ||
| module_number | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It explains the core resolution behavior and the flagging of unsupported modules, which is a valuable edge-case behavior. It does not mention return format or error handling, but for a read-only resolver this is acceptable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence plus a short usage instruction. It is front-loaded with the primary action ('Resolves...') and contains no filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with two parameters and no output schema. The description covers the main function, the flagging behavior, and the whole-table option. It could optionally describe the output structure, but the information given is sufficient for selecting and initially invoking the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate for parameter meaning. It does so for module_number by noting 'Omit module_number for the whole table', clarifying optionality and scope. However, course_id is not explained beyond the schema's required field; while its name is self-explanatory, the description could have provided more detail.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Resolves' and clearly states the mapping from Timing-Allocation module numbers to PH/FG chapter and NOS code. It also mentions flagging unsupported modules, which adds a distinct behavioral aspect. This clearly separates it from sibling tools like get_timing_allocation or get_module_source.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use the tool: when you need to map module numbers to source chapters/codes. It also includes a usage tip ('Omit module_number for the whole table'). However, it does not explicitly state when not to use it or name alternative tools, so it falls 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.
Returns the package state: the plan, the segments and the slides written so far, with their citations. Use get_module_video_script or get_module_slides for the deliverables themselves.
| Name | Required | Description | Default |
|---|---|---|---|
| version | No | ||
| package_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. 'Returns the package state' strongly implies a non-mutating read operation, and the description adds useful behavioral context about what the response contains ('the plan, the segments and the slides written so far, with their citations'). It stops short of explicitly declaring non-destructiveness or prerequisites, but for a simple fetch tool it covers the key traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, zero filler. The first sentence front-loads the purpose and return contents; the second adds alternative tool guidance. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is low-complexity (2 params, 1 required, no nested objects, no output schema), and the description covers purpose, return-content categories, and alternatives. However, with no output schema and 0% schema description coverage, the unexplained 'version' parameter and the high-level-only return description leave the agent guessing about exact usage semantics and response shape.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description provides no parameter-level explanation. The agent must infer that package_id identifies the package and guess what 'version' (an optional integer) controls — whether it selects a historical snapshot, a draft iteration, or something else. The phrase 'written so far' hints at versioning but does not clarify the parameter's semantics, leaving a real gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Returns') with a clear resource ('the package state') and details its contents: 'the plan, the segments and the slides written so far, with their citations.' It also distinguishes itself from siblings by explicitly stating this is the state, not the deliverables, which is confirmed by the sibling names get_module_video_script and get_module_slides.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit guidance: 'Use get_module_video_script or get_module_slides for the deliverables themselves.' This tells the agent when not to use this tool and names the exact alternatives, which is exactly what this dimension asks for.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns a package's version list. Versions are append-only and can be read back.
| Name | Required | Description | Default |
|---|---|---|---|
| package_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden. It discloses that versions are append-only and can be read back, implying immutability and read-only nature. However, it lacks details on error handling, permissions, pagination, or ordering, which could be expected for a get operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. It efficiently conveys the core functionality and the append-only trait.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read tool with one parameter and no output schema, the description is adequate but minimal. It does not mention pagination, version ordering, or what fields are in the version list, though these may not be critical given the simplicity. The append-only note adds some context, but more behavioral details could improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate, but it only mentions 'a package' without clarifying package_id beyond its name. It does not provide format, examples, or constraints, leaving the parameter semantics almost entirely to the schema property name.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns a package's version list, which is a specific verb+resource. It distinguishes from siblings like get_module_package (current package) and list_module_packages (list packages) by focusing on version history.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as get_module_package or other history tools. There are no prerequisites, exclusions, or mention of alternatives, leaving the agent to infer usage from the name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns the 14 slides as plain text -- title, bullets, speaker notes -- for reading or copying. Call render_module_pptx for the .pptx file itself.
| Name | Required | Description | Default |
|---|---|---|---|
| version | No | ||
| package_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It discloses the output format (plain text) and content (title, bullets, speaker notes) and the fixed slide count (14). However, it doesn't mention whether this is a read-only operation, but that's implied by 'returns' and the contrast with render_module_pptx. The description adds some behavioral context beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the core purpose, and the alternative tool is named in the second sentence. Zero waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (2 params, no output schema, no nested objects). The description covers the output format and content, and points to the alternative for binary output. It doesn't explain the version parameter, but given the simplicity and the sibling context, the description is mostly complete. A small gap is the lack of parameter explanation, but overall it's adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. However, the description doesn't explain the parameters (package_id and version) at all. The schema itself provides basic types but no semantics. The description's mention of 'module slide deck' implies package_id refers to a module package, but this is not explicit. With 0% coverage, the description should have explained the parameters, so a 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns the 14 slides as plain text including title, bullets, and speaker notes. It distinguishes itself from the sibling render_module_pptx by explicitly noting that tool is for the .pptx file itself.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool (for reading or copying text) and explicitly names the alternative for binary output (render_module_pptx). It doesn't mention when not to use it beyond that, but the guidance is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns the Participant Handbook text behind a package: by default every unit of the module in full, and optionally the exact portion allocated to one video segment or one slide. The plan says which unit and portion each slot covers; this is the text to write it from. Content may present this material any way that teaches well, but may not go beyond it.
| Name | Required | Description | Default |
|---|---|---|---|
| package_id | Yes | ||
| slide_number | No | Return only this slide's allocated text. | |
| segment_number | No | Return only this segment's allocated text. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It discloses the key behaviors: returning all units by default, optionally returning only a slide/segment's allocated text, and scoping content to that text. It does not mention auth/errors, but this is a read-oriented fetch and the disclosed behavior is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tight sentences with the core behavior front-loaded, followed by a useful usage constraint. No wasted words or redundant restatement of the tool name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and no annotations, the description covers the essential return type (text), default behavior, optional filters, and a content-use boundary. This is enough to select and invoke the tool among many source-related siblings.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaning to slide_number and segment_number by explaining they return 'only this ... allocated text' and that omitting them returns full units. package_id lacks a schema description and is not elaborated, but the name and tool title make it self-evident.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Returns'), identifies the exact resource ('Participant Handbook text behind a package'), and clarifies the default full-module scope versus optional slide/segment filtering. This clearly distinguishes it from sibling source-text tools like get_source_chunk or get_ph_unit_source.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states when the tool should be used: it returns the source text that a plan slot covers, and it frames downstream content creation as constrained to that text. It does not explicitly name alternatives or when-not-to-use cases, but the plan/slot context provides clear enough guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Builds the subtitle track from the segments' narration as a progressive, word-by-word typewriter reveal, synced to each segment's ten seconds. Format "srt" (the default) is a SubRip file to burn in or load into an editor; "cues" returns the timings as data. Word timing is estimated from word length -- there is no audio to align against -- so treat it as a starting point an editor nudges, not a finished sync.
| Name | Required | Description | Default |
|---|---|---|---|
| format | No | ||
| version | No | ||
| package_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of explaining behavior. It discloses key traits: the subtitle is generated, synced per segment's ten seconds, timed only by word length, and should not be treated as finished because there is no audio to align against. This is exactly the kind of non-obvious behavior an agent needs.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded with the essential behavioral statement, then separates output formats and limitations clearly. Every sentence adds value, and there is no filler or repetition of schema details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
It explains the generated nature, the two output forms, and the important precision caveat, which is valuable because there is no output schema or annotations. However, given the low parameter coverage, missing package_id and version context makes the guidance slightly less complete than it could be.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains 'srt' versus 'cues' meaningfully, but it does not explain the required 'package_id' or the optional 'version' parameter at all, leaving the agent to guess their exact role and expected values.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific behavior: it 'Builds the subtitle track from the segments' narration' with a word-by-word 'typewriter reveal'. This distinguishes it well from related transcript and storyboard tools by emphasizing it constructs a subtitle product rather than reading existing content.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The format choices are clearly contextualized: 'srt' is the default file output for editing, while 'cues' returns timing data. The limitation that the result is a starting point for an editor communicates when this tool is appropriate. It does not explicitly name alternative or sibling tools, so exact exclusion guidance is missing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lists the units of one handbook module with their lengths. The user-facing flow stops at the module, so this is for your own orientation and for answering a question about what a module contains -- not a menu to put in front of the user.
| Name | Required | Description | Default |
|---|---|---|---|
| subject | Yes | ||
| module_number | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It states the read-only nature ('Lists... with their lengths') and adds contextual behavior about its intended use. It doesn't detail return format or edge cases, but this is a simple lookup tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with purpose, and every sentence earns its place. There is no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with two required parameters and no output schema, the description adequately covers what the tool does and when to use it. It could mention return format or prerequisites, but given the simplicity, it is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description adds no meaning to the parameters 'subject' and 'module_number'. It only refers to 'one handbook module' without explaining how parameters map to that concept.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool 'Lists the units of one handbook module with their lengths', using a specific verb and resource. It distinguishes from sibling tools by focusing specifically on units, not packages or other content.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: it is for the agent's own orientation and answering questions about module contents, explicitly stating it is 'not a menu to put in front of the user'. This gives an exclusion, though it does not name alternative tools for user-facing flows.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns the 3-minute script as eighteen self-contained 10-second segments in plain text, each ready to paste straight into the video generator: narration, scene, visual direction, on-screen text and the transition into the next segment. No page numbers or citations. Also writes the script to a .txt file and returns its path: ATTACH THAT FILE FOR THE USER TO DOWNLOAD alongside the text, since eighteen full segments are more than anyone wants to copy out of a chat window. Give the user the text as it stands.
| Name | Required | Description | Default |
|---|---|---|---|
| version | No | ||
| package_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Because annotations are absent, the description carries the transparency burden. It explicitly discloses the side effect of writing a .txt file and returning its path, as well as the exact content/format of the returned script. It does not cover prerequisites or failure cases, but the provided behavioral detail substantially exceeds basic obligations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and front-loads the core return value, then adds the file-side-effector and presentation instructions. It is slightly verbose with the rationale about why the file should be attached, but that reasoning is still useful for agent behavior.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given there is no output schema, the description does a good job explaining what the tool returns: 18 segments, their contents, plain text formatting, and the absence of citations/page numbers. The main gap is the lack of any explanation of input parameters, which makes the overall context incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain package_id or version (e.g., which version of the package, what package_id refers to, or whether version is optional). The parameter names are somewhat self-explanatory, but the description adds no value beyond the schema itself.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly specifies the resource (module video script), the verb (returns), and the output scope (18 self-contained 10-second segments with narration, scene, visual direction, on-screen text, and transitions). It does not explicitly distinguish itself from sibling tools like get_video_transcript, but the output-level detail makes the purpose fairly clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to call this tool versus alternatives such as get_video_transcript or plan_video_transcript. It includes agent-facing instructions about attaching the .txt file and returning the text unchanged, but these are presentation instructions, not usage-selection criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns a subject's modules and units exactly as its Participant Handbook has them, derived from the indexed document rather than declared anywhere, so re-ingesting a revised handbook updates it. Module numbers here are the handbook's chapter numbers; where a reviewed crosswalk exists the Timing Allocation module number is reported alongside as timing_module, and the two are never interchangeable.
| Name | Required | Description | Default |
|---|---|---|---|
| subject | Yes | Subject id, code or course_id, e.g. "biofuels" or "Solar PV". | |
| module_number | No | Narrow to one module, listing its units. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses a key behavioral trait: the outline is derived from the indexed document and updates upon re-ingestion, not from declared data. It also clarifies that module numbers are handbook chapter numbers and timing_module is a crosswalk reference, which prevents misuse. No annotations are provided, so this transparency is crucial. However, it does not mention potential side effects like rate limits or auth, but for a read tool this is acceptable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences, front-loaded with the primary action, and each clause earns its place. It conveys critical constraints (derivation source, module number semantics, timing_module non-interchangeability) without verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only retrieval tool with no output schema, the description covers the source, semantics of module numbers, and the timing_module special case. It lacks explicit mention of units structure or pagination, but given the simplicity (two params, no nested objects), it's reasonably complete. Sibling comparisons are not needed for completeness given the clarity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%: both parameters (subject, module_number) are described. The description adds context about module_number being the handbook chapter number, which supplements the schema. It doesn't explain return format or unit structure, but since schema covers syntax, the description's added meaning is marginal.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns a subject's modules and units from the Participant Handbook, distinguishing it from siblings like get_module_units and get_ph_unit_source. It names the specific resource (Participant Handbook) and emphasizes the data source (indexed document), which differentiates its purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the primary use case (retrieving handbook outline) and implies when to use it (when the exact handbook structure is needed) but does not explicitly contrast with alternative tools like get_module_units or get_timing_allocation. Though not naming alternatives, it provides clear context about the handbook provenance, which helps the agent decide.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns a unit's handbook text split into the citable blocks the scene plan allocates from, with each block's chunk_id and page. Use it while writing when you want more of the unit than one scene's allocation, or to check which chunk_id covers a passage. For showing the user what the unit says, use read_ph_unit instead -- that one is the reading flow and carries its handling rules.
| Name | Required | Description | Default |
|---|---|---|---|
| subject | Yes | ||
| unit_code | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses the return structure (citable blocks, chunk_id, page) and the read-like behavior implied by 'Returns'. It stops short of stating side-effect absence, errors, or access requirements, but for a simple retrieval tool, this is transparent enough.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, front-loaded with the core behavior in sentence one, usage in sentence two, and a sibling contrast in sentence three. Every sentence earns its place and there is no padding or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter read tool with no annotations and no output schema, the description covers purpose, usage, output shape, and the key alternative. It lacks parameter detail and possible edge-case behavior, but overall it is complete enough for an agent to invoke the tool correctly in its intended context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for the two string parameters (subject and unit_code). It never explains their formats, allowed values, or how they map to the returned content. While the parameter names are self-evident, the description adds no meaning beyond what the schema already exposes.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Returns') and names the exact resource ('a unit's handbook text split into citable blocks') plus result details (chunk_id and page). It clearly distinguishes itself from the sibling read_ph_unit by contrasting the generation-focused source access with the user-facing reading flow.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance is provided: 'Use it while writing when you want more of the unit than one scene's allocation, or to check which chunk_id covers a passage.' It also names the alternative tool (read_ph_unit) and explains why that one should be chosen instead, which is model behavior for usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetches one indexed chunk verbatim by chunk_id, scoped to a course. Use it to re-read the exact text behind a citation, or to verify a citation resolves before committing content.
| Name | Required | Description | Default |
|---|---|---|---|
| chunk_id | Yes | ||
| course_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It reveals the behavior of fetching a chunk verbatim and being scoped to a course, but does not explicitly state side effects, error handling, or authentication requirements. Since it is a read operation, the lack of explicit 'read-only' confirmation or details on missing chunks leaves some transparency gaps, but the core behavior is disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the action. The first sentence states exactly what the tool does, and the second adds practical use cases. Every word earns its place with no redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a simple tool with only two parameters and no output schema. The description covers the purpose, usage scenarios, and implicitly the return value ('verbatim' text behind a citation). It does not mention error handling or edge cases, but given the simplicity, the description is largely complete. It slightly lacks explicit details on what happens when a chunk is not found, but this is not critical for such a basic fetch operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must add meaning. It explains that chunk_id identifies the specific indexed chunk ('by chunk_id') and that course_id provides the scope ('scoped to a course'). This adds semantic meaning beyond the raw schema fields, but it does not describe formats, how to obtain valid IDs, or any relationship between the parameters, so it is adequate but not rich.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool 'Fetches one indexed chunk verbatim by chunk_id, scoped to a course.' This is a specific verb (fetches), resource (indexed chunk), and scope (course), distinguishing it from sibling tools like get_document_page or get_module_source which fetch broader content. The purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use the tool: 'Use it to re-read the exact text behind a citation, or to verify a citation resolves before committing content.' This gives clear context and use cases, though it does not mention when not to use it or name alternative tools. Thus it earns a 4 rather than 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns a storyboard's state. Defaults to the current version. Narrow to one module to keep the payload small while filling content.
| Name | Required | Description | Default |
|---|---|---|---|
| version | No | ||
| artifact_id | Yes | ||
| module_number | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It says 'Returns a storyboard's state,' which implies a read-only operation, but it doesn't explicitly confirm that no side effects occur. It hints that payload can be large (by suggesting narrowing to one module) but doesn't describe error handling, return value structure, or whether it may return empty content. The description adds some context (version defaulting, module narrowing) but is still quite sparse.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, conveying the main purpose and the key parameter semantics without excessive fluff. The sentence 'Narrow to one module to keep the payload small while filling content' is a bit convoluted, but it does add a practical tip on how to use the tool. Overall, it is concise and structurally efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a getter tool with no output schema and high complexity (3 params, optional version, optional module), the description is incomplete. It does not describe what the returned 'state' contains, how to interpret versions, what error responses might look like, or the exact scope of the response (e.g., does it include all modules if no module_number is given?). Both annotations and output schema are absent, so the description must be more self-sufficient; it isn't.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description interprets two parameters: version via 'Defaults to the current version' and module_number via 'Narrow to one module.' However, the required artifact_id is not explained—a user must infer it is the storyboard identifier from the tool name. Since schema coverage is 0%, the description partially compensates but misses the most important parameter, leaving the agent to guess.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Returns a storyboard's state.' This is a specific verb and resource. It also adds context about versioning ('Defaults to the current version') and module narrowing, which clarifies scope. However, it does not explicitly differentiate from sibling tools like get_storyboard_history, which might be the appropriate choice for retrieving an older version.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage, such as specifying a version when you need a non‑current one, and passing module_number to reduce payload size ('Narrow to one module to keep the payload small'). But it lacks explicit guidance on when to prefer this tool over alternatives (e.g., when to use get_storyboard_history instead) or any exclusions. No 'when to use' or 'when not to use' is stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Describes exactly which fields you are expected to write for each section, what each one means in the reference document, and which fields are read-only because they come from the Timing Allocation Document. Read this before your first set_storyboard_content call.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the behavioral burden. It discloses that some fields are read-only because they originate from the Timing Allocation Document, and the verb 'describes' signals a read-only informational operation. It does not explicitly state absence of side effects or output format, but the intent is clear.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no filler, and the core value is front-loaded: 'Describes exactly which fields you are expected to write.' Every clause adds useful context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter informational tool with no output schema, the description covers purpose, content, and usage timing well. It could name the reference document more precisely, but this is a minor gap given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and schema coverage is 100%. The description appropriately focuses on what the returned spec covers rather than parameter semantics. This matches the baseline for a 0-parameter tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: it describes which fields to write for each storyboard section, their meanings, and which are read-only. It also differentiates itself by explicitly linking to set_storyboard_content, making it distinct from generic get_storyboard or validation siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides an explicit usage trigger: 'Read this before your first set_storyboard_content call.' This gives concrete when-to-use guidance. It does not mention when-not-to-use or alternatives, but for a prerequisite spec tool this is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns the version list and change log for an artifact, so you can answer "what changed between version 1 and 4" or "what changed in module 3". Narrow with from_version / to_version.
| Name | Required | Description | Default |
|---|---|---|---|
| to_version | No | ||
| artifact_id | Yes | ||
| from_version | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden. It clearly indicates a read operation ("Returns") and gives a sense of output (version list and change log), but does not mention specifics like pagination, output format, or error behavior. Basic but adequate for a simple list-retrieval tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (two sentences) and front-loaded with the main purpose. No fluff, immediately tells the user what it does and how to narrow results.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequate for a simple history tool. It explains the tool's purpose and parameter usage, but misses details about return structure, version numbering, or any limitations. Given the medium complexity (3 params) and no output schema, it could be more complete but is not inadequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It explains that from_version and to_version narrow the results, adding meaning beyond the raw schema. However, it does not clarify defaults, optionality, or behavior when unspecified, leaving some gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns a version list and change log for an artifact, with concrete examples of the questions it answers ("what changed between version 1 and 4"). This is specific and distinguishes it from sibling tools like get_storyboard (current state) or rollback_storyboard (modification).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides context on when to use it via examples of typical queries and mentions narrowing with from_version/to_version. However, it does not explicitly state when not to use it or mention alternative tools for related purposes (e.g., get_storyboard for a single version).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Parses the Timing Allocation Document and returns the authoritative durations: module totals, per-unit minutes, sub-topics, and a page citation for every value. This is the only source of timing -- never compute or assume a duration. Optionally narrow to one module.
| Name | Required | Description | Default |
|---|---|---|---|
| course_id | Yes | ||
| module_number | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of disclosing behavior. It indicates a read-only parsing operation that returns data, and notes the authoritative nature of the output. It does not mention edge cases or failure modes, but the core behavior is well-described.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the tool's purpose and output. Every word adds value; there is no redundancy or filler. It is concise yet comprehensive.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (two params, no output schema), and the description provides all essential context: what it returns, the authoritative source, and optional narrowing. No important information is missing for an AI agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% description coverage, but the description explains module_number via 'Optionally narrow to one module.' course_id is not described, but its purpose is self-evident in a course context. The description compensates partially but not fully for the missing schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: parsing the Timing Allocation Document and returning authoritative durations. It specifies the output elements (module totals, per-unit minutes, sub-topics, page citations) and distinguishes itself as the only source of timing, differentiating it from siblings like validate_timing_allocation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly instructs when to use this tool (whenever timing is needed) and when not to: 'never compute or assume a duration.' This is a strong, explicit usage guideline that also implicitly directs the agent away from alternative methods.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns the transcript. Format "script" (the default) is the finished scene-by-scene script as plain text, ready to copy straight into a teleprompter or editor: titles, timings, visuals and narration, with no page numbers, citations or word counts in it. Give the user this text as it is -- do not append sources to it. Format "production" adds the sourcing and budget annotations for a reviewer; "json" returns the structured state including the plan and every citation. This flow produces no file by design.
| Name | Required | Description | Default |
|---|---|---|---|
| format | No | ||
| version | No | ||
| transcript_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With zero annotations provided, the description carries the full transparency burden and does a solid job: it discloses the no-side-effect nature ('produces no file by design'), precisely delimits content of each format ('no page numbers, citations or word counts'), and explains the state-laden 'json' output. The instruction to 'not append sources' reveals expected downstream behavior with the returned content. Gaps exist around error handling, access control, and version behavior, but for a read-style tool the key traits are well covered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description opens with a direct verb phrase and front-loads the core behavior before detailing formats. It's a single dense paragraph with each clause adding content knowledge. The mid-paragraph aside 'Give the user this text as it is -- do not append sources to it' breaks the otherwise uniform descriptive voice slightly, reading more like an interaction directive than tool documentation, but it does encode genuine behavioral nuance that earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool of modest complexity (3 flat params, no output schema, no annotations), the description addresses most of what an agent needs: return values per format, default behavior, and expected side-effect profile. The JSON output is helpfully described as containing 'the plan and every citation,' mitigating the missing output schema. The one gap is the `version` parameter's semantics (defaults? history behavior?) which neither schema nor description explains; this prevents a top score.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 0% schema description coverage, the description substantially enriches the `format` parameter — detailing exact content, use case, and output shape for each enum value ('production' = 'adds the sourcing and budget annotations for a reviewer'; 'json' = 'structured state including the plan and every citation'). The `transcript_id` and `version` parameters receive no additional color, though their function is reasonably inferable. One tricky param well-explained out of three is a solid contribution, but not exhaustive.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The opening 'Returns the transcript' is somewhat tautological with the tool name, but the detailed elaboration on the three format options (script, production, json) makes the purpose unmistakably clear. Each format's output is precisely specified ('finished scene-by-scene script as plain text... techniques... titles, timings, visuals and narration'), which goes well beyond a basic statement. However, it never explicitly distinguishes itself from siblings like get_module_video_script or get_video_transcript_spec, so it doesn't fully earn a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is conveyed through implication rather than explicit guidance — the agent can infer that 'script' is for teleprompter/editor content, 'production' for review workflows, and 'json' for structured access. However, the description never directly states when to prefer this tool over related siblings or names alternatives. The final note 'This flow produces no file by design' hints at edge-case expectations but stops short of explicit when-to-use direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns a transcript's version list. Versions are append-only, so an earlier draft can always be read back with get_video_transcript and a version number.
| Name | Required | Description | Default |
|---|---|---|---|
| transcript_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden. It discloses the append-only nature of versions, a useful behavioral trait, but does not explicitly state whether the operation is read-only or mention any side effects. The description adds some context (append-only, ability to read back) but could go further in clarifying the exact behavior and response structure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (two sentences), directly states the purpose, and includes a key behavioral note (append-only) without any fluff. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter and no output schema, the description tells what it does but does not specify the format of the returned version list (e.g., version numbers, timestamps) or any ordering/pagination details. It is minimally sufficient but could provide more detail to fully guide the agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter transcript_id is implied by the phrase 'transcript's version list', but the description does not explicitly describe its meaning (e.g., 'the ID of the transcript'). With 0% schema description coverage, the description should compensate, but given the simplicity and self-evident nature of the parameter, this is adequate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns a transcript's version list, and distinguishes it from related tools like get_video_transcript (which fetches a specific version) and list_video_transcripts (which lists transcripts). The verb 'Returns' plus the resource 'transcript's version list' is specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
While it doesn't explicitly say 'use this when you need to see all versions', it explains that versions are append-only and implies that to read an earlier draft, one uses get_video_transcript with a version number. This provides clear context on when to use this tool versus the alternative, though it could have been more explicit about 'when not to use'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Describes what to write into each scene, what is fixed by the plan and may not be changed, and the grounding rules validation enforces. Read this before your first submit_video_transcript call.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of behavioral disclosure. It explains that the tool describes scene-writing requirements, fixed plan elements, and validation grounding rules, which clearly implies a read-only informational operation. It doesn't explicitly state side-effect-free behavior or auth needs, but for a zero-parameter spec tool this is acceptable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences and every sentence earns its place. The first sentence front-loads the core purpose and content; the second adds a practical workflow pointer. No filler or redundant restatement of the title.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple no-parameter spec tool with no annotations and no output schema, the description sufficiently explains what the returned spec contains and when to consult it. It could additionally name the related validation tool, but the core information needed for correct use is present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the schema contributes nothing and the baseline is 4. The description compensates by explaining the kind of information the tool will return, making the purpose of the no-parameter call clear.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Describes') and identifies the resource (video transcript field spec), while also clarifying exactly what the spec covers: per-scene content, plan-fixed constraints, and validation grounding rules. This distinguishes it from sibling tools like get_video_transcript (which retrieves a transcript) and get_storyboard_field_spec (which targets storyboards).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit usage timing: 'Read this before your first submit_video_transcript call.' This provides clear when-to-use context and connects the tool to the submission workflow. It doesn't discuss when not to use it or mention alternatives, but the timing instruction is strong enough for a spec-retrieval tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Extracts, chunks and indexes a course's approved PDFs for retrieval. Idempotent: documents whose checksum is unchanged are skipped unless force is true. Must be run once per course before search_course_content returns anything.
| Name | Required | Description | Default |
|---|---|---|---|
| force | No | Re-index even if the document checksum is unchanged. | |
| course_id | Yes | ||
| document_types | No | Restrict to these document types. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses idempotency, checksum-based skipping, and the force parameter behavior, which are key behavioral traits. It does not mention potential side effects like disk usage or indexing time, but core behaviors are covered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the core action and purpose. The idempotency detail is concise and critical. The prerequisite note is essential and placed at the end without bloat.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has 3 params, no output schema, and no annotations. Description covers its purpose, idempotency, and prerequisite usage, which is sufficient for an ingestion tool. It does not mention return values or error cases, but output schema absence is common; the description is adequate for the complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 67% (2 of 3 params have descriptions). The description adds context on the force parameter ('Re-index even if the document checksum is unchanged' is in schema, but description explains idempotency context). It does not describe course_id or document_types beyond schema, but the schema already covers document_types with enum and description. The force parameter's semantic is reinforced by the idempotency statement.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the verb 'Extracts, chunks and indexes', the resource 'a course's approved PDFs', and the purpose 'for retrieval'. It also distinguishes from siblings by noting it must be run once before search_course_content returns anything, tying it to the retrieval workflow.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use: 'Must be run once per course before search_course_content returns anything'. Implies when not to re-run: idempotent unless force. It also indicates an alternative via sibling search_course_content, clarifying the dependency.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lists every registered course with its QP code, NSQF level, module count and the presence/index status of its four approved source documents (QP, PH, FG, TIMING). Call this first to discover valid course_id values.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It discloses the output fields and the fact that it lists all courses, implying a read-only operation. It does not explicitly state side-effect-free behavior, but the nature of listing is unambiguous. The description adds useful detail about the four source documents, enhancing transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core purpose, and includes the key output specifics without extraneous detail. Every word contributes to understanding the tool's function and usage.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter tool with no output schema, the description is fully self-contained. It explains what is returned, the purpose of calling it, and the foundational role it plays. There are no gaps given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has 0 parameters, so the baseline is 4. The description correctly focuses on output rather than parameters, and no parameter documentation is needed. The schema is empty, so there is nothing to compensate for.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states what the tool does: it lists every registered course with specific attributes (QP code, NSQF level, module count, and document presence/index status). It also mentions the purpose of discovering valid course_id values, which distinguishes it from other listing tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs to 'Call this first to discover valid course_id values', providing clear when-to-use guidance. This positions the tool as a foundational discovery step, which is effectively differentiated from sibling tools that operate on specific course_ids.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lists module packages, newest first, optionally for one subject.
| Name | Required | Description | Default |
|---|---|---|---|
| subject | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations present, the description carries the transparency burden. It discloses the ordering ('newest first') and the optional filter behavior ('optionally for one subject'), which is useful. However, it omits details like pagination, default limits, or behavior when subject is not provided. Adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence that communicates the action, resource, ordering, and optional filter. Every word earns its place; no fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list operation with one optional parameter and no output schema, the description covers the essential behaviors: what is listed, the order, and the optional filter. It might benefit from mentioning pagination or result limits, but given the tool's simplicity, it is reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides only a parameter name 'subject' with no description, resulting in 0% schema coverage. The description adds meaning by clarifying that the subject is optional ('optionally') and filters the list. This goes beyond the schema and directly explains the parameter's role.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Lists' and resource 'module packages', and adds sorting order 'newest first' and optional scoping 'for one subject'. It is specific enough to differentiate from singular 'get_module_package' though it doesn't explicitly mention alternatives. A clear, functional purpose statement.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus siblings like get_module_package or get_module_package_history. The optional subject filter implies a use case but no exclusions or alternative recommendations are given. The context is implicit at best.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lists storyboard artifacts, optionally filtered by course.
| Name | Required | Description | Default |
|---|---|---|---|
| course_id | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description carries full responsibility for behavioral disclosure. It only states that it 'lists' artifacts and optionally filters, but does not mention return format, pagination, ordering, or whether it returns full storyboards or summaries. This is minimal and leaves important behavior unspecified.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise, front-loaded sentence (7 words) that directly states the action and the optional filter. No filler, no repetition, every word is informative.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with one optional parameter and no output schema. The description gives a basic understanding of what it does, but it doesn't mention what the returned 'storyboard artifacts' contain (metadata, full content, etc.) or any potential limits. For a list operation, this is adequate but not fully complete given the lack of annotations and output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides only a property name 'course_id' with type string, no description, and schema coverage is 0%. The description compensates by stating the filter is optional and by course, giving meaning to the parameter. However, it lacks details like whether the course_id is the exact course identifier or any other constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Lists storyboard artifacts, optionally filtered by course' clearly specifies the verb (lists) and the resource (storyboard artifacts), and mentions the optional filter. It distinguishes from 'get_storyboard' which presumably returns a single item, and from history tools, by indicating a plural list operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for listing storyboards with an optional course filter, but provides no explicit guidance on when to prefer this over alternatives like 'get_storyboard' or 'get_storyboard_history'. It does not mention any exclusions or conditional use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lists the two course types and their subjects, with whether each one's Participant Handbook is present and indexed. A subject that is not ready carries the one action that would make it ready. Call this before offering the user a choice, so an unavailable subject is never offered as though it worked.
| Name | Required | Description | Default |
|---|---|---|---|
| track | No | Restrict to one course type. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses that the output includes readiness status and the action needed to make a subject ready, which is beyond a simple list. It appropriately implies a read‑only operation via the verb 'Lists', and adds operational context about avoiding offering unavailable subjects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no redundancy. The first sentence states the core functionality, the second provides the usage guideline. Every word earns its place and the structure is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list operation with one optional parameter and an output that is straightforward (subjects, readiness, action), the description covers the purpose, the readiness indicator, the corrective action, and when to call. No output schema is needed to explain return values here. The description is complete for its complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already fully documents the 'track' parameter with its enum and description ('Restrict to one course type'). The description adds the useful fact that there are exactly two course types, but does not elaborate on parameter semantics beyond what the schema provides. Baseline 3 is appropriate given 100% schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool 'Lists the two course types and their subjects' and adds the specific detail about Participant Handbook presence and index status. This specifies the verb and resource precisely, distinguishing it from generic course listing tools like list_courses.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to call: 'Call this before offering the user a choice, so an unavailable subject is never offered as though it worked.' This provides clear timing and rationale, and implicitly indicates alternatives (other workflow tools) by positioning this as a preparatory step.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lists video transcripts, newest first, optionally for one subject.
| Name | Required | Description | Default |
|---|---|---|---|
| subject | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses ordering ('newest first') and the optional subject filter, which are behavioral traits. However, it omits other relevant specifics such as pagination, authorization requirements, or the structure of returned transcript objects. The provided details are helpful but sparse, so a score of 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, grammatically simple sentence that immediately conveys the tool's purpose. It is front-loaded with the verb 'Lists' and includes only essential qualifiers ('newest first', 'optionally for one subject'). No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only listing tool with one optional parameter, the description is mostly complete. It conveys the default ordering and optional filtering. However, it does not mention pagination or what fields are returned (though no output schema exists), and it could hint at the relationship to list_video_subjects for obtaining valid subject values. Slight deduction for these minor gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides no description for the 'subject' parameter (0% coverage), so the description must compensate. The phrase 'optionally for one subject' clarifies that the parameter is optional and filters results by subject, but it does not specify the expected format (e.g., ID vs. name) or how to obtain valid subjects. It adds partial meaning beyond the schema, justifying a 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists video transcripts, specifying ordering ('newest first') and an optional filter ('optionally for one subject'). It identifies the resource (video transcripts) and the action, which is specific enough to distinguish from siblings like list_video_subjects or get_video_transcript, though it doesn't explicitly name alternatives. A small deduction because it doesn't clarify what happens without a subject (e.g., all subjects) as explicitly as the high-calibration example.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this versus alternatives. The phrase 'optionally for one subject' hints at usage but does not direct the agent to use list_video_subjects for valid subject values or get_video_transcript for a single transcript. There is no mention of prerequisites or exclusions, falling short of minimal guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Attempts to change a module or unit duration. Permitted only when the requested value matches the Timing Allocation Document, which is authoritative for time. A conflicting request is refused with an explanation rather than applied -- durations may never come from model judgement.
| Name | Required | Description | Default |
|---|---|---|---|
| reason | No | ||
| unit_code | No | Omit to target the module total. | |
| artifact_id | Yes | ||
| base_version | Yes | ||
| module_number | Yes | ||
| requested_minutes | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of behavioral disclosure. It clearly reveals key traits: the operation is conditional, conflicting requests are refused with an explanation, and durations must never come from model judgment. It does not describe success behavior or error details, but the refusal mechanism and hard constraint are substantial transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the action and scope, and every clause adds important constraint or context. It avoids redundancy and wastes no words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a mutating tool with six parameters, no annotations, and no output schema, so the description must do more. It explains the governing rule and refusal behavior but omits parameter semantics, success response shape, prerequisites like obtaining the Timing Allocation Document, and how base_version interacts with the edit. The description is not sufficient for confident invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 17%, and the description does not compensate by explaining artifact_id, base_version, module_number, or requested_minutes. It adds general meaning around 'requested value' and module/unit duration, but leaves most required parameters semantically undocumented. unit_code is the only parameter clarified, and that clarity comes from the schema itself.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific action ('change a module or unit duration') on a clear resource (storyboard timing). It distinguishes itself from read/validation siblings like get_timing_allocation and validate_timing_allocation by focusing on mutation of timing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives concrete usage guidance: it is only permitted when the requested value matches the Timing Allocation Document, and conflicting requests will be refused. It does not explicitly name alternatives like validate_timing_allocation, but the authoritative-source constraint clearly frames when this tool should and should not be used.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Plans the full 12 minutes of content for one Participant Handbook module. The video is three parts: Part 1 (segments 1-6, 60s) orients the learner to the whole module using the handbook's stated learning outcomes, Part 2 (segments 7-15, 90s) teaches every unit in handbook order, Part 3 (segments 16-18, 30s) consolidates. The deck is sized to the module rather than fixed: nine minutes across as many slides as it needs, never more than 30 seconds on any one slide. Returns a package_id, the plan, and a content map of the module's outcomes and units. Every segment and slide is told which unit it covers, which portion, which chunk_ids to cite and how many words fit its seconds. Accepts a module number, or a topic to resolve to the module that holds it. Ask the user nothing further: every duration and count is settled.
| Name | Required | Description | Default |
|---|---|---|---|
| title | No | Title for the video and deck. Defaults to the module title. | |
| topic | No | A topic or unit heading; the module containing it is used. Requires no module_number. | |
| subject | No | Subject id, code or course_id, e.g. "biofuels". | |
| module_number | No | Participant Handbook module (chapter) number. | |
| words_per_minute | No | Narration pace used to size every segment and slide. Defaults to 140. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and delivers richly: it discloses the exact three-part structure (segments 1-6/60s, 7-15/90s, 16-18/30s), the dynamic deck-sizing rule (never more than 30 seconds per slide), the return composition (package_id, plan, content map), per-segment/slide attribution details, and the no-follow-up behavior ('Ask the user nothing further').
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is longer than average (~140 words) but information-dense: each sentence conveys a distinct structural rule, input mode, or output detail that the agent needs. It is front-loaded with the core purpose. Slightly verbose but no wasted sentences.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having no output schema, the description compensates by enumerating the return values (package_id, plan, content map) and the granular per-segment metadata. It covers the complex structure, inputs, and behavior well. Minor gaps remain: failure modes, whether an existing package is overwritten, and handling of ambiguous topic resolution are not addressed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds genuine cross-parameter meaning beyond the schema: it clarifies that module_number and topic are alternatives ('Accepts a module number, or a topic to resolve to the module that holds it') and confirms that words_per_minute drives the 'settled' durations and counts.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Plans the full 12 minutes of content for one Participant Handbook module.' It then details the exact three-part video structure and deck-sizing rules, making the tool's scope unmistakable and distinct from siblings like plan_video_transcript or get_module_content_spec.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies when to use it (planning a full module content package) and explains input modes ('Accepts a module number, or a topic to resolve to the module that holds it'), but it never explicitly names alternatives or states when not to use it. Given the sibling list contains the narrower plan_video_transcript, explicit differentiation would have strengthened this.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Creates a video transcript draft for one Participant Handbook unit and returns its scene plan. The plan divides the requested duration into scenes, gives each scene a word budget at a stated speaking rate, and attaches to each scene the exact handbook text it must be built from and the chunk_ids it must cite. Accepts either subject + unit_code, or a heading to resolve -- which is the shortcut flow, where the user names a unit and skips the menus. The handbook is the source of truth: presentation, narration, examples and visual direction are yours to author, the educational content is not.
| Name | Required | Description | Default |
|---|---|---|---|
| title | No | Video title. Defaults to the unit title. | |
| heading | No | Unit heading, when the user named the unit rather than its code. | |
| subject | No | Subject id, code or course_id, e.g. "biofuels". | |
| duration | Yes | Requested length: "2 min", "90 seconds", "1:30", or a bare number meaning minutes. | |
| unit_code | No | Unit code such as "7.1". | |
| scene_count | No | Overrides the derived scene count. Leave unset unless the user asked for a specific structure. | |
| words_per_minute | No | Narration pace used to size every scene. Defaults to 140. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description carries most of the behavioral disclosure burden. It explains key behaviors: the tool divides the requested duration into scenes, computes word budgets using a speaking rate, attaches exact handbook text to scenes, and specifies chunk_ids to cite. It also clarifies the boundary between authored creative content and fixed educational content, though it does not state whether the created draft is persisted or whether permissions are required.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences long and every sentence earns its place: the first explains what the tool does, the second explains the output structure, and the third establishes content-authoring boundaries. It is front-loaded with the primary action and contains no filler or redundant restating of the tool name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that there is no output schema and no annotations, the description compensates well by explaining the central return value—the scene plan—with its scene division, budgets, source text, and chunk_ids. It also covers the two identification paths and the authoring boundary, so an agent has enough context to invoke the tool correctly and use the returned plan.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents all parameters well. The description adds valuable meaning by framing subject + unit_code and heading as alternative resolution flows, and by connecting duration and words_per_minute to the returned scene budget. It also makes the purpose of scene_count clearer as an override of the derived structure.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: it creates a video transcript draft for one Participant Handbook unit and returns its scene plan. This clearly separates it from sibling tools like submit_video_transcript or validate_video_transcript, since this tool explicitly produces a plan rather than a final submitted transcript.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear usage guidance on how to identify the unit: either via subject plus unit_code, or via the heading shortcut flow where the user names a unit and skips the menus. It also sets an important creative boundary around the handbook being the source of truth. It does not explicitly mention sibling tools for when-not-to-use, but the guidance is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns the Participant Handbook's own text for one unit, verbatim and complete, in document order. This is a reading operation, not a generation one: pass the text on to the user unchanged. Do not summarise, shorten, expand, paraphrase, re-order, re-format, correct or comment on it, and do not merge it with anything else. It carries a fidelity_note stating the only two mechanical differences from the printed page (removed running headers and folio numbers, removed indexing overlap); repeat that note if the user asks how exact this is. If the user afterwards wants a video, that is the separate video flow, not a rewrite of this text.
| Name | Required | Description | Default |
|---|---|---|---|
| heading | No | Unit heading, when the user named the unit rather than its code. | |
| subject | No | Subject id, code or course_id. Omit when giving a heading to search. | |
| unit_code | No | Unit code such as "7.1". Requires subject. |
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 so thoroughly. It discloses that output is verbatim and complete, that it must be passed through unchanged, that a fidelity_note is included, and exactly what the two mechanical differences are. This is rich behavioral context beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but every sentence earns its place: purpose, usage constraints, fidelity note handling, and video exclusion. It is front-loaded with the core purpose and then provides necessary behavioral rules without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no annotations, the description fully covers what the tool returns, how to handle it, the fidelity note, and the boundary with the video flow. It is complete for an agent to select and invoke this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description does not add parameter-level meaning beyond the schema, but it does not need to because the schema already documents heading, subject, and unit_code clearly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description opens with a specific verb and resource: 'Returns the Participant Handbook's own text for one unit, verbatim and complete, in document order.' It clearly distinguishes this from generation tools by emphasizing it is 'a reading operation, not a generation one,' and differentiates from the video flow.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for when to use the tool: whenever exact handbook text is needed, and explicitly says not to summarize or alter it. It also states that if the user wants a video, that is a separate flow. It does not name specific sibling tools as alternatives, but the guidance is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Writes the 14-slide deck to a .pptx file, with each slide's speaker notes attached as PowerPoint notes, and returns the path. Refuses by default if validation has errors; pass allow_invalid to render a draft anyway.
| Name | Required | Description | Default |
|---|---|---|---|
| version | No | ||
| package_id | Yes | ||
| allow_invalid | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It explains key behaviors: writing a .pptx, attaching speaker notes, returning the path, and refusing on validation errors unless allow_invalid is set. However, it does not mention side effects like file overwriting, whether the package is modified, or any authorization requirements, leaving gaps for a mutating tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded: two sentences that clearly state the action, output specifics, return value, and a key behavioral condition. Every sentence contributes essential information without redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 3 parameters and no output schema, the description covers the essential aspects: the exact deliverable (14-slide .pptx), inclusion of speaker notes, return value (path), and validation gating behavior. It is sufficiently complete for an agent to understand and invoke correctly, though it could mention error handling or file overwrite details for full context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description must compensate. It explains the allow_invalid parameter's effect (rendering a draft despite errors) but does not explain the version parameter at all. package_id is self-explanatory, but the description adds no detail on its format or purpose beyond the schema's required flag.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool writes a 14-slide deck to a .pptx file with speaker notes and returns the path. It distinguishes itself from siblings like render_storyboard_docx (Word output) and validate_module_package (validation only) by specifying the PowerPoint output and rendering action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by describing the rendering action and mentions the validation gate with allow_invalid to produce a draft. However, it does not explicitly state when to use this tool versus alternatives or when not to use it, leaving some ambiguity in a tool-rich environment.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Renders the storyboard to .docx by cloning the template and inserting content. Template formatting is preserved by construction -- styles, theme, numbering, header, footer and section properties are carried over untouched. Returns the output path. Refuses by default if validation has errors; pass allow_invalid to render a draft anyway.
| Name | Required | Description | Default |
|---|---|---|---|
| version | No | ||
| artifact_id | Yes | ||
| allow_invalid | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully carries the transparency burden. It discloses key behaviors: template cloning, preservation of formatting (styles, theme, header/footer, etc.), return of the output path, and the validation refusal with the allow_invalid override. This is rich, useful behavioral information beyond what the schema shows.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the primary action, and includes essential details without fluff. Every sentence earns its place, making it highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers core functionality (rendering to docx), template preservation, return value (output path), and validation behavior with the override flag. Given the tool's moderate complexity and lack of output schema, this is sufficient for an agent to use it correctly without further context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains allow_invalid clearly ('pass allow_invalid to render a draft anyway'), but artifact_id and version are left to inference from their names. This adds some value but not comprehensive parameter documentation, warranting a 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool renders a storyboard to .docx by cloning a template and inserting content, which precisely defines its function. It also differentiates from siblings like render_module_pptx by explicitly naming the .docx output format.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context: use when a storyboard needs to be rendered as a .docx file. It does not explicitly name alternatives (e.g., render_module_pptx) or state when not to use, but the format specificity makes the context clear, so it earns a 4.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Restores a previous version's state as a new version. History is append-only: the versions between are preserved and the rollback can itself be rolled back.
| Name | Required | Description | Default |
|---|---|---|---|
| reason | No | ||
| to_version | Yes | ||
| artifact_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description correctly assumes full burden for disclosing the tool's safety semantics, and it delivers: 'History is append-only: the versions between are preserved and the rollback can itself be rolled back' directly addresses the critical risk for a mutating tool — that it's non-destructive and reversible. This is exactly the behavioral disclosure an agent needs before invoking a state-changing operation named 'rollback.' Loses a point for not covering error/edge conditions (e.g., what happens when to_version is the current version) but is otherwise exemplary.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Exactly two sentences, no wasted words. The first sentence is action-oriented with a clear verb and object; the second immediately surfaces the critical non-obvious semantic — the append-only behavior. Every clause earns its place, with no content-free filler or restating of the tool's name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutating tool with zero annotations and no output schema, the description covers the essential ground: what it does (restore state), how it does it (append-only, new version), and why it's safe (reversible). It's not a 5 because a state-restoring operation might warrant more explicit coverage of concurrency or validation implications, but for a two-sentence description it handles the critical complexity well.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema coverage, the description must compensate, and it partially does: 'previous version's state' clarifies to_version's role, and the append-only framing clarifies why a rollback needs to_version at all. However, the description never explicitly walks through parameter usage — 'reason' is left entirely unexplained (though it's a role-player-typical audit field), and the description doesn't explicitly map version terminology to the to_version parameter. The conceptual clarity in the description does carry meaning beyond the raw schema field names, warranting a middle score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Uses a specific verb+resource+scope pattern: 'Restores a previous version's state as a new version' precisely describes the operation while preemptively correcting the semantically misleading 'rollback' name. The critical 'as a new version' clause clearly distinguishes it from a destructive restore and does meaningful work that sets it apart from sibling tools like get_storyboard_history (read-only) and set_storyboard_content (direct edit).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The usage context is implied ('restores a previous version's state') but the tool never explicitly names alternatives or gives when/when-not guidance. Given the rich sibling environment full of other mutators like set_storyboard_content and modify_storyboard_timing, explicit disambiguation would materially help an agent, but the append-only framing does convey the core decision-relevant scenario adequately for an implied-usage rating.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Deterministic BM25 search over one course's approved documents. Results are always scoped to the given course; there is no way to retrieve another course's content. Narrow further with document_types, and with either chapter (for PH/FG) or nos_code (for the QP) -- use get_module_crosswalk or module_number to get the right values. Each result carries a chunk_id, which is what you must cite in generated content.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | Yes | Search terms. Punctuation is handled; terms are OR-ed and ranked. | |
| chapter | No | PH/FG chapter number. Ignored if module_number is given. | |
| nos_code | No | QP NOS code, e.g. "SGJ/N4105". | |
| course_id | Yes | ||
| unit_code | No | Unit code, e.g. "7.1". | |
| module_number | No | Timing-Allocation module number. Convenience: resolves via the crosswalk to the correct PH/FG chapter and QP NOS code automatically. Prefer this over chapter. | |
| document_types | No | Defaults to ["QP","PH","FG"]. Pass ["TIMING"] only to inspect timing text. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden and does well: it discloses deterministic behavior, course-only scope, no cross-course retrieval, and the need to cite chunk_id in generated content. It omits failure behavior and full response shape, but the core behavioral traits are communicated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three dense sentences, front-loaded with the core purpose, and each subsequent sentence adds parameter or output guidance without repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an 8-parameter search tool with no output schema, the description covers scope, narrowing options, crosswalk resolution, and the critical chunk_id citation contract. It doesn't describe result ordering, pagination, or no-result behavior, but the essential invocation context is present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although schema coverage is 75% and many parameters are already described, the description adds useful relationships: chapter is for PH/FG, nos_code is for QP, and module_number/get_module_crosswalk resolve the right values. The only weakly covered parameter is unit_code, but the added grouping justifies an above-baseline score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Deterministic BM25 search over one course's approved documents' – a specific verb, resource, and scope. It clearly differentiates from retrieval/detail tools by emphasizing course-scoped document search and the chunk_id output.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly says results are always scoped to the given course and explains how to narrow by document_types, chapter, or nos_code, including a pointer to get_module_crosswalk/module_number. It does not explicitly contrast with sibling search/retrieval tools, so it falls just short of full when-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Writes the assessment strategy blueprint and the question bank, committing a new version. The template runs ten questions per module, grouped under a per-module heading. Every question must cite the chunk_ids that support its stem, correct answer and explanation; the three incorrect options are authored, since a source document contains no answer key, and the rendered document discloses that. Questions accumulate across calls, so you can submit one module at a time -- pass replace: true to start over. Question numbers are assigned automatically in module order unless you set them.
| Name | Required | Description | Default |
|---|---|---|---|
| note | No | ||
| remarks | No | The QP's remarks line, e.g. total hours breakdown. | |
| replace | No | Discard existing questions instead of adding to them. Default false. | |
| questions | No | ||
| artifact_id | Yes | ||
| base_version | Yes | ||
| strategy_points | No | Assessment guideline points from the QP. Defaults to the standard SCGJ seven. | |
| weightage_electives | No | Elective marks tables, keyed by elective name. | |
| weightage_compulsory | No | Compulsory NOS marks table from the QP. | |
| minimum_aggregate_pass_pct | No | From the QP, e.g. 70. Defaults to 70 if never set. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full transparency burden and handles it well. It discloses version committing, question accumulation across calls, replaced semantics, and automatic numbering. It also reveals the nuanced behavior that the three incorrect options are authored (not sourced) because documents lack an answer key, and that the rendered document discloses this — genuine behavioral context beyond what any schema would show.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is four dense sentences (~110 words) that front-load the main purpose and then pack in template format, citation rules, distractor authorship, accumulation, replace, and auto-numbering. There is no filler, and each sentence earns its place, though the breadth of content makes it slightly long for a front-loaded read.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex 10-parameter tool with nested objects and no output schema, the description covers most critical behaviors: what gets written, versioning, template structure, citation requirements, distractor handling, and incremental submission semantics. Minor gaps remain on prerequisites (e.g., base_version implications) and return behavior, but it is otherwise thorough for a mutation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 60%, and the description adds partial value: it explains the required chunk_ids citations and the replace/accumulation semantics that the schema documents. However, it adds nothing on the undocumented params (note, artifact_id, base_version) and only slightly supplements the numbering behavior already in the schema. It does not fully compensate for the 40% coverage gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb-resource pair ('Writes the assessment strategy blueprint and the question bank'), clearly distinguishing it from sibling write tools like set_module_story and set_storyboard_content by scoping to assessment content. It also covers the commit/versioning behavior, making the core function unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description conveys a clear workflow: questions accumulate and one module can be submitted at a time, with 'replace: true' to start over. It does not name alternatives or state when not to use this tool, but the incremental submission pattern is practical usage guidance that aids selection among the many get/set sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Records the constants of the 3-minute film: the protagonist, the handful of locations, the light and camera language, the narrator, the three acts and the opening image the ending returns to. Write this BEFORE the segments. Each 10-second clip is generated separately and the generator remembers nothing between calls, so continuity exists only where it is written down -- and validation checks every segment against what you record here. Build the whole story first, then cut it into eighteen shots; do not write eighteen prompts and hope they join up.
| Name | Required | Description | Default |
|---|---|---|---|
| note | No | ||
| story | Yes | ||
| package_id | Yes | ||
| base_version | Yes | ||
| replace_subject_character | No | Deliberately change the presenter this subject has already established. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does so admirably. It discloses the stateless nature of the generator ('remembers nothing between calls'), the persistence mechanism ('continuity exists only where it is written down'), and the validation behavior ('checks every segment against what you record here'). This is valuable behavioral context beyond the plain purpose.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences, front-loaded with the purpose, followed by the timing directive and the system rationale. Every sentence earns its place; there is no fluff or repetition. The structure flows from what to know, to when to act, to why it matters.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the high complexity (nested objects, many required fields, no output schema, no annotations), the description covers the 'what, when, and why' thoroughly. However, it does not explain versioning semantics (base_version) or the exact behavior of replace_subject_character, and the three-vs-four acts inconsistency leaves a gap in the mental model. Still, the essential workflow and system constraints are well communicated.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is only 20% for top-level parameters, so the description must compensate. It does add meaning by naming the core story fields, but it introduces an error: it says 'the three acts' while the schema requires four acts (discovery, exploration, action, payoff). This mismatch could mislead an agent into providing an incomplete 'acts' object. It also omits semantics for base_version and package_id, though those are arguably self-explanatory.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb-resource pair: 'Records the constants of the 3-minute film,' and enumerates exactly what those constants are (protagonist, locations, light/camera language, narrator, acts, opening image). This clearly distinguishes it from sibling tools like set_storyboard_content by framing it as the story-bible level definition.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit temporal guidance is given: 'Write this BEFORE the segments' and 'Build the whole story first, then cut it into eighteen shots; do not write eighteen prompts and hope they join up.' This communicates both when to use the tool and the anti-pattern to avoid, effectively serving as an implicit alternative (improvisational per-clip writing without this tool).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Writes generated content into a storyboard and commits it as a new version. Address rows and slides by their row_id / slide_id from get_storyboard; anything you do not mention is left unchanged, so this is safe for incremental edits. Every content field should carry sources citing chunk_ids returned by search_course_content -- validate_storyboard checks that they resolve and are in the right chapter. Durations, unit codes and unit titles are not writable here: they come from the Timing Allocation Document. Use modify_storyboard_timing if a duration genuinely needs to change.
| Name | Required | Description | Default |
|---|---|---|---|
| note | No | Recorded in the change log for this version. | |
| slides | No | ||
| lms_rows | No | Replaces the module's LMS Technical Mapping rows entirely. | |
| artifact_id | Yes | ||
| part_a_rows | No | ||
| part_b_rows | No | ||
| base_version | Yes | The version you read. Rejected if it is no longer current. | |
| module_number | Yes | ||
| part_c_subtitle | No | ||
| module_description | No | ||
| module_description_sources | No | Citations for module_description. Required whenever the description is set. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description carries the behavioral disclosure burden. It does well by stating that the tool commits a new version, leaves unspecified content unchanged, and rejects duration/unit/title edits. It does not mention auth/permissions or return shape, but the disclosed mutation semantics are substantial.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four well-structured sentences, each with a distinct job: main action, addressing behavior, citation requirements, and boundary constraints. It is front-loaded and contains no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex 11-parameter write tool with no output schema and no annotations, this description covers core workflow, incremental-safety behavior, validation expectations, and alternatives. The main gaps are exact success/return semantics and the precise partial-update behavior of the lms_rows array, but the coverage is still strong.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 36%, so the description must compensate. It adds key semantics around row/slide targeting, preserving omitted content, source chunks, and non-writable fields. However, many top-level parameters still receive little clarification, and lms_rows says it "Replaces the module's LMS rows entirely" while the top-level description suggests omitted items are unchanged.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: "Writes generated content into a storyboard and commits it as a new version." It also distinguishes itself from sibling tools like set_assessment_content and modify_storyboard_timing by focusing on storyboard content and explicitly delegating timing changes elsewhere.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear operational context: use row_id/slide_id from get_storyboard, cite chunk_ids from search_course_content, and use modify_storyboard_timing for duration changes. It does not exhaustively contrast with all siblings, but it names the main alternative and explains what is not writable here.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns the three things this server can do, as a menu, plus a session_id. CALL THIS FIRST whenever the user opens with an unscoped request -- "can we start", "let's start", "show me what you have", "what can you do", "hi", "begin" -- and whenever they finish one thing and want another. Show the three options to the user and wait for their pick; do not ask any question of your own before or after, and do not begin work until they have chosen. The options are: 1 video script + slide deck for a module, 2 read a handbook unit word for word, 3 course storyboard. Answer with flow_choose. Sessions are independent and cheap, so call this again rather than reusing a finished one.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description carries the full burden. It fully discloses the behavioral contract: call this first, wait for user choice, don't do extra work, and treat sessions as independent and cheap so calling again is fine. This is thorough and actionable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is longer than average but every sentence earns its place: it covers the returned output, trigger conditions, interaction rules, the three menu options, and the next tool to use. It is front-loaded with the main purpose and never drifts into filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that there is no output schema and no annotations, the description is fully complete: it tells the user what the output contains, when to call it, how to behave, what options to present, and even hints at the next step via flow_choose. An agent can confidently invoke this tool without additional context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and the input schema confirms this, so there is no parameter information for the description to add. The baseline of 4 is appropriate here.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states exactly what the tool does: 'Returns the three things this server can do, as a menu, plus a session_id.' It also clearly distinguishes this as the initial entry point compared to sibling flow_choose and other content-specific tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit when-to-use instructions with concrete user phrases: 'CALL THIS FIRST whenever the user opens with an unscoped request' and 'whenever they finish one thing and want another.' It also tells the agent not to ask questions or start work before the user chooses, making the expected flow unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns the one next piece of the storyboard to write, with the handbook text to write it from already attached and the exact fields enumerated. Call this immediately after create_storyboard_draft, and again any time you lose track of where you are. The result is either status WRITE_THIS with a task, or status READY_TO_RENDER when nothing is left. You never need to choose a module, a row or a search query: the queue is ordered for you and the sources are scoped to the module the task belongs to.
| Name | Required | Description | Default |
|---|---|---|---|
| artifact_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully describes behavior: it returns either status WRITE_THIS with a task or READY_TO_RENDER when done, and mentions the attached handbook and scoped sources. This goes beyond a generic getter by disclosing the possible outcomes and the prepackaged context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, all informative, no fluff. The purpose, usage, and outcomes are packed into a compact, well-structured text. Every sentence contributes value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (one param) and the description covers the essential behavioral context and expected outputs, including the two statuses. It lacks detail on the exact task fields (though hinting they are enumerated) and error cases, but given the simplicity and no output schema, it is largely sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description does not mention artifact_id at all, and schema coverage is 0%. The parameter name is somewhat self-explanatory but the description should clarify what artifact it refers to (e.g., the storyboard draft ID). Since the description must compensate for low schema coverage and fails to, this is a notable gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns the next storyboard task with attached handbook text and enumerated fields. It distinguishes from siblings by positioning itself as the immediate follow-up to create_storyboard_draft and the go-to when losing track, unlike get_storyboard or validate_storyboard.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance: 'Call this immediately after create_storyboard_draft, and again any time you lose track of where you are.' It also states the queue is pre-ordered and sources are scoped, eliminating the need to choose modules or queries, which clearly directs when to use this over siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Writes the fields of the task you were given and returns the NEXT task, in the same shape. This is the whole build loop: submit, write what comes back, submit again, until status is READY_TO_RENDER. Pass one entry per field in task.fields, each with the field_id exactly as given. For a field marked requires_citation, pass chunk_ids taken from task.sources -- those chunks are already scoped to the right module, so citing any of them is correct. Nothing is committed if any entry is rejected, so a failed call can be corrected and resent unchanged otherwise.
| Name | Required | Description | Default |
|---|---|---|---|
| note | No | ||
| entries | No | One entry per field, for every section except assessment. | |
| task_id | Yes | The task_id from the task you were given. | |
| lms_rows | No | For an LMS Technical Mapping task only: one row per entry in expected_rows. | |
| questions | No | For an assessment task only: the module's questions. | |
| artifact_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full responsibility for behavioral disclosure. It does mention a critical transactional property: 'Nothing is committed if any entry is rejected, so a failed call can be corrected and resent unchanged otherwise.' It also states it returns the next task. However, it doesn't describe error formats, idempotency, authentication needs, or rate limits, which leaves gaps in full transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured paragraph that front-loads the purpose and then provides critical usage details. No sentence is wasted. It is concise yet comprehensive for the core loop.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (multiple parameter groups for different task types) and absence of an output schema, the description covers the primary usage loop and return shape ('in the same shape'). It doesn't explicitly explain when to use lms_rows vs questions vs entries, but the input schema carries those conditional descriptions. The atomicity note and loop termination condition ('until status is READY_TO_RENDER') provide sufficient context for an agent to operate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 67%, so the description adds meaningful value. It clarifies the 'entries' parameter: 'Pass one entry per field in task.fields, each with the field_id exactly as given.' It also explains chunk_ids usage for citation fields. It doesn't elaborate on lms_rows/questions, but those have schema descriptions. The guidance on chunk_ids and atomicity goes beyond the schema, warranting a strong score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Writes the fields of the task you were given and returns the NEXT task.' This is a specific verb (submit/write) and resource (storyboard task), and it distinguishes from siblings like storyboard_next_task (which likely just fetches the next task) and validate_storyboard (which likely validates without submission). The build-loop framing makes its role unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides explicit usage context: 'This is the whole build loop: submit, write what comes back, submit again, until status is READY_TO_RENDER.' This tells the agent when to invoke it repeatedly. It also gives specific guidance for citation fields: 'For a field marked requires_citation, pass chunk_ids taken from task.sources.' It doesn't explicitly name alternatives or state when not to use it, but the loop context is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Writes the fourteen slides and commits a new version. Submit all fourteen together -- the deck is checked as one for unit coverage. The video half of the package is left untouched. Slide copy must be written from the unit content, not copied out of it.
| Name | Required | Description | Default |
|---|---|---|---|
| note | No | ||
| title | No | ||
| slides | Yes | ||
| package_id | Yes | ||
| base_version | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden. It discloses that it writes and commits a new version, leaves videos untouched, and enforces all-or-nothing submission, plus a content originality constraint. It does not mention error cases or return behavior, but these are not critical given the schema's richness.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences long, front-loaded with the primary purpose, and each sentence adds distinct value—purpose, submission grouping, and content quality. There is no redundant or vague wording.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (nested slides, many fields) and absence of an output schema, the description covers the core operational constraints: all-or-nothing submission, separation from video, and content originality. It does not explain how to obtain package_id or base_version, but these are likely evident from the workflow or schema. The mention of 'fourteen slides' may conflict with schema's 'deck length set by plan,' but this is minor and likely resolved by context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds useful constraints like the fixed count of fourteen slides and the requirement for original content, which are not in the schema. However, the schema itself already includes detailed descriptions for all slide fields, so the description's additional value is moderate. Since schema description coverage from the tool is 0%, it partially compensates but doesn't explain each parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool writes the fourteen slides and commits a new version, which is a specific verb-resource action. It also explicitly distinguishes from the video counterpart by stating 'the video half of the package is left untouched,' thus separating it from sibling tools like submit_module_video.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides key context: all fourteen slides must be submitted together because the deck is checked as one for unit coverage, and slide copy must be original from unit content. This indirectly guides usage (not for video, not individually) but does not explicitly name alternatives like validate_module_package or get_module_slides.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Writes the eighteen 10-second segments and commits a new version. Submit all eighteen together -- they are one film and are checked as one. The slide half of the package is left untouched. Word counts and citation metadata are filled in from the plan and the handbook index; you supply the words and the chunk_ids.
| Name | Required | Description | Default |
|---|---|---|---|
| note | No | ||
| title | No | ||
| segments | Yes | ||
| package_id | Yes | ||
| base_version | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full transparency burden and largely succeeds. It discloses that this tool commits a new version, leaves the slide half untouched, performs unit validation on the 18 segments, and auto-fills word counts and citation metadata. It does not fully disclose failure behavior when validation fails, but it goes well beyond a perfunctory 'submit'.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences, no fluff. Every phrase delivers information: the write/commit action, the atomic batch constraint, the exclusion of the slide half, and the automatic vs. user-supplied fields. The structure front-loads the most critical information and proceeds in logical order.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a high-complexity tool with no output schema, the description does an adequate job covering what gets written, what is excluded, what is auto-filled, and what the caller must provide. The main gaps are version conflict behavior given base_version, validation failure semantics, and any side effects beyond committing a new version (e.g., triggering downstream workflows).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% at the top level, so the description must compensate. However, it only explains the segments conceptually ('you supply the words and the chunk_ids') and leaves package_id, base_version, note, and title completely unexplained. In particular, base_version is an integer likely involved in concurrency control or versioning, and its omission is a significant gap. The eighteen-segment requirement clarifies the array shape but not individual field semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The first sentence ('Writes the eighteen 10-second segments and commits a new version') states a specific action on a specific resource. The description also differentiates this tool from siblings like submit_module_slides ('The slide half of the package is left untouched') and clarifies the atomic, all-or-nothing semantics that make this tool unique.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description conveys strong usage context: submit all segments at once because they are checked as one film, and only the words and chunk_ids need to be supplied by the agent. However, it does not name alternative tools for cases when the description is violated (e.g., partial submission) or explicitly state when not to use this tool beyond the implied slide vs. video split.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Writes the authored scenes into a transcript and commits a new version. Scenes replace the previous set wholesale, so submit the complete script each time; base_version is the version you read, and a stale one is refused rather than overwriting newer work. Word counts and citation metadata are filled in from the plan and the handbook index -- you supply the words and the chunk_ids only.
| Name | Required | Description | Default |
|---|---|---|---|
| note | No | Recorded against this version. | |
| title | No | ||
| scenes | Yes | ||
| base_version | Yes | ||
| transcript_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does so richly. It discloses that scenes replace the prior set entirely, that a stale base_version is refused (protecting concurrent work), and that word counts/citation metadata are auto-filled. This goes beyond basic mutation disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three dense sentences with no filler. The action is front-loaded, followed by the critical caveat about replacement and a succinct explanation of what the system fills in. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex submission tool with nested objects and no output schema, the description covers the essential semantics: commit behavior, destructive replacement, optimistic concurrency, and metadata handling. It leaves no significant ambiguity about how to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is low (20%), so the description compensates by explaining key parameters: 'base_version is the version you read' and 'you supply the words and the chunk_ids only' clarifies scenes/sources. It does not annotate transcript_id, note, or title, but these are either obvious or optional.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Writes the authored scenes into a transcript and commits a new version.' It clearly distinguishes this from sibling tools like get_video_transcript (read-only) and validate_video_transcript (validation), establishing it as the write/commit operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage context: 'Scenes replace the previous set wholesale, so submit the complete script each time; base_version is the version you read' implies you should fetch the current version before submitting. It does not explicitly name alternatives, but the guidance around complete scripts and optimistic concurrency is strong.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Checks the package mechanically: all 18 segments and 14 slides written, every segment's narration short enough to fit its ten seconds, notes within their budget, every unit of the module covered by both the video and the deck, every citation resolving to a chunk of this module, and no reference to the handbook, a page, a figure or a unit number in any delivered text. Whether the writing is good is your judgement, not this tool's.
| Name | Required | Description | Default |
|---|---|---|---|
| version | No | ||
| package_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It explicitly enumerates every validation check performed and states the tool's limitation regarding writing quality. This fully discloses behavior for an agent, leaving no ambiguity about what will happen when invoked.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single dense sentence that front-loads the action ('Checks the package mechanically') and then enumerates specific checks. It is efficient and every clause adds information, though the enumeration is long. No fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no output schema and no annotations, the description covers the tool's scope and exclusions thoroughly. However, it does not state what the tool returns (e.g., pass/fail, list of errors), which would be useful for agents deciding how to interpret the result. Overall, quite complete but misses the output structure.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description does not mention the parameters at all. The two parameters (package_id, version) are minimally described by their names, but the description adds no semantic meaning beyond what the schema already shows. With no param descriptions, this is a gap for a tool with 0% coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Checks the package mechanically' and enumerates exact criteria (18 segments, 14 slides, narration timing, etc.). It distinguishes itself from sibling validation tools by focusing on the full module content package with specific, mechanical checks.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clarifies what the tool does (mechanical validation) and what it does NOT do (judge writing quality), but offers no explicit guidance on when to choose this over sibling tools like validate_timing_allocation or validate_storyboard. The intended context is implicit rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Runs all three validation levels and returns structured findings. Level 1 checks traceability mechanically: every content field carries a citation, each citation resolves to a real chunk in the correct course and chapter, and the wording measurably overlaps the cited text. Level 2 checks timing arithmetic against the Timing Allocation Document. Level 3 checks structural conformance to the template. Findings are reported, never auto-fixed -- decide how to address each one and resubmit via set_storyboard_content. Note that low_grounding_overlap is a lexical signal only, not a judgement about meaning.
| Name | Required | Description | Default |
|---|---|---|---|
| version | No | ||
| artifact_id | Yes | ||
| skip_content | No | Run only timing and structure checks. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the transparency burden. It explicitly states findings are 'reported, never auto-fixed' and cautions that low_grounding_overlap is 'a lexical signal only, not a judgement about meaning.' It does not cover failure modes or return structure, but the key side-effect-related and interpretive behaviors are disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core action ('Runs all three validation levels and returns structured findings'), then efficiently enumerates the levels. Every sentence adds value: the no-auto-fix note and the lexical-signal caution are both important and non-redundant.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description provides a thorough behavioral and workflow context for a validation tool with no output schema and no annotations: it explains what each level checks, that findings require manual resolution, and how to proceed via set_storyboard_content. It is slightly incomplete in not describing the structure of the returned findings or the artifact_id parameter, but overall it is sufficiently complete for selecting and invoking the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 33%, and the description does not explain artifact_id or version. The level breakdown indirectly helps understand skip_content (which skips Level 1), but the required artifact_id remains undocumented in both schema and description. The description thus fails to compensate for the low schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool 'runs all three validation levels' for the storyboard, enumerating precisely what each level checks (traceability, timing arithmetic, structural conformance). This distinguishes it from siblings like validate_timing_allocation and validate_module_package with a specific verb and resource.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context: this is the full validation tool, and findings are not auto-fixed; you must decide and resubmit via set_storyboard_content. It does not explicitly name alternatives or say when not to use it, but the phrase 'all three validation levels' and the resubmission guidance make the usage context obvious.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Checks the Timing Allocation Document's internal arithmetic: unit minutes sum to their module total, module totals sum to the stated course total, and each unit's stated hours match its stated minutes. Reports discrepancies without repairing them.
| Name | Required | Description | Default |
|---|---|---|---|
| course_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the transparency burden. It discloses the exact validation checks performed and explicitly states that discrepancies are reported without being repaired, conveying a read-only intent. It stops short of describing the exact report format or behavior if validation fails.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two tight sentences. The first enumerates the concrete validation rules in a front-loaded way, and the second clarifies scope by stating the tool does not repair discrepancies. No filler or redundant phrasing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with one parameter, no output schema, and no annotations, the description is fairly complete: it lists the validation categories and states the outcome (reports discrepancies without repairing). It only lacks detail on the exact return format, but 'reports discrepancies' provides enough orientation for this simple validation use case.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and there is one required parameter (course_id). The description does not explicitly explain what course_id represents or how it selects the Timing Allocation Document to validate; it only mentions a 'course total' indirectly. The description does not sufficiently compensate for the empty schema field.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Checks') with a clear resource ('Timing Allocation Document') and precise scope: sums and hour/minute consistency. It also distinguishes itself from the sibling get_timing_allocation, which retrieves, not validates.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies when to use this tool: when you need to verify arithmetic consistency rather than retrieve or modify a timing document. It explicitly states it reports discrepancies and does not repair them, which provides a useful exclusion even though no alternative tools are named.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Checks a transcript mechanically: every planned scene written, each scene within its word budget, the whole script reading back in about the requested duration, and every citation resolving to a chunk of this unit of the Participant Handbook. Whether the narration is a fair rendering of the source is your judgement, not this tool's. Findings are reported and never auto-fixed.
| Name | Required | Description | Default |
|---|---|---|---|
| version | No | ||
| transcript_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses that it reports findings and never auto-fixes, indicating a read-only validation behavior. It also clarifies the scope of checks. It does not mention required permissions or output format, but it covers key behavioral traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each informative, no fluff, front-loaded with the tool's primary function.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema and no annotations, so the description should indicate return behavior and parameter semantics. It mentions 'Findings are reported' but no structure. It omits the optional version param entirely. For a tool with two params, it is not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% and the description does not mention parameters. The 'version' parameter is unexplained, and 'transcript_id' is implied but not elaborated. With low schema coverage, the description should compensate, but it does not.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description specifies the exact checks: planned scenes written, word budget, duration, and citation resolution. It also clarifies what it does not check (fair rendering), distinguishing it from subjective review tools and sibling validation tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It implies use for mechanical validation of a transcript. It explicitly states the tool does not judge narrative fairness, so users know not to rely on it for that. However, it does not name alternative tools or explicit when-not conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0analyze_storyboard_templatecreate_storyboard_draftexport_module_packagefind_ph_unitflow_chooseget_course_manifestget_document_pageget_flowget_module_content_specget_module_crosswalkget_module_packageget_module_package_historyget_module_slidesget_module_sourceget_module_subtitlesget_module_unitsget_module_video_scriptget_ph_outlineget_ph_unit_sourceget_source_chunkget_storyboardget_storyboard_field_specget_storyboard_historyget_timing_allocationget_video_transcriptget_video_transcript_historyget_video_transcript_specingest_course_documentslist_courseslist_module_packageslist_storyboardslist_video_subjectslist_video_transcriptsmodify_storyboard_timingplan_module_contentplan_video_transcriptread_ph_unitrender_module_pptxrender_storyboard_docxrollback_storyboardsearch_course_contentset_assessment_contentset_module_storyset_storyboard_contentstart_flowstoryboard_next_taskstoryboard_submit_tasksubmit_module_slidessubmit_module_videosubmit_video_transcriptvalidate_module_packagevalidate_storyboardvalidate_timing_allocationvalidate_video_transcriptScored across 54 tools
Despite the high tool count, most tools target a distinct resource and action, and the descriptions are unusually explicit about which flow each belongs to. A few pairs—such as get_ph_unit versus get_ph_unit_source, or plan_module_content versus plan_video_transcript—require careful reading to disambiguate, but the intent is clear.
The huge majority of tool names follow a recognizable get_/list_/set_/submit_/validate_ verb + noun pattern in snake_case, which is predictable. Minor deviations like flow_choose, storyboard_next_task, and storyboard_submit_task break the pattern enough to prevent a perfect score.
At 54 tools, this is far beyond the typical well-scoped MCP surface and crosses the rubric's explicit 50+ extreme-mismatch threshold. Even though each tool appears to have a purpose, the sheer number would overwhelm an agent's tool-selection space and create unnecessary selection and orchestration risk.
The three main authoring flows—storyboards, module packages, and video transcripts—are covered end-to-end with plan, submit, validate, retrieve, render, export, and history tools. Minor gaps include the lack of rollback for module and transcript versions, and no delete or archive operations, though these are partially by design given the append-only history model.
MCP server for generating rough-draft project plans from natural-language prompts.
MCP Server for Slima - AI Writing IDE for Novel Authors with AI Beta Reader.
Presentations.AI MCP server — create designed slide decks from a topic, text, or document.
Generate and manage Storydoc presentations from any MCP-compatible client.
