Tutorial: Random Words - Gnist Context

Reference

Data source: In-memory curated collection

Overview

Random Words wraps In-memory curated collection, handling authentication, pagination, and rate limits for you. This tutorial covers all 5 tools with working code examples you can copy and run.

Prerequisites

Sign up at https://context.gnist.ai/signup for a free API key (100 calls/day).
Choose your integration method: MCP protocol or REST API.

Connect via MCP

Add to your MCP client config (Claude Desktop, Cursor, etc.):

MCP Config

{
  "mcpServers": {
    "gnist-random-words": {
      "url": "https://context.gnist.ai/mcp/random-words/",
      "headers": {
        "Gnist-API-Key": "YOUR_API_KEY"
      }
    }
  }
}

Tools (5)

`get_random_word`

Get a random English word. Returns a word with its type and length. Optionally filter by word type and length range.

Parameter	Type	Required	Description
`word_type`	any	optional	Filter by word type (noun, verb, adjective, adverb). Omit for any type.
`min_length`	any	optional	Minimum word length (inclusive).
`max_length`	any	optional	Maximum word length (inclusive).

curl -X POST "https://context.gnist.ai/mcp/random-words/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "get_random_word", "arguments": {"word_type": "example"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/random-words/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'word_type': 'example'}, 'name': 'get_random_word'}},
)
print(resp.json())

`get_random_words`

Get multiple random English words at once. Returns a list of words, optionally filtered by type. Words are sampled without repeats.

Parameter	Type	Required	Description
`count`	any	optional	Number of random words to return (default: 5, max: 50).
`word_type`	any	optional	Filter by word type (noun, verb, adjective, adverb). Omit for any type.

curl -X POST "https://context.gnist.ai/mcp/random-words/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "get_random_words", "arguments": {"count": "example"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/random-words/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'count': 'example'}, 'name': 'get_random_words'}},
)
print(resp.json())

`search_words`

Search for words by substring. Searches across word text and word types. Case-insensitive.

Parameter	Type	Required	Description
`query`	string	required	Search substring — matches word text or word type.
`max_results`	any	optional	Maximum number of results (default: 20, max: 100).

curl -X POST "https://context.gnist.ai/mcp/random-words/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "search_words", "arguments": {"query": "renewable energy"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/random-words/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'query': 'renewable energy'}, 'name': 'search_words'}},
)
print(resp.json())

`list_word_types`

List all available word types. Returns the type names that can be used to filter random words (noun, verb, adjective, adverb).

curl -X POST "https://context.gnist.ai/mcp/random-words/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "list_word_types", "arguments": {}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/random-words/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {}, 'name': 'list_word_types'}},
)
print(resp.json())

`report_feedback`

Report a bug, feature request, or general feedback for this data source. Use this when something doesn't work as expected, when you'd like a new feature, or when you have suggestions for improvement. Args: feedback: Describe the issue or suggestion. feedback_type: One of 'bug', 'feature_request', or 'general'.

Parameter	Type	Required	Description
`feedback`	string	required
`feedback_type`	string	optional	(default: `general`)

curl -X POST "https://context.gnist.ai/mcp/random-words/" \
  -H "Content-Type: application/json" \
  -H "Gnist-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "id": 1, "params": {"name": "report_feedback", "arguments": {"feedback": "example"}}}'

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/random-words/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {'feedback': 'example'}, 'name': 'report_feedback'}},
)
print(resp.json())

Common Patterns

Search then retrieve
Use search_words to find items, then get_random_word to get full details. This two-step pattern is common for exploring data before drilling down.

Pagination
Several tools support limit, offset, or page parameters. Start with small limits during development, then increase for production queries.

FAQ

What data does Random Words provide?

Random English word generator — 120 curated words across 4 types (noun, verb, adjective, adverb) with length filtering. It exposes 5 tools: get_random_word, get_random_words, search_words, list_word_types, report_feedback.

What do I need to get started?

A Gnist API key (free tier: 100 calls/day). Sign up at https://context.gnist.ai/signup.

What format does the Random Words API return?

JSON, via either MCP protocol (JSON-RPC 2.0) or REST API.