How do I use Homebox MCP Server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Homebox MCP Server search for products matching 'drill'" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

Homebox MCP Server

by Tafeen

Overview Schema Source Related Servers Score Discussions Admin

Python

Remote

Homebox MCP Server

An MCP server that exposes Homebox inventory management as tools for AI agents.

What it does

This server lets an AI agent (Claude, Hermes, OpenClaw, or any MCP-compatible client) read and write your Homebox inventory: search, add, update, and delete products and locations, manage tags and maintenance entries — all through the unified Homebox v0.26+ entities API.

It runs in two transports:

stdio — for local agents that launch the server as a subprocess.
Streamable HTTP (/mcp) — for remote agents that talk HTTP. Per-request credentials are passed via request headers.

Key behaviors:

Targets Homebox v0.26.0+ (the entity-merge release) — items and locations share /api/v1/entities, with parentId denoting the parent entity. Older Homebox releases using /api/v1/items and /api/v1/locations are not supported.
search_products with only name splits the phrase into terms and queries each in parallel for broader recall.
add_product and update_product_by_id use grouped parameter objects (identity, location, identifiers, purchase, metadata, status) so large calls stay readable.
Maintenance tools (create_maintenance_entry_for_product, list_maintenance_entries, update_maintenance_entry, delete_maintenance_entry) operate against /api/v1/maintenance.
Multi-collection (tenant) support is exposed via the Homebox-native X-Tenant request header on the HTTP transport.

Related MCP server: inventree-mcp-plugin

Installation

Requirements

Component	Version
Homebox (server)	v0.26.0 or newer (tested v0.26.2)
Python	3.10.13+
Dependencies	Listed in `pyproject.toml`
`uv` (recommended)	https://docs.astral.sh/uv/

Older Homebox releases that still expose /api/v1/items and /api/v1/locations are not supported — the server talks to /api/v1/entities exclusively.

Install the server

git clone <repo-url> homebox-mcp
cd homebox-mcp
uv sync                 # installs runtime + dev dependencies
cp .env.example .env   # then edit .env with your Homebox credentials

.env.example:

HOMEBOX_BASE_URL=https://your-homebox-instance.com
HOMEBOX_USERNAME=your_email@example.com
HOMEBOX_PASSWORD=your_password
# Optional HTTP server settings (server_http.py)
# FASTMCP_HOST=0.0.0.0
# FASTMCP_PORT=8000

Docker

docker build -t homebox-mcp .
docker run -p 8000:8000 \
  -e HOMEBOX_BASE_URL="https://your-homebox-instance.com" \
  -e HOMEBOX_USERNAME="your_email@example.com" \
  -e HOMEBOX_PASSWORD="your_password" \
  homebox-mcp

Run the server

just start         # stdio mode (default for local agents)
just start-http    # Streamable HTTP mode at http://0.0.0.0:8000/mcp

Or directly:

uv run main.py            # stdio
uv run server_http.py     # streamable HTTP

Install inside an agent

Pick the snippet that matches your agent and copy-paste it into the agent's MCP configuration. Replace the values in <…> with your own.

The examples assume stdio mode (local agent) with credentials read from environment / .env. Streamable HTTP mode exposes the same tools but takes credentials through request headers instead.

Claude Desktop / Claude Code (`claude_desktop_config.json`)

{
  "mcpServers": {
    "homebox": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/homebox-mcp", "run", "main.py"],
      "env": {
        "HOMEBOX_BASE_URL": "https://your-homebox-instance.com",
        "HOMEBOX_USERNAME": "your_email@example.com",
        "HOMEBOX_PASSWORD": "your_password"
      }
    }
  }
}

Hermes (stdio)

Add to your Hermes MCP servers configuration:

{
  "homebox": {
    "command": "uv",
    "args": ["--directory", "/absolute/path/to/homebox-mcp", "run", "main.py"],
    "env": {
      "HOMEBOX_BASE_URL": "https://your-homebox-instance.com",
      "HOMEBOX_USERNAME": "your_email@example.com",
      "HOMEBOX_PASSWORD": "your_password"
    }
  }
}

OpenClaw (stdio)

{
  "servers": {
    "homebox": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/homebox-mcp", "run", "main.py"],
      "env": {
        "HOMEBOX_BASE_URL": "https://your-homebox-instance.com",
        "HOMEBOX_USERNAME": "your_email@example.com",
        "HOMEBOX_PASSWORD": "your_password"
      }
    }
  }
}

Remote / Streamable HTTP

