> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nimbleway.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Common Mistakes

> The patterns that burn runs, and what to do instead

Most poor results trace back to one of these. Each row links to the page that explains the fix.

| You did | Do instead | Why |
| - | - | - |
| Ran an agent to look up one fact | [Search](https://docs.nimbleway.com/nimble-sdk/web-tools/search.md) with `include_answer` | Seconds and cents instead of minutes and dollars. See [Choosing the Right Tool](https://docs.nimbleway.com/nimble-sdk/web-search-agents/choosing-the-right-tool.md) |
| Gave the agent one known URL | [Extract](https://docs.nimbleway.com/nimble-sdk/web-tools/extract/quickstart.md), or the site's [Extract Template](https://docs.nimbleway.com/nimble-sdk/agentic/agent-gallery.md) | A known page is read deterministically. An agent searches for what you already have |
| Created a new agent for every question | One agent by `agent_name`, many runs | The tuned skill, goals and sources are the asset. See [Running at Scale](https://docs.nimbleway.com/nimble-sdk/web-search-agents/best-practices/running-at-scale.md) |
| Asked one run to crawl a whole catalog | 50 to 100 rows per run, scoped by section, then merge | One `x-high` run over a full manufacturer tree returned 78 items; scoped runs returned 200 or more each |
| Asked for "all", "every", "comprehensive" on the open web | A row cap and a stop rule; split by region or category | The agent stops when the budget ends, not when the task is done. See [Writing the Task](https://docs.nimbleway.com/nimble-sdk/web-search-agents/best-practices/writing-the-task.md) |
| Put twelve entities in one research prompt | One entity per run | Twelve products returned five rows covering two, and the run said completed |
| Wrote goals as caveats and the skill as a feature list | Skill as a playbook with steps; goals as checkable requirements | Rewriting one skill into a procedure lifted filled cells from 68% to 99% |
| A 25-field schema with no descriptions | 5 to 8 described fields; a second agent for the rest | Wide undescribed schemas are the top cause of partial output. See [Output Schema](https://docs.nimbleway.com/nimble-sdk/web-search-agents/best-practices/output-schema.md) |
| Nested arrays in an enrichment schema, or `$ref` | Flat object per row; inline definitions | Nested arrays exhaust the write budget; `$ref` fails at run start |
| Required fields the web cannot fill | `required` on identity fields only; everything else nullable | The agent invents a value or drops the row |
| Asked for `confidence` or `reasoning` fields in the schema | Leave them out; read the trust report | The report already grades every path. Self-grading is a worse copy |
| Built on LinkedIn, Instagram, Zillow or a login-walled site | Drop the field, use a template, or ask about social data access | Login and anti-bot walls return thin or padded results. See [Controlling Sources](https://docs.nimbleway.com/nimble-sdk/web-search-agents/best-practices/sources.md) |
| Hunted personal emails and mobile numbers | Ask for the URL of the published contact page; forbid pattern-built emails | Rarely public; invites construction |
| `medium` effort with a structured schema | Free text at `medium`, or `high` with the schema | A third of those runs ship partial output. See [Effort and Cost](https://docs.nimbleway.com/nimble-sdk/web-search-agents/best-practices/effort-and-cost.md) |
| Raised effort to fix a vague task | Fix the task text and schema first, effort last | Higher tiers buy sources and time, not clarity |
| Pasted 300 prior results into the prompt to dedupe | The prior rows in `input_data` with "exclude these" | Keeps the prompt short and the exclusion exact |
| Copied a gallery template and ran it unchanged | Read the copied agent's goals and sources first | Copies have come across with empty goals and sources |
| Trusted `completed`, or the confidence grade, as proof | Count rows against asked, check fill, open five citations | Truncated and padded runs both complete with a high grade. See [Evaluating Results](https://docs.nimbleway.com/nimble-sdk/web-search-agents/best-practices/evaluating-results.md) |
| Skipped canaries on a big batch | Ten known inputs first, including two that should return nothing | Catches wrong-entity and fabrication before 1,000 runs repeat it |
| Called synchronously with a 5-minute timeout | Poll or stream events; allow 30 minutes at `high` and `x-high` | Nine in ten runs finish sooner; the tenth does not |

## Next Steps

> **[Choosing the Right Tool](https://docs.nimbleway.com/nimble-sdk/web-search-agents/choosing-the-right-tool.md)**
>
> Before the first run

> **[Writing the Task](https://docs.nimbleway.com/nimble-sdk/web-search-agents/best-practices/writing-the-task.md)**
>
> Input, skill, goals

> **[Evaluating Results](https://docs.nimbleway.com/nimble-sdk/web-search-agents/best-practices/evaluating-results.md)**
>
> After the run


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.