Skip to main content
Glama
Sign In
anki-connect-mcp

anki-connect-mcp

by SolarianGG
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

notes.convert

notes_convert
Destructive

Convert same-type Anki notes to a target note type using field and template mappings, with plan tokens validating the conversion before applying it.

Instructions

Convert same-type notes through Anki note-type conversion.

Mappings are complete target-name to source-name/null lists. Reject duplicate source mappings, mixed source note types and stale tokens. Removed source templates lose their cards/history as defined by Anki; cloze mappings use native supported rules, never raw mid assignment.

Anki-Connect method notes.convert. Scope: collection. Effect: write. Completion: completed. Undo: single.

Possible errors: collectionUnavailable, conflict, editorConflict, internalError, invalidParams, notFound, staleSession, unsupportedCapability.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "ids": "<ids>",
      "target": "<target>",
      "fields": "<fields>",
      "templates": "<templates>",
      "planToken": "<planToken>"
    },
    "name": "notes_convert"
  }
}

Input Schema

NameRequiredDescriptionDefault
idsYesNotes to convert (decimal string, e.g. "1700000000001"); all must have the same note type.
fieldsYesField mapping [{target, source}] (source = old field name or null), usually taken from `notes_planConversion`.
targetYesNote type to convert to: exactly one of {"id": "<noteTypeId>"} or {"name": "<note type name, e.g. Basic>"}.
sessionNoOptional. Collection session ID: the `session` field returned by `collection_get`. Usually omit it — the server then uses the session current at the time of the call. Pass it to make the call fail with `staleSession` instead of acting on a different profile/collection than the one your IDs, cursors and tokens came from.
planTokenYesToken from `notes_planConversion`; it becomes invalid if either note type changes.
templatesYesTemplate mapping [{target, source}] (source = old template name or null), usually taken from `notes_planConversion`.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4/5.0
Behavior5/5

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

Annotations only declare destructiveHint=true and readOnlyHint=false; the description goes well beyond them by stating that removed source templates lose their cards and history as defined by Anki, that cloze mappings follow native rules and never use raw mid assignment, and that undo is a single step. It also enumerates the concrete error surface (staleSession, conflict, editorConflict, unsupportedCapability), which is exactly the operational context an agent needs before an irreversible write.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose, then constraints, then effect/undo, then errors — a sensible order with no filler sentences. The telegraphic phrasing ('Effect: write. Completion: completed. Undo: single.') is dense but information-bearing rather than redundant.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a destructive, six-parameter write tool with no output schema, the description covers scope, effect, undo granularity, data-loss consequences and the error set, which is most of what an agent needs. It does not describe what the call returns on success, a gap masked only by the absence of an output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3; the description adds meaning beyond the schema by specifying that mappings are complete target-to-source lists, that duplicate source mappings are rejected, and that all ids must share one note type. It also ties planToken invalidation to changes in either note type, which the schema does not say.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The opening sentence names a specific verb and resource: converting same-type notes via Anki note-type conversion, which separates it from notes_planConversion (planning) and notes_update (field edits). It stops short of explicitly naming the sibling tools in prose, leaving that differentiation to the schema's cross-references.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied rather than stated: the tool converts existing same-type notes, requires a planToken, and rejects duplicate source mappings, mixed note types and stale tokens. There is no explicit 'call notes_planConversion first' or 'use notes_update instead when only fields change' guidance in the description itself; that routing hint only appears inside the schema text.

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

Deploy Server

Other Tools