If you run the server with uv run server_http.py (or via the Docker image), any MCP-compatible HTTP client can reach it at http://host:8000/mcp and pass credentials via request headers:

HOMEBOX_USERNAME: your_email@example.com
HOMEBOX_PASSWORD: your_password
X-Tenant: 00000000-0000-0000-0000-000000000000   # optional, multi-collection

HOMEBOX_BASE_URL is read only from the runtime environment of the server process; it cannot be overridden per request.

Finding the `X-Tenant` value

Open Homebox, log in, then in DevTools → Network find the request GET /api/v1/users/self and copy the X-Tenant request header. Pass it on every MCP request via the X-Tenant header.

Available tools

17 tools are exposed. Grouped parameter objects accept both snake_case and camelCase keys.

Products (entities)

`search_products`

Search products via Homebox query plus local filters. Provide at least one filter; name is split into per-term queries when no other strict filter is provided.

name (Optional[str]) — product name (or phrase) query
item_id (Optional[str]) — exact product UUID
asset_id (Optional[str]) — asset ID filter
serial_number (Optional[str])
model_number (Optional[str])
manufacturer (Optional[str])
query (Optional[str]) — generic full-text query

Returns: list of matching product dicts, or an error string.

`add_product`

Create a new product or subitem with grouped parameters. If both location and parent_item are provided, parent_item wins (subitem creation).

identity (dict, required): {"name", "description", "asset_id"}
location (Optional[dict]): {"id"} or {"name"} — for standalone products
parent_item (Optional[dict]): {"id"} or {"name"} — for subitems
identifiers (Optional[dict]): {"serial_number", "model_number", "manufacturer"}
purchase (Optional[dict]): {"price", "seller", "date", "warranty_expires"}
metadata (Optional[dict]): {"notes", "quantity", "tag_ids", "tag_names", "custom_fields"}
status (Optional[dict]): {"archived", "insured", "lifetime_warranty"}

Returns: created product dict (after optional update pass), or error string.

`update_product_by_id`

Update an existing product. Pass IDs (item_id, location.id) — names are only resolved through list_locations outside this tool.

item_id (str, required) — UUID of the item to update
identity (Optional[dict]): {"new_name", "description", "asset_id"}
location (Optional[dict]): {"id"} or {"name"}
identifiers (Optional[dict]): {"serial_number", "model_number", "manufacturer"}
purchase (Optional[dict]): {"price", "seller", "date", "warranty_expires"}
metadata (Optional[dict]): {"notes", "quantity", "tag_ids", "tag_names", "custom_fields"}
status (Optional[dict]): {"archived", "insured", "lifetime_warranty"}

Returns: updated product dict, or error string.

`add_bulk_products`

Add multiple products in one call. Each entry uses the grouped shape from add_product.

items (list[dict], required) — each item must contain an identity.name
Returns: list (one result per input item).

`delete_product_by_id`

Delete a single product by ID.

item_id (str, required) — UUID of the item
product_name (str, required) — used for the success/error message only

Returns: success message, or error string.

`delete_bulk_products`

Delete multiple products. Delegates to delete_product_by_id for each entry.

items (list[dict], required) — each entry {item_id, product_name}
Returns: list (one result message per input item).

Locations

`list_locations`

Return Homebox's location tree (GET /api/v1/entities/tree).

No parameters.
Returns: list of top-level tree nodes (each with nested children).

`create_location`

Create a new location (entity with isLocation implied by being parent-less).

name (str, required)
description (Optional[str])
parent_id (Optional[str]) — UUID of a parent location

Returns: created location dict, or error string.

`update_location_by_id`

Update a location's editable fields. Fetches the current state first to preserve omitted fields.

location_id (str, required) — UUID of the location
new_name (Optional[str])
new_description (Optional[str])
new_parent_id (Optional[str]) — pass empty string "" to detach from parent

Returns: updated location dict, or error string.

`delete_location_by_id`

Delete a single location.

location_id (str, required) — UUID of the location
Returns: success message, or error string.

`list_items_by_location`

List direct child items of a location (uses ?parentIds=…).

location_id (str, required) — UUID of the location
Returns: list of {"id", "name"} items, or error string.

Maintenance

`create_maintenance_entry_for_product`

Create a maintenance entry for an existing product. Provide scheduled_date, completed_date, or both; if neither, both default to today.

product_id (Optional[str]) — preferred if known
product_name (Optional[str]) — resolved to a product ID if product_id is missing
name (str, required) — title/summary of the task
description (Optional[str])
cost (Optional[float])
scheduled_date (Optional[str]) — YYYY-MM-DD
completed_date (Optional[str]) — YYYY-MM-DD

