Tools Reference
SmartGate MCP tools — purpose, inputs, and when to use each smart_* tool.
SmartGate exposes seven MCP tools on tools/list. Each tool is also available through the REST API under /api/v1/* with the same semantics.
For connection setup, see MCP Endpoint. This page describes what each tool does and typical usage — not internal routing algorithms.
Summary
| Tool | One-line purpose |
|---|---|
smart_fetch | Fetch a URL and return Markdown |
smart_search | Web search across configured engines |
smart_context_gate | Compress long text before sending to your LLM |
smart_dedup | Remove duplicate or near-duplicate passages |
smart_budget_guard | Check, count, or record budget usage |
smart_memory | Team-scoped memory CRUD |
smart_pipe | Run multi-step pipelines (templates or custom) |
Authoritative parameter schemas are returned on tools/list from your connected MCP server.
smart_fetch
Purpose: Retrieve a public URL and normalize content to Markdown for agent consumption.
Typical inputs: url (required)
When to use: Research steps, reading docs, pulling page content into an agent loop.
Notes:
- You must have the right to access the URL.
- Large pages may be shaped or truncated according to gateway policy.
- Optional audit headers help group fetches into a task in Activity Logs.
smart_search
Purpose: Run a multi-engine web search and return structured results.
Typical inputs: query string, optional result limits (see live schema)
When to use: Discovery before fetch, fact-checking, building citations.
Notes: Search results are summaries — follow up with smart_fetch for full pages when needed.
smart_context_gate
Purpose: Compress prompts or long context before they are sent to your model provider.
Typical inputs: text body; optional compression ratio (team defaults apply)
When to use: Long tool outputs, bloated system prompts, repeated context in agent loops.
Notes:
- Works over REST and MCP.
- Dashboard → Playground can test compression separately (REST path, not MCP).
- Effective compression ratio may come from team gateway settings on paid plans.
smart_dedup
Purpose: Detect and remove semantically duplicate chunks in text.
Typical inputs: text or list of passages (see schema)
When to use: After multiple fetches or searches merged into one context block.
Notes: Helps reduce token waste without manual editing.
smart_budget_guard
Purpose: Check remaining budget, increment counters, or record usage for guardrails.
Typical inputs: action mode (check, count, record, etc. — see schema)
When to use: Before expensive loops, enforcing team spending caps, agent self-throttling.
Notes:
- Bound to your API key's team by default.
- Pairs with Dashboard → Budget and usage reports.
smart_memory
Purpose: Add, search, retrieve, or delete team-scoped memory entries.
Typical inputs: operation + content / query / id (see schema)
When to use: Persist facts across agent tasks within a team.
Notes: Memory is isolated per team. Do not store secrets or regulated PII without policy review.
smart_pipe
Purpose: Execute predefined or custom multi-step pipelines in one call.
Built-in templates: research, read, remember
Custom steps: Use module names (fetch, search, context_gate, dedup, budget_guard, memory) or the same smart_* names.
When to use: Standardize common agent workflows (research → compress → dedup) without chaining many separate tool calls from the host.
Playground vs MCP
| Surface | Path | Use |
|---|---|---|
| Playground | Dashboard → Playground | Manual REST tests (fetch, compress) |
| MCP tools | Connect config | Agent integrations |
They share gateway policy but use different entry points. See Connect Guide.
Tool rate limits (search and fetch)
smart_search and smart_fetch share a separate gateway limit of 20 requests per minute per team (rolling minute bucket). This is independent of MCP requests per minute per API key shown in plan settings.
When exceeded, MCP tools return an English error with Retry-After; REST /api/v1/search and /api/v1/fetch return HTTP 429.
The public pricing page may not list this row until the pricing redesign spec ships; limits still apply at the gateway.
Related
- MCP Endpoint — auth, URLs, audit headers
- Activity Logs — trace tool usage
- Security — quotas and retention
Capability map (prefer this over memorizing seven names)
| Capability | Primitives | Typical use |
|---|---|---|
| Research | smart_search, smart_fetch | Find sources; read URLs to Markdown |
| Context | smart_dedup, smart_context_gate | Remove overlap; compress before host LLM |
| Memory | smart_memory | Team-scoped add/search/get/delete |
| Control | smart_budget_guard | Check/record budget; support hard caps |
| Pipeline | smart_pipe | Templates or custom step arrays |
When to use which Research tool
- search when there is no definitive URL.
- fetch when the user already gave a URL (skip search).
- pipe research when you want one audited chain: search then fetch then dedup then context_gate.
- pipe read for fetch then context_gate on a known URL.
- pipe remember when search results should land in memory for later sessions.
Context and Control tips
Set compression ratios deliberately; savings depend on input structure. Dedup after multi-fetch/multi-search. Call smart_budget_guard before expensive jobs and record after. On plans with L2 hard cap, expect blocked tool calls when the monthly pool is exhausted—alerts alone do not stop loops.
Safety and fairness
smart_fetch must not invent page text. smart_search / smart_fetch share a per-team gateway request budget separate from MCP RPM per key. Free/Playground fair-use returns HTTP 429 on breach. See Security and Pricing.
Composability
Builders should embed the runtime once via MCP/API instead of reimplementing fetch, dedup, compression, budget, memory, and orchestration per agent. That is the Positioning Bible developer promise: a complete intelligence runtime for agents—not another search API.
Live schemas come from ools/list on your deployment; this page explains intent and composition. For wire details see MCP Endpoint.
Practical adoption notes
Treat SmartGate as shared infrastructure: one gateway URL, team-scoped keys, and audit on by default. Prefer pipe templates for repeatable research paths so Activity Logs show a coherent chain instead of ad-hoc tool spam. Keep host-model prompts focused on decisions; let Research and Context primitives prepare evidence. When FinOps asks for savings, export Usage Reports alongside the gateway benchmark explanation—never present Est. USD saved as a vendor LLM invoice. When security asks for evidence, export an audit window and show retention tied to the current plan catalog.
If you are migrating from scripts, replace raw HTTP fetch helpers first, then add dedup and compression, then budget guard. If you are migrating from a model gateway mindset, stop expecting chat completions on /api/mcp and wire MCP hosts instead. If you are writing human-facing product copy, lead with Smart Research / Smart Decision outcomes; keep MCP JSON on builder paths. These habits keep the site and the product aligned with the Positioning Bible: intelligence layer between AI and the world, not an LLM proxy.