Skip to main content
Glama

yeastar_prepare_change

Read-only

Preview and validate a PBX configuration change by reading current state and calculating a before/after diff, returning a change_id for user confirmation before applying.

Instructions

PREPARA (non applica) una modifica di configurazione. Legge lo stato attuale, calcola il diff prima/dopo e restituisce un change_id. Mostra l'anteprima all'utente e aspetta il suo sì prima di chiamare yeastar_apply_change.

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": {
      "resource": "<resource>",
      "action": "<action>"
    },
    "name": "yeastar_prepare_change"
  }
}

Input Schema

NameRequiredDescriptionDefault
idNoID univoco dell'oggetto (update/delete)
dataNocreate: tutti i campi del nuovo oggetto. update: SOLO i campi da cambiare. Impostazioni globali: action='update' senza id.
actionYes
resourceYesNome risorsa dal catalogo

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.2/5.0
Behavior4/5

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

The description adds substantial behavioral context beyond the annotations: it reads live state, produces a diff, returns an opaque change_id, and requires a human confirmation step before any apply. This is consistent with readOnlyHint=true and destructiveHint=false, because nothing is mutated at prepare time. It stops short of describing what happens to a prepared change_id if it is never applied or how long it stays valid.

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?

Three short sentences that are fully front-loaded: the negation 'non applica' comes first, followed by mechanics and then the required user-confirmation workflow. Nothing is wasted, and the ordering tells the agent what to do next.

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 staged-change tool that has an output schema, the definition covers the essential contract: it does not mutate, it returns a change_id, and it must be confirmed by the user. What is missing is minor: where 'resource' values come from (presumably yeastar_catalog) and what happens after a prepare is abandoned, neither of which is critical to calling it correctly.

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 75%, and the schema already documents id ('ID univoco dell'oggetto'), data (create vs update semantics, global settings without id), and resource ('Nome risorsa dal catalogo'). The description adds no parameter-level meaning itself; the only gap is the action enum, which is self-describing. Baseline 3 is appropriate when the schema does the heavy lifting.

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?

The definition gives a specific verb and an explicit negation of the neighboring write tool: 'PREPARA (non applica) una modifica di configurazione'. It outlines the resulting behavior clearly: it reads the current state, computes the before/after diff, and returns a change_id. An agent can instantly tell this apart from yeastar_apply_change.

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?

The definition gives clear sequencing guidance: show the preview to the user, wait for the user's yes, then call yeastar_apply_change. It does not explain when to choose this tool instead of the other prepare variants (yeastar_prepare_operation, yeastar_prepare_raw, yeastar_prepare_rollback), so it leaves an important set of alternatives unaddressed.

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