Returns: created maintenance entry dict, or error string.

`list_maintenance_entries`

List maintenance entries from Homebox. The global /api/v1/maintenance endpoint is broken on Homebox v0.26+; this tool falls back to enumerating per-entity maintenance lists and aggregating them.

product_id (Optional[str]) — restrict to entries for one product
product_name (Optional[str]) — used to resolve the entity when product_id is missing
Returns: list of maintenance entry dicts, or error string.

`update_maintenance_entry`

Update an existing maintenance entry. Homebox v0.26+ exposes maintenance only per-entity, so the owning product must be supplied.

entry_id (str, required) — UUID of the entry
product_id (Optional[str]) — UUID of the owning entity (preferred)
product_name (Optional[str]) — resolved to an entity when product_id is missing
name (Optional[str])
description (Optional[str])
cost (Optional[float])
scheduled_date (Optional[str]) — YYYY-MM-DD
completed_date (Optional[str]) — YYYY-MM-DD

Returns: updated maintenance entry dict, or error string.

`delete_maintenance_entry`

Delete a maintenance entry.

entry_id (str, required) — UUID of the entry
Returns: success message, or error string.

Testing

The project ships unit tests and end-to-end tests.

Unit tests (no Docker required)

just test
# or: uv run pytest tests/ -v -k "not e2e"

End-to-end tests (requires Docker)

The E2E suite spins up a pinned Homebox v0.26.2 container, builds the MCP server image, registers a test user, and exercises all 17 tools through the Streamable HTTP transport. Each tool's effect is then verified against the real Homebox API (not just the MCP response envelope).

just test-e2e

What it does:

docker compose -f docker-compose.e2e.yml up -d — start Homebox v0.26.2 on port 31745 and the MCP server on port 31746.
Wait for the Homebox healthcheck.
Register a test user (idempotent).
Run pytest tests/e2e/ -m e2e.
Tear down all containers.

See docker-compose.e2e.yml for the pinned image and tests/e2e/ for the suite. The suite covers every tool:

Category	Tools tested
Locations	`list_locations`, `create_location`, `update_location_by_id`, `list_items_by_location`, `delete_location_by_id`
Products	`search_products`, `add_product`, `update_product_by_id`, `add_bulk_products`, `delete_product_by_id`, `delete_bulk_products`
Tags	`list_tags`, `create_tag`
Maintenance	`create_maintenance_entry_for_product`, `list_maintenance_entries`, `update_maintenance_entry`, `delete_maintenance_entry`

Recommended workflow for adding items

Find a location for a standalone product — call list_locations to get a location UUID.
Find a parent for a subitem — call search_products(name=...) to resolve the parent item UUID.
Create or update — use add_product (new) or update_product_by_id (existing). If both location and parent_item are passed to add_product, parent_item is used and location is ignored for the creation target.

Justfile commands

just --list           # Show all commands
just start            # Start MCP server in stdio mode
just start-http       # Start MCP server in Streamable HTTP mode
just stop             # Stop running HTTP servers
just lint-format      # Run linting checks
just lint-fix         # Run linting and auto-fix issues
just test             # Run unit tests
just test-e2e         # Run E2E tests (requires Docker)
just wipe             # Clean cache/build artifacts
just docker-build     # Build Docker image
just docker-run       # Run Docker container

Repository layout

homebox-mcp/
├── main.py                          # FastMCP server, all 17 tools, helpers
├── models.py                        # Grouped dataclasses for tool inputs
├── server_http.py                   # Streamable HTTP transport entrypoint
├── request_config_middleware.py     # Per-request credential/tenant scoping
├── Dockerfile                       # HTTP server image
├── docker-compose.e2e.yml           # Pinned Homebox + MCP server stack
├── justfile                         # Dev/test commands
├── scripts/e2e-setup.sh             # Test user registration helper
├── tests/
│   ├── test_main.py                 # Unit tests (mocked HTTP)
│   ├── test_request_config_middleware.py
│   ├── test_transport_servers.py
│   └── e2e/                         # E2E tests against real Homebox v0.26.2
└── pyproject.toml

Available Tools

17 tools

add_bulk_productsD

ParametersJSON Schema

Name	Required	Description	Default
`items`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

D1/5.0

Behavior1/5

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

Tool has no description.

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

Conciseness1/5

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

Tool has no description.

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

Completeness1/5

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

Tool has no description.

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

Parameters1/5

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

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

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

Usage Guidelines1/5

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

Tool has no description.

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

add_productA

