Voice Agent Linter: catch it before the caller does.

high

The agent is never told today’s date

A language model has no clock. Asked to book "Thursday", it fills in a year from its training data, often one or two years in the past, and a booking tool that checks against the real calendar refuses every date it is offered. The transcript reads like a broken integration or a lead-time rule, so the real cause is easy to miss, and it does not show up in testing done the same week the prompt was written.

Sources: Vapi docs: dynamic variables ({{now}}, {{date}}, {{year}} and the LiquidJS date filter with a timezone) (read 2026-10-11); Retell docs: dynamic variables ({{current_time}}, {{current_time_[timezone]}}, {{current_calendar}}) (read 2026-10-11); ElevenLabs Agents docs: system dynamic variables ({{system__time}}, {{system__time_utc}}, {{system__timezone}}) (read 2026-10-11)

medium

A date is written without its year

A date with no year ("closed March 3", "Wed, Aug 20") is completed by the model, which guesses the year. When the guess lands in the past, every downstream check (calendar, booking, holiday rule) fails for a reason the agent cannot see. The same applies to dates a tool returns: if they carry no year, the model invents one before sending them back.

medium

A tool takes a date with no format

A tool parameter called date, day or time with no stated format lets the model construct the value itself, which is where the wrong year and the wrong timezone come from. A stated format plus an instruction to copy dates from the availability tool closes it.

medium

A phone number is written as numerals

Whatever the prompt writes, the model tends to repeat, and text to speech reads numerals as quantities: 2023 becomes a year, 200 becomes "two hundred", a lone 0 can come out as a sound that is not a word. A caller writing down a number cannot tell which digit was garbled.

medium

An email address is written the way it is typed

An address like info@acme-co.com is read aloud with symbols and run-together words that callers mishear. Hyphens are often read as "minus". The spoken form has to be written out so the agent says it the same way every time.

low

A web address is written with its scheme

Text to speech reads "https://www." letter by letter or as "h t t p s colon slash slash", which nobody can act on over the phone.

low

A range is written with a hyphen

Ranges like "9-5" or "Mon-Fri" are read as "nine minus five" or skipped, depending on the voice. Hours are the most common thing a caller asks for.

low

A long number is written as digits

A zip code, account number or code written as digits is read as a quantity ("fifty-nine thousand nine hundred one"). Identifiers have to be read digit by digit to be written down.

low

The prompt asks for formatted output

Bullet points, bold, headings, tables and emojis make no sense spoken and some voices read the symbols aloud. Lists read aloud also lose callers.

high

The agent collects names or emails with no spelling protocol

Speech recognition turns a name or an email said at speed into the nearest ordinary word, so the agent writes down something that sounds right and is wrong. Measured on recordings run back through speech recognition: anchored letters ("b as in boy") came back letter perfect at studio and phone quality, bare letters mostly survived, and letter sounds ("bee", "ay") came back wrong. An agent with no protocol also tends to read the value back several ways, and the caller hears only the broken one.

medium

Spelling uses bare letters or letter sounds

Spelling "one character at a time" or with letter sounds ("bee, eye, zee") is the version that failed in measurement: "ay" is heard as I, and the corruption sounds careful, so nobody catches it.

low

English spelling anchors in a multilingual agent

An agent that answers in the caller’s language but spells with English anchors ("b as in boy") gives a Spanish speaker nothing to hold on to. The anchors have to travel with the language, as does any pronunciation respelling.

critical

The prompt tells the agent to pass as human

An AI agent that says it is a person, or is told never to admit it is AI, deceives the caller. The FCC treats AI-generated voices as artificial voices under the TCPA, Utah requires disclosure when a consumer asks, and California requires bots used to sell to disclose that they are bots.

Sources: FCC Declaratory Ruling FCC 24-17 (Feb. 8, 2024): AI-generated voices are "artificial" voices under the TCPA (read 2026-10-11); Utah Code 13-75-103 and 13-75-104 (S.B. 226, 2025, effective May 7, 2025): disclose generative AI when a consumer asks; safe harbor for disclosure at the outset (read 2026-10-11); California Business and Professions Code 17941: bots used to sell goods or services must disclose that they are bots (read 2026-10-11)

