# Limitations & troubleshooting

Things to check when the Query Agent isn't behaving as expected, plus the soft usage limits and typical execution timings to keep in mind.

## Usage limits

Each Weaviate Cloud [organization](../cloud-account-management/users-and-organizations.md#organizations) can make up to 1,000 Query Agent requests per month at no cost.

Requests are consumed based on query type:

- `Ask`: 4 requests per query
- `Search`: 1 request per query
- `Suggest Queries`: 1 request per query

This limit may change in the future. For questions about usage limits, contact product@weaviate.io.

## Custom collection descriptions

The Query Agent makes use of each collection's `description` metadata as well as individual property descriptions in deciding what collection to query.

Both collection descriptions and property descriptions can be updated after the collection has been created. For detailed instructions on updating collection and property descriptions, see the [update collection definition documentation](../how-to-manage-collections/collection-operations.md#update-a-collection-definition).

We are investigating an ability to specify a custom collection description at runtime.

## Execution times

The Query Agent performs multiple operations to translate a natural language query into Weaviate queries, and to process the response.

This typically requires multiple calls to generative models (e.g. LLMs) and multiple queries to Weaviate.

As a result, each Query Agent run may take some time to complete. Depending on the query complexity, it may not be uncommon to see execution times of \~10 seconds.

**For long-running or complex queries**, consider using [streaming responses](../modes/ask-mode.md#streaming) rather than non-streaming requests. Streaming provides progress updates and sends heartbeats to maintain the connection, preventing timeout issues that can occur with long-running non-streaming requests.

## Questions and feedback

Have a question or feedback? Here's how to reach us.

::::card-grid
:::card{title="Community Forum" href="https://forum.weaviate.io/c/support" icon="messages-square"}
Ask questions and connect with other developers on our **Community forum**.
:::

:::card{title="Support" href="/guides/support-overview" icon="life-buoy"}
Weaviate Cloud user or customer? Find the right channel on the **Support page**.
:::
::::

## Related pages

- [Agents](./agents-index.md)
- [AI-assisted Weaviate code generation](./ai-assisted-vibe-coding-index.md)
- [APIs](./apis-index.md)
- [Authorization and authentication](./authorization-and-authentication-index.md)
- [Benchmarks](./benchmarks-index.md)
- [Best practices](./best-practices-index.md)
- [Client libraries](./clients-index.md)
- [Client Libraries / SDKs](./client-libraries-index.md)
- [Cloud](./cloud-index.md)
- [Cloud account management](./cloud-account-management-index.md)

# Agent Instructions

This portal answers questions programmatically. To receive a synthesized,
source-cited answer instead of crawling page by page, append the `?ask=`
query parameter to any page URL on this site:

    /guides/quickstart?ask=how+do+I+authenticate

Optional parameters:

- `&goal=<what-you-are-trying-to-do>` steers the answer toward your
  objective (e.g. `&goal=write+a+python+client`).
- `&version=<label>` scopes the answer to a mounted version when the
  portal publishes more than one.

The response is `text/markdown`: the answer followed by a `# Sources` list
of the portal pages it was grounded in. Status codes are the contract:

- `200` — the answer; `402` — the portal owner’s plan or answer credits are
  exhausted (surface this to your operator; do NOT retry); `429` — you are
  rate-limited; back off for the `Retry-After` seconds; `503` — the answer
  lane is temporarily unavailable; fall back to crawling the `.md` pages.

For the full corpus map read `llms.txt` at the site root; for the tool
surface (search + page fetch as MCP tools) see `/mcp`.