Add a new product (or subitem) to Homebox with grouped parameters.

    Args:
        identity: Required product identity {"name": str, "description": str, "asset_id": str}
        location: Optional location {"id": str} or {"name": str}
        parent_item: Optional parent item {"id": str} or {"name": str}.
            If provided, the new item is created as a subitem and parent_item
            takes precedence over location.
        identifiers: Optional manufacturing info {"serial_number", "model_number", "manufacturer"}
        purchase: Optional purchase details {"price": float, "seller": str, "date": str, "warranty_expires": str}
        metadata: Optional extra info {"notes": str, "quantity": int, "tag_ids": [str], "tag_names": [str], "custom_fields": [{}]}
        status: Optional flags {"archived": bool, "insured": bool, "lifetime_warranty": bool}

    Behavior:
        - Standalone product: provide a location (id or name).
        - Subitem product: provide parent_item (id or name).
        - If both parent_item and location are provided, parent_item wins.

ParametersJSON Schema

Name	Required	Description	Default
`status`	No
`identity`	Yes
`location`	No
`metadata`	No
`purchase`	No
`identifiers`	No
`parent_item`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.2/5.0

Behavior3/5

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

With no annotations, the description should fully disclose side effects. It explains the grouping and precedence well, but does not mention what happens on success or failure (e.g., return value, error conditions). This leaves some behavioral gaps.

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?

The description is well-structured with an Args list and Behavior section, front-loading the purpose. It is somewhat lengthy but every part adds value; minor redundancy could be trimmed.

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?

Given the complexity (7 params, nested objects) and lack of annotations, the description covers the core functionality and parameter semantics well. The presence of an output schema reduces the need to describe return values, but error handling is not addressed.

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 description coverage is 0%, yet the description provides detailed structured Args documentation for all 7 parameters, including expected keys and optionality. This fully compensates for the schema's lack of semantic detail.

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 description clearly states the action ('Add') and resource ('product or subitem' to Homebox). It distinguishes from the sibling 'add_bulk_products' by focusing on single product addition and explains standalone vs subitem scenarios.

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 behavior section explicitly explains when to use location vs parent_item, including the precedence rule. However, it does not explicitly mention alternatives like 'add_bulk_products' for batch operations or conditions to avoid using this tool.

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

create_locationD

ParametersJSON Schema

Name	Required	Description	Default
`name`	Yes
`parent_id`	No
`description`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

D1/5.0

Behavior1/5

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

Tool has no description.

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

Conciseness1/5

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

Tool has no description.

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

Completeness1/5

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

Tool has no description.

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

Parameters1/5

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

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

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

Usage Guidelines1/5

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

Tool has no description.

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

create_maintenance_entry_for_productA

Create a maintenance entry for a specific Homebox product/entity.

    Use this when the user wants to log servicing, repairs, inspections,
    scheduled maintenance, or maintenance cost for an item.

    If only a product name is known, provide `product_name` and this tool
    will resolve the product first, then create the maintenance entry.
    If the product ID is known, provide `product_id` directly for faster execution.

    At least one of `scheduled_date` or `completed_date` must be provided.
    If neither is provided, both default to today's date.

    Args:
        product_id: UUID of the product/entity (preferred if known).
        product_name: Name of the product to search for (used if product_id not provided).
        name: Title/summary of the maintenance task (required).
        description: Detailed description of the work performed or planned.
        cost: Cost of the maintenance in numeric format (e.g., 150.50).
        scheduled_date: Scheduled date for maintenance (ISO 8601: YYYY-MM-DD).
                          Defaults to today if neither date is provided.
        completed_date: Completion date for maintenance (ISO 8601: YYYY-MM-DD).
                          Defaults to today if neither date is provided.

    Returns:
        Created maintenance entry dict on success, or error string on failure.

ParametersJSON Schema

Name	Required	Description	Default
`cost`	No
`name`	No
`product_id`	No
`description`	No
`product_name`	No
`completed_date`	No
`scheduled_date`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.3/5.0

Behavior3/5

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

Annotations have all false hints, so the description carries the burden. It discloses the write operation (creating an entry) and default date behavior. However, it does not mention potential side effects like overwriting or state changes beyond creation.

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?

The description is well-structured with sections for use cases, parameter details, and return. It is somewhat lengthy but not overly verbose; every sentence contributes to clarity.

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?

Given the complexity (7 parameters, two-way product resolution, date logic), the description covers all essential aspects. It addresses input, defaults, and output format, making it complete for an agent to use correctly.

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?