high

No AI disclosure

Neither the prompt nor the opening line says the caller is talking to an AI. Disclosure at the start of the call is the safe harbor under Utah’s law, the FCC treats AI voices as artificial voices for outbound calls, and callers who find out later trust the business less. When the agent only discloses on request, outbound calls to strangers are where it matters most.

Sources: Utah Code 13-75-103 and 13-75-104 (S.B. 226, 2025, effective May 7, 2025): disclose generative AI when a consumer asks; safe harbor for disclosure at the outset (read 2026-10-11); FCC Declaratory Ruling FCC 24-17 (Feb. 8, 2024): AI-generated voices are "artificial" voices under the TCPA (read 2026-10-11); 47 CFR 64.1200(b): artificial or prerecorded voice calls must identify the business at the start and give a phone number (read 2026-10-11)

medium

No recording notice

Voice platforms record and transcribe calls, often by default. Federal law and most states allow recording with one party’s consent, but California and several other states require every party to consent to recording a confidential call, and callers can be in any state. A short notice in the opener covers it.

Sources: California Penal Code 632: recording a confidential communication requires the consent of all parties (read 2026-10-11); 18 U.S.C. 2511(2)(d): federal one-party consent to record (read 2026-10-11); Vapi API reference: create assistant (firstMessage, firstMessageMode, maxDurationSeconds default 600, endCallPhrases, artifactPlan.recordingEnabled default true) (read 2026-10-11)

medium · vapi

A tool has a scripted start line

When the model speaks its own lead-in and calls a tool in the same turn, and the tool also has a scripted "request start" line, the two collide. Observed on live calls: the tool returned in under a second, no model request followed, and the caller sat in silence until they hung up. Empty start lines with a model-spoken beat, or a scripted line with no model lead-in, both worked; the combination did not.

Sources: Vapi docs: custom tools (function name, description and JSON Schema parameters; request start, complete, failed and delayed messages; results returned as strings) (read 2026-10-11)

medium

The prompt scripts stall phrases

Scripted stalls ("hold on a sec", "let me check on that", "bear with me") fill a gap the caller would not have noticed, sound like a dropped call on a phone line, and on some platforms collide with tool messages to wedge the turn.

medium · vapi, retell, elevenlabs

The agent waits in silence when the call connects

With no first message, the agent waits for the caller to speak first. On an inbound business line the caller expects a greeting, so both sides wait and many callers hang up. Vapi documents that an unspecified firstMessage makes the assistant wait for the user; an empty Retell begin_message or ElevenLabs first_message does the same.

Sources: Vapi API reference: create assistant (firstMessage, firstMessageMode, maxDurationSeconds default 600, endCallPhrases, artifactPlan.recordingEnabled default true) (read 2026-10-11); Retell API reference: create Retell LLM (general_prompt, begin_message, general_tools) (read 2026-10-11); ElevenLabs API reference: create agent (conversation_config.agent.first_message, prompt, tools; tts.model_id) (read 2026-10-11)

low

The opener is long

Callers start talking over a long greeting, interruptions cut it off, and the disclosure or the question at its end gets lost.

medium

A tool has no description

The model decides when to call a tool, and what to put in it, from its description. Without one it calls the tool at the wrong time or not at all.

high

A tool parameter has no type

An untyped parameter can arrive as anything, and some platforms drop the whole argument object when the schema is not one they handle.

low

A tool parameter has no description

The parameter name is the only guide the model has, so formats and allowed values get guessed.

high

A required parameter is not defined

The schema requires a field that has no definition under properties, so a valid call can never be made, or the platform rejects the schema.

low

A tool does not say what it returns

When neither the tool description nor the prompt names the fields a tool returns, the model guesses at the result, and a refusal or partial result is read as success. Tools that return explicit named fields (booked: true or false, a reason, the open times) let the agent answer from facts.

high · vapi

An enum inside array items (Vapi)

A Vapi function parameter of type array whose items carry an enum was observed to arrive at the webhook as an empty object: not just that field, every field, including required ones. The config saved, read back and listed cleanly; the only trace was empty arguments in the call history. A plain top-level string enum works. This is an observed platform behavior, not one the docs describe.

