Endpoints (Tools)
Define the external REST or GraphQL APIs your AI can call during /ask — the create wizard, schema, authentication, headers, and per-turn limits.
An Endpoint (a Tool in the API and MCP) is an external REST or GraphQL API that the
LLM may call during an /ask request — to fetch live data or take an action. You define
it once in the Console; the AI decides when to call it based on the description and
schema you give it.
Recommended: let an agent build your endpoints
Instead of filling in the wizard by hand, connect the EgoX MCP and ask
your agent: "Look at my OrdersResolver and create an EgoX tool getOrderStatus that
calls it, using $userId as a variable." The agent reads your real API/GraphQL schema
and writes a correct definition — headers, forwardHeaders, and all — then it lands as a
reviewable draft in the Console. We think this is the better way to build tools, and
it's how the platform is designed to be used at scale.
Create an endpoint
In the Console: Project → Endpoints → New. It's a three-step wizard — Definitions → Inputs → Review (your progress is saved if you refresh).
Definitions
| Field | What it is |
|---|---|
| Name | A camelCase identifier the AI uses to reference the tool (e.g. getOrderStatus). Letters/numbers, no spaces. |
| Type | REST or GraphQL. |
| HTTP method (REST) | GET, POST, PUT, PATCH, or DELETE. POST/PUT/PATCH send a body. |
| Description | At least 10 characters. This is how the AI decides when to call the tool — be specific about what it does and when to use it. |
| API endpoint | A full URL (https://api.example.com/orders) or a path (/orders) that resolves against your default Base URL. |
Inputs
Teach the AI how to call the endpoint, and how EgoX should authenticate the outbound call.
| Field | What it is |
|---|---|
| Parameters schema | A JSON Schema describing the arguments the LLM must produce (the request body for REST body methods; variables for GraphQL). |
| GraphQL operation (GraphQL) | The operation string — use $variables, never hardcoded literals. |
| Example request / response | Optional but recommended — concrete examples teach the model the exact shape and improve reliability. |
| Authentication | Forward token passes the caller's Authorization: Bearer … through to your endpoint; None sends no auth. |
| Custom headers | Static headers EgoX always sends (e.g. an upstream API key). |
| Forwarded request headers | An allowlist of inbound /ask headers to pass through (e.g. x-locale). Anything not listed stays with EgoX; sensitive headers are blocked. |
| Max calls per turn | A hard cap (1–50, default 5) on how many times the AI may run this tool within a single conversation turn. It resets every turn — it is not a per-day rate limit. |
Project-wide settings
Some configuration is shared across every tool — Project → Endpoints → Settings:
- General → Base URL. A default host prepended to any tool defined with just a path. Set it once instead of repeating the host on every tool. A path-only endpoint won't validate until a Base URL exists.
- Authentication. The token-validation callback that authenticates calls into your tools — it gates who may invoke them.
How EgoX calls your endpoint
When the LLM triggers a tool, EgoX makes the outbound call on your behalf — safely:
- Signed requests. Every call is signed (HMAC-SHA256) with a timestamp so your endpoint can verify it genuinely came from EgoX. Verify it — see Integrating securely with the SDK.
- Header rules. Only names on the tool's
forwardHeadersallowlist are passed through from/ask; reserved and sensitive headers are stripped server-side. - Storm protection. Beyond your per-turn cap, EgoX layers dedup, error classification, bounded retries, and an iteration cap so a flaky tool can't loop.
Using it from /ask
Once an endpoint exists and Tools is enabled in AI Settings, no code changes are needed — the model calls it automatically when a request needs it. The response tells you which tool ran:
const res = await egox.ask({ message: "Where's my order #123?" });
console.log(res.toolUsed); // e.g. "getOrderStatus"
console.log(res.intent); // "tools" or "rag_tools"// response
{ "status": "OK", "data": {
"answer": "Your order #123 shipped yesterday…",
"toolUsed": "getOrderStatus",
"intent": "tools"
} }Related
- Grounding answers in content instead → Knowledge Base (RAG)
- Verify tool-call signatures → Client SDK
- Build tools with an agent → MCP Connection
Overview
Give your AI the two capabilities that make it useful — Endpoints (Tools) to act on your APIs, and a Knowledge Base (RAG) to ground answers in your content.
Knowledge Base (RAG)
Add documents your AI can retrieve from — how content is chunked, embedded, and queried per request, plus tags, statuses, and management.