Skip to main content
Glama

RationalBloks

by io.github.rationalbloks
OverviewDiscussionsAdmin

Patch Schema

patch_schema

Change PART of a project's schema without dropping any of it (saves to database, does NOT deploy).

Send only the change. The server applies it to the saved schema, in order and all together, and keeps every table and field it does not touch — including their identity, so a rename stays a rename and the column keeps its data.

OPERATIONS (each one small object, applied in the order given): • {"op": "add_table", "table": "clocks", "definition": {...}} new table, same FLAT rules as create_project • {"op": "rename_table", "table": "clocks", "to": "timers"} • {"op": "add_field", "table": "assets", "field": "serial", "definition": {"type": "string", "max_length": 64}} • {"op": "rename_field", "table": "parameters", "field": "is_clock", "to": "clock_kind"} • {"op": "set_field", "table": "assets", "field": "name", "properties": {"max_length": 300}} merges; a property set to null is removed • {"op": "set_table", "table": "assets", "properties": {"audit": true}} policy, constraints, audit, admin_write

Dropping a table or field is drop_schema_items, a tool of its own.

ALL OR NOTHING: an operation that cannot be applied — a table or field that is not there, a name already taken, a schema the deploy would refuse — refuses the whole patch, naming the operation, and nothing is saved.

EVERY ANSWER IS A DIFF: 'applied' (what each operation did), 'diff' (every changed property by path), 'summary' and 'plan' (the migration a deploy would then run), and 'version' (the schema's version after the change).

WORKFLOW:

  1. get_schema with tables/fields to read the part you are changing (its 'version' is the whole schema's)

  2. preview_schema_change with the operations: check 'diff' and 'plan'

  3. patch_schema with the same operations (pass expected_version to be refused if someone else saved meanwhile)

  4. deploy_staging, then get_job_status

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
operationsYesThe operations, applied in order and all together. See the tool description for every op and its fields.
project_idYesProject ID (UUID)
expected_versionNoThe 'version' a get_schema read answered. The patch is refused (409) when the saved schema changed since, so two editors never overwrite each other silently.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • removedInput schema / properties / dry_run
      Removed value: -{
-  "description": "Save nothing: answer what the operations did, the diff and the migration plan a deploy would run.",
-  "type": "boolean"
-}
  2. Added

TDQS

A4.9/5.0
Behavior5/5

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

Annotations declare readOnly=false, destructive=false, idempotent=false but disclose nothing about semantics. The description adds the real behavioral payload: it writes to the saved schema but does not deploy, is all-or-nothing (a single bad op refuses the whole patch naming the operation), preserves untouched tables/fields including identity so renames and data survive, and supports optimistic concurrency via expected_version returning 409.

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

Conciseness5/5

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

Long, but front-loaded with the single most important constraint (patch, don't drop; save, don't deploy), then organized under OPERATIONS / ALL OR NOTHING / EVERY ANSWER IS A DIFF / WORKFLOW headers with copy-pasteable op examples. Length is proportionate to the op grammar an agent must construct, and no sentence is filler.

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?

With no output schema, the description carries the return burden and does so by enumerating the response keys ('applied', 'diff', 'summary', 'plan', 'version'). The workflow and atomicity/refusal rules make it callable without guesswork. Minor gap: the diff/plan shapes are named but not illustrated, though that is a small omission for a tool this complex.

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

Parameters5/5

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

Schema coverage is 100% (baseline 3), but the operations param is typed as an untyped object array whose schema description literally says 'See the tool description for every op and its fields' — so the full op grammar (add_table, rename_table, add_field, rename_field, set_field, set_table) with concrete JSON examples exists only here. The description also explains expected_version's race-refusal semantics and that set_field merges/null-deletes.

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 precise verb+resource+scope: 'Change PART of a project's schema without dropping any of it (saves to database, does NOT deploy).' It explicitly carves itself away from siblings update_schema and drop_schema_items, including naming the sibling that handles drops.

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

Usage Guidelines5/5

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

Provides an explicit 4-step workflow (get_schema → preview_schema_change → patch_schema → deploy_staging/get_job_status) and an explicit exclusion ('Dropping a table or field is drop_schema_items, a tool of its own'). It also states the condition that triggers a refusal (expected_version / 409), which tells the agent when to pass it.

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

All RationalBloks toolsInspect
Try in Browser
Shareable, User-Owned Context BackendPeople, applications, and agents read, write, and coordinate together in one context lake. Reach it over MCP, a CLI, a Python SDK, or REST.fulcradynamics.comAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources