An educational MCP server that helps AI assistants teach machine learning, artificial intelligence, and large language models through interactive lessons, quizzes, learning paths, and simulations.
Scored across 8 tools
Each tool targets a clearly distinct resource+action: keyword search vs full-item fetch vs curriculum outline vs filtered study path vs simulation list vs simulation detail vs language inventory vs quiz generation. Descriptions explicitly state negative boundaries (e.g. 'do not use it to read a lesson (use get_content)'), so the list/detail and search/fetch pairs are unambiguous.
All eight names are snake_case with a predictable verb_noun shape: get_content, get_learning_path, get_simulations, get_simulation_details, list_learning_stages, list_supported_languages, search_content, generate_quiz. The get_/list_/search_/generate_ prefixes map cleanly onto retrieve/enumerate/search/create semantics.
Eight tools is well within the ideal 3-15 range and each earns its place: discovery, retrieval, curriculum, path building, simulations, languages, and quiz. No filler or trivially redundant entries.
The surface covers the full read lifecycle for the domain: search → fetch by id/slug, curriculum outline, personalized path, simulation list/detail, locale coverage, and a practice-quiz endpoint. Minor gap: Guides articles and tool pages appear only through search_content (with Guide counts surfacing only in list_supported_languages), so there is no dedicated listing or browsing entry point for those content types, and there are no write/account operations (which may be out of scope).
Return a practice quiz made only of original MasterAI Now knowledge-check questions selected from published stage cards for topic, with options, the correct option, the published explanation and a stage citation URL. Selection is deterministic; no question is generated by a model at request time. Use it for practice or checking understanding; the answer key is included, so present the questions first if the user wants to attempt them. Do not use it to find lessons (use search_content) or to imply a score was recorded (nothing is saved).
| Name | Required | Description | Default |
|---|---|---|---|
| topic | Yes | Subject to quiz on, e.g. "attention", "tokenization", "overfitting", "kv cache". Matching is keyword-based against published stages. | |
| language | No | Locale code. Supported: en, zh, hi, es, fr, ar, tr, de. Defaults to en; any other value falls back to English and is reported as a fallback. | |
| difficulty | No | Restrict to stages labelled at this level. Omit to search the whole curriculum. | |
| questionCount | No | How many questions to return, 1-10. Defaults to 5. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare read-only/idempotent/closed-world safety, but the description adds non-obvious behavior: selection is deterministic and no model generation occurs at request time, and nothing is persisted after the call. The note that the answer key is bundled changes how an agent should sequence its response to the user.
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 sentences, front-loaded with the resource and source, then usage, then exclusions — no filler. The opening sentence is long and packs the return payload into a dense clause, which slightly slows the read but every element is load-bearing.
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 four parameters and no output schema, the description still spells out the return shape (options, correct option, published explanation, stage citation URL) and discloses the determinism and no-persistence guarantees. Nothing an agent needs to call it and present results correctly 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 coverage is 100%, so topic, language, difficulty and questionCount are already documented with ranges, defaults, enum values and fallback behavior. The description references `topic` and the stage-card source but adds no syntax or edge-case meaning beyond the schema, so the baseline 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?
States a specific verb and resource ('Return a practice quiz') plus the exact content source ('original MasterAI Now knowledge-check questions selected from published stage cards'), and explicitly contrasts itself with search_content. An agent can distinguish it from get_content and search_content without opening any schema.
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?
Gives a positive use case ('practice or checking understanding'), a presentation caveat (answer key included, so show questions first), and two explicit exclusions with an alternative named ('Do not use it to find lessons (use search_content)' and 'do not imply a score was recorded'). This is the full when/when-not/alternative pattern.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return one public MasterAI Now item in full, looked up by the stable id from search_content or by a URL slug; provide at least one of the two (id wins when both are set). Includes title, description, plain-text body, type, language, tags, canonical URL, source and update date. Body text is capped at 40,000 characters and truncated says when the canonical URL should be opened for the rest. Use it after search_content to read a lesson before explaining it; do not use it to browse (use search_content). Drafts and scheduled Guides are never returned.
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | Stable id returned by search_content, e.g. "stage:2", "question:training-vs-inference" or "post:<uuid>". Provide this or `slug` (not neither). | |
| slug | No | URL slug, e.g. "linear-regression" (stage), "what-is-a-loss-function" (lesson) or "token-counter" (tool). Ignored when `id` is set. | |
| type | No | Narrows a slug lookup when two content types share a slug: article (published Guides post), lesson (answer-hub explainer), stage (curriculum stage), simulation (browser playground) or tool (AI tool page). | |
| language | No | Locale code. Supported: en, zh, hi, es, fr, ar, tr, de. Defaults to en; any other value falls back to English and is reported as a fallback. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/non-destructive, but the description adds behavior those annotations cannot convey: the 40,000-character body cap, the `truncated` flag and what to do when it is set (open the canonical URL), the `id`-over-`slug` precedence, and the exclusion of drafts and scheduled content. These are exactly the operational details an agent needs before relying on the result.
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?
Purpose, lookup keys and precedence come first, then return contents, then limits, then routing guidance — a well front-loaded structure with no filler. The first sentence is long and semicolon-heavy with parenthetical asides, which slightly taxes scanning, but no clause is wasted.
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?
There is no output schema, and the description compensates by enumerating the returned fields (title, description, body, type, language, tags, canonical URL, source, update date). Combined with the truncation behavior and eligibility exclusions, nothing material is missing for a four-parameter read 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 the baseline is 3, but the description adds a constraint the schema cannot express: at least one of `id` or `slug` must be provided even though neither is formally required. The precedence rule is repeated from the schema's `slug` description, so the gain is modest rather than substantial.
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 and resource ('Return one public MasterAI Now item in full') and immediately names the two lookup keys. It explicitly distinguishes itself from the sibling search_content, so an agent can choose between them without opening either schema.
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?
It gives an explicit when-to-use ('after search_content to read a lesson before explaining it') and an explicit when-not-to-use with the named alternative ('do not use it to browse (use search_content)'). It also states a negative eligibility rule: drafts and scheduled Guides are never returned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Build an ordered study path from real published stages for a required difficulty band (level) and an optional topic. Returns stage URLs, objectives, prerequisites, authored reading minutes and supporting lessons/tools, and reports whether the result follows the official curriculum order. Use it for "where do I start" or "make me a study plan"; it assembles existing content and does not create a new course. Do not use it to read a lesson (use get_content).
| Name | Required | Description | Default |
|---|---|---|---|
| level | Yes | Difficulty band to build the path from. Required. Use beginner for new learners. | |
| topic | No | Optional focus, e.g. "attention", "tokenization", "fine-tuning", "cost". Matching stages are ordered by curriculum position and the response is labelled a recommendation. | |
| language | No | Locale code. Supported: en, zh, hi, es, fr, ar, tr, de. Defaults to en; any other value falls back to English and is reported as a fallback. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover safety and idempotency, but the description adds meaningful behavior beyond them: it assembles existing content rather than creating a course, returns stage URLs, objectives, prerequisites, reading minutes and supporting tools, and reports whether the path follows official order. Auth and rate-limit details are absent, but those are less central for this read-only tool.
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 front-loaded with the core purpose, then return contents, then usage and exclusion guidance. Every sentence contributes useful information, with no filler or redundant restatement.
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 three-parameter read-only assembly tool with full schema coverage but no output schema, the description supplies the missing return-value context and clarifies that no new course is created. The language fallback is adequately covered by the schema.
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 `level`, `topic`, and `language`, including enum values, topic examples, and fallback behavior. The tool description mentions `level` and `topic` but does not add semantics beyond the schema, so the 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 uses a specific verb, 'Build,' and resource, 'ordered study path,' and scopes it to required `level` and optional `topic`. It also distinguishes the tool from `get_content`, so an agent can identify its role without opening the schema.
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?
It gives explicit trigger phrases such as 'where do I start' and 'make me a study plan,' and states a when-not-to-use case with a named alternative: reading a lesson should use `get_content`. This is clear routing guidance with both positive and negative conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Describe one MasterAI Now simulation by its key from get_simulations (a stage slug or stage number is also accepted). Returns purpose, concepts, adjustable parameters, expected outcomes, prerequisite stage, related lessons and the canonical URL, plus steps for using it on the site. Use it before recommending a specific playground; it cannot run the simulation and does not claim to.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes | Simulation key from get_simulations, e.g. "attention-heatmap" or "line-fitter". A stage slug ("linear-regression") or stage number ("7") is also accepted. | |
| language | No | Locale code. Supported: en, zh, hi, es, fr, ar, tr, de. Defaults to en; any other value falls back to English and is reported as a fallback. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint and openWorldHint=false, and the description still adds real value on top: it enumerates what the response contains (purpose, concepts, adjustable parameters, expected outcomes, prerequisite stage, related lessons, canonical URL, usage steps) and disclaims the ability to execute the simulation. That is the kind of expectation-setting the annotations cannot carry.
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, front-loaded with the core action and identifier source, with the usage directive last. The first sentence is a long enumeration of return fields, but each item is informative rather than 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?
There is no output schema, so the description must carry the return-value burden, and it does by listing the fields and the site-usage steps. Combined with a fully documented input schema and clear read-only annotations, an agent has everything needed to call and interpret 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?
Schema description coverage is 100%, so both parameters are already fully documented, including the stage-slug/stage-number acceptance and the locale fallback list. The description only restates the slug flexibility the schema already states and never mentions the language parameter, so it adds no meaning beyond the structured fields.
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?
States a specific verb and resource ("Describe one MasterAI Now simulation") and immediately anchors it to the sibling that produces the identifier ("by its key from get_simulations"). This cleanly separates it from the list-style get_simulations and from unrelated siblings like generate_quiz or search_content.
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?
Gives a concrete usage trigger ("Use it before recommending a specific playground") and a scope exclusion ("it cannot run the simulation and does not claim to"). It does not explicitly say when to prefer get_simulations instead, but naming it as the key source makes the ordering implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the browser-based simulations shipped with the MasterAI Now curriculum (line fitter, perceptron gate, gradient flow, MinHash/LSH, BPE tokenizer, 3D vector space, QKV heat-map, pre-training sandbox, LoRA lab, preference tuner, KV-cache/VRAM sandbox). Each entry gives its key, purpose, concepts, difficulty, prerequisite stage and canonical URL. Use it to recommend hands-on practice; these playgrounds run only in a browser and cannot be executed by this server.
| Name | Required | Description | Default |
|---|---|---|---|
| topic | No | Optional keyword filter, e.g. "attention", "tokenizer", "embeddings", "vram". Omit to list all simulations. | |
| language | No | Locale code. Supported: en, zh, hi, es, fr, ar, tr, de. Defaults to en; any other value falls back to English and is reported as a fallback. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint, idempotentHint, and openWorldHint=false. The description adds genuinely new behavioral information beyond those hints: the simulations are browser-only and cannot be executed server-side, and each entry contains a canonical URL. It does not describe result ordering or the fallback reporting behavior, but with rich annotations the remaining gap is small.
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 purpose and usage come first, followed by a useful enumeration of simulations that helps an agent map user requests to valid topic keywords. The parenthetical list of eleven names is long but carries real matching value, so it earns its space; only minor trimming would improve it.
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 two-parameter, read-only listing tool with no output schema, the description covers purpose, returned fields, the browser-only constraint, and a use case. An agent has everything needed to decide when to call it and what it will get back.
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%: both the topic keyword filter and the language locale, including its fallback behavior, are documented in the schema with examples. The description adds no parameter detail beyond that, so the baseline 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 names a specific resource (the browser-based simulations shipped with the curriculum) and enumerates all eleven of them, plus states the fields each entry returns (key, purpose, concepts, difficulty, prerequisite stage, URL). It is clearly distinguishable from get_simulation_details, which must return a single simulation.
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?
It gives an explicit use case ("recommend hands-on practice") and a hard constraint (playgrounds run only in a browser and cannot be executed by this server), which prevents an agent from trying to run them. It stops short of naming siblings such as get_simulation_details or search_content as alternatives for narrower lookups.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The published MasterAI Now curriculum in authored order (11 stages): stage number, title, tagline, summary, level, module, authored reading time, objectives (the published reading-card titles), prerequisite stage, interactive simulation and canonical URL. Optionally includes every reading card. Use it for an outline of what the curriculum covers; do not use it to read lesson text (use get_content) or to build a filtered study route (use get_learning_path).
| Name | Required | Description | Default |
|---|---|---|---|
| language | No | Locale code. Supported: en, zh, hi, es, fr, ar, tr, de. Defaults to en; any other value falls back to English and is reported as a fallback. | |
| includeCards | No | Include every reading card title and hook per stage (default true). Set false for a compact outline. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare this a read-only, idempotent, closed-world operation, so the safety profile needs no restating. The description adds genuine behavior: only *published* stages are returned, ordering is authored rather than alphabetical, the stage count is fixed at 11, and the payload expands when cards are included. It does not discuss size, truncation or error behavior, which keeps it just short of a 5.
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?
Purpose and scope are front-loaded, and the closing sentence routing to siblings is well placed. The long comma-separated field enumeration is dense but earns its space given the absence of an output schema, though the parenthetical glosses make it slightly heavy to parse.
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 no output schema, the description compensates by describing the returned fields in detail, and it covers scope, ordering, optional expansion, exclusions and alternatives. An agent has everything needed to pick this tool and call it correctly with no further reading.
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 schema already documents both parameters thoroughly, including the language fallback behavior and the compact-outline meaning of includeCards=false. The description's "optionally includes every reading card" restates the schema rather than extending it, so the baseline 3 is correct.
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 names the exact resource (the published MasterAI Now curriculum), its size (11 stages) and ordering (authored order), then enumerates the fields each stage carries, which is critical because there is no output schema. It is clearly distinguishable from get_content and get_learning_path, which are named explicitly.
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?
It states the intended use ("Use it for an outline of what the curriculum covers") and two explicit exclusions with the correct alternatives: reading lesson text goes to get_content, building a filtered study route goes to get_learning_path. Nothing about selection is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the eight locales MasterAI Now publishes (en, zh, hi, es, fr, ar, tr, de) with real per-locale counts: stages, fully and partially translated stages, average stage translation coverage, simulations, English-only lessons and tool pages, and published Guides per locale. Takes no parameters. Use it before promising a translation. A Guide count of null means the Guides database was unreachable; never read null as zero.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description adds genuinely non-obvious behavior beyond that: the null-Guide-count case signals partial failure of an upstream source, and states explicitly it must not be coerced to zero — a real interpretive trap the annotations do not cover.
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?
Front-loaded with purpose and the enumerated locales, then the return metrics, then the usage cue and the null caveat. Dense but every clause carries information except the redundant 'Takes no parameters', which the empty schema already conveys.
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?
There is no output schema, so the description carries the burden of describing return values, and it does so by naming every metric returned per locale. The null-handling caveat closes the main ambiguity; only the exact response shape (e.g., object vs. array, field names) is left implicit.
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?
Zero parameters, so the baseline is 4, and the description confirms 'Takes no parameters' consistently with the empty schema. No additional parameter meaning is needed or possible here.
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?
Names a specific verb and resource ('List the eight locales MasterAI Now publishes') and enumerates the exact locales returned, plus the per-locale metrics. Nothing among the siblings (generate_quiz, get_content, get_simulations...) overlaps with a static locale inventory, so the agent can distinguish it immediately.
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?
'Use it before promising a translation' gives an explicit trigger condition tied to a real agent failure mode. No alternative tool is named, but none of the siblings offers locale coverage data, so there is no meaningful alternative to redirect to.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search the public MasterAI Now catalogue by keyword: curriculum stages, answer-hub lessons, AI tool pages, browser simulations and published Guides articles. Returns stable ids, canonical URLs, types, languages, excerpts, total count and a pagination cursor. Use it first when you do not already know an id or slug; omit the query to browse. Do not use it to fetch full lesson text (call get_content with a returned id) or to create a quiz (use generate_quiz).
| Name | Required | Description | Default |
|---|---|---|---|
| type | No | Restrict results to one content type: article (published Guides post), lesson (answer-hub explainer), stage (curriculum stage), simulation (browser playground) or tool (AI tool page). | |
| limit | No | Page size, 1-25. Defaults to 8. | |
| query | No | Keywords, e.g. "bpe tokenization", "self-attention", "kv cache", "rlhf" (max 200 characters). Omit or pass an empty string to browse the catalogue in curriculum-first order. | |
| cursor | No | Opaque cursor from a previous search_content response. Reuse it only with the same query, language, type and category. | |
| category | No | Optional category filter, e.g. "llms", "machine-learning", "LLM Internals", "free-tools". Must match a category the content actually uses. | |
| language | No | Locale code. Supported: en, zh, hi, es, fr, ar, tr, de. Defaults to en; any other value falls back to English and is reported as a fallback. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered and the bar is lower. The description still adds real context beyond them by disclosing the return payload (stable ids, canonical URLs, types, languages, excerpts, total count, pagination cursor) and the browse-vs-query behavior. It stops short of mentioning auth, rate limits, or the language-fallback reporting that the schema documents, so it is not a 5.
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 sentences, front-loaded: purpose first, what-it-returns second, routing and exclusions third. Every sentence carries distinct information and there is no restatement of the title 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?
Six optional parameters, no output schema, yet the description states the response shape (ids, URLs, types, languages, excerpts, total count, cursor) so the agent knows what comes back and how to paginate. Combined with the exclusions routing to get_content and generate_quiz, nothing an agent needs in order to call this correctly 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%, so every one of the six parameters, including the type enum, limit bounds, cursor reuse rules and language fallback, is already fully documented in the schema. The description only echoes the omit-query-to-browse behavior, which the schema also states, and adds no syntax or format guidance of its own. Baseline 3 applies when the schema carries the parameter 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?
States a specific verb ('Search') and resource ('the public MasterAI Now catalogue') and enumerates what is searchable: curriculum stages, answer-hub lessons, AI tool pages, browser simulations and Guides articles. This maps cleanly onto the sibling tools, so an agent can tell it apart from get_content, list_learning_stages or get_simulations without opening any schema.
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?
Gives an explicit entry-point rule ('Use it first when you do not already know an id or slug'), an explicit browse mode ('omit the query to browse'), and two explicit exclusions with the correct alternative named for each ('call get_content with a returned id', 'use generate_quiz'). Both when-to-use and when-not-to-use are covered, with alternatives routed by name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
generate_quizget_contentget_learning_pathget_simulation_detailsget_simulationslist_learning_stageslist_supported_languagessearch_content
Add one secure layer between your agents and this server.