Create and manage flashcards, tags, and saved decks in Nibomo, and study due cards one question at a time through MCP.
Scored across 8 tools
Each tool targets a distinct action or resource: SQL read vs write, review flow steps, informational guides, and workspace listing. The descriptions explicitly disallow overlapping capabilities (e.g., sql_execute cannot write review_events, submit_review is the only way to grade), so an agent can easily choose the right tool.
Most names follow a verb_noun pattern (get_guide, list_workspaces, reveal_answer, submit_review), but sql_execute/sql_query use a noun_verb prefix and next_review_card lacks a verb. The snake_case convention is consistent, and the deviations are readable and logically grouped.
Eight tools is well-scoped for a flashcard/review server, with each tool covering a distinct area: guides, limits, workspaces, review steps, and SQL read/write. No tool feels redundant or unnecessary, and the count stays well within the ideal 3-15 range.
Core workflows are well covered: reviewing cards, revealing answers, submitting reviews, and full CRUD on cards/decks via SQL. Minor gaps exist, such as no explicit workspace creation or deletion and no direct card-detail tool outside of SQL, but these are workable given the generic SQL endpoints.
Returns a bundled Nibomo reference guide for sql_dialect (grammar/limits/examples), card_authoring (content/tags/duplicates/formatting/links), bulk_authoring (batches/recovery/verification), or review_flow (review/rating). No workspace access, external fetches or writes.
| Name | Required | Description | Default |
|---|---|---|---|
| topic | Yes | Guide topic. |
| Name | Required | Description |
|---|---|---|
| data | Yes |
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 closing 'No workspace access, external fetches or writes' largely restates structured data. It does usefully confirm the guide is a static bundled artifact with no network or workspace dependency, which is modest added value over the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence whose only elaboration is a tight four-item topic map. No filler, no restatement of the title, and the safety note is kept to a short trailing clause.
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 one enum parameter fully documented and an output schema present, the description need not explain return values. Purpose, topic selection, and the safety profile are all covered, leaving nothing an agent needs in order to select and invoke it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the enum already lists the four topic values, but the description adds meaning the schema does not: what content each topic contains (grammar/limits/examples, tags/duplicates/formatting, batches/recovery, review/rating), giving the agent a basis for choosing a topic.
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 a specific verb and resource ('Returns a bundled Nibomo reference guide') and enumerates the four topic domains with a parenthetical of what each covers, so an agent can tell it apart from sql_execute/sql_query siblings 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?
The topic parentheticals imply when each guide is relevant, but the description never states when to call this tool versus siblings like sql_execute or next_review_card (e.g. 'consult before writing SQL'). Usage is inferable rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Reads the authenticated account's plan, monthly AI limits and current usage for plan or remaining-allowance questions. No arguments, card access or writes. null aiMonthlyMessages means uncapped, not zero.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| data | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/non-destructive/closed-world, and the description reinforces this with 'No arguments, card access or writes' — the card-access note adds auth-scope context beyond the hints. The 'null aiMonthlyMessages means uncapped, not zero' line is a genuinely useful semantic disclosure about a null sentinel that the output schema alone may not convey.
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 short sentences, each earning its place: what it reads, when to call it, and the null-sentinel caveat. Front-loaded with the resource before the routing hint.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, return structure need not be restated, and the description covers the one remaining ambiguity (null meaning uncapped). Nothing an agent needs to call it 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?
Zero parameters, so the baseline is 4; the description correctly confirms 'No arguments,' matching the empty schema with additionalProperties=false. Nothing more is required.
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 (Reads) plus the exact resource set: the authenticated account's plan, monthly AI limits and current usage. No sibling tool (review cards, SQL, workspaces) overlaps with this scope, so an agent can route to it unambiguously.
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?
Names the triggering intent explicitly: 'for plan or remaining-allowance questions.' That is a clear use context, but it offers no exclusions or named alternatives for adjacent questions (e.g., per-workspace usage).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lists the authenticated user's accessible workspaces with IDs, names, card counts, activity and isSelected. Does not create or modify workspaces.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| data | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is fully covered externally. The description adds the user-scoping constraint ('authenticated user's accessible') and the returned field set, but the latter duplicates the output schema, leaving only modest added behavioral context.
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, no filler, with the core behavior front-loaded and the scope boundary second. Every clause carries information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter read tool with a full output schema and rich annotations, the description supplies everything an agent needs: scope, contents, and the negative boundary. Nothing material 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?
The tool takes zero parameters, so per the baseline this scores 4. There is nothing for the description to clarify beyond confirming the no-argument nature, which it implicitly does by describing an unfiltered listing.
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 (Lists) and resource (workspaces) with an explicit scope (the authenticated user's accessible workspaces) and enumerates the returned fields. No sibling tool overlaps with workspace listing, so an agent can select it unambiguously.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides a clear negative boundary: 'Does not create or modify workspaces,' which rules out confusion with a write operation. It stops short of naming when to call it (e.g., 'call before selecting a workspace') or pointing at any alternative, so it's strong but not complete.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns one eligible cardId/frontText or card:null for conversational review, without the answer, reservation, scheduling or grading. Server-time app queue order: due cards reviewed within an hour, other due cards, then new cards. Optional tags or deckId narrow the queue and are mutually exclusive.
| Name | Required | Description | Default |
|---|---|---|---|
| tags | No | Match any existing workspace tag, case-insensitively. Unknown tags return 400; [] matches nothing. Cannot combine with deckId. | |
| deckId | No | Saved deck UUID (tag filter); no deck tags means all cards. Cannot combine with tags. | |
| workspaceId | No | Workspace UUID; omit for selected. Keep fixed through review/retries. |
| Name | Required | Description |
|---|---|---|
| data | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safe-read profile is covered. The description adds genuinely useful context beyond that: it returns no answer, performs no reservation, scheduling or grading, and the queue order is server-time. Return shape ('or card:null') is also 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?
Three dense sentences, front-loaded with the return contract before the queue-ordering and filtering rules. Every sentence carries information, though the mutual-exclusivity clause is repeated from the schema, slightly reducing economy.
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 read-only queue-peek tool with a full output schema and fully documented parameters, the description covers return shape, side-effect exclusions, ordering semantics and filter constraints. Nothing an agent needs in order to call it 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 all three parameters are documented in the schema, including the mutual exclusivity of tags and deckId. The description restates the mutual exclusivity and filtering intent but adds no syntax or format detail 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 ('Returns one eligible cardId/frontText or card:null') and explicitly scopes it to conversational review without the answer, reservation, scheduling or grading. This cleanly separates it from siblings like reveal_answer and submit_review 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?
Gives clear operative context: server-time queue ordering (due within an hour, other due, then new) and that tags/deckId optionally narrow the queue and are mutually exclusive. It stops short of naming when to prefer it over siblings such as reveal_answer or sql_query, so it is clear but not fully routed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns the saved backText for a workspace card when revealing its reference answer during review. Does not submit a review or modify the card or schedule.
| Name | Required | Description | Default |
|---|---|---|---|
| cardId | Yes | The cardId returned by next_review_card. | |
| workspaceId | No | Workspace UUID; omit for selected. Keep fixed through review/retries. |
| Name | Required | Description |
|---|---|---|
| data | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint and non-destructive; the description adds real value by drawing the side-effect boundary explicitly — no review submitted, no card or schedule mutation. It stops short of 5 because it says nothing about permissions, or whether repeated reveals are safe within a session beyond what idempotentHint implies.
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 return value and then the non-effect. Every clause earns its place with no repetition of the title or schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so the description need not explain the return shape, and it still names the returned field (backText). With full schema coverage, a clear read-only side-effect statement, and no nested objects, nothing an agent needs to invoke 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% and both parameters are documented there, including that cardId comes from next_review_card and workspaceId defaults to the selected workspace. The description adds no parameter-level detail, so this is the baseline 3 case where the schema does the heavy lifting.
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 — returns the saved backText for a workspace card — and scopes it to the reveal step of a review. It also distinguishes itself from the review-submission flow, so an agent can separate it from siblings like submit_review without opening schemas.
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 clear context for use (revealing the reference answer during review) plus an explicit exclusion: it does not submit a review or modify the card or schedule. It doesn't name a sibling tool by name as the alternative path (e.g. submit_review), which keeps it just short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Writes to the Nibomo API (https://nibomo.com/docs/api/) with the published SQL dialect, not full PostgreSQL. Creates, updates or deletes workspace cards/decks with INSERT, UPDATE or DELETE; rejects read statements. Cannot write review_events or hidden FSRS state. front_text is a question and back_text its answer; new cards require at least one tag. Atomic batches allow 50 semicolon-separated write statements, 100 affected rows each. Arrays use ('a', 'b'), or () to clear. RETURNING * or columns returns affected rows. UPDATE and DELETE support tag filtering with tags OVERLAP ('tag'); UNNEST is available only in SELECT.
| Name | Required | Description | Default |
|---|---|---|---|
| sql | Yes | One or more write statements in the published Nibomo SQL dialect (INSERT, UPDATE, DELETE). | |
| workspaceId | No | Workspace UUID from list_workspaces; omit for the selected default. |
| Name | Required | Description |
|---|---|---|
| data | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well past the annotations (destructiveHint=true, readOnlyHint=false): it names protected tables (review_events, hidden FSRS state), batch limits (50 statements, 100 affected rows each), array literal syntax, and RETURNING semantics. This is the kind of constraint detail an agent cannot infer from structured fields.
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 the core write/dialect constraint, then dense constraint clauses; every sentence carries information, though the run of dialect rules makes it longer than strictly needed.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema covering return values and annotations covering the safety profile, the description supplies the remaining operational constraints (limits, protected resources, dialect quirks) an agent needs to call this correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents both parameters; the description adds dialect-level meaning for the sql value (allowed statement types, batch and row caps, OVERLAP tag filtering, UNNEST restriction) that the terse schema description omits.
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 (writes) and resource (workspace cards/decks via INSERT/UPDATE/DELETE) and explicitly excludes the sibling read path by noting it 'rejects read statements', separating it from sql_query.
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?
Clearly signals the write context and rules out read statements, which routes the agent to sql_query, but it never names the alternative tool or states prerequisites for selecting this one.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Queries the Nibomo API (https://nibomo.com/docs/api/) with the published read-only SQL dialect, not full PostgreSQL. Reads workspace-scoped workspace, cards, decks and review_events using SHOW TABLES, DESCRIBE, SHOW COLUMNS FROM or SELECT; rejects writes. Decks are tag filters; cards have no deck_id. SELECT returns at most 100 rows; pagination uses LIMIT, OFFSET and ORDER BY in the SQL string.
| Name | Required | Description | Default |
|---|---|---|---|
| sql | Yes | One or more read statements in the published Nibomo SQL dialect (SHOW TABLES, DESCRIBE, SHOW COLUMNS, SELECT). | |
| workspaceId | No | Workspace UUID from list_workspaces; omit for the selected default. |
| Name | Required | Description |
|---|---|---|
| data | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the annotations (readOnlyHint/idempotentHint), disclosing a hard 100-row SELECT cap, the pagination mechanism (LIMIT/OFFSET/ORDER BY inside the SQL string), rejection of writes, and a non-obvious schema constraint (cards have no deck_id, decks are tag filters). This is exactly the operational detail an agent needs to query correctly.
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 dense sentences that front-load the core identity (read-only SQL over Nibomo) before details. No filler, though the middle sentence packs four topics (allowed statements, write rejection, deck semantics, card schema) into one line, making it slightly run-on.
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?
An output schema exists, so return formatting need not be explained. The description covers dialect scope, allowed statement classes, write rejection, row limits, pagination, and schema gotchas, leaving nothing material missing for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both sql and workspaceId are already documented in the input schema. The description adds the notion that reads are workspace-scoped and names the SHOW TABLES/DESCRIBE/SELECT statement forms, but adds no syntax or fallback detail (e.g., default selection behavior) beyond the schema; 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 (Queries) and resource (Nibomo API with read-only SQL dialect), and explicitly negates full PostgreSQL. The 'rejects writes' clause distinguishes it from the sibling sql_execute, so an agent can tell the two apart 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?
Gives clear usage context: read-scoped statements (SHOW TABLES, DESCRIBE, SHOW COLUMNS FROM, SELECT) and the rejection of writes, which implies sql_execute is the write-path alternative. However, it never names that sibling or states an explicit when-not-to-use rule, so routing still requires inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Atomically records the supplied review rating and advances the card's authoritative FSRS schedule. Server stamps online review time; no history import. Returns the schedule, without card text or editable memory state. Reusing the same reviewId for the same card returns 409 REVIEW_EVENT_CONFLICT with the current schedule and no duplicate review. The same ID on another card returns 409 REVIEW_ID_CARD_MISMATCH without a write.
| Name | Required | Description | Default |
|---|---|---|---|
| cardId | Yes | The cardId returned by next_review_card. | |
| rating | Yes | Agent-assessed or manual learner rating: Again=failed recall; Hard=correct but difficult; Good=correct; Easy=complete and effortless. Default to Good if effort is unclear. Spoken aliases require learner agreement. | |
| reviewId | Yes | Persist this client-generated UUID before sending; reuse it on retries of this card's review to prevent duplicate reviews. | |
| workspaceId | No | Workspace UUID; omit for selected. Keep fixed through review/retries. | |
| reviewedTimeZone | Yes | Learner's IANA timezone, e.g. Europe/Sofia, for the local streak/progress day. |
| Name | Required | Description |
|---|---|---|
| data | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond annotations by disclosing atomicity, server-side timestamping, the reduced return shape (no card text or editable memory state), and precise 409 semantics for REVIEW_EVENT_CONFLICT and REVIEW_ID_CARD_MISMATCH, including that no duplicate or write occurs. This is exactly the retry/conflict context the idempotentHint and destructiveHint flags cannot convey.
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?
Four tight sentences, front-loaded with the core action, then constraints, then error behavior. No filler; every clause carries operational information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with a rich parameter set and an output schema, the description supplies what structured fields cannot: atomicity, conflict/retry handling, and what is deliberately omitted from the response. Nothing an agent needs to call it safely 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 the baseline is 3, but the description adds meaning the schema does not: reuse of reviewId on retries is tied to the 409 conflict behavior, and reviewedTimeZone's purpose (authoritative schedule vs. local streak day) is clarified. Per-field semantics remain mostly in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a precise verb+resource ('atomically records the supplied review rating and advances the card's authoritative FSRS schedule'), and the scope is immediately distinguishable from read-only siblings like next_review_card or reveal_answer. An agent knows this is the write step of the review loop.
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 draws a clear boundary with 'Server stamps online review time; no history import', telling the agent this is only for live reviews, not backfilling. It does not explicitly name sibling alternatives, but the exclusions give actionable context.
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.
get_guideget_usage_limitslist_workspacesnext_review_cardreveal_answersql_executesql_querysubmit_reviewRead, write, and conversationally review open-source flashcards through split read/write MCP tools.
Build and study spaced-repetition flashcards with your agent.
Spaced-repetition flashcards your AI writes, quizzes you on by voice, and schedules with FSRS.
Connect AI to your flomo notes. Search, create, edit notes and manage tags via MCP.
Add one secure layer between your agents and this server.
