Interact with a SQLite database through JMD documents using four MCP tools: open, read, write, and delete.
Open or switch SQLite databases, and inspect the active database (path, table count, tables/views).
Read records via exact lookup or QBE filters (equality, comparisons, alternation, substring, regex, negation).
Query with pagination, projection, joins, aggregation (sum, avg, min, max, count), grouping, HAVING, and sorting.
Read schema for tables, columns, types, modifiers, constraints, indexes, triggers, and views.
Write records via INSERT OR REPLACE, including bulk inserts.
Write schema: create/alter tables, composite primary keys, unique/check/reference constraints, indexes, triggers, views, virtual tables, and rebuilds.
Delete records by filter or bulk primary-key list.
Drop DDL objects: tables, views, indexes, and triggers with required confirm keys.
Optionally restrict database paths via ~/.config/jmd/sql.jmd; all inputs/outputs are JMD, with structured error documents.
Provides tools for interacting with SQLite databases, enabling agents to open databases, query records with filters and aggregation, insert or replace data, and manage tables using JMD documents.
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., "@jmd-mcp-sql List all tables in the database"
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 JMD demonstration server for relational data analysis through four MCP tools. QBE supplies compact datasets; the LLM combines results and develops its own analysis. The interface follows generic SQL concepts, with SQLite as its execution backend. Exposing every SQLite feature is not the objective.
Start with read("# Capabilities") for the supported operations, controls,
QBE syntax, response shapes, examples, and current limitations. Then inspect
read("#! Database") and read("#! <Table>") for the actual database structure.
Server instructions and each emitted tool description stay within 500
characters; the returned discovery document carries the detailed contract.
Northwind is the default analysis playground. See the multi-query walkthrough for exploring employee performance without requiring joins or aggregation in a single request.
JMD (JSON Markdown) is a lightweight
document format that combines Markdown headings with key: value pairs. It is
designed as a structured data format that LLMs can read and write naturally —
without JSON brackets or SQL syntax. A heading line sets the document type and
target table; the body carries the data:
# Order
id: 42
status: shipped
total: 149.99A prefix on the heading selects the operation: # for data, #? for queries,
#! for schema, #- for deletes. See the
JMD specification for the full format
definition.
Related MCP server: PySqlitMCP
Tool |
|
|
|
|
| Open database / show status | — | — | — |
| Capabilities / exact lookup | QBE; optional joins and aggregation | Describe database objects | — |
| INSERT OR REPLACE | — | CREATE / ALTER TABLE | — |
| — | — | DROP TABLE | DELETE WHERE |
All inputs and outputs are JMD documents. The LLM speaks JMD — no SQL required.
Install from PyPI:
pip install jmd-mcp-sqlOr with uv (no manual install needed — uvx fetches it on demand):
uvx jmd-mcp-sqlAlternatively, install directly from GitHub:
pip install git+https://github.com/ostermeyer/jmd-mcp-sql.gitThe server runs as a stdio-based MCP server. Without arguments it starts with the bundled Northwind demo database. Pass a path to use your own SQLite file:
jmd-mcp-sql /path/to/your.dbThe demo database ships as northwind.sql (plain text, version-controlled). On the
first run without an explicit path, the server creates northwind.db from that dump
automatically.
Add the server via CLI:
claude mcp add --transport stdio sql -- uvx jmd-mcp-sqlWith a custom database:
claude mcp add --transport stdio sql -- uvx jmd-mcp-sql /path/to/your.dbThis writes a .mcp.json in the project root (shareable via version control).
You can also create it manually:
{
"mcpServers": {
"sql": {
"command": "uvx",
"args": ["jmd-mcp-sql"]
}
}
}Claude Cowork runs inside Claude Desktop. MCP servers configured in the Desktop config are automatically available in Cowork sessions.
Edit claude_desktop_config.json:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"sql": {
"command": "uvx",
"args": ["jmd-mcp-sql"]
}
}
}With a custom database:
{
"mcpServers": {
"sql": {
"command": "uvx",
"args": ["jmd-mcp-sql", "/path/to/your.db"]
}
}
}Restart Claude Desktop after saving the file. The server will appear as a tool in both Chat and Cowork mode.
Create .vscode/mcp.json in the project root:
{
"servers": {
"sql": {
"type": "stdio",
"command": "uvx",
"args": ["jmd-mcp-sql"]
}
}
}Alternatively, add it to your VS Code settings.json (user or workspace):
{
"mcp": {
"servers": {
"sql": {
"type": "stdio",
"command": "uvx",
"args": ["jmd-mcp-sql"]
}
}
}
}Every document starts with a heading line that sets the document type and table name,
followed by key: value pairs (one per line):
# Product → data document (exact lookup / insert-or-replace)
#? Product → query document (filter / list / aggregate)
#! Product → schema document (describe / create / drop table)
#- Product → delete document (delete matching records)
key: value → string, integer, or float — inferred automatically
key: true/false → booleanOpen a different SQLite database at any time:
open("# Database\npath: /path/to/mydb.db")If the file does not exist, a new empty database is created. The previous database is closed automatically. The response uses frontmatter for metadata and lists tables in the body:
path: /path/to/mydb.db
table-count: 3
# Database
## tables[]
- Customers
- Orders
- ProductsCheck which database is currently active:
open("# Database")The server reads optional settings from ~/.config/jmd/sql.jmd:
# Config
root: /Users/me/dataField | Default | Description |
| (none) | Restricts |
Without a config file, no restrictions apply and the server accepts any path.
To see which tables exist, read each table's schema:
read("#! Customers")This returns a #! document with column declarations under ## columns:
JMD types and modifiers (readonly = primary key, optional = nullable).
Table constraints live under ## constraints, with ### primary-key[],
### unique[], ### check[] and ### references[]. Column- and table-level
CHECK constraints are included: simple string enums use a|b|c; other
expressions remain SQL CHECK expressions.
For example, a column named check coexists with a CHECK constraint:
#! Item
## columns
check: string optional
n: integer optional
## constraints
### check[]
- n > 0Schema writes use this same structure. Legacy flat columns and root-level
constraint arrays are refused with placement guidance. Virtual tables also
put columns under ## columns; using, unindexed[] and options[] stay
at the root. Inline Index[] and Trigger[] also remain at the root.
Both open and read("#! Database") list tables and views separately in
tables[] and views[]. The open response's table-count counts tables
only. Views remain available to ordinary reads and QBE queries.
Schema metadata is cached. After external schema changes, call open with
the same database path to refresh it. Calling open without a path only
returns status.
Schema output remains an approximation rather than a migration/backup format. The column namespace is independent of schema metadata names; generated columns and some default expressions still have discovery limitations.
List all rows (small tables only):
read("#? Orders")Filter rows — equality:
read("#? Orders\nstatus: shipped")Filter rows — comparison:
read("#? Orders\nFreight: > 50")Filter rows — alternation (OR):
read("#? Orders\nShipCountry: Germany|France|UK")Filter rows — literal substring (SQLite's default ASCII case folding):
Percent and underscore are ordinary characters here, not SQL wildcards. An invalid regex is refused before execution rather than treated as text.
field: null matches SQL NULL; field: !null matches non-null values.
A quoted "null" remains a string, and a valueless query field (field:)
is an empty-string condition. Other negated predicates follow SQL
three-valued logic: !Germany does not include rows whose field is NULL.
Alternatives such as null|Germany explicitly include NULL.
Filter rows — ranges with SQL semantics:
#? Products
UnitPrice: BETWEEN 10 AND 50BETWEEN includes both endpoints. NOT BETWEEN (or !BETWEEN) negates the
range. For half-open periods, combine ordered comparisons on one field:
#? Orders
OrderDate: >=1997-01-01 AND <1997-05-01
ShipCountry: GermanyAll field predicates combine with AND. Within a field, ordered comparisons can also combine with AND; either order of bounds works. Keywords are case-insensitive. Bounds are parameterized JMD scalars; SQLite applies its normal type affinity, collation and NULL logic. Dates remain stored values, without timezone conversion or end-of-day assumptions. Reversed bounds need not match any rows. A NULL endpoint follows SQL three-valued logic.
Quote endpoint strings containing connector words, for example
name: BETWEEN "A AND B" AND "Z OR Z". Outer JMD quoting only encodes the
complete scalar; it does not disable its query operators. Existing equality,
contains and regex expressions retain their meaning. Malformed ranges are
refused before execution; there is no arbitrary SQL, Boolean OR or grouping
grammar inside a predicate.
Field-to-field comparisons and date arithmetic are not offered. Narrow the dataset with supported filters, retrieve the required fields across all pages, and finish the comparison or calculation locally. Repeating a field does not add another condition; it is invalid JMD.
Projection, sorting, grouping, filters and HAVING resolve names against the applicable source or aggregate-result namespace. Ambiguous joined columns require explicit unambiguous projection or separate queries. Equivalent join keys appear once. Malformed controls and duplicate result names are refused.
read("#? Customers\nCompanyName: ~Corp")Filter rows — regex pattern:
read("#? Products\nProductName: ~re:Chai.*")Filter rows — negation (composes with any operator):
read("#? Orders\nShipCountry: !Germany")
read("#? Products\nProductName: !~re:LEGACY.*")Look up one record:
read("# Customers\nid: 42")Insert or replace a record:
write("# Orders\nid: 1\nstatus: pending\ntotal: 99.90")Create a table:
write("#! Products\n## columns\nid: integer readonly\nname: string\nprice: float optional")Delete a record:
delete("#- Orders\nid: 1")Drop a table:
delete("#! OldTable")Always use pagination when querying tables that may contain many rows.
Use frontmatter fields before the #? heading to control pagination:
read("page-size: 50\npage: 1\n\n#? Orders")The response carries pagination metadata as frontmatter — before the root heading:
total: 830
page: 1
pages: 17
page-size: 50
# Orders
## data[]
- OrderID: 10248
...Count only (no rows returned):
read("count: true\n\n#? Orders")Returns:
count: 830
# OrdersUse total and pages to determine whether to fetch more pages.
For tables with fewer than ~20 rows pagination is optional.
Use select: frontmatter to return only specific columns. This keeps
responses small and context windows focused.
read("select: OrderID, EmployeeID\npage-size: 50\n\n#? Orders")Works with both # (data) and #? (query) documents. When combined with
aggregation, select: filters the result columns after the GROUP BY.
Comma-separated controls take actual names without per-name quotes:
select: TicketID, opened at. The quotes in the schema key "opened at"
belong to JMD key syntax and are not part of the name. A column name containing
a comma cannot be addressed through these controls.
Use join: frontmatter to query across multiple tables in one call.
The value is <TableName> on <JoinColumn> (INNER JOIN, equi-join on a
column that exists in both tables).
read("join: Order Details on OrderID\nsum: UnitPrice * Quantity * (1 - Discount) as revenue\ngroup: EmployeeID\nsort: revenue desc\n\n#? Orders")Multiple joins — comma-separated in a single join: value:
join: Order Details on OrderID, Employees on EmployeeIDExpression syntax — use <expression> as <alias> in aggregate functions.
Single-table and joined queries accept the same arithmetic subset:
sum: UnitPrice * Quantity * (1 - Discount) as revenueThe alias becomes the result column name. Without as, the default alias
<func>_<field> applies (e.g. sum_Freight).
Expressions accept simple column identifiers, numeric literals, parentheses,
unary signs, arithmetic operators (+, -, *, /) and single-argument
ABS, ROUND, LENGTH, UPPER, LOWER calls. A plain column reference
can also be its full name, including spaces. Commas separate aggregate entries;
multi-argument calls, nested aggregates, date arithmetic and arbitrary SQL
expressions are outside this grammar.
Projection rules for join queries:
Unambiguous columns (appear in exactly one table) resolve automatically.
Shared join keys appear once only when every occurrence is constrained equal.
Other names present in multiple tables are ambiguous. Select unambiguous columns or query related tables separately; table-qualified names are not supported.
A one-to-many join repeats the one-side's values for every matching detail row. Aggregate order-level measures such as freight before joining order details; summing them after the join changes the measure. Several small queries and local calculations are a normal analysis workflow.
Aggregation is expressed as frontmatter before the #? heading.
QBE filter fields narrow rows before aggregation (SQL WHERE).
The having: key filters after aggregation (SQL HAVING).
Key | SQL | Result column name |
| GROUP BY | grouping keys pass through unchanged |
| SUM(field) |
|
| AVG(field) |
|
| MIN(field) |
|
| MAX(field) |
|
| COUNT(*) |
|
Multiple fields per function: sum: Freight, Total → sum_Freight and sum_Total.
Frontmatter | Meaning |
| ORDER BY (multiple columns, mixed) |
| HAVING COUNT(*) > 5 |
| HAVING … AND … (comma = AND) |
having: supports: >, >=, <, <=, =.
sort: references any result column — grouping keys or aggregate aliases.
page-size: and page: apply to the aggregated result set.
Example — top 3 employees by revenue:
read("group: EmployeeID\nsum: revenue\nsort: sum_revenue desc\npage-size: 3\n\n#? OrderDetails")All tools return a # Error document on failure:
# Error
status: 400
code: not_found
message: No records found in OrdersCheck the code field to decide how to proceed. Expected failures carry
structured context where available: parser kind, line, and field;
frontmatter unknown[] and accepted[]; path path and root; or SQLite
sqlite-code and sqlite-name (when supplied by the Python runtime).
Exception strings are never copied into responses.
Constraint violations return status 409, busy/locked databases 503, and
database permission failures 403. Unexpected implementation errors return
status 500 with code: internal_error; the traceback stays in the server log.
These statuses are fields in the JMD document, not HTTP transport statuses.
A failed database switch preserves the current connection. Bulk inserts validate all records before writing and roll back the batch on execution failure.
This checkout uses the published jmd-format>=0.10.3 package and the compatible
MCP SDK v1 line (mcp>=1.26,<2). It does not depend on an editable sibling
checkout. Install the versions recorded in uv.lock and run the quality gates
before the tests:
uv sync --locked
uv run --locked ruff check .
uv run --locked mypy jmd_mcp_sql tests
uv run --locked pytest -qCI runs these same gates on Python 3.10–3.13. The broader JMD API alignment and remaining design questions are recorded in JMD-REVIEW.md.
The JMD format is documented at jmd-spec.
Copyright © 2026 Andreas Ostermeyer.
Licensed under the Apache License, Version 2.0 — see LICENSE. The JMD ecosystem is open: the specification is CC BY 4.0, the Python and JavaScript reference implementations are Apache 2.0, and this server matches. No copyleft, no dual licensing, no CLA. Use it, fork it, extend it, ship it — attribution preserved per Apache 2.0 § 4.
This project has changed license twice during its early development:
0.4 – 0.7.1 (MIT, yanked from PyPI as the default install target)
0.8.0 – 0.9.x (AGPL-3.0, reflecting a brief period in which a commercial deployment path was under consideration)
0.10.0 and later (Apache 2.0, aligned with the rest of the JMD ecosystem)
Users who installed any of the prior versions retain the rights those licenses granted for those specific artifacts. License changes are not retroactive. See CHANGELOG.md for the rationale.
Delete records or drop a DDL object (https://github.com/ostermeyer/jmd-spec).
Delete (#- Label): filter-based delete (≥1 field required).
#- Order
id: 42Bulk delete (#- Label[]): primary-key list (or objects for composite keys).
#- Order[]
- 42
- 43Schema (#! Label): drop a DDL object. Each kind needs its own confirm-key:
Tables / views (legacy): confirm: drop-table
#! OrderIndexes: confirm: drop-index
#! Index
name: idx_order_statusTriggers: confirm: drop-trigger
#! Trigger
name: trg_log_ordersViews (preferred over the legacy drop-table path): confirm: drop-view
#! View
name: PendingOrdersFrontmatter policy: strict refusal — unknown keys cause an error. Accepted keys: confirm, debug. Debug: 'debug: sql, timing, table'.
| Name | Required | Description | Default |
|---|---|---|---|
| document | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden and does well: it discloses confirm-key requirements, strict refusal on unknown keys, accepted keys (confirm, debug), and the debug option. The destructive nature is implied by 'delete'/'drop' and reinforced by confirm keys; return values are covered by the output schema.
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 long, but the length is earned: purpose is front-loaded and each block adds a distinct mode or policy. The code examples are compact and scannable, and the URL provides a reference without bloating the text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with three modes, one opaque parameter, and no annotations, the description covers the necessary syntax, confirm keys, accepted frontmatter, and debug behavior. It falls just short of fully complete because it never explicitly ties the examples to the 'document' parameter or states the output shape, though an output schema exists.
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 0% and there is only a 'document' string parameter. The description effectively documents the document format through labeled examples and frontmatter policy, which adds substantial meaning beyond the bare schema, though it never explicitly names the 'document' parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Delete records or drop a DDL object'. It then distinguishes three concrete modes (filter-based delete, bulk delete, schema drop), which makes the tool's scope unmistakable and separates it from siblings like open/read/write.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives clear usage context for each mode, e.g. 'filter-based delete (≥1 field required)' versus 'primary-key list', and notes that schema drops require per-kind confirm keys. It does not explicitly mention when to prefer delete over write, so it misses the top-level alternative guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Open a SQLite database or inspect the current one.
Open (# Database with path):
# Database
path: /path/to/mydb.dbIf the file does not exist, it is CREATED as an empty
database and the response contains created: true.
Inspect (# Database with no fields):
# DatabaseReturns path, table count, and a list of all tables.
Frontmatter policy: observable tolerance — unknown keys are echoed in the response as 'ignored-keys: ...'.
| Name | Required | Description | Default |
|---|---|---|---|
| document | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden. It discloses the key side effect: if the file does not exist it is CREATED, and the response contains 'created: true'. It also describes inspect output and the frontmatter ignored-keys policy. It does not mention connection lifecycle or permissions, but the main side effects are covered.
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 compact and front-loaded with the main purpose. It uses clear code blocks for the two invocation shapes, and every sentence adds value: creation side effect, inspect result, and frontmatter policy. No filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter tool with an output schema, the description covers the two modes, the create-if-missing behavior, and the inspect return summary. It is slightly incomplete about what opening an existing database returns and how the 'current' database changes, but the output schema covers return details.
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 only names a required 'document' string with no description (0% coverage). The description provides examples showing the document structure ('# Database' with 'path: ...' and no fields for inspect), but it never explicitly states that the 'document' parameter is the string containing these fields, leaving the mapping implicit.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Open a SQLite database or inspect the current one.' It clearly distinguishes two modes (open with a path vs. inspect with no fields) and names the resource, making it easy to tell apart from the sibling read/write/delete 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 gives clear context for when to use each mode: open with a path, or inspect with no fields. However, it does not explicitly contrast with the sibling tools read/write/delete or state when not to use this tool, so it stops short of full routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read records or schema via a JMD document (https://github.com/ostermeyer/jmd-spec).
Data (# Label): exact-match lookup.
# Order
id: 42Query (#? Label): QBE filter; optional pagination, projection, aggregation, and JOIN.
#? Order
status: pendingSchema (#! Label): describe the table — columns, types, modifiers, and any sub-section constraints.
#! OrderReserved DDL-object labels (dispatch to per-kind shape unless a real table by that name exists):
#! Database list tables, indexes, triggers, views
#! Index / name: foo index: table, columns, unique, where
#! Trigger / name: foo trigger: when, event, condition, body
#! View / name: foo view: selectQBE operators in #? bodies: = equality (default)
greater than >= greater or equal < less than <= less or equal | alternation (OR), e.g. 'Germany|France' ~ substring (case-insensitive), e.g. '~Corp' ^ regex (implicit full-match anchoring) ! negation, composable with any operator
Frontmatter keys: page-size, page pagination count return only the row count select projection (comma-separated columns) join cross-table JOIN, e.g. 'Table on Col' sum, avg, min, max aggregations with optional 'as alias' group, having, sort GROUP BY / HAVING / ORDER BY
Frontmatter policy: observable tolerance — unknown keys are echoed back as 'ignored-keys: …'. Debug: 'debug: sql, timing, table, plan, filters, resolved, coercions' (composable; 'debug: true' enables all).
| Name | Required | Description | Default |
|---|---|---|---|
| document | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does substantial work: it discloses exact-match vs QBE behavior, frontmatter unknown-key tolerance, debug options, and DDL dispatch rules. It does not explicitly state side-effect safety, but 'read' plus the detailed query semantics make the non-mutating nature clear enough.
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 long, but the content is dense and genuinely needed for a complex DSL. It is well-structured with headers, inline code examples, and tables; the opening line front-loads the core purpose. A small amount of trimming could improve conciseness, but the length is largely justified.
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 single-parameter tool with a complex document format, this description is remarkably complete: it covers the syntax, operators, frontmatter, reserved labels, and debug controls. The presence of an output schema means not explaining return shape is acceptable, and no critical usage detail appears 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 0%, so the description must fully explain the lone 'document' string, and it does so exhaustively: JMD labels, QBE operators, frontmatter keys, aggregation, joins, and debug flags. This transforms an opaque string parameter into a fully specified query language.
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: 'Read records or schema via a JMD document,' and supports it with concrete syntax examples. This clearly separates it from the write/delete siblings, and the detail makes the tool's purpose unambiguous even without a 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 tool's purpose implies it is for reading data or schema, and the sibling names (open, write, delete) provide context. However, the description never explicitly tells an agent when to prefer read over open, nor does it describe exclusion criteria or alternative choices.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Write a record or define a DDL object (https://github.com/ostermeyer/jmd-spec).
Data (# Label): INSERT OR REPLACE one record.
# Order
id: 42
status: shipped
total: 149.99Bulk insert (# Label[]):
# Order[]
- id: 42
status: shipped
- id: 43
status: pendingSchema (#! Label): full SQLite DDL surface.
Per-column types: integer, float, string, boolean (int in SQLite). Per-column modifiers: readonly primary key (single-col); do not supply on insert optional NULL allowed = DEFAULT value (number, string, CURRENT_TIMESTAMP) a|b|c enum form — generates a CHECK (col IN (…))
#! Order
id: integer readonly
status: pending|shipped|cancelled
total: float = 0
customer_id: integerTable-level constraints as sub-sections:
Inline DDL objects under #! Table (created atomically with the table):
Top-level DDL-object documents:
#! Index
name: idx_order_status
table: Order
columns: status
unique: false
where: deleted_at IS NULL
#! Trigger
name: trg_log_orders
table: Order
when: AFTER # BEFORE | AFTER | INSTEAD OF
event: INSERT # INSERT | UPDATE [OF cols] | DELETE
condition: NEW.status = 'pending'
body: "INSERT INTO Log(msg) VALUES ('x');"
#! View
name: PendingOrders
select: "SELECT id FROM \\\"Order\\\" WHERE status='pending'"Virtual tables — using: <module> modifier on #! Table:
#! Notes
using: fts5
title: string
body: string
## unindexed[]
- memory_id
## options[]
- "tokenize = 'porter unicode61'"Existing tables: writes are additive — only new columns are added. Constraint or column-type changes need 'action: rebuild' frontmatter, which runs the SQLite table-rebuild dance atomically (data preserved over the column intersection; pre-existing dependent indexes and triggers must be redeclared inline in the rebuild document).
Frontmatter policy: observable tolerance. Frontmatter keys: action (= 'rebuild'), debug. Debug: 'debug: sql, timing, table'.
| Name | Required | Description | Default |
|---|---|---|---|
| document | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations to rely on, the description fully discloses behavior: INSERT OR REPLACE semantics, bulk insert support, atomic creation of inline DDL objects, additive writes for existing tables, the rebuild dance, and debug frontmatter. This is far beyond minimal behavioral disclosure.
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 long, but every section adds necessary DSL detail and examples. It is front-loaded with the purpose and then organized by document form; the length is justified by the complexity of the format.
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 single untyped string parameter and no annotations, the description is essentially complete as a usage manual. It covers all supported syntax, edge cases like additive schema changes, rebuild requirements, and even debug options. An agent has enough context to construct valid documents.
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 only provides a generic 'document' string with 0% schema coverage, so the description must carry the full semantic burden. It does so comprehensively, specifying exact syntax for records, schemas, constraints, indexes, triggers, views, virtual tables, and frontmatter.
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 leads with a specific verb and resource: 'Write a record or define a DDL object'. It clearly separates this write-oriented tool from siblings like open, read, and delete, and immediately signals both data and schema-writing responsibilities.
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 operational guidance, including when to use 'action: rebuild' for constraint changes and how to structure records versus DDL objects. It does not explicitly contrast with the sibling tools, but the usage context is unambiguous.
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.11.0deleteopenreadwriteScored across 4 tools
The four tools are broadly distinct: open manages the database connection/inspection, read queries records/schema, write creates/updates records and DDL, and delete removes records/drops objects. A minor overlap exists between open's inspect mode and read's #! Database schema listing, which could cause an agent to pick either for listing tables.
All tool names are single-word lowercase verbs (open, read, write, delete), forming a perfectly consistent naming style. There is no mixing of conventions or verb patterns.
Four tools is a well-scoped count for a SQLite interface, with each tool covering a fundamental operation: connection, read, write, delete. Although each tool is internally rich with sub-commands, the top-level surface is minimal and each tool earns its place.
The surface covers the full database lifecycle: opening/creating a database, reading and querying data/schema, inserting/replacing records and defining DDL objects, and deleting records or dropping DDL objects. No obvious dead ends exist for the stated JMD-document-based SQLite purpose.
Text-to-SQL MCP server: read-only queries on PostgreSQL, MySQL and SQL Server with your real schema
GibsonAI MCP server: manage your databases with natural language
Explore, query, and inspect SQLite databases with ease. List tables, preview results, and view det…
Read and edit DB Planner database schemas, diagrams and board layouts as an AI agent.
