Skip to main content
Glama
platypus-db

platypus-db

Official

propose_edits

Submit row inserts, updates and deletes as pending edits in the table's data viewer for user review, save or discard; nothing is written until approved.

Instructions

Proposes rows to change in a table: PlatypusDB opens the table's data viewer with them as pending edits (new rows, changed cells, rows marked for deletion) that the user reviews, saves or discards (now if the app is open, else when it starts). Nothing is written here, whatever the connection's agent access. inserts: objects of column to value. updates: {key, set}, key naming a row by exactly the columns of a primary or unique key. deletes: objects naming rows by such a key. A value is a string, number, boolean or null (no arrays or objects); at most 500 rows and 1 MiB in all. The table needs a primary or unique key. On MongoDB the table is a collection (not a view) and the key is _id alone, read by the type of the collection's _id: an ObjectId as its 24 hex digits. Redis, Elasticsearch and Cassandra, read-only connections and those that forbid editing data are refused. title names the tab.

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": {
      "connection": "<connection>",
      "schema": "<schema>",
      "table": "<table>"
    },
    "name": "propose_edits"
  }
}

Input Schema

NameRequiredDescriptionDefault
tableYesThe table (a collection in MongoDB).
titleNoThe data viewer tab's title, e.g. what the changes do.
schemaYesThe table's schema (a database in MySQL and MongoDB, `main` in SQLite and DuckDB).
deletesNoRows to delete: each names a row by exactly the columns of a primary or unique key (`_id` alone in MongoDB, as for `updates`).
insertsNoRows to insert: each an object of column to value. A value is a string, number, boolean or null; columns left out take their default.
updatesNoRows to change: `key` names a row by exactly the columns of a primary or unique key of the table, `set` gives the new values of other columns (or the same). In MongoDB the key is `_id` alone, read by the type of the collection's `_id`: an `ObjectId` as its 24 hexadecimal digits (`{"_id": "65a1b2c3d4e5f60718293a4b"}`), a number as a number.
connectionYesThe connection's name, as `list_connections` shows it.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.6.2

TDQS

A4.2/5.0
Behavior4/5

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

With no annotations, the description carries the full burden and does so well: nothing is written, edits are applied now if the app is open or on next start otherwise, the user must approve, and limits of 500 rows / 1 MiB are disclosed. It also states the primary-or-unique-key precondition and the MongoDB collection and ObjectId encoding rules. It stops short of saying what happens to a partially invalid proposal or how conflicts with concurrent edits are handled.

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 the core behavior and the write-safety guarantee before the per-field mechanics, and every sentence carries information. The dense single-paragraph delivery with parenthetical asides makes it harder to scan than it needs to be, but there is no filler wording.

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

Completeness5/5

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

For a mutation-shaped tool with no annotations, no output schema, and seven parameters, the description covers safety, timing of effect, preconditions, size limits, engine-specific key rules, and refusal cases. An agent has everything needed to decide whether to call it and how to shape arguments.

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 nonetheless adds meaning beyond the schema with the aggregate limits (at most 500 rows and 1 MiB in all), the allowed scalar value types, and the requirement that keys use exactly the columns of a primary or unique key. Nearly all of this is duplicated in the per-parameter descriptions, so it is reinforcement rather than net-new semantics.

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

Purpose5/5

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

States a specific verb and resource ('Proposes rows to change in a table') and immediately explains the mechanism: rows surface as pending edits in the data viewer for review, save or discard. An agent can distinguish this from a query-execution sibling 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.

Usage Guidelines3/5

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

Usage context is implied clearly (edit existing table rows via a review workflow) and the refusal conditions are spelled out: Redis, Elasticsearch, Cassandra, read-only connections, and connections that forbid editing data. However, it never contrasts itself with the sibling SQL-proposal path, so an agent gets no explicit routing rule for choosing between them.

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