MCP server for trivia: 1.4M+ questions (EN+PL), 24 categories, 12 tools + 4 prompts, OAuth 2.1.
Glama MCP Gateway
Connect through Glama MCP Gateway for full control over tool access and complete visibility into every call.
Full call logging
Every tool call is logged with complete inputs and outputs, so you can debug issues and audit what your agents are doing.
Tool access control
Enable or disable individual tools per connector, so you decide what your agents can and cannot do.
Managed credentials
Glama handles OAuth flows, token storage, and automatic rotation, so credentials never expire on your clients.
Usage analytics
See which tools your agents call, how often, and when, so you can understand usage patterns and catch anomalies.
Average 4.6/5 across 12 of 12 tools scored.
Each tool has a clearly distinct purpose: categories, languages, list, question_by_id, random, regions, report, stats, subcategories, tags, topic_by_slug, and topics. Descriptions explicitly guide when to use which, avoiding ambiguity even between similar tools like quizbase_list and quizbase_random.
All tools follow a consistent 'quizbase_' prefix followed by a noun or noun phrase, with underscores for compound names like question_by_id and topic_by_slug. This pattern makes it easy to predict tool names based on function.
With 12 tools, the set is well-scoped for a trivia question database. It covers metadata discovery, question browsing, random sampling, reporting, and statistics without unnecessary bloat or missing essentials.
The tool set provides comprehensive read access and reporting for the catalog: metadata (categories, languages, regions, stats, taxonomy), question retrieval (list, random, by ID), and issue submission. No obvious gaps for typical consumption workflows.
quizbase_categoriesList all top-level categoriesAList of 24 top-level categories with i18n labels. USE WHEN: building a category picker, validating ?category= input. Stable enum (rarely changes). For higher-resolution browsing → quizbase_subcategories or quizbase_topics.
| Name | Required | Description | Default |
|---|---|---|---|
| lang | No | Language for category `name` field (ISO 639-1). Default "en". Supported: en, pl. Slugs are language-agnostic. | en |
| Name | Required | Description |
|---|---|---|
| meta | Yes | Response metadata: how many categories returned and which language. |
| categories | Yes | All 24 top-level categories with localized names. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, so safety is known. Description adds valuable behavioral context: stability ('Stable enum (rarely changes)') and cardinality (24 items), which informs caching and decision-making. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: purpose in the first sentence, usage in the second, alternatives in the third. Every sentence adds value with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with an output schema, annotations, and full schema coverage, the description fully covers purpose, usage, stability, and alternatives. Nothing important is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description covers 100% of the lang parameter, specifying enum, default, and language semantics. Description adds no extra param detail, but does not need to given the schema's thoroughness. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description states 'List of 24 top-level categories with i18n labels' with a clear verb (List), resource (categories), and scope (top-level, 24). It distinguishes from siblings by explicitly directing to quizbase_subcategories and quizbase_topics for higher resolution.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit 'USE WHEN' cases: building a category picker, validating ?category= input. Also names alternatives for other needs, making when-to-use vs not completely clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
quizbase_languagesList supported languages with countsAReturns supported language whitelist (ISO 639-1) with question counts per language. USE WHEN: showing language picker, validating ?lang= input, deciding fallback. Day 1: en + pl.
| Name | Required | Description | Default |
|---|---|---|---|
| lang | No | Language for `displayName` of each supported language entry (ISO 639-1). Default "en". E.g. with `lang=pl` Polish returns as "polski", English as "angielski". Codes themselves are language-agnostic. | en |
| Name | Required | Description |
|---|---|---|
| meta | Yes | Response metadata. |
| languages | Yes | Supported languages with localized display name and question count per language. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds that it returns ISO 639-1 codes and question counts, plus the current 'Day 1: en + pl' limitation, which is valuable context. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences plus a use-case list; every part earns its place. The 'Day 1: en + pl' note is concise and relevant for fallback decisions.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present and only one simple parameter, the description covers purpose, usage scenarios, and current data state. It is complete enough for an agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 100% description coverage for the 'lang' parameter, including its role in setting displayName. The tool description does not add extra parameter details beyond what the schema already provides, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Returns supported language whitelist (ISO 639-1) with question counts per language' – a specific verb, resource, and output detail. It clearly distinguishes this from siblings like quizbase_categories or quizbase_list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes explicit 'USE WHEN' scenarios: 'showing language picker, validating ?lang= input, deciding fallback'. No exclusions or alternatives are mentioned, but the use cases are concrete and sufficient for an agent to decide when to call this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
quizbase_listBrowse questions catalog with cursor paginationACursor-paginated browse over the catalog. Quality-first: by default excludes questions flagged for review (use quality='all' for full pool).
USE WHEN: full catalog sync, delta sync (updated_since), exhaustive enumeration by filter. NOT WHEN: you only need N random samples (use quizbase_random) or a single record (use quizbase_question_by_id).
PAGINATION: stable cursor over id UUIDv7 DESC. First call: omit cursor. Next: pass meta.nextCursor. Stop when nextCursor is null.
KEY FILTERS (full parity with REST):
lang: ISO 639-1, default "en". Supported: en, pl.
category (slug), difficulty (trivial|easy|medium|hard|expert — LLM-calibrated), type (multiple|boolean), subcategory (raw slug).
tags (AND), tags_any (OR, max 10): raw tag slugs.
topic (curated, alias resolver), topics_any (OR over curated): higher precision than tags.
regions (cultural affinity, AND): empty = no cultural advantage assumed. Lowercase ISO 3166-1 alpha-2 ('us', 'pl', 'gb') + cultural codes ('jewish', 'christian-catholic', 'islam'). Filter for content statistically more likely known by residents/members. Discover via quizbase_regions.
source (array): include only these of 12 (opentdb, opentriviaqa, kqa-pro, entityq, mintaka, mkqa, nq-open, creak, qasc, arc, webq, quizbase).
exclude_source (array): drop these sources, e.g. ["entityq"]. Applied after source.
license (SPDX): e.g. CC-BY-SA-4.0, MIT.
quality: 'high' (default) = cleanest, most broadly-useful. 'standard' = broader pool incl. niche/too-specific. 'all' = full pool incl. flagged; when 'all', each question gains a "quality" field ('high' or 'needs_review').
updated_since (ISO 8601): only questions updated after this — for delta sync caches.
BATCH + TRANSLATION MAPPING:
ids (up to 250): fetch those exact records in one call (anti-repeat, deep-links, restoring a saved set). Terminal selector — browse filters and cursor are ignored. Missing ids → meta.missing.
content_language (en|pl): with ids, returns each question's sibling in that CONTENT language across the translation chain — the same questions in another language. Distinct from lang (labels only).
PAGINATION + COUNTING:
cursor (string): from previous meta.nextCursor. Omit for page 1.
limit (1-100, default 20).
count: none (default, skip — page via nextCursor) | exact (precise COUNT(*), index-only ~25-90ms).
OUTPUT: { questions: [...], meta: { count, countMode, language, nextCursor, total? } }. Each question carries full per-record attribution (source, author, license, licenseVersion, licenseUrl, sourceId, url, modifications, lastModified) — identical shape to REST /api/v1/questions.
ATTRIBUTION REQUIRED if you redistribute. Credit each question using its own attribution object — see license + licenseUrl + modifications fields per record.
COMMON MISTAKES: not passing the cursor on subsequent calls (you'll re-read page 1); polling without updated_since when doing delta sync.
| Name | Required | Description | Default |
|---|---|---|---|
| ids | No | Batch fetch by id (up to 250). Returns those exact records in one call — anti-repeat, deep-links, reconstructing a saved set. Terminal selector: all browse filters and cursor are ignored. Ids with no result come back in `meta.missing`. Combine with `content_language` to map a set across languages. | |
| lang | No | Question language as ISO 639-1 code. Default "en". Supported: en, pl. Translated rows share the same `id` across languages. | en |
| tags | No | AND-logic: question must have ALL these tag slugs (kebab-case) | |
| type | No | "multiple" = 1 correct + 3 distractors. "boolean" = True/False. | |
| count | No | Total count strategy. `none` (default, fastest — page via nextCursor, no total). `exact` (precise COUNT(*), index-only ~25-90ms — when you need the exact number of matches). | none |
| limit | No | Page size (1-100, default 20). Larger pages reduce round-trips but increase latency. | |
| topic | No | Curated topic slug — alias resolver matches subcategories and tags | |
| cursor | No | Opaque pagination cursor from previous `meta.nextCursor`. Omit for page 1; pass last response's `meta.nextCursor` for subsequent pages. Stop when `nextCursor` is null. | |
| source | No | Include only these source databases (one or more of 12): opentdb, opentriviaqa, mkqa, mintaka, kqa-pro, entityq, nq-open, creak, qasc, arc, webq, quizbase. Matches `attribution.source`. | |
| license | No | SPDX license string (e.g. CC-BY-SA-4.0, MIT). Filter for redistribution-friendly content. | |
| quality | No | Quality preset. "high" (default) returns only the cleanest, most broadly-useful questions. "standard" broadens to the full reviewed pool incl. niche/too-specific. "all" includes everything flagged for review — for audit, research, or BY-SA dump. | high |
| regions | No | Cultural affinity codes. A question is tagged with a region if residents of that country, or members of that cultural/religious group, are **statistically more likely to know** the answer (NOT geography of the subject). Lowercase ISO 3166-1 alpha-2 (`us`, `pl`, `gb`) plus cultural codes (`jewish`, `christian-catholic`, `islam`). AND-logic. Empty array in DB = universally accessible. Use `quizbase_regions` for the full catalog with counts. | |
| category | No | Top-level category slug (kebab-case) — e.g. `geography`, `history`, `science-and-nature`. 24 total. Use `quizbase_categories` for canonical list with localized names. | |
| tags_any | No | OR-logic: question must have AT LEAST ONE of these tag slugs | |
| difficulty | No | LLM-calibrated 5-level difficulty. trivial=common-knowledge, easy=approachable, medium=requires-thought, hard=needs-domain-context, expert=specialist. Records not yet LLM-rated hold the importer placeholder (mostly "medium" for factoid sources). | |
| topics_any | No | OR-logic over curated topic slugs (resolves aliases) | |
| subcategory | No | Raw subcategory slug (kebab-case). Prefer `topic` for OR + alias resolver. | |
| updated_since | No | ISO 8601 timestamp — return only questions updated after this (delta sync) | |
| exclude_source | No | Exclude these source databases, e.g. `["entityq"]`. Use to drop noisy auto-generated sources. Applied after `source` if both are present. | |
| content_language | No | With `ids`, returns each question in this CONTENT language (its `text`/answers) by following the translation chain — the same questions in another language, not a re-draw. Distinct from `lang` (which only localizes category/tag labels). Supported: en, pl. Untranslated ids land in `meta.missing`. |
| Name | Required | Description |
|---|---|---|
| meta | Yes | Pagination metadata: count of returned rows, total (exact match count, only when count=exact), nextCursor (null = end), language echoed. |
| questions | Yes | Array of trivia questions for the current page, each with full attribution. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds substantial behavior beyond annotations: default quality exclusion (quality='all' reveals flagged), stable cursor over id UUIDv7 DESC, ids as a terminal selector ignoring browse filters, missing ids in meta.missing, the 'quality' field behavior, attribution requirements, and common mistakes. Annotations mark read-only/idempotent; description complements without contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but well-structured with labeled sections (USE WHEN, PAGINATION, KEY FILTERS, etc.) that make navigation easy. Some content repeats schema descriptions (e.g., limit, count), but most sentences add necessary context. A 4 reflects the slight redundancy weighed against excellent organization.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 20-parameter tool, the description is remarkably complete: all filters, pagination contract, batch behavior, output shape, and attribution obligations. It even documents common mistakes. With an output schema present, it optionally explains the return structure, but does so succinctly and correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
While schema covers 100% of parameters, the description enriches meaning significantly: explains cultural affinity for regions, distinguishes topic vs tags and content_language vs lang, defines quality presets, clarifies source/exclude_source precedence, and positions updated_since for delta sync. This goes well beyond the schema's field-level descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource+scope: 'Cursor-paginated browse over the catalog.' It explicitly distinguishes from siblings by stating 'NOT WHEN: you only need N random samples (use quizbase_random) or a single record (use quizbase_question_by_id).' It also covers batch fetch via ids, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Contains explicit 'USE WHEN' and 'NOT WHEN' sections naming quizbase_random and quizbase_question_by_id as alternatives. Also references quizbase_regions for discovering region codes and quizbase_categories for category slugs, guiding the agent to the right tool for auxiliary lookups.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
quizbase_question_by_idGet a single question by UUIDAFetch one question with FULL per-record attribution (source, author, license, modifications, lastModified, sourceId, url) and quality: "high" | "needs_review" (always present — deep-link semantic means full row). USE WHEN: deep link to a question, full provenance lookup for redistribution, cache refresh, moderation inspection. INPUTS: id (UUID), lang (affects category.name and label translations only). 404 returned via {question: null, error: "not_found"} — id may be invalid, pending/rejected, canonical-duplicate, or tombstoned.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Question UUID (v7 format). Stable across language translations — the same UUID may exist in multiple languages with different text but same canonical answer. | |
| lang | No | Language for the response (ISO 639-1). Default "en". Supported: en, pl. Affects `text`, `correct`, `incorrect`, plus localized labels in `category.name`, `subcategories[].label`, `tags[].label`. | en |
| Name | Required | Description |
|---|---|---|
| error | No | Error code when question is null (e.g. `not_found`). |
| question | Yes | Question object with full attribution and quality flag. Null when not found. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly and idempotent hints, but the description adds valuable behavioral details: the 'always present' quality field, the 404 response shape with {question: null, error: 'not_found'}, and the possible id states (invalid, pending/rejected, canonical-duplicate, tombstoned). This goes beyond annotations and is highly useful for handling edge cases.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: purpose, use cases, inputs, then error behavior. Every sentence contributes meaningful information without unnecessary filler. The structure is easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers error responses, id states, and the scope of language effects, making it largely complete for a single-resource fetch tool with an output schema present. However, the inaccurate statement about lang reduces overall completeness and trust, so it doesn't earn a 5.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description incorrectly states that lang 'affects category.name and label translations only,' but the input schema explicitly says lang affects 'text, correct, incorrect' as well. This is misleading and contradicts the schema, undermining the value of the parameter guidance. The schema is comprehensive, but the description introduces an error rather than adding clarity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Fetch one question' with a specific verb and resource, and emphasizes the full per-record attribution and deep-link semantics. This distinguishes it from sibling tools like quizbase_list or quizbase_random, which are about listing or random selection.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit 'USE WHEN' contexts (deep link, provenance lookup, cache refresh, moderation inspection), giving clear guidance on when to use this tool. However, it does not explicitly mention alternatives or exclusions, so it misses the top score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
quizbase_randomGet random trivia questionsAFetch N random trivia questions matching filters. Quality-first: by default excludes questions flagged for review (use quality='all' to include for audit/research).
USE WHEN: building a quiz, sampling content for warmup, generating practice sets. NOT WHEN: you need a specific question ID (use quizbase_question_by_id) or want to explore a topic deeply with facets (use quizbase_topic_by_slug).
KEY FILTERS:
amount: 1-50, default 10.
lang: ISO 639-1. Default "en". Supported: en, pl. Strict — unknown language returns 400.
category (slug): e.g. geography, history, science-and-nature. Full list via quizbase_categories.
difficulty: trivial | easy | medium | hard | expert. LLM-calibrated. Records not yet LLM-rated hold the importer placeholder (mostly "medium" for factoid sources).
type: multiple | boolean (default both; no text_input in random).
regions (cultural affinity, AND): empty in data = no cultural advantage assumed. Lowercase ISO 3166-1 alpha-2 ('us', 'pl', 'gb') + cultural codes ('jewish', 'christian-catholic', 'islam'). Filter for content statistically more likely known by residents/members. Discover via quizbase_regions.
source (array): include only these source databases (one or more of 12: opentdb, opentriviaqa, kqa-pro, entityq, mintaka, mkqa, nq-open, creak, qasc, arc, webq, quizbase).
exclude_source (array): drop these sources, e.g. ["entityq"] for human-curated only. Applied after source.
license (SPDX): CC-BY-SA-4.0 | CC-BY-SA-3.0 | MIT | etc. Restrict to redistribution-friendly content.
topic (curated slug): higher precision than tags. Alias resolver matches subcategories+tags. List via quizbase_topics.
topics_any: OR over curated topics, max 10.
tags (AND), tags_any (OR), subcategory: raw taxonomy. Use topic if available.
quality: 'high' (default, recommended) = cleanest, most broadly-useful. 'standard' = broader pool incl. niche/too-specific (more volume). 'all' = audit/research, includes flagged — when 'all', each question gains a "quality" field ('high' or 'needs_review').
exclude (UUIDs, max 250): de-dupe within a quiz session.
OUTPUT: { questions: [...], meta: { count, language } }. Each question carries full per-record attribution (source, author, license, licenseVersion, licenseUrl, sourceId, url, modifications, lastModified) — identical shape to REST /api/v1/questions/random.
ATTRIBUTION REQUIRED if you redistribute. CC-BY-SA modifications must be credited per § 3(a)(1)(B) using each question's own attribution object.
COMMON MISTAKES: forcing lang='pl' for a global audience (use 'en' default); skipping quality (default already excludes flagged content — only pass quality='all' for audit); using tags when a curated topic exists (worse precision).
| Name | Required | Description | Default |
|---|---|---|---|
| lang | No | Question language as ISO 639-1 code. Default "en". Supported: en, pl. Strict — unknown language returns 400. The same `id` may exist in multiple languages (translated rows share `id`). | en |
| tags | No | AND-logic: question must have ALL these tag slugs (kebab-case) | |
| type | No | "multiple" = 1 correct + 3 distractors. "boolean" = True/False (Prawda/Fałsz in pl). | |
| topic | No | Curated topic slug — alias resolver matches subcategories and tags | |
| amount | No | Number of random questions to return. Range 1-50, default 10. Each call samples independently — pass `exclude` with previously-seen UUIDs to avoid duplicates across calls within one session. | |
| source | No | Include only these source databases (one or more of 12: opentdb, opentriviaqa, mkqa, mintaka, kqa-pro, entityq, nq-open, creak, qasc, arc, webq, quizbase). Matches `attribution.source` per question. | |
| exclude | No | List of question UUIDs to exclude from random sampling. Use to de-dupe within a quiz session — pass IDs you already showed the user so they are not repeated. Max 250 IDs per call. | |
| license | No | SPDX license string (e.g. CC-BY-SA-4.0, CC-BY-SA-3.0, MIT). Filter for redistribution-friendly content. Each question carries its own `attribution.license`. | |
| quality | No | Quality preset. "high" (default) returns only the cleanest, most broadly-useful questions. "standard" broadens to the full reviewed pool incl. niche/too-specific (more volume). "all" includes everything flagged for review too — for audit, research, or BY-SA dump consumption. | high |
| regions | No | Cultural affinity codes. A question is tagged with a region if residents of that country, or members of that cultural/religious group, are **statistically more likely to know** the answer (NOT geography of the subject). Lowercase ISO 3166-1 alpha-2 (`us`, `pl`, `gb`) plus cultural codes (`jewish`, `christian-catholic`, `islam`). AND-logic. Empty array in DB = universally accessible (no cultural advantage assumed). Use `quizbase_regions` for the full catalog with counts. | |
| category | No | Top-level category slug (kebab-case) — e.g. `geography`, `history`, `science-and-nature`. 24 categories total. Use `quizbase_categories` for the full canonical list with localized names. | |
| tags_any | No | OR-logic: question must have AT LEAST ONE of these tag slugs | |
| difficulty | No | LLM-calibrated 5-level difficulty. trivial=common-knowledge, easy=approachable, medium=requires-thought, hard=needs-domain-context, expert=specialist. Records not yet LLM-rated hold the importer placeholder (mostly "medium" for factoid sources). | |
| topics_any | No | OR-logic over curated topic slugs (resolves aliases) | |
| subcategory | No | Raw subcategory slug (kebab-case). Prefer `topic` for OR semantics + alias resolver. | |
| exclude_source | No | Exclude these source databases. Use to drop noisy auto-generated sources, e.g. `["entityq"]` for human-curated only. Applied after `source` if both are present. |
| Name | Required | Description |
|---|---|---|
| meta | Yes | Response metadata: how many questions returned and which language. |
| questions | Yes | Array of trivia questions, each carries full per-record attribution. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Even with annotations (readOnlyHint=true, destructiveHint=false) already covering safety, the description adds substantial behavioral context: quality-first default excluding flagged content, independent random sampling, strict language validation returning 400, and placeholder difficulty for unrated records. It also discloses attribution requirements and modification crediting, going well beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but impeccably structured: purpose, usage guidance, key filters, output, attribution, common mistakes. Each section earns its place and adds distinct value. Bullet-listed filters with inline explanations and a separate 'COMMON MISTAKES' section make it skimmable and practical—no waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 16-parameter, 0-required tool, the description covers everything: output shape (questions + meta), attribution requirements, de-duplication via exclude, quality semantics, and common pitfalls. The openWorldHint and idempotentHint annotations are modest, but the description fully compensates with real-world guidance and edge-case behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description significantly enriches parameter semantics. It explains cultural affinity for regions, precision differences between topic and tags, the effect of quality='all' adding a field, and common mistakes like forcing lang='pl' or using tags when a curated topic exists. This far exceeds what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource+scope: 'Fetch N random trivia questions matching filters.' It clearly distinguishes the tool from siblings by explicitly naming alternatives (quizbase_question_by_id for specific IDs, quizbase_topic_by_slug for deep topic exploration), leaving no ambiguity about what this tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'USE WHEN' and 'NOT WHEN' sections provide explicit guidance on appropriate contexts (building quizzes, sampling, practice sets) and explicitly exclude scenarios better served by sibling tools, naming them directly. This is exactly the when/when-not/alternatives guidance the dimension asks for.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
quizbase_regionsList region codes (cultural affinity) with countsADiscover region codes used by the catalog. Cultural affinity — a question is tagged with a region if residents of that country, or members of that cultural/religious group, are statistically more likely to know the answer (NOT geography of the subject). USE WHEN: planning a quiz targeting users from a specific country or cultural background, exploring "what regions are represented". OUTPUT: array of {code, kind, label, count} sorted by count DESC. INPUTS: lang (en|pl), q (substring on code/label), kind (country|cultural), cursor, limit (max 500). Pair with quizbase_random or quizbase_list using regions:[...] to fetch matching questions.
| Name | Required | Description | Default |
|---|---|---|---|
| q | No | Substring search on region code + label (case-insensitive). E.g. `q=jew` returns `jewish` cultural code. | |
| kind | No | Filter by region type. `country` returns ISO 3166-1 alpha-2 codes (`us`, `pl`, `gb`...). `cultural` returns cultural/religious affinity codes (`jewish`, `christian-catholic`, `islam`...). Omit for both. | |
| lang | No | Language for region `label` (ISO 639-1). Default "en". Supported: en, pl. Codes themselves language-agnostic. | en |
| limit | No | Page size (1-500, default 100). Catalog has ~150 distinct codes per language. | |
| cursor | No | Opaque pagination cursor from previous `meta.nextCursor`. Omit for page 1. |
| Name | Required | Description |
|---|---|---|
| meta | Yes | Pagination metadata: count returned, total available, cursor for next page. |
| regions | Yes | Region codes (cultural affinity) with localized labels, kind (country|cultural), and per-region counts. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is clear. The description adds behavioral context beyond annotations: the cultural affinity definition, output format `array of {code, kind, label, count}`, sort order (count DESC), and input semantics. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact yet rich, using bold labels (cultural affinity, USE WHEN, OUTPUT, INPUTS) to structure information. Every sentence adds value — from purpose to usage to pairing — with no filler or redundant restatement of the title.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of a full output schema, the description is complete enough. It covers the tool's purpose, key semantic disambiguation, usage scenarios, output shape, and how to combine with sibling tools. No significant gaps remain for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and each parameter (q, kind, lang, limit, cursor) already has clear descriptions. The tool description merely summarizes the parameters without adding new meaning beyond what the schema provides, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Discover region codes used by the catalog' — a specific verb and resource. It then clarifies the crucial 'cultural affinity' meaning, explicitly distinguishing it from geography, and defines the output array shape. This clearly differentiates it from sibling list tools like categories, tags, and languages.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides an explicit 'USE WHEN' section (planning quizzes for country/cultural backgrounds) and a negative constraint ('NOT geography of the subject'). It also instructs users to pair with quizbase_random or quizbase_list using the `regions:[...]` parameter, which is concrete cross-tool guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
quizbase_reportSubmit a content correction or copyright reportAInspectSubmit a content correction, copyright concern, or factual error report. USE WHEN: user (via your interface) flags a wrong answer, broken translation, attribution issue, or DMCA concern. INPUTS: at least one of (questionId UUID, questionText, questionUrl), type (translation|factual|inappropriate|attribution|other), comment (optional, max 2000), reporterEmail (optional). OUTPUT on success: {ok:true, reportId}. On failure the result is marked isError:true with structuredContent {error, message} — error codes: invalid_input, not_found, rate_limit_exceeded (per-IP 5/min), internal_error.
| Name | Required | Description | Default |
|---|---|---|---|
| type | Yes | Report category. `translation` = bad EN→PL or other lang translation. `factual` = incorrect answer / outdated fact. `inappropriate` = offensive content. `attribution` = missing/wrong source credit (CC-BY-SA § 3 violation). `other` = anything else (use `comment` to explain). | |
| comment | No | Free-text explanation of the issue (max 2000 chars). Strongly recommended — bare flag without context is hard to triage. Examples: "Currency in answer was correct in 2018 but Argentina changed it in 2023", "Polish translation reads as gibberish". | |
| questionId | No | Question UUID (v7) being reported. Highest-fidelity identifier — use when you have it. At least one of `questionId`, `questionText`, `questionUrl` is required. | |
| questionUrl | No | URL referencing the question (e.g. your app deep-link, screenshot host). Useful when question came from a downstream surface and the user clicks "Report" without raw text/ID access. | |
| questionText | No | Full or partial question text (10-2000 chars) when UUID is not available. Used by moderators to locate the record. Lower fidelity than `questionId`. | |
| reporterEmail | No | Reporter email for follow-up (optional). Use when you have user consent — we may contact for clarification if the report is unclear. |
| Name | Required | Description |
|---|---|---|
| ok | Yes | Always true on success; failures use isError, not this field. |
| reportId | No | UUID of the recorded report. Use for follow-up references. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes well beyond annotations by disclosing the success output shape ({ok:true, reportId}), failure behavior (isError:true with structuredContent), and concrete error codes including a per-IP rate limit of 5/min. This adds meaningful behavioral context that annotations alone do not provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is densely packed but every clause earns its place: usage trigger, input summary, output contract, and error codes. It uses clear labels (USE WHEN, INPUTS, OUTPUT) and front-loads the core purpose, making it highly scannable without unnecessary filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 6 parameters, one required, a group constraint, an output schema, and error handling, the description covers all necessary operational context: when to use it, what inputs are acceptable, what the caller receives on success/failure, and rate-limit behavior. It is fully actionable for an AI agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
While schema coverage is 100%, the description adds the critical group constraint that at least one of questionId, questionText, or questionUrl is required—information not enforced by the JSON schema alone. It also summarizes the type enum categories and the optionality of comment/reporterEmail, enriching the bare property definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Submit') and identifies the resource (content correction, copyright concern, or factual error report), making the tool's purpose unmistakable. It clearly differentiates from all sibling tools, which are read-only retrieval operations, by signaling this is the reporting/mutation tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states 'USE WHEN' and enumerates the triggering scenarios: wrong answer, broken translation, attribution issue, or DMCA concern. It implies this is the report-submission counterpart to the read-only quizbase tools, giving clear guidance for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
quizbase_statsGet public catalog statisticsAPublic catalog counters with live breakdowns by language, source, category, difficulty, topic, tag.
USE WHEN: showing catalog overview, picking a category programmatically, building landing copy, deciding "do we have enough X-content for this quiz".
OUTPUT FIELDS:
total: approved questions in 'en' + 'pl'.
byLanguage: { en: N, pl: N }.
bySource: { entityq: N, mintaka: N, 'kqa-pro': N, ... } — 12 keys, one per source database.
byDifficulty: { trivial: N, easy: N, medium: N, hard: N, expert: N, unrated: N } — null difficulty mapped to 'unrated'. trivial/expert populated by LLM calibration.
byCategory: top 24 with localized names.
byTopic / byTag: top 30 curated topics + top 30 tags with localized labels.
meta: { generatedAt: ISO 8601, language }.
INPUTS: lang (default "en") affects byCategory[].name and byTopic[].label / byTag[].label.
DATA FRESHNESS: snapshot regenerated daily (~03:00 UTC) + on demand after batch imports. generatedAt shows when. Counts stable ±0.01% between snapshots.
COMMON MISTAKES: polling stats every request (cache it on your side; 5-min Redis TTL on ours); treating bySource keys as stable enum (use quizbase_languages / quizbase_categories for canonical input enums).
| Name | Required | Description | Default |
|---|---|---|---|
| lang | No | Language for localized labels in `byCategory[].name`, `byTopic[].label`, `byTag[].label`. Default "en". Supported: en, pl. Numeric counts (total, byLanguage, bySource, byDifficulty) are language-agnostic. | en |
| Name | Required | Description |
|---|---|---|
| meta | Yes | Snapshot metadata: generation timestamp and echoed language. |
| byTag | Yes | Top 30 raw tags with localized labels. |
| total | Yes | Approved questions count across all supported languages. |
| byTopic | Yes | Top 30 curated topics with localized labels. |
| bySource | Yes | Count per source database (12 keys). |
| byCategory | Yes | Top 24 categories with localized names and counts. |
| byLanguage | Yes | Count per language code. |
| byDifficulty | Yes | Count per difficulty bucket (trivial / easy / medium / hard / expert / unrated). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, and non-destructive hints, but the description adds significant behavioral detail: snapshot regeneration at ~03:00 UTC, on-demand regeneration after batch imports, ±0.01% count stability, null difficulty mapped to 'unrated', trivial/expert populated by LLM calibration, and a 5-min Redis TTL. This contextualizes the annotation's safety profile and explains data freshness and caching behavior without contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is organized with clear section headers (USE WHEN, OUTPUT FIELDS, INPUTS, DATA FRESHNESS, COMMON MISTAKES), front-loads the purpose, and every sentence contributes meaningful information. It is detailed but compact, avoiding redundant phrasing while covering all relevant operational aspects.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a statistics tool with one optional parameter, the description comprehensively explains the output schema fields, freshness model, language effects, and common pitfalls. The presence of an official output schema is complemented rather than duplicated, and the description covers everything an agent would need to correctly select and interpret results from this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers the single `lang` parameter 100% with an enum and description. The tool description adds further semantic value by specifying exactly which fields are affected (`byCategory[].name`, `byTopic[].label`, `byTag[].label`) and clarifying that numeric counts are language-agnostic. This goes beyond the schema's generic description, though the schema already did most of the work.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific, verb-driven statement: 'Public catalog counters with live breakdowns by language, source, category, difficulty, topic, tag.' This clearly identifies the tool as a statistics aggregator, differentiating it from sibling tools like quizbase_list or quizbase_categories, which provide individual items rather than aggregate counts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'USE WHEN' section explicitly enumerates use cases (showing catalog overview, picking a category programmatically, building landing copy, deciding content sufficiency) and the 'COMMON MISTAKES' section advises against polling every request and points to quizbase_languages/quizbase_categories for canonical enums, offering alternatives. This exceeds the minimum bar by providing both when-to-use and when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
quizbase_subcategoriesList raw subcategories with countsARaw subcategory dump (LLM-organic kebab-case, middle taxonomy layer between category and tags) with display label and count. USE WHEN: navigating between top-level category and individual tags, exploring topic structure. Filter questions via quizbase_random?subcategory=. INPUTS: q, cursor, limit (max 500).
| Name | Required | Description | Default |
|---|---|---|---|
| q | No | Substring search across subcategory slug + label (case-insensitive). Useful for partial discovery. | |
| lang | No | Language for subcategory `label` (ISO 639-1). Default "en". Supported: en, pl. Slugs language-agnostic. | en |
| limit | No | Page size (1-500, default 100). | |
| cursor | No | Opaque pagination cursor from previous `meta.nextCursor`. Omit for page 1. |
| Name | Required | Description |
|---|---|---|
| meta | Yes | Pagination metadata: count returned, total available, cursor for next page. |
| subcategories | Yes | Subcategories on this page with localized labels and per-subcategory counts. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds valuable context beyond that: 'LLM-organic kebab-case' implies slugs may be unstructured, and 'raw dump' clarifies no enrichment or aggregation. It also mentions 'display label and count' for return contents. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded with purpose, followed by usage guidance. The 'INPUTS' line is somewhat redundant and incomplete (missing lang), which prevents a perfect score, but overall the size is appropriate and every other sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists and annotations are strong, the description sufficiently covers the tool's role, usage, and return basics (label and count). The omission of 'lang' in the INPUTS summary is a minor gap, but the schema already documents it. For a read-only listing tool, this description is complete enough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and each parameter already has a description. The INPUTS line in the description is redundant and actually omits the 'lang' parameter, which is a minor inaccuracy. It adds no new semantic meaning beyond the schema, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists raw subcategories with display labels and counts, and explicitly positions it as the middle taxonomy layer between categories and tags, distinguishing it from siblings like quizbase_categories and quizbase_tags. The verb 'dump' plus resource 'subcategories' is specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage context: 'USE WHEN: navigating between top-level category and individual tags, exploring topic structure.' It also gives a concrete downstream action (filtering questions via quizbase_random). However, it does not explicitly mention when not to use the tool or name alternative tools, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
quizbase_tagsList raw tags with countsARaw tag dump (10k+ entries) with display label and question count. USE WHEN: building a tag picker, searching "is X a tag", running analytics. Curated higher-level groupings → quizbase_topics. INPUTS: q (substring), cursor, limit (max 500).
| Name | Required | Description | Default |
|---|---|---|---|
| q | No | Substring search across tag slug + label (case-insensitive). Use to find specific tags by partial name. | |
| lang | No | Language for tag `label` (ISO 639-1). Default "en". Supported: en, pl. Slugs are language-agnostic canonical identifiers. | en |
| limit | No | Page size (1-500, default 100). | |
| cursor | No | Opaque pagination cursor from previous `meta.nextCursor`. Omit for page 1. Stop when null. |
| Name | Required | Description |
|---|---|---|
| meta | Yes | Pagination metadata: count returned, total available, cursor for next page. |
| tags | Yes | Tags on this page with display labels and per-tag question counts. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, and non-destructive. Description adds the scale ('10k+ entries'), raw/uncurated nature, and output fields (display label, question count). This goes beyond annotations, though it doesn't mention potential performance or sort behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences with clear labels (USE WHEN, INPUTS) and a pointer to alternative. Every sentence earns its place, and the structure front-loads purpose and usage.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Output schema exists, so return values are covered. Parameters are fully documented in schema, annotations cover side effects, and description covers usage and alternatives. It is complete for a read-only list tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and each parameter is described. The description's 'INPUTS' line simply restates q, cursor, and limit without adding new semantic detail (e.g., lang is omitted). It provides no added meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states a raw tag dump with display label and question count, using 'raw' to distinguish from curated topics. The explicit pointer to quizbase_topics for curated groupings differentiates it from the sibling tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides a concrete 'USE WHEN' list (building a tag picker, searching 'is X a tag', running analytics) and explicitly mentions the alternative for curated groupings (quizbase_topics). This gives clear when-to-use and alternative guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
quizbase_topic_by_slugGet curated topic detail with facetsAFetch one curated topic with facets (byCategory, byDifficulty, byLanguage, coOccurringTags, coOccurringSubcategories) and 3 sample questions. USE WHEN: zooming into a topic, deciding multi-round quiz structure. Returns {topic: null, error: "not_found"} when slug is unknown.
| Name | Required | Description | Default |
|---|---|---|---|
| lang | No | Language for `topic.label` and sample question text (ISO 639-1). Default "en". Supported: en, pl. Numeric facet counts language-agnostic. | en |
| slug | Yes | Curated topic slug (kebab-case) — e.g. `star-wars`, `world-war-ii`, `programming-languages`. List all via `quizbase_topics`. Aliases resolve automatically (e.g. `sw` → `star-wars`). |
| Name | Required | Description |
|---|---|---|
| meta | No | Response metadata. |
| error | No | Error code when topic is null (e.g. `not_found`). |
| topic | Yes | Topic detail with metadata. Null if slug not found. |
| facets | No | Facet breakdowns: byCategory, byDifficulty, byLanguage, coOccurringTags, coOccurringSubcategories. |
| samples | No | Up to 3 sample questions matching this topic. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true; the description adds the not-found response shape (`{topic: null, error: "not_found"}`) and the sample-question detail. This is useful behavioral context beyond annotations, with no contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences: the first front-loads the action and output composition, the second combines a labeled 'USE WHEN' directive with the error case. Every phrase earns its place, with no redundancy against schema or annotations.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (2 params, output schema, strong annotations), the description covers purpose, usage context, and error behavior. Nothing critical is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both `slug` and `lang` fully explained in the schema. The description itself adds no parameter-level details, so baseline 3 is appropriate; the schema carries the burden.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Fetch one curated topic with facets' – a specific verb plus resource – and enumerates the exact facets returned, distinguishing it from list tools like quizbase_topics. Mentioning '3 sample questions' further sharpens the scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
An explicit 'USE WHEN' clause ('zooming into a topic, deciding multi-round quiz structure') provides clear context. However, it does not name alternatives or give when-not-to-use guidance, stopping short of the top score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
quizbase_topicsList curated topics with aliasesADiscover curated topics (2,184 entries with aliases). USE WHEN: planning a multi-round quiz, exploring "what is available about X", showing topic browser. Sorted by count DESC, slug ASC. Cursor-paginated. INPUTS: q (substring on label/alias), kind (tag|subcategory), cursor, limit (max 500).
| Name | Required | Description | Default |
|---|---|---|---|
| q | No | Substring search across topic label, slug, and aliases (case-insensitive). Use to find a curated topic by partial name — e.g. `q=star` returns `star-wars`, `star-trek`, `stars-and-astronomy`. | |
| kind | No | Filter by underlying taxonomy origin. `tag` returns topics resolving to tag-level slugs (proper nouns, specific entities). `subcategory` returns topics resolving to broader subcategory groupings. Omit for all. | |
| lang | No | Language for `label` field in each topic (ISO 639-1). Default "en". Supported: en, pl. Slugs themselves are language-agnostic (canonical). | en |
| limit | No | Page size (1-500, default 100). Higher = fewer round-trips. | |
| cursor | No | Opaque pagination cursor from previous `meta.nextCursor`. Omit for page 1; pass last response's `meta.nextCursor` for next pages. Stop when `nextCursor` is null. |
| Name | Required | Description |
|---|---|---|
| meta | Yes | Pagination metadata: count returned, total available, cursor for next page. |
| topics | Yes | Topics on this page with localized labels, counts, and underlying kind. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, so the description adds valuable behavioral context: sorted by count DESC, slug ASC, cursor-paginated, and a fixed entry count of 2,184. This goes beyond the structured annotations and helps the agent anticipate response characteristics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Highly concise and well-structured: main purpose first, then 'USE WHEN' scenarios, then behavioral details (sorting, pagination). Every sentence adds value, and the format is easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists and all parameters are optional with rich schema descriptions, this description covers purpose, use cases, sorting, pagination, and input summary. No critical gaps for a read-only list tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with detailed descriptions for all parameters (q, kind, lang, limit, cursor). The description summarizes q, kind, cursor, and limit but omits lang. It does not add significant meaning beyond the schema, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description uses specific verb 'Discover' with resource 'curated topics (2,184 entries with aliases)', clearly distinguishing from sibling tools like quizbase_categories or quizbase_tags. It also mentions sorting and pagination, making the tool's role unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit 'USE WHEN' with three concrete scenarios: planning multi-round quiz, exploring what is available about X, and showing a topic browser. No 'when not' or alternative tool names are mentioned, but the context is clear enough for most use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Claim this connector by publishing a /.well-known/glama.json file on your server's domain with the following structure:
{
"$schema": "https://glama.ai/mcp/schemas/connector.json",
"maintainers": [{ "email": "your-email@example.com" }]
}The email address must match the email associated with your Glama account. Once published, Glama will automatically detect and verify the file within a few minutes.
Control your server's listing on Glama, including description and metadata
Access analytics and receive server usage reports
Get monitoring and health status updates for your server
Feature your server to boost visibility and reach more users
For users:
Full audit trail – every tool call is logged with inputs and outputs for compliance and debugging
Granular tool control – enable or disable individual tools per connector to limit what your AI agents can do
Centralized credential management – store and rotate API keys and OAuth tokens in one place
Change alerts – get notified when a connector changes its schema, adds or removes tools, or updates tool definitions, so nothing breaks silently
For server owners:
Proven adoption – public usage metrics on your listing show real-world traction and build trust with prospective users
Tool-level analytics – see which tools are being used most, helping you prioritize development and documentation
Direct user feedback – users can report issues and suggest improvements through the listing, giving you a channel you would not have otherwise
The connector status is unhealthy when Glama is unable to successfully connect to the server. This can happen for several reasons:
The server is experiencing an outage
The URL of the server is wrong
Credentials required to access the server are missing or invalid
If you are the owner of this MCP connector and would like to make modifications to the listing, including providing test credentials for accessing the server, please contact support@glama.ai.
No comments yet. Be the first to start the discussion!