QuizBase

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds that it's a stable enum (rarely changes), providing extra context without contradicting 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?

Two sentences: first states purpose, second gives usage and alternatives. No wasted words; front-loaded key information.

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 output schema present, description needn't explain return values. It covers purpose, usage, stability, and sibling tools, making it complete for a simple 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%, so baseline is 3. The description adds minimal parameter info beyond the schema; it mentions i18n labels, which aligns with lang parameter but doesn't enhance meaning.

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 'List of 24 top-level categories with i18n labels,' specifying the resource and action. It distinguishes from siblings by directing to quizbase_subcategories or 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?

Explicitly states 'USE WHEN: building a category picker, validating ?category= input,' and notes the stable enum nature, guiding appropriate use.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate readOnly, idempotent, and not destructive. Description adds 'Day 1: en + pl' indicating limited initial language support, and mentions ISO 639-1 standard.

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?

Very concise: two sentences plus usage hint and day note. Front-loaded with primary purpose, no extraneous text.

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 low complexity, one optional parameter, and presence of output schema (from context), description is complete. Covers purpose, usage, and behavioral notes like initial language set.

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 covers 100% of parameter details with enum and default. Description adds extra context: 'Codes themselves are language-agnostic.' Adds value beyond 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 starts with 'Returns supported language whitelist (ISO 639-1) with question counts per language.' This is specific and differentiates 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?

Explicitly states 'USE WHEN: showing language picker, validating ?lang= input, deciding fallback.' Provides clear context but does not mention alternatives among siblings.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint and idempotentHint, so the description adds context beyond that: quality-first default, pagination stability, attribution requirements, and behavior of the 'quality' filter. No contradictions.

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?

Well-structured with clear sections (USE WHEN, PAGINATION, KEY FILTERS). It is relatively long but necessary given the complexity. Front-loaded with the main purpose. Could trim some redundant details, but overall well-organized.

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 complexity (17 parameters, many filters, pagination, counting), the description covers virtually all aspects: filtering options, pagination mechanics, counting strategies, output structure, and attribution requirements. Very thorough.

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 baseline is 3. The description adds extra context for many parameters (e.g., regions interpretation, quality field behavior, AND vs OR logic for tags), which justifies a 4.

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?

Clearly states it is a cursor-paginated browse over the catalog. Explicitly distinguishes from sibling tools like quizbase_random and quizbase_question_by_id, making it easy for an agent to select the correct 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 explicit 'USE WHEN' and 'NOT WHEN' sections that list use cases (full catalog sync, delta sync) and alternatives (quizbase_random, quizbase_question_by_id). Also highlights common mistakes, such as not passing the cursor.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate read-only, idempotent, non-destructive. Description adds details on quality field always present and 404 response format, adding value beyond 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?

Two well-structured sentences plus concise USE WHEN and INPUTS notes. No filler; every sentence adds value.

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. Description also explains error response and conditions, making it complete for a single-entity retrieval 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%, so baseline 3. Description enriches by explaining lang affects only category.name and label translations, and id is UUID v7 stable across languages.

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 fetches a single question by UUID with full attribution, and the 'deep link' context distinguishes it from sibling tools like quizbase_list or quizbase_random.

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?

Explicit USE WHEN scenarios are given (deep link, provenance, cache refresh, moderation inspection), though it does not specify when not to use it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations indicate readOnlyHint=true and destructiveHint=false. The description adds context on quality filtering, strict language enforcement, difficulty calibration, attribution requirements, and common mistakes, going well beyond 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?

Well-structured with headings and front-loaded purpose. Slightly verbose due to comprehensive coverage, but every section adds value. Minor deduction for length.

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 15 parameters, full schema coverage, and output schema existence, the description covers edge cases (strict language, placeholder difficulty, empty regions), attribution rules, and common mistakes, making it highly complete.

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?

With 100% schema coverage, baseline is 3. The description adds rich meaning for many parameters, such as explaining quality values, regions cultural affinity, difficulty levels, and source types, far exceeding schema 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 clearly states the tool fetches N random trivia questions with filters, and distinguishes itself from siblings like quizbase_question_by_id (for specific ID) and quizbase_topic_by_slug (for deep topic exploration).

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?

Explicitly mentions when to use (building a quiz, sampling, practice sets) and when not to use (need specific ID, deep topic exploration), and names alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. The description adds useful context: explains the output format (array sorted by count DESC) and how it relates to queries. No contradictions.

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 concise (3 sentences) and front-loaded with purpose. Uses bold for emphasis. Could be slightly more structured but is clear and not verbose.

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 complexity (5 parameters, full schema coverage, output schema exists), the description covers the output format, typical usage, and pairing hints. It is complete enough for an agent to use 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%, so each parameter has a description. The description recaps inputs briefly but does not add significant meaning beyond what the schema provides. 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 it lists region codes with cultural affinity counts, with a specific verb ('list') and resource ('region codes'). It distinguishes from siblings by explaining the cultural affinity concept (not geography) and mentions pairing with quizbase_random 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 usage scenarios: 'USE WHEN: planning a quiz targeting users from a specific country or cultural background, exploring what regions are represented.' It also suggests pairing with other tools. However, it does not explicitly state when NOT to use or provide alternatives to this specific tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations indicate non-read, non-idempotent, non-destructive mutation. Description adds outputs, error codes, and rate limit (5/min per IP), which are not in 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?

Single dense paragraph front-loads purpose, then usage, inputs, output, errors. Every sentence adds value, no repetition of schema.

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 6 params, 1 required, and existing output schema, the description covers all aspects: when to use, what to provide, what to expect on success/failure, and error codes.

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 has 100% coverage but description adds multi-parameter constraint ("at least one of"), clarifies combinations, and reiterates max lengths. Output schema is also described.

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?

