Samuelz® Policy

Regeländerung prüfen

prepare_policy_change

Read-onlyIdempotent

Preview an explicitly requested policy replacement without applying it. Read confirmed content with get_policy, or discover editable revisions with get_policy_write_options. Activation belongs exclusively to the Owner card's app-only confirm_policy; models never call that confirmation.

Keep moduleKey/policyKey/expectedRevision from one options result. value replaces the whole policy rather than patching it: include the existing fields the user wants to retain.

The preview is neither queued nor saved. Its nextAction.arguments carries that exact replacement into the human card, which Business hosts present automatically.

Requires policy:read/write and current Owner/module access. Invalid or stale input fails without persistence. Reread the policy and renew intent rather than substituting a revision.

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": {
      "moduleKey": "<moduleKey>",
      "policyKey": "<policyKey>",
      "expectedRevision": "<expectedRevision>",
      "value": "<value>"
    },
    "name": "prepare_policy_change"
  }
}

Input Schema

Name	Required	Description
`value`	Yes	Complete explicitly requested replacement, not a patch: omitted fields are not retained. Must satisfy the selected native contract; canonical JSON is limited to 12000 UTF-16 code units. Copy supplied exact continuation arguments unchanged.
`moduleKey`	Yes	Policy module key from the same supported get_policy_write_options result as policyKey and expectedRevision; never a tenant selector.
`policyKey`	Yes	Existing editable policy identifier from that same result; arbitrary new identities and templates are unsupported.
`expectedRevision`	Yes	Opaque hash of the current complete state from that result, not a proposed-value hash or numeric history version. Stale state requires a fresh read and renewed intent.

Output Schema

Name	Required	Description
`after`	Yes	Validated explicit replacement during a preview; null during discovery. This value has not been saved.
`title`	Yes
`before`	Yes	Native current value, null when unconfigured. Read failures are errors, not empty configuration.
`effect`	Yes
`status`	Yes
`proposed`	No	Optional native adapter guidance, possibly null; never requested intent or approval.
`tenantId`	Yes	Workspace already bound by the current grant, never a selectable destination.
`moduleKey`	Yes	Policy module key from the same supported get_policy_write_options result as policyKey and expectedRevision; never a tenant selector.
`policyKey`	Yes	Existing editable policy identifier from that same result; arbitrary new identities and templates are unsupported.
`nextAction`	Yes	Existing private human-card continuation. Does not itself apply the value.
`displayAfter`	No
`settingsPath`	Yes
`writesPolicy`	Yes
`canDeactivate`	Yes	True only when this native settings contract defines a safe disabled value. Use deactivate_policy for an explicitly requested stop; unconfigured policies still have nothing to deactivate. Other policy values and templates have no generic delete or enabled-field fallback.
`displayBefore`	No
`currentVersion`	Yes	Current verified numeric policy version, or null when unconfigured; not the write revision.
`activatesPolicy`	Yes
`expectedRevision`	Yes	Opaque hash of the current complete state from that result, not a proposed-value hash or numeric history version. Stale state requires a fresh read and renewed intent.

Schema Changelog

Changes observed during successful MCP inspections.

First observedNov 11, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Beyond the readOnly/idempotent annotations, it discloses that the preview is neither queued nor saved, that nextAction.arguments carries the exact replacement into a human card presented automatically, and the access requirements (policy:read/write plus current Owner/module access). It also states failure behavior: invalid or stale input fails without persistence.

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 purpose and boundary in the first two sentences, then workflow, then access/failure rules. A few clauses restate what the schema already says about whole-replacement semantics, but nearly every sentence carries actionable instruction.

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 preview tool with an output schema and full annotation coverage, the description covers base-state sourcing, mutation semantics, downstream human confirmation, permissions, and stale-input recovery. Nothing an agent needs to call it safely is missing.

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, but the description adds cross-parameter meaning the schema cannot express: moduleKey/policyKey/expectedRevision must come from one options result, and value replaces the whole policy rather than patching, so retained fields must be included. That is genuine added value beyond the per-field schema text.

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?

Opens with a specific verb+resource and an explicit negative scope: 'Preview an explicitly requested policy replacement without applying it.' It names the related tools it is not (get_policy, get_policy_write_options, confirm_policy), so an agent can distinguish it from siblings without opening schemas.

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?

Gives an explicit workflow: read confirmed content with get_policy, discover editable revisions with get_policy_write_options, and route activation exclusively to confirm_policy. It also states an exclusion ('models never call that confirmation') and base-state guidance ('Reread the policy and renew intent rather than substituting a revision').

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

All Samuelz® Policy tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?