Skip to main content
Glama

update_schema

Idempotent

Replaces an agent schema using its current base version to prevent overwrites; on conflict, reread and reconcile before applying changes.

Instructions

Update an agent schema using its current base_version. Supplied schema_data replaces the full document; reload and reconcile on CONFLICT.

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": {
      "schema_id": "<schema_id>"
    },
    "name": "update_schema"
  }
}

Input Schema

NameRequiredDescriptionDefault
changelogNoReason for the change, recorded in version history
schema_idYesUUID of the schema to update
schema_dataNoComplete new schema_data in the format used by create_schema. Replaces the previous object entirely; partial updates are not supported.
base_versionNoRecommended: version read from get_schema. A concurrent change returns CONFLICT with the current version and saves nothing; reread and reapply. Without it, the last write wins.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed4 schema fields changedv2.2.4
    • changedInput schema / properties / base_version / description
      Previous value: -"Recomendado. A `version` que você leu em get_schema. Se o schema mudou desde então (outra pessoa editou), nada é gravado e volta CONFLICT com a versão atual — releia e reaplique. Sem ele, a última escrita vence."New value: +"Recommended: version read from get_schema. A concurrent change returns CONFLICT with the current version and saves nothing; reread and reapply. Without it, the last write wins."
    • changedInput schema / properties / changelog / description
      Previous value: -"Por que a mudança foi feita. Fica gravado na versão criada (list_versions/compare_versions)."New value: +"Reason for the change, recorded in version history"
    • changedInput schema / properties / schema_data / description
      Previous value: -"Novos dados do schema (mesma estrutura por tipo de create_schema). IMPORTANTE: enviar schema_data completo, não parcial — o objeto substitui o anterior por inteiro."New value: +"Complete new schema_data in the format used by create_schema. Replaces the previous object entirely; partial updates are not supported."
    • changedInput schema / properties / schema_id / description
      Previous value: -"UUID do schema a atualizar"New value: +"UUID of the schema to update"
  2. Changed4 schema fields changedv2.2.2
    • addedInput schema / properties / base_version
      Added value: +{
      +  "description": "Recomendado. A `version` que você leu em get_schema. Se o schema mudou desde então (outra pessoa editou), nada é gravado e volta CONFLICT com a versão atual — releia e reaplique. Sem ele, a última escrita vence.",
      +  "minimum": 0,
      +  "type": "integer"
      +}
    • addedInput schema / properties / changelog
      Added value: +{
      +  "description": "Por que a mudança foi feita. Fica gravado na versão criada (list_versions/compare_versions).",
      +  "maxLength": 500,
      +  "type": "string"
      +}
    • removedInput schema / properties / description
      Removed value: -{
      -  "description": "Nova descrição",
      -  "type": "string"
      -}
    • removedInput schema / properties / name
      Removed value: -{
      -  "description": "Novo nome",
      -  "minLength": 1,
      -  "type": "string"
      -}
  3. First observedv0.1.0

TDQS

A4/5.0
Behavior4/5

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

Annotations already declare readOnlyHint=false and idempotentHint=true, so the safety profile is partly covered. The description adds meaningful context beyond them: the supplied schema_data replaces the whole document, and omitting base_version means last-write-wins. It doesn't state what happens to existing fields on a replacement or what a CONFLICT response contains, which keeps it below 5.

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?

Two tight sentences: identity and required version first, then the replacement and conflict handling. Every clause carries operational weight, and the conflict instruction is placed where the agent will read it before calling.

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?

This is a mutating tool with a nested object parameter and no output schema, so the description needs to cover replacement and concurrency; it covers both. It doesn't mention the changelog parameter or how a missing or unknown schema_id is treated, which are minor omissions rather than blocking gaps.

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

Parameters3/5

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

Schema coverage is 100%, so the schema already documents all four parameters, including base_version's conflict behavior and schema_data's full-replacement requirement. The description largely restates the base_version contract rather than adding new parameter detail. Baseline 3 is the right ceiling here.

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?

States a specific verb and resource: 'Update an agent schema using its current base_version.' The update semantics are unmistakable, and the base_version mention distinguishes it from create_schema in practice. It never names a sibling tool explicitly, so it falls short of a 5.

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

Usage Guidelines4/5

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

Gives concrete operational guidance: supply the version read from the schema, and 'reload and reconcile on CONFLICT.' That tells the agent what to do when a concurrent change occurs, which is the main decision point for this tool. It doesn't say when to prefer create_schema or validate_schema_data over it, so 4 rather than 5.

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