With 0% schema coverage, the description provides detailed explanations for all 7 parameters, including the logic for resolving product by name vs ID, cost format, and date defaults. This adds significant value beyond the raw schema.

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 description clearly states it creates a maintenance entry for a Homebox product/entity, listing specific use cases like servicing and repairs. It distinguishes itself from sibling tools such as update_maintenance_entry and delete_maintenance_entry by focusing on creation.

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 description explains when to use the tool (logging servicing, repairs, etc.), how to provide product information (name or ID), and date requirements. It does not explicitly state when not to use it or suggest alternatives, but the context is clear.

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

create_tagA

Create a Homebox tag if it does not already exist.

ParametersJSON Schema

Name	Required	Description	Default
`name`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A3.5/5.0

Behavior3/5

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

Description reveals idempotent creation behavior ('if it does not already exist'), but lacks details on what happens on conflict, permissions, or return values. Without annotations, more context needed.

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?

One concise sentence front-loads action and condition. No redundant information.

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?

Simple tool with 1 param and output schema exists. Description covers core behavior but omits output details or error handling. Adequate for low complexity.

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

Parameters2/5

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

Single parameter 'name' is not elaborated beyond schema. With 0% schema coverage, description should add meaning (e.g., format, uniqueness, examples) but does not.

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?

Description clearly states verb (create), resource (Homebox tag), and condition (if not exists). Distinguishes from siblings like list_tags or create_location.

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

Usage Guidelines2/5

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

No guidance on when to use vs alternatives (e.g., list_tags for checking existing tags). No when-not-to-use or prerequisites mentioned.

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

delete_bulk_productsD

ParametersJSON Schema

Name	Required	Description	Default
`items`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

D1/5.0

Behavior1/5

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

Tool has no description.

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

Conciseness1/5

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

Tool has no description.

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

Completeness1/5

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

Tool has no description.

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

Parameters1/5

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

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

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

Usage Guidelines1/5

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

Tool has no description.

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

delete_location_by_idD

ParametersJSON Schema

Name	Required	Description	Default
`location_id`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

D1/5.0

Behavior1/5

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

Tool has no description.

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

Conciseness1/5

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

Tool has no description.

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

Completeness1/5

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

Tool has no description.

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

Parameters1/5

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

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

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

Usage Guidelines1/5

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

Tool has no description.

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

delete_maintenance_entryA

Destructive

Delete a maintenance entry from Homebox.

    Use this to remove maintenance records that are no longer needed.

    Args:
        entry_id: UUID of the maintenance entry to delete (required).

    Returns:
        Success message on success, or error string on failure.

ParametersJSON Schema

Name	Required	Description	Default
`entry_id`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.3/5.0

Behavior4/5

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

Annotations already indicate destructiveHint=true. The description adds the return format ('Success message on success, or error string on failure'), which provides behavioral context beyond what annotations offer.

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?

The description is concise and well-structured with a short explanation, args section, and returns section. It avoids unnecessary verbosity while covering all essentials.

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 simple delete tool with one required parameter, the description adequately covers purpose, usage, parameter meaning, and return type. The presence of an output schema reduces the need for further detail.

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?

With 0% schema description coverage, the description compensates by explaining that entry_id is a 'UUID of the maintenance entry to delete (required)', adding meaning beyond the schema's basic type and title.

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 description clearly states 'Delete a maintenance entry from Homebox' with a specific verb and resource. It distinguishes from sibling tools like create_maintenance_entry_for_product, update_maintenance_entry, and list_maintenance_entries.

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 description says 'Use this to remove maintenance records that are no longer needed', providing clear context. It doesn't explicitly list exclusions or alternatives, but the use case is straightforward.

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

delete_product_by_idD

ParametersJSON Schema

Name	Required	Description	Default
`item_id`	Yes
`product_name`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

D1/5.0

Behavior1/5

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

Tool has no description.

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

Conciseness1/5

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

Tool has no description.

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

Completeness1/5

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

Tool has no description.

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

Parameters1/5

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

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

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

Usage Guidelines1/5

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

Tool has no description.

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

list_items_by_locationD

ParametersJSON Schema

Name	Required	Description	Default
`location_id`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

D1/5.0

Behavior1/5

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

Tool has no description.

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

Conciseness1/5

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

Tool has no description.

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

Completeness1/5

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

Tool has no description.

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

Parameters1/5

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

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

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

Usage Guidelines1/5

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

Tool has no description.

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

list_locationsD

ParametersJSON Schema

Name	Required	Description	Default
No parameters

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

D1/5.0

Behavior1/5

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

Tool has no description.

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

Conciseness1/5

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

Tool has no description.

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