Sources: Vapi docs: custom tools (function name, description and JSON Schema parameters; request start, complete, failed and delayed messages; results returned as strings) (read 2026-10-11)

high · vapi

Flat analysisPlan prompt keys (Vapi)

analysisPlan.summaryPrompt, structuredDataPrompt and structuredDataSchema are accepted and stored, but an assistant created with them came back with summaryPlan and successEvaluationPlan disabled, so call.analysis.summary was empty on every real call. A synthetic webhook test passes because the test supplies its own summary.

Sources: Vapi docs: call analysis (summaryPlan, structuredDataPlan, successEvaluationPlan stored in call.analysis; structured outputs recommended for new setups) (read 2026-10-11); Vapi docs: structured outputs (read 2026-10-11)

medium · vapi

An analysis plan is defined but disabled (Vapi)

A plan with messages and enabled: false never runs, so the dashboard shows the prompt and the call shows nothing.

Sources: Vapi docs: call analysis (summaryPlan, structuredDataPlan, successEvaluationPlan stored in call.analysis; structured outputs recommended for new setups) (read 2026-10-11)

medium · vapi

An analysis plan never sees the transcript (Vapi)

Plan messages are templates. Without {{transcript}} in them, the analysis model receives the instruction and none of the call, and answers anyway.

Sources: Vapi docs: call analysis (summaryPlan, structuredDataPlan, successEvaluationPlan stored in call.analysis; structured outputs recommended for new setups) (read 2026-10-11)

medium

ElevenLabs Turbo voice model

On one production voice, eleven_turbo_v2_5 inserted words that were not in the text in about 8 of 96 takes, including a duplicated digit inside an email readback, which defeats any spelling protocol. Changing stability or speed did not move the rate. eleven_multilingual_v2 came back clean on 84 takes; streaming latency optimization at level 2 kept the extra delay to about 130 milliseconds. Measured on one voice: test yours.

Sources: ElevenLabs docs: models (Turbo, Flash and Multilingual families) (read 2026-10-11)

high

No way to reach a person

Every agent meets a caller it cannot help: an emergency, an angry customer, a question outside its knowledge. With no transfer and no message-taking path, it either loops or invents an answer.

Sources: Vapi docs: default tools (transferCall, endCall) (read 2026-10-11); Retell docs: transfer call function (read 2026-10-11); ElevenLabs Agents docs: transfer to human system tool (read 2026-10-11)

medium

The agent cannot end the call

Without an end-call tool or phrase, the agent fills silence after the caller is done, or the call runs until the platform’s timeout, which costs minutes and sounds broken.

Sources: Vapi docs: default tools (transferCall, endCall) (read 2026-10-11); Retell docs: end call function (read 2026-10-11); ElevenLabs Agents docs: end call system tool (read 2026-10-11)

low · vapi

Calls are cut at ten minutes (Vapi default)

maxDurationSeconds defaults to 600. A long intake or a caller on hold is cut mid-sentence at ten minutes.

Sources: Vapi API reference: create assistant (firstMessage, firstMessageMode, maxDurationSeconds default 600, endCallPhrases, artifactPlan.recordingEnabled default true) (read 2026-10-11)

medium · vapi

Outbound calling from a free Vapi number

The prompt reads as an outbound caller and the config uses a Vapi-provided number. Vapi documents that free Vapi numbers are inbound only, and outbound calls through Vapi-provided numbers have been refused after a small daily count. Calls fail before the agent ever speaks.

Sources: Vapi docs: free telephony ("Free Vapi numbers are inbound only") (read 2026-10-11)

high

An unfilled placeholder

Template leftovers like [Business Name], {company}, XXX or TBD are read aloud to callers. Platforms fill double-brace variables only; single braces and brackets are spoken literally.

critical

A secret is in the prompt

Anything in the prompt or a tool description can be repeated to a caller who asks the right way. API keys, bearer tokens and passwords belong in server-side config.

low

The prompt is very long

Every turn of a voice call sends the whole prompt. Very long prompts add latency to every reply and bury rules in the middle, where models weight them least.

medium

Two instructions contradict each other

When one line says always and another says never about the same thing, the model picks one per call, so behavior changes from call to call.