Tutorial: Riddles & Puzzles

Entertainment

Data source: In-memory curated collection

Overview

Riddles & Puzzles 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-riddles": {
      "url": "https://context.gnist.ai/mcp/riddles/",
      "headers": {
        "Gnist-API-Key": "YOUR_API_KEY"
      }
    }
  }
}

Tools (5)

`get_random_riddle`

Get a random riddle WITHOUT the answer. Returns a brain teaser with question and hint. Use get_riddle_answer() with the riddle ID to reveal the answer. Optionally filter by category and/or difficulty.

Parameter	Type	Required	Description
`category`	any	optional	Filter by category (logic, wordplay, math, lateral-thinking, classic). Omit for any.
`difficulty`	any	optional	Filter by difficulty (easy, medium, hard). Omit for any.

curl -X POST "https://context.gnist.ai/mcp/riddles/" \
  -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_riddle", "arguments": {"category": "example"}}}'

import httpx

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

`get_riddle_answer`

Reveal the answer to a specific riddle. Takes a riddle ID (from get_random_riddle or search_riddles) and returns the full riddle including the answer.

Parameter	Type	Required	Description
`riddle_id`	integer	required	The ID of the riddle to reveal the answer for.

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

import httpx

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

`search_riddles`

Search for riddles by keyword. Searches across question text, hints, and categories. Case-insensitive. Results do NOT include answers.

Parameter	Type	Required	Description
`query`	string	required	Search keyword — matches question, hint, or category.
`max_results`	any	optional	Maximum number of results (default: 20, max: 100).

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

import httpx

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

`list_riddle_categories`

List all available riddle categories. Returns the category names that can be used to filter random riddles.

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

import httpx

resp = httpx.post(
    "https://context.gnist.ai/mcp/riddles/",
    headers={"Gnist-API-Key": "YOUR_API_KEY"},
    json={'id': 1,
 'jsonrpc': '2.0',
 'method': 'tools/call',
 'params': {'arguments': {}, 'name': 'list_riddle_categories'}},
)
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/riddles/" \
  -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/riddles/",
    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_riddles to find items, then get_random_riddle 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 Riddles & Puzzles provide?

Curated riddle and brain teaser database with 80 riddles across 5 categories (logic, wordplay, math, lateral-thinking, classic) — get random riddles, search, and reveal answers. It exposes 5 tools: get_random_riddle, get_riddle_answer, search_riddles, list_riddle_categories, 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 Riddles & Puzzles API return?

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