Completeness1/5

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

Tool has no description.

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

Parameters1/5

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

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

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

Usage Guidelines1/5

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

Tool has no description.

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

list_maintenance_entriesA

Read-onlyIdempotent

List maintenance entries from Homebox.

    If `product_id` (or `product_name`) is provided, returns entries for
    that product only. Otherwise aggregates maintenance entries across
    all non-location entities (the global `/api/v1/maintenance` endpoint
    is not available on Homebox v0.26+).

    Args:
        product_id: UUID of the product/entity. Preferred for speed.
        product_name: Name of the product to resolve when `product_id`
            is not provided.

    Returns:
        List of maintenance entries (each is a dict), or an error string.

ParametersJSON Schema

Name	Required	Description	Default
`product_id`	No
`product_name`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.4/5.0

Behavior4/5

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

Annotations already declare readOnlyHint and idempotentHint, so the description adds value by specifying return type (list of dicts or error string) and version-specific behavior. No contradictions.

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?

The description is well-structured with sections for general purpose, parameter behavior, and returns. It is appropriately sized, though slightly verbose; front-loaded with the main purpose.

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?

Given the presence of an output schema, the description adequately covers return format and error case. It addresses version limitations but could mention pagination or result limits if applicable.

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?

With 0% schema coverage, the description compensates fully by explaining product_id as UUID preferred for speed and product_name as resolution fallback. This adds essential meaning beyond the schema.

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 description clearly states 'List maintenance entries' and specifies the conditional behavior based on parameters. It distinguishes from sibling tools like create/delete/update by indicating this is a read operation.

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?

It explains when to use product_id vs product_name (preferred for speed) and notes the unavailability of the global endpoint on Homebox v0.26+. However, it does not explicitly state when not to use this tool or suggest alternative tools for other operations.

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

list_tagsA

List Homebox tags from the current /api/v1/tags endpoint.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A3.5/5.0

Behavior2/5

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

No annotations are provided, so the description bears full responsibility for behavioral disclosure. It only mentions the endpoint URL, not whether the operation is read-only, requires authentication, or any side effects.

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?

A single sentence that front-loads the purpose. No unnecessary words; every part contributes value.

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 simple listing with no parameters and an existing output schema, the description is adequate. It could mention that it returns a list of tags, but the output schema covers that.

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?

No parameters exist, so the schema coverage is 100%. The baseline for 0 parameters is 4, and there is no need for additional parameter information.

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?

Description clearly states 'List Homebox tags' with a specific verb and resource. It distinguishes from the sibling 'create_tag' by implying read-only listing, but does not explicitly call out the difference.

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?

Usage is implied: use when you need to view tags. No explicit guidance on when not to use or alternatives beyond the sibling name.

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

search_productsB

Search products using Homebox query + local filters.

    Provide at least one filter. `name` is split into terms and each term
    is queried in parallel when no other strict filter is provided.

ParametersJSON Schema

Name	Required	Description	Default
`name`	No
`query`	No
`item_id`	No
`asset_id`	No
`manufacturer`	No
`model_number`	No
`serial_number`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

B3.1/5.0

Behavior2/5

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

No annotations, so description carries full burden. Discloses that `name` is split and queried in parallel when no other strict filter, but fails to mention other behavioral traits like idempotency, pagination, or result limits.

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?

Two sentences, no redundancy. The summary statement front-loads the purpose, and the detail on `name` is efficient.

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?

Despite having an output schema, the description lacks explanation of 'Homebox query', filter combination logic, and prerequisites. With 7 parameters and no annotations, the description is incomplete.

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

Parameters2/5

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

Schema description coverage is 0%. Description mentions 'local filters' and explains `name` behavior, but does not elaborate on other six parameters, providing minimal added value over schema field 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?

Description clearly states 'Search products using Homebox query + local filters', indicating a specific verb (search) and resource (products). It distinguishes from siblings like list_items_by_location, though no explicit contrast.

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?

Explicitly states 'Provide at least one filter' and explains the behavior of the `name` parameter under certain conditions. Provides clear context but lacks alternative tool recommendations.

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

update_location_by_idD

ParametersJSON Schema

Name	Required	Description	Default
`new_name`	No
`location_id`	Yes
`new_parent_id`	No
`new_description`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

D1/5.0

Behavior1/5

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

Tool has no description.

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

Conciseness1/5

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

Tool has no description.

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

Completeness1/5

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

Tool has no description.

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

Parameters1/5

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

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

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

Usage Guidelines1/5

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

Tool has no description.

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

update_maintenance_entryA

