Troubleshooting

If your sub agent gives weak or inconsistent results, you usually do not need a full prompt rewrite. Start by matching symptoms, apply one targeted prompt fix, and testing again.

Quick symptom picker

If you see this	Start with
Silent assumptions or over-questioning	Ambiguity and assumptions
Conflicting sources handled poorly	Evidence and source quality
No escalation when blocked	Decision boundaries and risk
Long, repetitive responses with buried findings	Output clarity and structure
Only some list items processed	Deterministic operations
Date filtering is inaccurate	Deterministic operations

Copy-paste guardrails by category

Use these snippets as starting points.

Common issues and fixes

Ambiguity and assumptions

What you see: Silent assumptions, fabricated defaults, no clarification.

Why it happens: The prompt says what to do, but not when to pause and ask.

Fix:

Add: "If requirements are ambiguous and the decision is high impact, ask before proceeding."
Add: "If you proceed with assumptions, state them explicitly."

What you see: Repeated low-stakes questions and slow progress on reversible decisions.

Why it happens: The prompt does not define when asking is required versus optional.

Fix:

Add ask policy: ask only for high-impact ambiguity or preference-sensitive decisions.
Add proceed policy: for low-risk decisions, proceed with labeled assumptions.

What you see: New feedback causes the agent to ignore earlier goals and constraints.

Why it happens: The prompt does not include continuity guidance.

Fix:

Add: "New input adds context; it does not erase prior requirements."
Add: "If new input conflicts with prior constraints, surface the conflict before proceeding."

What you see: Output depends on multiple hidden assumptions that were never validated.

Why it happens: The prompt does not require explicit assumption disclosure.

Fix:

Add: "When assumptions affect outcome, list them explicitly before final recommendations."
Add: "If assumptions stack, pause and request confirmation before further work."

Evidence and source quality

What you see: Conflicting sources are treated as agreement; alternatives are not named.

Why it happens: The prompt does not explain how to handle ambiguous or conflicting evidence.

Fix:

Add: "When sources conflict, state the conflict and provide options with tradeoffs."
Add: "Separate direct evidence from inference."

What you see: Low-trust examples are used instead of official docs or established repo patterns.

Why it happens: The prompt does not define source priority.

Fix:

Add source priority guidance, for example: official docs -> established repo patterns -> examples -> blog posts.
Add: "Call out when applying guidance outside its original context."

What you see: Plausible but unverified claims are presented confidently.

Why it happens: The prompt does not allow uncertainty language, so the agent guesses.

Fix:

Add: "'I don't know' is valid when confidence is low."
Add: "Do not invent missing details; state what must be verified."

Decision boundaries and risk

What you see: The agent tries to answer everything, including out-of-scope decisions.

Why it happens: The prompt does not define escalation boundaries.

Fix:

Add explicit escalation criteria: out-of-scope requests, low confidence on high-impact decisions, missing permissions.
Add expected escalation output: what is blocked, why, and what is needed to continue.

What you see: Suggestions are treated as requirements, or hard requirements are ignored.

Why it happens: Directive strength is not defined consistently.

Fix:

Define terms once: must = non-negotiable, should = strong default, consider = optional.
Rewrite ambiguous constraints to use one of those terms consistently.

What you see: One option is presented even when multiple valid options exist.

Why it happens: The prompt does not require tradeoff framing when uncertainty is high.

Fix:

Add: "When multiple valid options exist, present options with tradeoffs."

Output clarity and structure

What you see: Long preambles, repeated phrasing, and key findings that are hard to locate.

Why it happens: The prompt does not define a clear output shape.

Fix:

Add a strict output format with ordered headings.
Add verbosity limits, for example: "Lead with 2-5 key bullets, then details."

Deterministic operations

What you see: You give the agent a list of 10 companies and ask it to call a tool or sub agent for each one, but only 3-5 get processed.

Why it happens: LLMs are not reliable iterators. When asked to loop through a list and perform an action for each item, they often stop early, skip items, or lose track of progress. This is a fundamental limitation of how LLMs process lists.

Fix:

Do not rely on the LLM to iterate. Instead, use programmatic iteration in a function tool from a separate agent which calls the sub agent using a webhook.
The function tool accepts the list, loops through each item in code, and calls the sub agent via webhook once per item.
The calling agent calls the function tool once with the full list; the tool handles the iteration deterministically.

What you see: You ask for "messages from the past 24 hours" but the agent returns messages from days ago, or misses recent ones. Date comparisons are inconsistent.

Why it happens: LLMs struggle with date/time reasoning. They may misparse timestamps, miscalculate relative dates ("past 24 hours"), or inconsistently compare date formats. This is especially problematic when filtering large result sets.

Fix:

Move date filtering into the tool itself. Add date parameters to the tool schema.
Have the tool compute the date range and filter results before returning them to the agent.
The agent's job is to extract the user's intent ("past 24 hours") and pass it as a parameter; the tool does the actual filtering.

Adding fixes to your prompt

You can add these guardrails in three ways. If you are new to prompt writing, start with Option A.

Option A: Dedicated troubleshooting section

## Prompt pitfalls to avoid

- If requirements are unclear on a high-impact decision, ask before proceeding.
- When sources conflict, acknowledge the conflict and separate evidence from inference.
- Lead with key findings and avoid repeated wording.

Option B: Weave fixes into operating principles

## Operating principles

- Clarify before action on high-impact ambiguity.
- Weigh evidence by source authority and relevance.
- Match confidence to certainty and provide options when needed.

Option C: Hybrid

Use operating principles for defaults, then add a short "watch-outs" block near the end of the prompt.

The agent assumes missing details and proceeds

The agent asks too many clarifying questions

The agent overreacts to the most recent message

Assumptions compound without visibility

The agent flattens nuance across conflicting sources

The agent treats weak sources as equally authoritative

The agent invents details when uncertain

The agent never escalates

The agent misreads directive strength

The agent presents one option only

The agent is verbose, repetitive, or buries key points

The agent only processes some items in a list

The agent filters dates incorrectly

On this page

The agent assumes missing details and proceeds

The agent asks too many clarifying questions

The agent overreacts to the most recent message

Assumptions compound without visibility

The agent flattens nuance across conflicting sources

The agent treats weak sources as equally authoritative

The agent invents details when uncertain

The agent never escalates

The agent misreads directive strength

The agent presents one option only

The agent is verbose, repetitive, or buries key points

The agent only processes some items in a list

The agent filters dates incorrectly