No description can guarantee that a video ranks. Search results and recommendations depend on the viewer, the competition, how people respond to the video, and signals that YouTube does not publish. A guide that promises a ranking, or a percentage gain from a template, is selling something it cannot deliver.
A description still matters. It tells viewers what the video covers before they commit, it holds the chapter list, and it is part of the metadata YouTube reads to understand the video. An AI tool can draft one quickly from your transcript. The risk is that a quick draft says things the video does not contain, repeats itself, or breaks a rule. This guide shows how to use a draft as raw material and check it before publishing. If you have not reviewed your captions yet, the local Whisper captions guide covers getting a reviewed transcript to work from.
What YouTube says matters
YouTube's help page on tags is direct about priorities. It says a video's title, thumbnail, and description are more important for discovery than tags, because those main items help viewers decide what to watch. It says tags can help when the topic is commonly misspelled and otherwise play a minimal role. That is a reason to spend your effort on the description and not on a long tag list.
The same discipline applies to accuracy. YouTube's spam policy lists malicious clickbait among its examples: titles, thumbnails, or descriptions meant to trick people into clicking a video that does not deliver what was promised. It also lists engagement manipulation, including "sub-for-sub" schemes and offering rewards for likes, views, or subscribers, while noting that it is fine to ask viewers to like, comment, or subscribe. And it names automated or synthetic mass-production, using tools or AI to churn out high volumes of similar content with minimal changes, as a violation. The page also says disclosing AI use is not a free pass to break other rules.
Together, these point to a plain standard for an AI-drafted description: it should describe the video you made, in words that are not stuffed or templated, and it should not promise anything the video does not contain.
A workflow for an AI-assisted description
- Start from a reviewed transcript. The tool should see what you actually said. Give it the corrected captions, not a guess.
- Ask for a draft, with constraints. Tell it to use only information in the transcript, to avoid claims about results, and to propose chapter titles with the transcript lines they came from.
- Fix the opening yourself. Write one or two sentences that say what the video answers. Put the most useful information first, then check how the description looks on your own upload screen, because layouts change.
- Build the chapter list from real timestamps. The tool cannot know your timestamps unless you give them. Copy them from your editor.
- Lint the draft. Run the script below against your transcript and the video length.
- Read it as a viewer. If a line promises something you cannot point to in the video, delete it.
A prompt for step 2, as plain text:
Using only the transcript below, draft a YouTube description.
Rules: two sentences saying what the video answers; no claims about results
or income; chapter titles taken from the section headings I give you; at most
three hashtags, each of which is spoken in the video. If something is not in
the transcript, do not mention it.
Section headings and timestamps: [paste]
Transcript: [paste]
The constraint "do not mention it" reduces invented content. It does not eliminate it, which is why the checks below exist.
Chapters: the one part with firm rules
YouTube's video chapters help page gives specific requirements for adding your own chapters in the description. The first timestamp must start at 00:00. You need at least three timestamps in ascending order. The minimum length for a chapter is 10 seconds. A manual chapter list overrides automatic chapters, and automatic chapters may not be available for every video, for example when the channel has active strikes.
Those rules are exact enough to check with code. The script below parses timestamps from a description, applies the three rules, flags a last timestamp past the end of the video, flags repeated lines and a word that appears too often, counts hashtags, and, if you provide a transcript, flags numbers and hashtag words in the description that never appear in it. It uses only the standard library.
"""desc_lint.py: check a YouTube description draft against rules you can verify. Standard library only.
python desc_lint.py description.txt --duration 8:12 [--transcript transcript.txt]
Checks: chapter timestamps (first is 00:00, at least three, ascending, each at least 10 seconds,
none past the video length), repeated lines, a word repeated far too often, many hashtags, and, when
a transcript is given, numbers and hashtag words in the description that never appear in the transcript.
Exit code 0 = clean, 1 = flags, 2 = bad input.
"""
import argparse
import re
import sys
from collections import Counter
STAMP = re.compile(r"^\s*((?:\d{1,2}:)?\d{1,2}:\d{2})\s+(.+?)\s*$")
def to_sec(stamp):
parts = [int(p) for p in stamp.split(":")]
sec = 0
for p in parts:
sec = sec * 60 + p
return sec
def chapters(text):
return [(to_sec(m.group(1)), m.group(1), m.group(2)) for m in
(STAMP.match(l) for l in text.splitlines()) if m]
def lint(text, duration, transcript=None, max_hashtags=5, word_limit=6):
flags = []
ch = chapters(text)
if ch:
if len(ch) < 3:
flags.append("only %d timestamps, chapters need at least 3" % len(ch))
if ch[0][0] != 0:
flags.append("first timestamp is %s, it should be 00:00" % ch[0][1])
for (a, sa, _), (b, sb, _) in zip(ch, ch[1:]):
if b <= a:
flags.append("timestamps not ascending: %s then %s" % (sa, sb))
elif b - a < 10:
flags.append("chapter at %s lasts %d seconds, minimum is 10" % (sa, b - a))
if duration and ch[-1][0] >= duration:
flags.append("last timestamp %s is past the end of the video" % ch[-1][1])
if duration and ch[-1][0] < duration and duration - ch[-1][0] < 10:
flags.append("last chapter lasts under 10 seconds")
lines = [l.strip().lower() for l in text.splitlines() if l.strip()]
for line, n in Counter(lines).items():
if n >= 2 and len(line) > 12:
flags.append("line repeated %d times: %r" % (n, line[:40]))
words = [w for w in re.findall(r"[a-z']{4,}", text.lower())]
for w, n in Counter(words).most_common(3):
if n > word_limit:
flags.append("word %r appears %d times, which may read as stuffing" % (w, n))
tags = re.findall(r"#\w+", text)
if len(tags) > max_hashtags:
flags.append("%d hashtags, more than %d" % (len(tags), max_hashtags))
if transcript is not None:
tl = transcript.lower()
for num in sorted(set(re.findall(r"(?<![:\d])\d+(?:[.,]\d+)?(?![:\d])", re.sub(STAMP.pattern, "", text, flags=re.M)))):
if num not in tl:
flags.append("number %s in the description is not in the transcript" % num)
for tag in sorted(set(t.lstrip("#").lower() for t in tags)):
if tag not in tl and tag not in tl.replace(" ", ""):
flags.append("hashtag #%s never appears in the transcript" % tag)
return flags
def main():
ap = argparse.ArgumentParser()
ap.add_argument("path")
ap.add_argument("--duration", help="video length as M:SS or H:MM:SS")
ap.add_argument("--transcript")
a = ap.parse_args()
try:
text = open(a.path, encoding="utf-8-sig").read()
transcript = open(a.transcript, encoding="utf-8-sig").read() if a.transcript else None
duration = to_sec(a.duration) if a.duration else None
except (OSError, ValueError) as err:
print("bad input: %s" % err, file=sys.stderr)
return 2
flags = lint(text, duration, transcript)
for f in flags:
print("FLAG", f)
print("%d flags" % len(flags))
return 1 if flags else 0
if __name__ == "__main__":
sys.exit(main())
What the script did on synthetic drafts
A synthetic 6 minute bike repair video had a transcript and two description drafts. The first draft had an opening sentence, four chapters at 00:00, 00:45, 02:30, and 05:10, and two hashtags. It passed every rule except one: the hashtag #bikerepair was flagged because nobody says "bike repair" in the transcript. Whether to keep it is a judgment call, and the flag makes you make it.
The second draft was written to fail. The script returned 15 flags, including a first timestamp of 0:05, two chapters shorter than 10 seconds, a last timestamp of 9:00 that sits past the end of a 6 minute video, a line repeated twice ("Subscribe for 500 free parts"), the word "brake" appearing seven times, eight hashtags, the number 500 and the year 2026 appearing in the description but never in the transcript, and six hashtags that were never spoken. A missing or unreadable file returned a separate exit code.
What the script cannot do: it does not know whether your chapter titles describe the right sections, whether the opening is clear, or whether the video is any good. A clean pass means these mechanical rules hold.
Tags, hashtags, and links
Tags matter little. Add a few for misspellings or alternate names if they apply, and do not fill the field. Hashtags in the description show as links, and a few that match what the video covers are fine. A long block of unrelated hashtags looks like stuffing, and the script flags more than five by default, which is an example limit you can change.
Links need two checks. First, they should go where the description says they go. Second, if a link is paid, sponsored, or an affiliate link, follow the disclosure rules that apply to you on YouTube and in your country. Those rules sit outside this guide, so check the platform's current requirements and your local advertising regulator.
A worked example
A hypothetical creator finishes the rubbing-brake video. They review the Whisper transcript, fix two mis-heard part names, and give an AI tool the transcript, the section headings, and the timestamps from their editor. The draft comes back with a decent opening, five chapters, and a line saying "learn the secret trick mechanics don't want you to know." The creator deletes that line, because no secret trick appears in the video. The linter flags a six-second chapter, so two sections are merged. The creator rewrites the opening to say what the viewer will be able to do, checks that each hashtag is something said on screen, and uploads. After a couple of days they look at the retention report to see whether viewers drop at the chapter boundaries, and use that to adjust the next video, not the description.
Mistakes to avoid
- Keyword stuffing. Repeating a phrase will not help, and it reads badly.
- Promising what the video does not contain. This is the pattern the spam policy calls out.
- Copying one template across every video. Near-identical descriptions on many videos look mass-produced.
- Trusting AI timestamps. A model cannot see your video, so any timestamps it makes up are guesses.
- Chasing a ranking. Measure whether viewers find what the description says, using retention and impressions data, and avoid concluding that a description caused a result after one video.
Limits
YouTube's pages change. The chapter rules, tag guidance, and spam policy above were read from the current Help pages, and they can be updated at any time. The script checks the rules it knows. It does not check policies it does not model, such as advertiser-friendly guidelines or copyright.
A next step
Take your most recent video. Rewrite the first two sentences of its description so they say what the video answers. Rebuild the chapter list from your editor's timestamps, then run the linter with the transcript. Fix every flag you agree with, and note the ones you chose to keep and why. If you are planning a whole channel, the launch plan shows where descriptions fit in the larger process.
Sources
- YouTube Help, Add tags to your YouTube videos: title, thumbnail and description matter more than tags, and tags play a minimal role.
- YouTube Help, Spam policy: misleading metadata and malicious clickbait, engagement manipulation, mass-produced automated content, and AI disclosure not being a free pass.
- YouTube Help, Video chapters: the 00:00 start, three timestamps in ascending order, 10 second minimum, override of automatic chapters, and automatic chapter limits.