Update an existing maintenance entry.

    Homebox v0.26+ only exposes maintenance entries per-product, so this
    tool requires either `product_id` (preferred) or `product_name` to
    locate the entry's owning entity before issuing the PUT.

    Args:
        entry_id: UUID of the maintenance entry to update (required).
        product_id: UUID of the product/entity owning the entry.
        product_name: Name of the product (used to resolve the entity
            when `product_id` is missing).
        name: New title for the maintenance task.
        description: New detailed description.
        cost: New cost value (numeric).
        scheduled_date: New scheduled date (ISO 8601: YYYY-MM-DD).
        completed_date: New completion date (ISO 8601: YYYY-MM-DD).

    Returns:
        Updated maintenance entry dict on success, or error string on failure.

ParametersJSON Schema

Name	Required	Description	Default
`cost`	No
`name`	No
`entry_id`	Yes
`product_id`	No
`description`	No
`product_name`	No
`completed_date`	No
`scheduled_date`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.5/5.0

Behavior4/5

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

Annotations set destructiveHint=false and idempotentHint=false, and the description adds that this is an update operation using PUT, requires product ownership info, and returns a dict or error. This adds useful behavioral context beyond the annotations without contradiction.

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?

The description is structured with an Args section and a Returns line, front-loading the purpose. However, it is somewhat lengthy, repeating parameter names, which could be more concise.

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?

Given the tool's complexity (8 parameters, entity resolution logic), the description covers all needed details: required fields, optional fields with formats, the two-step update process, and return type. With an output schema present, the description is complete enough for an agent to invoke correctly.

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?

The input schema has 0% coverage, so the description provides all parameter semantics. It explains the purpose of product_id/product_name for entity resolution, gives format hints for dates (ISO 8601), and describes the cost field. This adds significant meaning missing from the schema.

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 description starts with 'Update an existing maintenance entry,' providing a clear verb and resource. It is distinct from sibling tools like 'create_maintenance_entry_for_product' and 'delete_maintenance_entry', making its purpose unambiguous.

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 description explains the need for product_id or product_name to locate the entry due to API constraints, but does not explicitly state when not to use this tool or directly reference alternatives. The context is clear, but explicit exclusions are missing.

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

update_product_by_idA

Update an existing product with grouped parameters.

    Args:
        item_id: UUID of the item to update (required)
        identity: Optional identity updates {"new_name": str, "description": str, "asset_id": str}
        location: Optional location change {"id": str} or {"name": str}
        identifiers: Optional manufacturing updates {"serial_number", "model_number", "manufacturer"}
        purchase: Optional purchase updates {"price": float, "seller": str, "date": str, "warranty_expires": str}
        metadata: Optional metadata updates {"notes": str, "quantity": int, "tag_ids": [str], "tag_names": [str], "custom_fields": [{}]}
        status: Optional flag updates {"archived": bool, "insured": bool, "lifetime_warranty": bool}

ParametersJSON Schema

Name	Required	Description	Default
`status`	No
`item_id`	Yes
`identity`	No
`location`	No
`metadata`	No
`purchase`	No
`identifiers`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A3.9/5.0

Behavior3/5

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

No annotations are provided, so the description carries full burden. It explains parameter groups but does not disclose side effects, permission requirements, or behavior on missing products. It is moderately transparent.

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?

The description is well-structured using a docstring format with clear 'Args' listing. It is fairly concise, though could be slightly shorter by avoiding repetition of 'Optional' in every bullet.

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?

Given the presence of an output schema (not detailed here), the description adequately covers the input parameters. It is sufficient for the tool's complexity, though it could mention potential errors or prerequisites.

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?

With 0% schema description coverage, the description adds significant meaning by detailing each parameter group (e.g., identity, location). It compensates for the schema's lack of descriptions, though some details could be more explicit.

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 description clearly states the purpose: 'Update an existing product with grouped parameters.' It uses a specific verb ('update') and resource ('product'), and distinguishes from sibling tools like 'add_product' and 'delete_product_by_id'.

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 does not provide explicit guidance on when to use this tool versus alternatives. It implicitly suggests it's for updating existing products, but lacks conditions or exclusions.

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

17 tool updatesv0.2.0Jun 28, 2026
- First observedadd_bulk_products
- First observedadd_product
- First observedcreate_location
- First observedcreate_maintenance_entry_for_product
- First observedcreate_tag
- First observeddelete_bulk_products
- First observeddelete_location_by_id
- First observeddelete_maintenance_entry
- First observeddelete_product_by_id
- First observedlist_items_by_location
- First observedlist_locations
- First observedlist_maintenance_entries
- First observedlist_tags
- First observedsearch_products
- First observedupdate_location_by_id
- First observedupdate_maintenance_entry
- First observedupdate_product_by_id

