---
title: Querying Nue with Natural Language
slug: querying-nue-with-natural-language
createdAt: 2026-06-13T02:22:32.475Z
---

# Introduction

Nue exposes its data to AI agents through the **Model Context Protocol (MCP)**. Rather than writing GraphQL by hand, an agent connected to the Nue MCP server asks a question in plain language through a single tool — `queryNueData` — and Nue does the rest: it inspects the schema, builds the right GraphQL query, runs it against the correct service, and returns an answer.

This is the recommended way for conversational and agentic experiences to read Nue data. Developers who want to issue GraphQL directly can still do so through the API — see [Query Nue Objects using GraphQL](docId:-9J6pCiGzvpCGzSDIkCwc).

# How It Works

When an agent calls `queryNueData` with a natural-language question, Nue:

1. **Understands the question** and determines which objects and fields are involved.
2. **Discovers the schema** through introspection, so it works against your org's actual fields and picklists rather than hardcoded assumptions.
3. **Builds and runs GraphQL queries** against the correct endpoint — CPQ objects on one service, Order objects on the other.
4. **Joins across services when needed** by following scalar foreign keys (for example, linking a subscription's customer to that customer's invoices), so a single question can span CPQ and Order data.
5. **Returns a concise, natural-language answer** based on the results.

The agent only ever sees the one `queryNueData` tool. The underlying GraphQL machinery — schema discovery and query execution — runs internally and is not exposed as separate tools.

# Cross-Service Traversal via AI

The raw GraphQL endpoints traverse relationships only *within* a single service (see [GraphQL Relationship Traversal](docId\:vEMQp0s7GgC4wYRgYlgCp)). Natural-language queries remove that boundary: because Nue plans the query and joins on shared identifiers itself, an agent can ask questions that combine CPQ catalog and pipeline data with Order subscription and billing data in one request.

For example, all of the following are answerable through a single `queryNueData` call:

- "Which customers have an active subscription to *Acme Analytics* and an overdue invoice?"
- "What is the total open pipeline by stage for accounts in the technology industry?"
- "List subscriptions renewing in the next 90 days along with the customer's account owner."

# What to Expect

A few behaviors are worth knowing when you build on `queryNueData`:

- **Tenant-aware AI model.** Nue resolves the AI model configured for your org at request time, with a safe default if no specific model is configured.
- **Record limits apply.** As with direct GraphQL, results are capped at 100 records per underlying query. For broad questions, ask for a narrower set or an aggregate (for example, "how many…" or "total… by…") rather than a full list.
- **Bounded reasoning.** Each question runs through a capped number of internal steps, so responses stay timely.
- **Graceful answers.** If the question can't be answered from the available data, the tool responds with a clear "I couldn't find that" style message rather than surfacing raw query errors or retry noise.

# Tips for Better Answers

- **Be specific.** Name the object, the filter, and the metric you care about ("active subscriptions for Acme created this year") rather than asking open-ended questions.
- **Prefer aggregates for large sets.** Ask "how many" or "total by…" when you don't need every individual record — this avoids the 100-record cap and returns a direct answer.
- **Ask follow-ups.** Conversational refinement ("now break that down by region") works well, since each question is planned independently against the live schema.

# Related Guides

- [Query Nue Objects using GraphQL](docId:-9J6pCiGzvpCGzSDIkCwc) — issue GraphQL directly against the CPQ and Order endpoints.
- [GraphQL Relationship Traversal](docId\:vEMQp0s7GgC4wYRgYlgCp) — nested and reverse relationships within a service.
- [GraphQL Aggregations](docId\:WXOk4PXgWzYfBo4ici2zl) — counts, sums, and grouped rollups.