Skip to main content
Glama

manage_item

Modify OpenHAB items by creating or updating, deleting, changing state, managing tags and metadata. Use semantic_fix for hierarchy or semantic model fixes instead of create_or_update.

Instructions

Modify items. action: create_or_update, delete, update_state, add_tag, remove_tag, set_metadata, remove_metadata. WARNING: Do NOT use create_or_update for semantic model fixes (parentage, hierarchy). Use remediate action=semantic_fix instead. create_or_update safely merges existing groupNames and tags on update, but semantic relationships (hasLocation, isPointOf, isPartOf) must go through semantic_fix. WARNING: Do NOT use create_or_update for semantic model fixes (parentage, hierarchy). Use remediate action=semantic_fix instead. create_or_update safely merges existing groupNames and tags on update, but semantic relationships (hasLocation, isPointOf, isPartOf) must go through semantic_fix.

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": {
      "action": "<action>",
      "itemName": "<itemName>"
    },
    "name": "manage_item"
  }
}

Input Schema

NameRequiredDescriptionDefault
tagNoUsed by: add_tag, remove_tag
stateNoUsed by: update_state
valueNoUsed by: set_metadata
actionYes
configNoUsed by: set_metadata
itemDataNoUsed by: create_or_update
itemNameYes
namespaceNoUsed by: set_metadata, remove_metadata

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv1.3.2

TDQS

B3.1/5.0
Behavior3/5

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

With no annotations at all, the description carries the full burden, and it does disclose one genuinely valuable behavior: create_or_update safely merges existing groupNames and tags while semantic relationships (hasLocation, isPointOf, isPartOf) must be routed elsewhere. It says nothing about whether delete is destructive/reversible, what permissions are required, or what any action returns.

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

Conciseness2/5

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

The three-sentence warning block appears twice verbatim, roughly doubling the description length with zero added information. The opening action enumeration is well front-loaded, but a fifth of the text is pure duplication that an agent must read through twice.

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

Completeness2/5

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

This is an 8-parameter, nested-object, multi-action mutation tool with no annotations and no output schema, so the description should explain consequences. It covers the merge-vs-semantic-fix hazard but leaves delete destructiveness, side effects, and result shape entirely unaddressed.

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 description coverage is 75% and the schema itself tags each parameter with the action that consumes it ("Used by: add_tag, remove_tag", etc.), so the baseline of 3 applies. The description adds no format, syntax, or constraint detail for itemData, config, state, or namespace beyond restating action names.

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?

"Modify items" names a resource and mutation verb, and the enumerated action list (create_or_update, delete, update_state, add_tag, remove_tag, set_metadata, remove_metadata) makes the tool's scope concrete against siblings like query_items or manage_thing. It never explicitly names a sibling to differentiate itself, which keeps it below 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 Guidelines3/5

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

The description gives one strong, explicit routing rule: don't use create_or_update for parentage/hierarchy work, use remediate action=semantic_fix instead. But that covers only one of seven actions; there is no guidance on when to pick delete vs update_state, no prerequisites, and no contrast with siblings such as manage_thing or manage_link.

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