Install Server

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

C2.3/5.0

Disambiguation3/5

Most tools target distinct entities (products, locations, maintenance, tags), but 'add_bulk_products' and 'add_product' could be confused without description. Several tools lack descriptions, reducing clarity.

Naming Consistency2/5

Names mix patterns: 'add_product', 'create_location', 'create_maintenance_entry_for_product', 'delete_bulk_products', 'list_items_by_location'. Inconsistent verb styles and lengths.

Tool Count4/5

17 tools is reasonable for an inventory server covering products, locations, maintenance, and tags. Slightly on the higher end but still well-scoped.

Completeness3/5

CRUD for main entities is present, but missing explicit get-by-ID tools for products and locations. Many tools have no descriptions, creating dead ends for agents.

Maintenance

ActivityStale

ResponsivenessUnresponsive

Resources

GitHub Repository

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

mcp-serverOAuth
com.niftypm
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Project Management Communication File Systems
2
Anagent A
io.github.jaytahir
A registry of AI agent tools — MCP servers, APIs, CLIs, SDKs — kept current by automated ingestion.
Agent Orchestration Developer Tools
21
ZapierOAuth
com.zapier
Hosted MCP server connecting AI assistants to 9,000+ apps and 40,000+ actions via Zapier.
App Automation Workplace & Productivity
2297
anotherai
dev.anotherai
MCP server for building and testing AI agents with multi-model experimentation and insights.
Agent Orchestration Autonomous Agents Testing & QA Tools
2

Related MCP Servers

Homebox MCP Server
Home Automation & IoT Search
oangelo
A
license
Not graded
quality
D
maintenance
MCP server for managing Homebox inventory via AI assistants, enabling item management, location organization, and label categorization.
Updated 7 months ago (2026-02-02 10:41 UTC)
4
MIT
inventree-mcp-plugin
ERP Systems Search
eljefedelrodeodeljefe
A
license
Not graded
quality
C
maintenance
MCP server plugin for InvenTree, enabling AI assistants to interact with inventory data such as parts, stock, locations, orders, and BOMs.
Updated 6 months ago (2026-02-26 22:11 UTC)
5
MIT
mcp-homelab
Virtualization Networking & Infrastructure Shell Access
asvarnon
A
license
Not graded
quality
D
maintenance
An MCP server that gives AI assistants real-time access to your homelab infrastructure. It enables querying node status, managing Docker containers, controlling Proxmox VMs, and inspecting OPNsense firewall state through natural conversation.
Updated 3 months ago (2026-06-02 04:37 UTC)
2
MIT
homebox-mcp
App Automation
dgahagan
A
license
A
quality
B
maintenance
MCP server for Homebox home inventory, enabling natural language queries and management of items, locations, tags, warranties, maintenance, and attachments.
Updated 2 months ago (2026-07-06 02:21 UTC)
39
4
MIT

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/Tafeen/homebox-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server

Homebox MCP Server

What it does

Installation

Requirements

Install the server

Docker

Run the server

Install inside an agent

Claude Desktop / Claude Code (claude_desktop_config.json)

Hermes (stdio)

OpenClaw (stdio)

Remote / Streamable HTTP

Finding the X-Tenant value

Available tools

Products (entities)

search_products

add_product

update_product_by_id

add_bulk_products

delete_product_by_id

delete_bulk_products

Locations

list_locations

create_location

update_location_by_id

delete_location_by_id

list_items_by_location

Tags

list_tags

create_tag

Maintenance

create_maintenance_entry_for_product

list_maintenance_entries

update_maintenance_entry

delete_maintenance_entry

Testing

Unit tests (no Docker required)

End-to-end tests (requires Docker)

Recommended workflow for adding items

Justfile commands

Repository layout

Available Tools

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Tool Schema Changelog

Maintenance

Resources

Looking for Admin?

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API

Claude Desktop / Claude Code (`claude_desktop_config.json`)

Finding the `X-Tenant` value

`search_products`

`add_product`

`update_product_by_id`

`add_bulk_products`

`delete_product_by_id`

`delete_bulk_products`

`list_locations`

`create_location`

`update_location_by_id`

`delete_location_by_id`

`list_items_by_location`

`list_tags`

`create_tag`

`create_maintenance_entry_for_product`

`list_maintenance_entries`

`update_maintenance_entry`

`delete_maintenance_entry`