This server is an MCP tool providing a shared memory and coordination layer for AI-generated Senegalese MOHEBS teaching materials, ensuring consistency and variety across documents.
Context Management: Select and retrieve the active grade/subject (e.g., ci/ maths) to scope operations.
Curriculum Access: List top-level units and fetch detailed curriculum slices including lessons and progression.
Terminology & Prompts: Search a French/Wolof glossary, browse terminology sections, and retrieve generation prompts for specific deliverables.
Generation Support: Load full context (curriculum, characters, example domains) and get unused domain suggestions to rotate example object families across chapters.
Document Lifecycle: Generate signed upload/download URLs for .docx files, extract text, list tracked documents, reconcile bucket vs. history, and log/record generated content (write operations require user confirmation).
Knowledge Graph Management: Seed and manage KG versions with draft/publish workflow, apply mutations with audit log, and enforce role‑based access (curator/approver) via Supabase JWT. A get_capabilities tool reports available actions per role.
Confirmation Gating: All destructive or write operations prompt for explicit user confirmation before execution.
Provides integration with Firebase Storage for storing and retrieving generated documents, history, and other data, using a service account for authentication and signing URLs.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@senegal-mohebs-tlm-server set context to CI maths"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A remote MCP server ("Senegal Maths — TLM") that helps curriculum experts author teaching & learning materials — pupil manuals, teacher guides, lesson sheets — from a curriculum knowledge graph. It exposes MCP tools, not a UI: the server holds the graph, the authoring loop, the reusable pedagogy catalog and the document history; the calling LLM writes the actual .docx.
Work is always scoped to one (workspace, grade, subject) at a time, chosen with set_context. A workspace is the tenant that owns a set of graphs — it is the first segment of every namespace and every storage key, and roles are granted per workspace. Eight subjects across six workspaces are registered today (senegal/ci/maths, senegal/ce1/reading, nigeria/primary-1-3/maths, rwanda/primary-1-3/maths, cbse/class-9-10/science, ghana/basic-1-3/english, ghana/basic-4-6/maths, madhi/class-1-5/maths).
The knowledge graph lives only in a Firestore node/edge store, in raw Learning Commons (LC) ontology, behind a draft → review → publish curator loop. Generated .docx files and their history live in Firebase Storage (so the generating agent, the server, and you never need a shared disk). Auth is a Supabase JWT.
Going deeper: the operational manual is
docs/technical-reference/; the architecture summary + working conventions are inCLAUDE.md; the production runbook isDEPLOY.md; the why behind each subsystem is indocs/design-notes/.
Package | What it is |
The MCP server — its own | |
The read-only KG explorer (Vite + TS), served by Firebase Hosting against the server's | |
The expert-facing user guide (MkDocs), published to GitHub Pages by | |
The Cowork plugin (French workflow commands, skills and agents) shipped through the repo-root marketplace. | |
Technical reference, design notes, and the canonical LC ontology reference. |
Paths written as src/…, scripts/…, test/…, assets/… below are relative to backend/.
Related MCP server: myBrAIn
Thing | Location |
Knowledge graph (curriculum, catalog, glossary) | Firestore node/edge store — the single source of truth ( |
Subject profile + authoring guide | Firestore, as a per-slot config cell that rides the same draft/published pointer ( |
| Local |
Generated | Firebase Storage, under |
Converted graphs staged for import | Local |
Object hashing uses the GCS object md5 from metadata — the server never hashes a local file, which removes the cross-host mismatch that used to break log_generation.
cd backend
npm install
npm run build # check-cycles (layering) + tsc → dist/
npm test # vitest — no credentials needed (memory store + fake storage)
npm start # stdio MCP server (dist/index.js)
npm run start:http # HTTP MCP server (dist/http.js) — remote / Cloud RunRequired (both modes): SERVICE_ACCOUNT_KEY_PATH (or SERVICE_ACCOUNT_KEY_JSON where mounting a file is impractical) · FIREBASE_STORAGE_BUCKET.
Required in HTTP mode: SUPABASE_URL · SUPABASE_ANON_KEY · PUBLIC_URL. The server refuses to start without SUPABASE_URL unless ALLOW_UNAUTHENTICATED=1 — never set that in production. TLM_SUPER_ADMINS (comma-separated JWT subs or emails) is the root of trust: it must be set before any workspace exists, because only a super admin can create the first one.
Optional: TLM_WORKSPACE / TLM_GRADE / TLM_SUBJECT (pre-select a context at startup) · TLM_BUCKET_PREFIX (namespace all storage under a prefix — match it in the CLI scripts) · TLM_SEEDS_DIR · GEMINI_API_KEY / GEMINI_MODEL (the translate tool) · SUPABASE_SERVICE_ROLE_KEY (enables list_unaffiliated_users) · KG_EXPLORER_PUBLIC=1 (anonymous published explorer reads; it can never reach a draft) · KG_ALLOWED_ORIGINS · TLM_ALLOW_SELF_APPROVE=0 (strict separation of duties) · PORT · the response-size caps TLM_MAX_RESPONSE_BYTES / TLM_WALK_MAX_PAGE_BYTES / TLM_SUBTREE_MAX_BYTES / TLM_DOCUMENT_MAX_BYTES · TLM_CONFIRM_TTL_MS / TLM_CONFIRM_STORE_BYTES · TLM_DEBUG / TLM_TIMING.
Full semantics: technical reference → deployment.
The graph lives in a generic Firestore node/edge store, double-buffered: two slots behind a pointer { publishedSlot, draftSlot }. Reads and generation resolve to published; every edit stages onto the draft; publish_draft is an atomic pointer flip. Every mutation is two-phase — a dry-run returns a diff, warnings and an opaque confirmationToken and changes nothing; the confirm re-checks the token and applies to the draft only — and every mutation and denial lands in an append-only audit.
Roles are per workspace: curator may edit, apply and discard; approver also publishes; admin also manages members; an env-rooted super_admin spans every workspace. Published curriculum reads are open to anyone signed in — what membership buys is the workspace's live assets (its documents bucket, generation history, and the metered translator) and the draft.
Import a graph, or export it for backup/interchange:
npm run import:kg-store -- <workspace> <grade> <subject> knowledge_graph.jsonnpm run export:kg-store -- <workspace> <grade> <subject> out.jsonFull lifecycle, verbs, integrity rules and audit: technical reference → KG store.
A workspace is a tenant: a short slug that becomes the first segment of every namespace and storage key it owns. Creating it is what lets people enter it with set_context; loading its curriculum is a separate step.
There are two paths, and they perform the same writes.
1. Through MCP (super admin). The normal path when the server is already deployed:
create_workspace(id: "kenya", displayName: "Kenya")Then grant people roles — by email if they have never signed in (it becomes a pending invite claimed at first login):
add_member(workspace: "kenya", email: "someone@example.org", role: "curator")For a whole organisation, set_domain_rule(workspace, domain, role: "curator") auto-admits anyone signing in with a verified address at that domain. It only applies to providers that vouch for the address (Google today) — a password signup at that domain still needs an invite. list_members, invite_member / revoke_invite, remove_member and remove_domain_rule round out the surface.
2. From the CLI — when you have Firebase credentials but no super-admin MCP session:
node scripts/create-workspace.mjs kenya "Kenya" --member <userId> --role admin --dry-runDrop --dry-run to write for real. The CLI is its own trust boundary (it bypasses the MCP authz path, exactly like import-kg), and it still appends the audit record. Set the same TLM_BUCKET_PREFIX the server runs with, so the audit namespace lines up.
A new workspace is empty until you add at least one subject.
A subject is one graph plus one profile, both keyed by (workspace, grade, subject). The registry is keyed on all three because two tenants can own the "same" grade/subject with genuinely different graphs — Nigeria and Rwanda both sit at primary-1-3/maths.
1. Get the graph into the canonical envelope. import-kg consumes a raw Learning-Commons envelope: { nodes, relationships }, where a node is { id, labels: [LClabel], properties: { …camelCase } } and a relationship is { id, type, start, end, properties }. If you are starting from an EIDU/CASE JSONL export (one node per line, one relationship per line, snake_case, heavy extraction provenance), convert it first:
node scripts/convert-eidu-jsonl.mjs nodes.jsonl relationships.jsonl imports/kenya/primary-1/maths/knowledge_graph.jsonStage converted graphs under imports/<workspace>/<grade>/<subject>/ — deliberately not under test/fixtures/, so the test matrix does not pick them up. Check node/edge labels against docs/reference/learning-commons/ before importing; a non-canonical label parses into the wrong kind.
2. Author a subject profile under src/adapters/profiles/<workspace>/<grade>-<subject>.ts. A profile is data, not code — an id plus a parse descriptor — and the generic factory in src/adapters/build.ts turns it into the adapter. Most of the parse is already generic (a node's kind comes from its own canonical LC fields: groupName for groupings, statementType for standards, the label for content leaves), so a standards-only graph often needs nothing but the id:
export const RWANDA_MATHS_PROFILE: SubjectProfile = {
id: "rwanda-maths/lc-graph-v1",
parse: {}, // no ordinal field → sequence comes from traversal order
};The knobs that exist are the genuine per-subject differences: numberFrom (order | position | description — where a unit's ordinal lives), containerEdge / supportEdge / progressionEdge / dependencyEdge, and a named prune strategy. The schema is .strict(): an unrecognised key is a hard refusal, not a silent ignore, so a typo can never look like it took effect.
3. Register it in src/adapters/index.ts under the "<workspace>/<grade>/<subject>" key. Two keys may point at the same profile when the graphs share a shape — the builder still stamps each with its own identity.
4. Write the authoring guide at seeds/<workspace>/<grade>/<subject>/GRAPH_GUIDE.md — authored markdown that the authoring/generating LLM reads (via get_graph_guide) to interpret and modify the graph, including the subject's coverage expectations in prose. It ships as a data file, never a code literal, and is composed at seed time with the shared seeds/AUTHORING_CONVERSATION.md so the conversation rules cannot drift across subjects. It is a seed: once the namespace exists, the guide in force lives in its config cell and is edited with edit_profile. The workspace's FR/Wolof lexicon is authored separately, in its _glossary namespace (add_terms).
5. Dry-run, then import. The dry-run parses the graph against your profile in memory and writes nothing:
npm run import:kg-store -- kenya primary-1 maths imports/kenya/primary-1/maths/knowledge_graph.json --dry-runDrop --dry-run to write. The import parses the graph, serialises it to the store (ids verbatim), writes the subject-profile config cell ({ core, guide }, taken from the in-repo literal + GRAPH_GUIDE.md unless you pass --profile p.json), and initialises the pointer. Re-importing an existing namespace needs --replace-published, which writes the currently-published slot in place, delta-only — without it the import lands on the non-published slot and readers see nothing change. It is refused while a draft is open.
6. Deploy the code, then check it live. The profile is code, so a data-only re-import is not enough: the running server must also carry the new profile module or set_context will refuse the namespace ("no subject adapter is registered"). Deploy via the Deploy to Cloud Run workflow, then set_context(workspace, grade, subject) and namespace_stats against the live server.
Note on where the profile really lives. The in-repo literal is the registration check and the seed source. On a live server,
activateContextbuilds the adapter from the namespace's stored config cell — the store is the source of truth. Edit a live profile or guide throughedit_profile(curator-gated, two-phase, publishes with the graph).scripts/write-profile.mjsis the repair path for a cell too invalid to activate.
Fuller walkthrough: technical reference → architecture & extending.
set_context(workspace, grade, subject) — pick what you're working on. start_here orients you: where you are, what your role allows, what is unfinished.
Read what you're generating — walk_document for a whole document, walk_document_section for a single piece — each returns the subtree plus the instructional routines and formatters that apply. get_terminology supplies the glossary.
Generate the .docx.
create_upload_url(relPath) → PUT the file to the signed URL (no large payloads through MCP).
log_generation(nodeId, relPath, content) — records what you produced against the scope node the document covers (md5 read from storage).
evaluate_document scores it against the evaluation rubrics attached to that document.
The outward-writing tools (create_upload_url, log_generation, record_document_content) are gated by a confirmation step. preview_generation closes the editing loop instead: it resolves from the draft slot and writes to a segregated previews/ prefix, invisible to reconcile / list_documents and never touching history. Details: technical reference → generation & storage.
The live surface is mirrored by get_capabilities; this is the map.
Orientation & context: ping, start_here, set_context, get_context, get_capabilities, namespace_stats.
Graph reads (generic): walk_graph (directional, filtered, paginated BFS — the traversal primitive), find_node (a name → node ids, with the path that tells two same-named nodes apart), get_standards, export_graph_view.
Generation reads: walk_document, walk_document_section, get_terminology.
Authoring (role-gated): add_nodes, create_edges, edit_nodes, move_node, delete_nodes, delete_edges, plus the two task verbs create_document and add_section.
Draft lifecycle (role-gated): diff_draft, check_draft (mechanical wiring lint), lint_content (consistency lint — does an authored statement contradict another), review_draft (bundles the guide's expectations for the calling model to judge), undo_last, request_review, publish_draft, discard_draft, read_audit.
Subject profile & guide: get_profile, edit_profile, get_graph_guide.
Catalog — reusable routines, formatters & rubrics: list_catalog, get_catalog_entry, add_to_catalog, duplicate_entry, use_routine, use_formatter, use_rubric.
Glossary & translation: add_terms, edit_term, remove_terms, translate (FR↔Wolof via Gemini, glossary-grounded).
Documents & generation output: list_documents, create_upload_url, create_download_url, get_document_text, record_document_content, log_generation, reconcile, evaluate_document, preview_generation, create_preview_upload_url.
Rendering & round-trip: render_document (a composed block tree + the node's formatter stack → a .docx, optionally measured), check_stale (has the graph moved under a rendered document), propose_from_document (take an expert's corrections in a document back into the graph as staged edits).
Workspaces (tenant admin): list_workspaces, create_workspace, add_member, remove_member, list_members, invite_member, revoke_invite, set_domain_rule, remove_domain_rule, list_unaffiliated_users.
The connector also publishes four named French workflow prompts — Créer un nouveau document, Appliquer un style, Créer une routine pédagogique, Préparer une relecture. They are French because a prompt is the expert's first turn; every server-authored string is English and relayed in the expert's working language.
CLAUDE.md — architecture summary, module layering, conventions (the working guide).
docs/technical-reference/ — the operational manual: KG store & curator loop · explorer · generation & storage · rendering · deployment · architecture & extending.
docs/reference/learning-commons/ — the canonical LC ontology (node data models, every relationship, enums). Check it before adding or retyping any node or edge.
docs/design-notes/ — the why behind each subsystem. Each note carries a Status line; heed the "Historical / superseded" ones. Start with graph-native authoring · self-serve authoring · authorable catalog · workspaces · member onboarding · KG mutations.
DEPLOY.md — production deployment runbook.
Get a short-lived signed URL to download an EXISTING .docx from the bucket with an HTTP GET (no auth header needed). relPath is documents-relative, like 'chapitre_05/Manuel - Chapitre 5.docx' — the same path used by create_upload_url and get_document_text. Use this to fetch the original binary file (with its images and formatting intact) so you can edit it and re-upload via create_upload_url. Returns { url, objectKey, expiresAt, exists }; exists is false when there is no such object.
| Name | Required | Description | Default |
|---|---|---|---|
| relPath | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses behavioral traits: the URL is short-lived, signed, requires no auth header, works only for existing .docx, and returns a specific object with fields url, objectKey, expiresAt, exists. It also clarifies that exists is false when the object is missing.
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 four sentences, each serving a distinct purpose: function, path explanation, usage context, and return value. No redundant information, tightly packed with valuable details.
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 one parameter, no output schema, and no annotations, the description covers all aspects: parameter semantics, return value structure, usage scenario, and even the path convention. It is complete and leaves no ambiguity for the 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?
Despite 0% schema description coverage, the description extensively explains the sole parameter relPath: 'documents-relative, like 'chapitre_05/Manuel - Chapitre 5.docx' — the same path used by create_upload_url and get_document_text'. This provides format, examples, and cross-reference, fully compensating for the missing 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's function: 'Get a short-lived signed URL to download an EXISTING .docx from the bucket with an HTTP GET'. It specifies the resource (existing .docx), action (download URL), and distinguishes from siblings like create_upload_url (upload) and get_document_text (text extraction).
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 explains when to use: 'Use this to fetch the original binary file ... so you can edit it and re-upload via create_upload_url'. It relates to siblings and gives context. However, it does not explicitly state when NOT to use it (e.g., for text extraction), though the sibling set and context imply it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a short-lived signed URL to upload a generated .docx to the bucket. Upload with an HTTP PUT, Content-Type application/vnd.openxmlformats-officedocument.wordprocessingml.document. relPath is like 'chapitre_05/Manuel - Chapitre 5.docx'. After uploading, call log_generation with the same relPath. REQUIRES CONFIRMATION: called without confirm:true it only returns a needsConfirmation notice — ask the user to approve the upload, then call again with confirm:true.
| Name | Required | Description | Default |
|---|---|---|---|
| confirm | No | ||
| relPath | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses key behaviors: short-lived URL, upload method, relPath example, two-step confirmation process. No annotations provided, but description compensates fully without 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?
Single paragraph, front-loaded with purpose, then usage instructions, then confirmation details. No waste. Efficient and clear.
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?
Covers all key aspects: purpose, parameters with examples, return values (notice or URL), follow-up step, upload method. No output schema needed as return is described. Complete for agent use.
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 0% schema coverage, description explains both parameters: relPath given with example, confirm effect explained (returns notice vs URL). Adds meaning 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?
Specific verb 'get' and resource 'short-lived signed URL to upload a generated .docx' clearly stated. Distinguishes from siblings like create_download_url and log_generation by specifying upload context and follow-up step.
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 when to use (after generating .docx) and follow-up (call log_generation). Provides upload instructions (HTTP PUT, Content-Type). Describes confirmation flow clearly. No explicit when-not-to-use but context is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Which example domains have been used, and in which chapters. Maths-specific (example-domain rotation).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries full burden. It mentions 'maths-specific' and 'example-domain rotation' but does not disclose whether the operation is read-only, side effects, authorization needs, or rate limits. Minimal behavioral context beyond the core function.
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 purpose. Every word earns its place. No 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?
For a parameterless query tool with no output schema, the description sufficiently conveys what the tool returns and its scope. Could be slightly more specific about the data coverage (e.g., all users vs. current), but overall adequate.
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?
No parameters exist, so schema coverage is 100% trivially. The description adds value by explaining the output context (domains used and chapters, maths-specific), which is meaningful beyond the empty 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?
Clearly states the tool reports which example domains have been used and in which chapters, with a specific maths scope. However, it does not explicitly differentiate from siblings like get_curriculum or suggest_fresh_domain, though context signals partially compensate.
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?
No explicit guidance on when or when not to use this tool versus alternatives. The description implies it is for querying domain usage, but lacks explicit usage context or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return the currently selected grade/subject (null if none is set yet) and every installed grade/subject option. Use this to discover what's available, then set_context.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but description discloses behavior: returns current selection (null if none) and all options. Good transparency for a simple getter, though could explicitly state no side effects.
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 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?
Explains return value (current selection and options) but lacks detail on output format (e.g., data structure). Enough for a simple getter given good complementary siblings.
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?
No parameters (schema coverage 100%), baseline is 4. Description adds no parameter info, but none needed; the tool takes no input.
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 'Return the currently selected grade/subject and every installed grade/subject option.' It specifies verb 'return' and resource 'grade/subject options', and distinguishes from sibling 'set_context' by naming it.
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 says 'Use this to discover what's available, then set_context.' Provides clear when-to-use guidance and implies alternatives (avoid if context already known).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The curriculum slice for one unit (for maths: a chapter's ordered lessons with components and tasks, the bilan lesson, and cross-unit progression). 'unit' is the unit's scope value (maths: the chapter number).
| Name | Required | Description | Default |
|---|---|---|---|
| unit | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses the structure of the returned data for maths but does not mention side effects, permissions, or global behavior. The agent is informed of what the tool returns but not of any potential restrictions.
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, front-loaded with the core purpose, and contains no redundant information. 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?
Given one required integer parameter and no output schema, the description provides sufficient context about what the tool returns for maths. However, it could be more general or mention behavior for other subjects if applicable.
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 single parameter 'unit' is explained: it's the unit's scope value (maths chapter number). This adds meaning beyond the schema, which only specifies integer type. Schema description coverage is 0%, so the description compensates well.
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 that the tool retrieves the curriculum slice for one unit, specifying the content for maths (ordered lessons, components, tasks, bilan lesson, cross-unit progression). It distinguishes from sibling tools like get_context or get_terminology, but could be more explicit about its unique role.
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 implies that the tool should be used when needing curriculum details for a specific unit, but it does not explicitly state when not to use it or provide alternatives. No exclusions or context for other subjects are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Extract the plain text of a document in the bucket (by its documents-relative path) so you can read an UNTRACKED document and then record its content. When identifying characters, read the WHOLE document — characters appear in the opening scene AND in the activities and bilan, not only the amorce.
| Name | Required | Description | Default |
|---|---|---|---|
| relPath | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It clearly indicates a read-only operation (extract plain text) and adds a behavioral nuance about reading the entire document for characters. No destructive behavior or contradictions are present, though it lacks detail on authentication or rate limits.
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 with no unnecessary words. The first sentence states the primary purpose and context, and the second provides a critical behavioral guideline. 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?
Given no output schema and no annotations, the description covers the main aspects: what it does, when to use it, and a behavioral nuance. It does not explicitly state the output format (likely plain text), but that is reasonably inferred from 'extract plain text'.
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 0%, so the description must compensate. It adds the qualifier 'documents-relative path' for the relPath parameter, which provides some context beyond the schema. However, it does not specify the expected format (e.g., leading slash, file extension) or give an example.
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 verb (extract/read) and resource (document text) and specifies the context (UNTRACKED document). It distinguishes from siblings like record_document_content by implying this is the read step before recording. The additional detail about reading the whole document for character identification further clarifies the purpose.
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 clear context: read an untracked document and then record its content. It also gives a specific guideline about reading the whole document for character identification. However, it does not explicitly mention when not to use this tool or list alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One call to load before generating: curriculum for the unit, plus subject-specific context (for maths: established characters, a fresh example-domain suggestion, and — for the teacher guide — the manual to build on). 'unit' is the scope value (maths: chapter number); 'deliverable' is a deliverable key (maths: 'manual' or 'lessons').
| Name | Required | Description | Default |
|---|---|---|---|
| unit | Yes | ||
| deliverable | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It only mentions what is loaded but omits details on side effects, permissions, rate limits, or idempotency. Behavioral traits are insufficiently disclosed.
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 a single dense sentence that packs examples and clarifications. It is somewhat concise but could be split for readability. Some redundancy exists with parentheticals.
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?
No output schema is provided. The description only gives vague return content (curriculum, context) with maths-specific examples. It fails to describe the full structure or behavior for other subjects, leaving significant gaps.
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 0% schema description coverage, the description adds valuable meaning: it explains 'unit' as scope (e.g., chapter number) and 'deliverable' as key (e.g., 'manual' or 'lessons' for maths). This compensates for the schema's lack of 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 loads curriculum and subject-specific context for generation. It uses specific verbs and resources, and the examples help distinguish from siblings like get_curriculum or suggest_fresh_domain.
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 implies usage 'before generating' but does not explicitly state when to use this tool versus alternatives like get_curriculum or get_context. No exclusions or 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.
Return the generation prompt for one of the active subject's deliverables (its DeliverableSpec.promptFile). 'deliverable' is a deliverable key — for maths, 'manual' or 'lessons'.
| Name | Required | Description | Default |
|---|---|---|---|
| deliverable | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavior. It only states the return value (prompt) without addressing error cases, authentication needs, or whether the operation is read-only. This is minimal for a tool with no 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: the first states the purpose, the second explains the parameter. No redundant information, front-loaded with key action.
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 tool with one parameter and no output schema, the description covers the main functionality but omits the return format (e.g., string vs object) and assumes context like 'active subject' without explanation. Adequate but could be more explicit.
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 0% coverage and no description for the 'deliverable' parameter. The description adds value by explaining it is a deliverable key and providing examples for maths. However, it only covers one subject, leaving other cases ambiguous.
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 the generation prompt for a deliverable, with specific examples for maths ('manual' or 'lessons'). This distinguishes it from sibling tools like get_generation_context or get_context.
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 implies usage by explaining the deliverable parameter and giving examples, but it does not explicitly state when to use this tool versus alternatives, nor mention prerequisites like having an active subject.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search the MOHEBS French/Wolof terminology used as the fallback when the KG lacks a term's wording. Returns [] if nothing matches — then say the wording is missing rather than invent it.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavior. It states the tool is a search that returns an empty array on no match, implying read-only and safe behavior. However, it does not confirm lack of side effects or authorization needs, leaving some ambiguity.
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 concise sentences with no fluff. It is front-loaded with the core purpose and immediately useful guidance.
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 simple tool (2 params, no output schema), the description covers the use case and return behavior. However, it lacks parameter semantics, which is a gap that affects completeness.
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 2 parameters (query, limit) with 0% description coverage. The description does not mention any parameters, forcing the agent to rely solely on the schema for meaning. This is insufficient for correct parameter usage.
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 searches the MOHEBS French/Wolof terminology, specifying it is a fallback when the knowledge graph lacks a term. This distinguishes it from primary term searching tools and aligns with its name and title.
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 tells when to use the tool: as a fallback when the KG lacks term wording. It also instructs the agent to say the wording is missing if the result is empty, preventing hallucination. This is clear usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Current history: one canonical entry per document, with its known content.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description must disclose behavioral traits, but it only cryptically mentions 'canonical entry' and 'known content'. It does not clarify if the tool is read-only, requires authentication, or any other traits.
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 (one sentence) but lacks structure and clarity. It is not front-loaded with key information, making it less useful.
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 no output schema and no annotations, the description fails to adequately explain the return value or behavior. Terms like 'canonical entry' and 'known content' are ambiguous, leaving the agent uncertain.
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 no parameters (0 parameters, 100% coverage). The description adds no parameter information, but its minimal nature does not detract from parameter semantics since there are none.
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 is vague: 'Current history: one canonical entry per document, with its known content' does not clearly state that the tool lists tracked documents. The title provides some clarity, but the description fails to explicitly state the tool's function.
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?
No guidance is provided on when to use this tool versus alternatives like 'get_document_text' or 'record_document_content'. Context and exclusions are absent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
All top-level curriculum units for the active subject (for maths: chapters — number, title, domain). Numbering may skip.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description must carry full burden. It discloses that numbering may skip, but lacks important behavioral details such as idempotency, error states (e.g., no active subject), or return format beyond a brief example.
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?
Extremely concise: two sentences cover the core purpose and a key behavioral note (numbering may skip). 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?
Adequate for a simple zero-parameter list tool, but missing context such as error handling, return structure, or relationship to other curriculum tools. Lacks completeness without an output 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?
No parameters defined, so baseline score is 4. The description adds no parameter info because there are none.
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 lists top-level curriculum units for the active subject, with a concrete example (maths chapters) showing the returned fields. However, it does not explicitly differentiate from sibling tools like 'get_curriculum' or 'list_documents'.
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?
No guidance on when to use this tool versus alternatives, no prerequisites, and no mention of context like requiring an active subject.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Call after uploading a generated .docx to the bucket (via create_upload_url). Reads the object's hash from storage and records what you produced so it feeds future consistency + variety. Log each character with details like {name, type} (e.g. {name:'Awa', type:'child'}), not just the name. No local file needed. 'unit' is the scope value (maths: chapter number); 'deliverable' is a deliverable key (maths: 'manual' or 'lessons'). REQUIRES CONFIRMATION: called without confirm:true it only returns a needsConfirmation notice — ask the user to approve writing to history, then call again with confirm:true.
| Name | Required | Description | Default |
|---|---|---|---|
| unit | Yes | ||
| confirm | No | ||
| content | Yes | ||
| relPath | Yes | ||
| deliverable | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full transparency burden. It reveals that the tool reads the object's hash from storage, records data, and requires a confirmation step (without confirm:true it returns a notice). It could mention more about side effects or errors, but it's quite transparent for a logging 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 and workflow. It is concise but includes necessary details like the confirmation flow and character logging requirements. Slightly dense, but 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?
Given the tool's complexity (5 params, nested objects, confirmation flow), the description covers the workflow, parameter semantics, and behavioral notes. It explains the confirmation behavior and character requirements. It doesn't describe the return format, but the purpose is well-covered.
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 adds significant meaning beyond the input schema, which has 0% coverage. It explains that unit is a chapter number, deliverable is a key like 'manual', and characters must include every character found anywhere in the document with details like {name, type}. This compensates well for the schema's lack of 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 it logs a generated document after upload, reads a hash from storage, and records the output for future consistency. It distinguishes this tool by specifying the post-upload context and the required parameters like unit, deliverable, and content details.
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 explicitly states when to use (after uploading via create_upload_url), provides a two-step confirmation flow, and explains the meaning of unit and deliverable with examples. This gives clear invocation guidance and disambiguates from other tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the documents in Firebase Storage and diff against history: tracked docs, UNTRACKED docs needing ingestion, entries dropped because their object is gone, and duplicate resolutions.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavior. It describes output categories but does not indicate whether the tool is read-only, modifies state, or has side effects. The term 'reconcile' may imply actions beyond listing, leaving ambiguity.
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 a single sentence that conveys significant detail, but it is somewhat dense and could benefit from structuring as a list for clarity.
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 absence of output schema and annotations, the description provides moderate completeness by listing output categories. However, it lacks details on return format, error handling, or usage context.
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 has no parameters, so the description adds meaning by explaining the output categories, which is valuable beyond the empty 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 lists documents in Firebase Storage and diffs against history, enumerating specific output categories: tracked docs, untracked docs needing ingestion, dropped entries, and duplicate resolutions. This distinguishes it from sibling tools.
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 implies usage for reconciliation tasks but does not explicitly state when to use this tool over alternatives, nor does it provide context for prerequisites or exclusion conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
After reading an UNTRACKED document's text, store the structured content you extracted into history so it is never re-parsed. For characters, include every one found ANYWHERE in the document (opening scene and activities/bilan), each with details like {name, type}. The object must already be in the bucket. 'unit' is the scope value (maths: chapter number); 'deliverable' is a deliverable key (maths: 'manual' or 'lessons'). REQUIRES CONFIRMATION: called without confirm:true it only returns a needsConfirmation notice — ask the user to approve writing to history, then call again with confirm:true.
| Name | Required | Description | Default |
|---|---|---|---|
| unit | Yes | ||
| confirm | No | ||
| content | Yes | ||
| relPath | Yes | ||
| deliverable | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses the confirmation requirement, the precondition that the object must be in the bucket, and the irreversible nature of writing to history ('never re-parsed'). It does not discuss idempotency or error handling, but covers key behavioral traits adequately.
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 at about 120 words, with clear sentence structure. It front-loads the purpose and then provides necessary details. Every sentence adds value, and there is no 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?
The tool has 5 parameters (4 required, nested objects) and no output schema. The description explains the confirmation workflow, the bucket precondition, and the expected content structure. It does not describe return values or error states, but given the complexity and absence of output schema, it is mostly 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?
Given 0% schema description coverage, the description compensates by explaining the 'unit' (scope value, e.g., chapter number), 'deliverable' (e.g., 'manual' or 'lessons'), and the 'content' object's subfields (characters with required fields, exampleDomains, etc.). However, it does not explain 'relPath' or 'confirm' in detail, leaving some gaps.
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's purpose: 'store the structured content you extracted into history so it is never re-parsed.' It specifies the verb 'store' and the resource 'structured content,' distinguishing it from read-only or logging tools. The inclusion of 'After reading an UNTRACKED document's text' provides context for when this tool should be used.
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 guidelines: 'The object must already be in the bucket,' explains the 'unit' and 'deliverable' parameters with examples (maths), and details the confirmation workflow ('REQUIRES CONFIRMATION: called without confirm:true it only returns a needsConfirmation notice'). It also instructs on character inclusion: 'include every one found ANYWHERE in the document.' This is comprehensive and helps the agent use the tool correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Choose the grade (e.g. 'ci') and subject (e.g. 'maths') to work on. This selects which local sources load and which Firebase namespace documents and history live under, and MUST be set before any other tool. If you don't know which to use, call get_context to list the installed options, then ask the user.
| Name | Required | Description | Default |
|---|---|---|---|
| grade | Yes | ||
| subject | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It reveals key behaviors: selecting which local sources load and which Firebase namespace documents/history live under. It also notes the ordering constraint. Could be improved by mentioning if previous context is overwritten or if any loading occurs immediately, but still strong.
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, each adding distinct value: purpose, importance, and fallback. No unnecessary 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 no output schema and no annotations, the description covers the core aspects: what it sets, why it's necessary, and how to handle uncertainty. It lacks explicit details on parameter formats and exact side effects, but overall sufficient for a configuration 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 0%, so description must compensate. It provides examples ('ci' for grade, 'maths' for subject) and directs users to 'get_context' for valid options. However, it does not specify allowed values or format, leaving some ambiguity.
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 that the tool sets the grade and subject context. It uses specific verb 'choose' and resource 'grade and subject'. It distinguishes from sibling tool 'get_context' by directing users to call it for available options.
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 'MUST be set before any other tool', providing critical ordering guidance. Also advises to use 'get_context' and ask the user when uncertain, giving clear context-aware instruction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Suggest an unused (or least-recently-used) example domain so chapters rotate object families. Maths-specific (example-domain rotation).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It mentions returning an unused or least-recently-used domain, indicating a read-like operation. However, it doesn't disclose any side effects, permissions, or response format, leaving some gaps.
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, concise and to the point. However, the second sentence is a bit cryptic; could be structured more clearly. No wasted words, but front-loading could be better.
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 no parameters and no output schema, the description provides adequate context for its simple purpose. It explains the domain rotation context (Maths-specific) and the selection criterion (unused or least-recently-used), which is sufficient.
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?
No parameters, so schema coverage is 100%. The description adds meaning by specifying 'unused or least-recently-used' and 'Maths-specific rotation', which clarifies what the tool returns beyond the empty 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 states the verb 'suggest' and resource 'fresh domain', with clear purpose of rotating object families for chapters. It differentiates from siblings like 'domain_usage' by specifying 'Maths-specific (example-domain rotation)', but the phrasing could be less ambiguous.
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?
Implied usage is for getting a domain for chapter rotation, but no explicit when-not or alternatives. Sibling 'domain_usage' might serve a different purpose, but the description doesn't clarify when to choose this over others.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List terminology sections and entry counts.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must stand alone. The term 'list' implies a read-only operation, but no additional behavioral traits (e.g., scope, performance, caching) are disclosed. This is adequate for a simple tool with no parameters.
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 a single, concise sentence that conveys the essential information without any wasted words. It is front-loaded and efficient.
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 no parameters and no output schema, the description is largely complete. It could optionally mention ordering or pagination, but for a simple listing tool, this is sufficient. The lack of annotations does not create a critical gap.
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 has zero parameters, and the description does not need to add parameter details. However, it clarifies that the tool returns a full list of sections with counts, adding meaning beyond the empty schema. Baseline for 0 parameters with high coverage is 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?
The description clearly states the tool's purpose: to list terminology sections along with entry counts. The verb 'list' and the resource 'terminology sections' are specific, and the inclusion of 'entry counts' further clarifies the output. This distinguishes it from siblings like 'get_terminology'.
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 no guidance on when to use this tool versus alternatives such as 'get_terminology' or 'list_units'. There is no mention of prerequisites, contexts, or situations where other tools would be preferred.
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.
v0.4.0create_download_urlcreate_upload_urldomain_usageget_contextget_curriculumget_document_textget_generation_contextget_promptget_terminologylist_documentslist_unitslog_generationreconcilerecord_document_contentset_contextsuggest_fresh_domainterminology_sectionsScored across 17 tools
Each tool has a clearly distinct purpose. For example, set_context and get_context handle context, get_curriculum and get_generation_context are different in scope, and create_upload_url, create_download_url, get_document_text, record_document_content, log_generation each cover distinct steps in document management. No two tools appear to do the same thing.
Most tool names follow a verb_noun pattern (e.g., get_prompt, list_units, create_upload_url). The main exception is 'terminology_sections', which uses noun_verb. Overall, the naming is mostly consistent with minor deviations.
17 tools is slightly above the typical ideal range of 3-15, but each tool serves a specific function in a multi-step generation workflow. The count is justified by the complexity of the domain and does not feel excessive.
The tool surface covers the full lifecycle: context setting, curriculum access, terminology, prompt retrieval, domain rotation, document management (upload, download, read, record, log), and reconciliation. Minor gaps exist, such as no explicit tool to list deliverables or delete documents, but these are manageable.
An MCP memory server. One memory your agents share — across models, devices and apps.
Cloud-hosted MCP server for durable AI memory
Persistent AI memory shared across Claude, ChatGPT, coding agents, and compatible MCP clients.
Cross-tool persistent memory and context for AI assistants over MCP.