Clearly states "submit a content correction, copyright concern, or factual error report," a specific verb and resource. Distinct from all sibling tools which are retrieval/list-oriented.

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?

Begins with "USE WHEN: user flags a wrong answer..." providing explicit usage scenarios and conditions. No sibling tools perform reporting, so no alternative guidance needed.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds valuable behavioral traits: data freshness (snapshot regenerated daily + on demand, generatedAt timestamp), stability between snapshots (±0.01%), and caching advice (5-min Redis TTL). This exceeds the information provided by annotations alone.

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 well-structured with clear sections (USE WHEN, OUTPUT FIELDS, INPUTS, DATA FRESHNESS, COMMON MISTAKES) and is front-loaded with the core purpose. However, it is somewhat verbose in listing all output fields, which might be redundant given the output schema exists. Still, it earns its place by being informative and organized.

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 returning complex breakdowns, the description covers purpose, usage, data freshness, caching, parameter behavior, and common mistakes. It fully compensates for any lack of explanation in the output schema by listing all fields. The context of siblings and annotations further completes the picture.

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 for 'lang' has 100% description coverage and includes an enum. The description further specifies which output fields are affected by the parameter (byCategory[].name, byTopic[].label, byTag[].label) and the default value, adding meaningful context beyond the schema's own description.

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 it provides 'Public catalog counters with live breakdowns by language, source, category, difficulty, topic, tag.' It distinctively lists the specific breakdowns and contrasts with sibling tools that return entity lists rather than aggregated statistics.

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 includes 'USE WHEN: showing catalog overview, picking a category programmatically, building landing copy, deciding 'do we have enough X-content for this quiz'.' It also notes common mistakes (polling every request) and directs to sibling tools (quizbase_languages, quizbase_categories) for canonical enums, providing complete usage guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Description complements annotations by explaining what is returned (display label, count) and pagination behavior. No contradiction with readOnlyHint/idempotentHint/destructiveHint.

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 concise sentences plus a 'USE WHEN' clause. Front-loaded with core purpose, no wasted words.

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 output schema exists, description covers all needed context: taxonomy placement, input parameters, pagination, and downstream usage.

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. Description only lists parameter names without adding new meaning, meeting baseline 3.

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 it lists raw subcategories with counts and positions as middle taxonomy layer between category and tags, distinguishing from siblings.

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?

Explicit 'USE WHEN' section specifies when to use (navigating between category and tags) and how to use results (filter via quizbase_random?subcategory=<slug>).

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds context about scale (10k+ entries) and input parameters, which is useful 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?

Two sentences plus input list. Front-loaded with purpose and usage. Every sentence adds value. No fluff.

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 list tool with pagination and simple filters, the description covers purpose, usage, and inputs. Output schema exists, and description hints at output fields (label, count). Could mention pagination behavior more explicitly but still complete.

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 baseline is 3. Description briefly lists inputs but doesn't add significant meaning beyond what schema descriptions already provide. It confirms q is substring and limit max is 500, which is already in 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?

The description clearly states the tool returns a raw tag dump with count and label. It differentiates from sibling 'quizbase_topics' by noting that tool provides curated groupings.

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?

Explicitly states use cases: building tag picker, searching for tags, analytics. Directs to 'quizbase_topics' for curated groupings, providing clear alternative.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds useful behavioral context: it returns {topic: null, error: 'not_found'} for unknown slugs, and mentions facets and sample questions. No contradictions.

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 very concise: two main sentences plus a usage hint. Every word adds value, and it is front-loaded with the core purpose.

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 an output schema (not shown but indicated), the description covers all key aspects: purpose, facets, sample questions, error handling, and language support. The tool is well-contextualized.

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 descriptions for both parameters. The description adds value by noting alias resolution for slug ('e.g. `sw` → `star-wars`') and language support for lang, which goes beyond schema details.

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 it fetches one curated topic with facets and 3 sample questions, specifying the verb 'Fetch' and the resource. This distinguishes it from sibling tools like quizbase_topics (list all) and others.

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: zooming into a topic, deciding multi-round quiz structure', providing clear context. However, it does not mention when not to use or list alternatives, though the sibling tools context implies that.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, and the description consistently implies a read-only operation. The description adds behavioral detail beyond annotations: 'Sorted by count DESC, slug ASC. Cursor-paginated.' This discloses pagination and ordering, enhancing transparency. 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 three concise sentences, each adding value: purpose and scale, use cases, then behavior and input summary. It is front-loaded with the core function. No unnecessary words or redundancy.

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 complexity (pagination, filtering, sorting, language parameter), the description covers scale (2,184 entries), sorting, pagination method (cursor), and lists inputs. An output schema exists, so return values are documented elsewhere. It lacks mention of rate limits or potential empty results, but is largely complete for a listing 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 description coverage is 100%, so the input schema already provides thorough meaning for all 5 parameters. The description's summary ('INPUTS: q (substring on label/alias), kind (tag|subcategory), cursor, limit (max 500)') restates without adding new semantics. Baseline with high coverage is 3, and the description does not elevate beyond that.

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 'Discover curated topics (2,184 entries with aliases)' with a specific verb ('Discover') and resource ('curated topics'). It distinguishes this tool from siblings like quizbase_categories or quizbase_tags by focusing on topics with aliases, and mentions key behaviors like sorting and pagination.

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 says 'USE WHEN: planning a multi-round quiz, exploring "what is available about X", showing topic browser.' This provides clear context on when to use the tool. It also notes sorting and pagination. However, it does not explicitly mention when not to use or contrast with sibling tools like quizbase_categories, which would improve guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.