homebox-mcp

Server Quality Checklist

Profile completionA complete profile improves this server's visibility in search results.

Latest release: v0.1.0
Disambiguation4/5
Most tools have clearly distinct purposes (e.g., create_location vs. create_item vs. create_tag via set_tag), but a few are easy to confuse: set_tag vs. set_tags (one edits tag metadata, the other applies tags to an item) and set_item vs. the more specialized setters (set_fields, set_identity, set_warranty) require careful reading. The descriptions help resolve ambiguity, so the overlap is manageable.
Naming Consistency3/5
The majority follow a verb_noun pattern (create_location, delete_item, list_attachments, etc.), but there are notable exceptions: warranties_expiring is noun-first, qrcode and field_index are single nouns, and barcode_lookup and inventory_stats are noun-noun. The set_tag/set_tags pair is a naming pitfall, though consistent in their respective scopes.
Tool Count2/5
At 39 tools, this is well above the 25+ threshold that feels heavy. While the domain is broad (items, locations, tags, attachments, warranties, maintenance, import/export, labels, barcodes, stats), many tools could be consolidated (e.g., a single attachments management tool instead of five separate ones, or a single maintenance tool with action subcommands).
Completeness5/5
The tool set covers the full lifecycle for core entities: items (create, read, update, delete, duplicate, move, sell), locations (create, read, update, delete), tags (create, edit, delete, assign), attachments (attach, list, get, rename, delete), and maintenance (log, list, update, delete). It also includes search, bulk import/export, warranty tracking, labels/QR codes, barcode lookup, and inventory statistics—no obvious dead ends.
Average 4.5/5 across 39 of 39 tools scored. Lowest: 3.8/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 15 commits in the last 12 weeks
- Last stable release on July 6, 2026
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.

To manually sync the server, click the "Sync Server" button in the MCP server admin interface.

How is the quality score calculated?

The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).

Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.

Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).

Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.

Tool Scores

Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavior. It explains the save_to parameter's semantics (directory vs full path) and that it retains a name based on title. However, it doesn't mention overwrite behavior, return value, or error handling, leaving some gaps.
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?
The description is concise and well-structured, with the action stated up front and additional detail about save_to in a second sentence. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple download tool, the description covers the essential purpose and save_to behavior. But the missing identifier semantics and lack of output/return details mean it's not fully complete, especially without annotations or an output schema.
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 coverage is 0%, so the description must explain all parameters. It adequately explains save_to and hints that attachment_id comes from list_attachments, but identifier is completely unexplained, making its meaning ambiguous.
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 tool's action: "Download one attachment" to a local path. It specifies the resource (attachment) and references list_attachments for IDs, distinguishing it from sibling tools like attach_document or delete_attachment.
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 the intended use: downloading an attachment so its content can be read, and instructs the agent to see list_attachments for IDs. This provides clear context, though it doesn't explicitly exclude alternatives or mention when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It states the tool 'adds' an entry (a write operation), returns the new entry's id, and specifies date format and cost type. This goes well beyond a tautological description, though it stops short of discussing permissions, failure modes, or reversibility.
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?
The description is two sentences, front-loaded with the action and resource, followed by key constraints and return value. Every sentence earns its place with no filler or redundant schema repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 6 parameters, no annotations, no output schema, and no schema-level descriptions. The description covers the core purpose, date semantics, and return value, but lacks clarity on the identifier/name combination and does not fully explain all parameters. It is minimally viable but leaves gaps for correct invocation.
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 0%, so the description must compensate. It explains date format, cost as a number, and gives helpful examples for completed_date and scheduled_date. However, the parenthetical '(assetId / alias field / exact name)' is ambiguous about how identifier and name relate, and the description parameter is not explained at all.
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 uses a specific verb ('Add') and resource ('maintenance-log entry to an item'), with concrete examples showing maintenance actions. It clearly distinguishes from siblings like list_maintenance, set_maintenance, and delete_maintenance by framing this as a create/log operation.
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 implies when to use the tool (to add a maintenance log) and gives examples for completed vs. scheduled dates, but it does not explicitly mention alternatives or when not to use it. It lacks direct guidance such as 'use set_maintenance to update' or 'use list_maintenance to view'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the idempotentHint annotation, the description explicitly discloses that it uses a 'partial PATCH' and that nothing else on the item changes. This adds meaningful behavioral context that is not captured by the annotation alone.
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?
The description is compact, with the main purpose in the first sentence and supplementary details in a second sentence. It is front-loaded and every sentence earns its place without unnecessary filler.
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 tool's simplicity (two required string parameters, no output schema) and the presence of an idempotent annotation, the description adequately covers the key behavior, parameters, and location-path guidance. It does not explain return values or error cases, but these are not critical for a straightforward move operation.
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 tool description compensates well by explaining the 'location' parameter format (location name or /-separated path) and the 'identifier' parameter accepted formats (assetId / alias field / exact name). This adds meaning beyond the bare 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?
The description states a specific verb and resource: 'Move an item to another location', and lists possible identifier types (assetId / alias field / exact name). However, it does not explicitly distinguish from the sibling tool 'set_location', which may serve a similar purpose.
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 implies usage when an item needs to be relocated and gives a pointer to 'list_locations' for location paths, but it does not explicitly describe when to prefer this tool over alternatives like 'set_location' or 'set_item'. No exclusions or alternative scenarios are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations include readOnlyHint=true, and the description aligns by calling out the underlying GET endpoint. The description adds useful context about the return fields and the 'thin wrapper' nature, but does not disclose error handling, rate limits, or edge-case behavior. With annotations covering the read-only aspect, this is sufficient but not exceptional.
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?
The description is a single, dense sentence that front-loads the core purpose ('Look up a UPC/EAN barcode') and packs in the output fields and endpoint reference without waste. Every phrase earns its place.
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 tool's simplicity (1 parameter, no output schema), the description covers the essentials: input format, expected output, and the specific endpoint. It does not explain behavior on invalid/missing barcodes or elaborate on the 'optional path for boxed goods', but these are minor gaps for a thin wrapper lookup.
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?
The schema provides no description for the required 'code' parameter (0% coverage), but the description compensates by specifying 'UPC/EAN barcode', clarifying that the code is a barcode format. This adds meaning beyond the generic parameter name. However, it doesn't detail allowed formats, validation, or optional path handling for boxed goods.
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 tool's function: 'Look up a UPC/EAN barcode → name/manufacturer/model'. It names a specific resource (UPC/EAN barcode), a verb (look up), and the expected output fields. This distinguishes it from sibling tools like search_items or get_item, as it's specifically barcode-based lookup.
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 context is implied by the tool's name and description: use it when you have a UPC/EAN barcode to resolve. However, it does not explicitly contrast with alternatives (e.g., search_items, get_item) or provide when-not-to-use criteria. No exclusions or alternative tool recommendations are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true, and the description's 'Return' is consistent with a read-only operation. It adds useful context about the response format ('indented outline' and 'full tree'), but does not disclose potential limits like pagination or depth constraints, which would go beyond the annotation.
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?
The description is a single, front-loaded sentence with no wasted words. It conveys the action, resource, and output format efficiently.
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 simple zero-parameter read-only tool, the description fully covers what the agent needs to know: the tool returns the entire location tree as an indented outline. The presence of an output schema covers specifics of the return structure.
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?
The tool takes zero parameters and the input schema is empty, so there is no parameter information needing explanation. Per the calibration baseline, a no-parameter tool receives a score of 4.
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 uses a specific verb ('Return') with a clear resource ('full location tree') and format ('indented outline'). This clearly distinguishes it from sibling tools like location_contents, which likely focus on a single location's contents.
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 no explicit when-to-use or when-not-to-use guidance, nor does it mention alternatives. However, the purpose is clear enough that an agent can infer it is for retrieving the entire location hierarchy, so usage is implied rather than absent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses the partial update behavior in detail: 'Only the args you pass change; the rest of the entry is re-sent as-is (the update is a full PUT).' This adds significant value beyond the idempotentHint annotation, explaining how the update works and why it is idempotent. It does not contradict annotations.
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?
The description is two sentences, front-loaded with the purpose, and every clause earns its place. The parenthetical pointer to list_maintenance and the full PUT explanation are both essential and compact.
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 moderate-complexity tool with 6 parameters and no output schema, the description covers the key elements: purpose, id acquisition, an example, and update semantics. It does not enumerate every parameter, but the schema provides names and types, and the description gives enough context to use the tool effectively.
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%, so the description must compensate, but it only mentions completed_date as an example. It does not explain the meaning of the other parameters (cost, name, description, scheduled_date) or how null vs omitted values are handled. The general 'Only the args you pass change' rule helps, but it does not fully clarify the semantics for six parameters.
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 uses the specific verb 'Edit' with the resource 'maintenance entry', clearly distinguishing it from sibling tools like log_maintenance, list_maintenance, and delete_maintenance. The example of marking a scheduled entry completed by setting completed_date further clarifies the intended use.
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 provides clear guidance on where to get entry ids ('see list_maintenance for ids') and gives a concrete example use case. While it does not explicitly name alternatives or exclusions, the word 'Edit' and the sibling context make when-to-use implicit and reasonably clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the transparency burden. It discloses the field type coercion behavior (JSON type determines custom field type), the requirement that location/tags must pre-exist, and that the call returns assetId and id. It does not cover failure behavior or atomicity, but the core side effects are clearly described.
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?
The description is concise and front-loaded, with the main purpose in the first sentence and supporting details in separate lines. Every sentence adds value; no fluff.
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 13 parameters, no annotations, and no output schema, the description covers the essential enrichment behavior and return value. It lacks some edge-case details (e.g., how duplicate names are handled), but overall is adequate for an agent to invoke the tool 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 description coverage is 0%, so the description must compensate. It explains the semantics of location (name or path), tags (must exist), and fields (type mapping), which are the least obvious parameters. However, the other 10 parameters (quantity, dates, etc.) have no additional explanation beyond their schema titles, leaving some ambiguity.
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 states 'Create an inventory item' – a specific verb and resource – and adds 'enrich it in one call' indicating it can also set location, tags, and custom fields at creation. This clearly distinguishes it from sibling update tools like set_item or set_tags.
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 provides explicit prerequisites: location must exist (use list_locations) and tags must already exist (use list_tags). This gives clear guidance for using the tool successfully, but does not explicitly discuss when to prefer this over the separate set_* tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of disclosing behavior. It states that the tool 'Returns the new location id' and describes the format of `parent` and constraints on `description` (≤1000 chars). However, it does not mention potential failure modes (e.g., duplicate names, invalid parent) or any side effects, leaving some gaps for a create operation.
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?
The description is efficient and well-structured: three sentences front-load the purpose, then address parameters, return value, and an alternative tool. Every sentence adds value, with no redundant filler or repetition of schema fields.
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 low complexity (3 parameters, no output schema) and the presence of sibling tools, the description provides sufficient information to invoke the tool correctly. It covers the return value, parameter formats, and an alternative for deep paths. Minor omissions like error handling or uniqueness constraints do not significantly hinder usability for a simple creation tool.
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?
The schema has no parameter descriptions (0% coverage), so the description adds essential meaning. It explains `parent` as 'an existing location name or /-separated path (optional)' and `description` as 'optional free text, e.g. a contents summary (≤1000 chars).' The `name` parameter is not explicitly described beyond the entity context, but the description still covers most parameter semantics effectively.
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 tool's function: 'Create a LOCATION entity (e.g. a new tote/bin/shelf) to bootstrap a new storage spot.' This uses a specific verb ('Create') and a clear resource ('LOCATION entity'), with concrete examples. It also distinguishes itself from siblings like delete_location and set_location by emphasizing creation of a new storage spot.
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 provides explicit use context: 'bootstrap a new storage spot.' It also gives a clear alternative: 'For deep paths, prefer import_csv's HB.location auto-create.' While it doesn't enumerate when-not-to-use scenarios, the conditional alternative provides strong guidance for choosing between tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With annotations already declaring readOnlyHint=true, the description adds extra behavioral context: the AND semantics when both query and tags are given, and the exact return fields (immediate location, assetId, alias custom field if configured). This goes beyond the annotation without contradicting it, though it doesn't cover pagination or limit behavior.
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?
The description is two sentences: the first states purpose and filtering logic, the second states return fields and points to an alternative. Every sentence earns its place with no fluff or repetition of schema fields.
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?
The tool has an output schema, so return values don't need explaining in the description. The description covers the core search behavior, return field highlights, and the main alternative. It doesn't explain the limit parameter's effect, but for a simple search tool with a default value, the description is otherwise complete.
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?
The schema has 0% description coverage, so the description must carry the burden for parameter meaning. It explains query and tags semantics, including the AND logic, but it does not mention the 'limit' parameter at all. This partial coverage of 2 out of 3 parameters is helpful but not fully compensating for the lack of schema descriptions.
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 opens with 'Search inventory items by name/keyword and/or by tag names', which names a specific verb ('search'), a specific resource ('inventory items'), and the search criteria. It also distinguishes itself from get_item by noting 'Use get_item for full detail on one result', making the tool's scope clear.
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 provides clear context on when to use this tool: when searching by name/keyword or tags. It explicitly points to get_item as an alternative for full detail, and clarifies that it returns items, not locations. However, it doesn't mention when not to use it or other alternatives like barcode_lookup, so it stops short of full exclusion guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral disclosure burden. It discloses key traits: URLs are 'downloaded then uploaded', identifier tries item match first then location fallback, and primary=True replaces the entity's primary image. It does not mention return format, errors, or permissions, but the most decision-relevant behaviors are covered.
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?
The description is compact, front-loaded with the core action, and each sentence adds value. It uses backticks for parameters and a concrete primary-image example, with no filler or repetition.
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 moderate complexity (two target types, URL download, identifier fallback, primary behavior) and no output schema, this description is largely complete. It lacks details like supported file types or failure behavior, but those are secondary; an agent has enough information to select and invoke the tool correctly.
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 0%, but the description directly explains source, doc_type, identifier, and primary with examples and fallback logic. The title parameter is not explained, though its meaning is likely self-evident. Overall, the prose compensates well for the absence of schema descriptions.
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 opens with 'Attach a document to an item OR a location', a specific verb+resource pair that clearly defines the action. It also distinguishes this from sibling attachment tools by naming the two possible targets and mentioning attach-specific concepts like primary image and doc_type.
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 gives concrete usage context: what source can be (local path or URL), what doc_type values look like, how identifier resolves against items or locations, and when primary=True is useful (wayfinding photos). It lacks explicit 'use this instead of X' exclusions, but the context is clear enough for an agent to know when to invoke this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the description is not required to repeat safety. It adds useful context about the identifier's accepted forms and the purpose of the returned ids. However, it does not disclose potential error conditions, pagination, or ordering behaviors, which the annotation does not cover.
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?
The description is two concise sentences with zero filler. It front-loads the core purpose, then adds the key parameter detail and cross-references to related tools, all in an efficient manner.
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 simple list tool with an output schema (not shown) and readOnly annotation, the description covers the essential inputs, outputs, and usage context. It explains what the returned ids are for and how to specify the target item/location, making it self-sufficient for the agent.
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 provides only a bare string 'identifier' with no description. The description compensates fully by explaining that identifier can be an assetId, alias field, name, or a location name/path, giving complete semantic 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 the tool's function: 'List an item's (or location's) attachments with their ids'. It specifies the resource (attachments) and the verb (list), and distinguishes itself from sibling tools by noting these ids are the handle for get_attachment/rename_attachment/delete_attachment.
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 provides clear context for when to use the tool: to obtain attachment ids needed for subsequent attachment operations. It names the related tools but does not explicitly state when not to use it or contrast with alternatives like attach_document; however, the integration with sibling tools is explicit and helpful.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses partial-update behavior ('Only the args you pass change; the rest is re-sent as-is'), which is valuable beyond the idempotentHint annotation. It also enumerates allowed type values. There is no contradiction with annotations.
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?
The description is two focused sentences with no wasted words. The first sentence states purpose and enumerates fields, the second clarifies update semantics. It is front-loaded and information-dense.
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?
Despite having no output schema, the description covers the core purpose, allowed values, partial-update semantics, and where to find IDs. It does not explain return values or potential side effects (e.g., setting primary), but it is adequate for typical use.
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 title, doc_type (including allowed values), and primary. It also directs users to list_attachments for identifier/attachment_id. However, the precise distinction between `identifier` and `attachment_id` is left implicit.
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 identifies the verb ('Update') and the resource ('attachment'), and specifies the exact mutable fields: title, type, and primary flag. This distinguishes it from related siblings like delete_attachment, get_attachment, and list_attachments.
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 gives clear context for when to use this tool: when modifying an existing attachment's metadata. It also provides a helpful pointer to list_attachments for obtaining IDs. However, it does not explicitly contrast with alternatives like attach_document or delete_attachment, so it stops short of full when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes well beyond the idempotentHint annotation by disclosing merge/remove/replace semantics, case-insensitive tag matching, auto-creation of tags, and partial PATCH behavior. This is rich, actionable behavioral context with no contradiction to annotations.
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?
Four sentences, purpose first, with no wasted words. Each sentence adds critical behavioral or parameter detail, making it efficient and well-structured.
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?
Despite no output schema, the description covers all key aspects needed for correct invocation: modes, matching behavior, auto-creation, and side-effect scope (partial PATCH). It is complete for the tool's complexity and annotation coverage.
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 description coverage, the description fully compensates by explaining the 'mode' enum values, the meaning of 'identifier' (assetId / alias / exact name), and how 'tags' are matched and auto-created. This is essential meaning not available from the schema alone.
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?
The description clearly specifies the action (add/remove/replace) and resource (tags on an existing item), along with identifier forms. However, it does not explicitly distinguish this from the sibling tool 'set_tag', so it narrowly misses the top score.
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 explains the three modes and default behavior, and references list_tags for case-insensitive matching, implying when the tool is useful. However, it does not explicitly state when to prefer this tool over alternatives like set_tag, or provide exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds behavioral context beyond the destructiveHint annotation by emphasizing 'PERMANENTLY' and the confirmation requirement. This discloses the irreversibility and safety mechanism.
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?
The description is a single concise sentence with a key note, front-loaded with the action and no wasted words.
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 simple delete operation with three required parameters, the description covers purpose, prerequisites, and confirmation requirements. The absence of an output schema is acceptable as delete operations typically return minimal results.
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 explains the confirm parameter explicitly and hints at attachment_id/identifier via the list_attachments reference and 'from an item or location' context.
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 tool's purpose: 'PERMANENTLY delete one attachment from an item or location'. It uses a specific verb and resource, and distinguishes from sibling tools like rename_attachment and get_attachment.
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 provides usage guidance by referencing list_attachments to obtain IDs and requiring exact title confirmation. It doesn't explicitly mention exclusions or 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the idempotentHint annotation, the description reveals that the tool ensures primary images and generates missing thumbnails, and that it wraps two actions executed as a pair. This gives meaningful insight into the mutation behavior without contradicting the annotation.
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?
The description is two sentences, front-loaded with the action and purpose, and every clause adds value. It is concise without sacrificing 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?
For a zero-parameter tool with no output schema, the description fully explains what the tool does, when to use it, and its internal behavior. It is complete and leaves no significant gaps.
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 zero parameters, the schema provides full coverage and there is nothing for the description to add. The baseline of 4 is appropriate as there's no parameter information that could be missing.
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 tool's function with a specific verb ('finalize') and resource ('photos'), and explains it runs post-bulk-attach to ensure primary images and thumbnails. It distinguishes itself as a finalization step and references the wrapped actions, 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?
It provides clear context: 'Finalize after a bulk photo attach' indicates when to use it. It also explains that it wraps two actions that are always run as a pair, implying it's the right choice when both need to occur together, though it doesn't explicitly list alternatives or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of disclosing side effects. It states that the tool saves a PNG to 'out_dir', defaults to an environment variable or current directory, resolves identifiers differently based on 'kind', and returns the saved file path. This goes well beyond a bare action statement, though it does not mention file overwrite behavior or error conditions.
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 sentences efficiently front-load the purpose, then cover parameters and behavior. Every clause adds value: what is produced, where it is saved, how identifiers are interpreted, and the return value. No filler or redundant content.
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?
The description is largely complete for a 3-parameter tool with no output schema: it explains parameter semantics, defaults, and return value. It lacks explicit notes on file naming, overwriting, or error handling, but these are not essential for correct invocation.
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%, so the description is the only source of parameter meaning. It thoroughly explains 'kind' with its enum values, 'identifier' semantics per kind ('name or slug' vs 'assetId'), and 'out_dir' default behavior. This fully compensates for the missing schema descriptions.
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 a specific verb and resource: 'Save a printable Homebox label PNG (QR + readable name)' for a location or item, including a concrete use case ('stick on a tote/bin'). It clearly distinguishes this from the sibling tool 'qrcode' by describing both QR and readable name, and it specifies the supported kinds.
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 provides clear context for when to use the tool: generating printable labels for locations, items, or assets. It does not explicitly name alternatives or state when not to use it, but the use case and identifier resolution guidance make the intended usage clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds context beyond the readOnlyHint annotation by noting the tool is efficient ('cheap') and does not scan items, which suggests a precomputed or optimized behavior. It also discloses the types of returned data (counts, values, time series), though it does not detail response structure or potential limitations.
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?
The description is front-loaded with a clear summary and uses a logical bulleted list for the `by` modes. Every sentence contributes necessary detail; no redundant or filler content is present, and the structure makes scanning easy.
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 no output schema, the description adequately describes the return categories (counts, total value per location/tag, value over time) and parameter usage. It does not specify the exact response shape, but for a statistics tool this level of detail is sufficient, especially with the readOnlyHint annotation.
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 zero schema description coverage, the description fully compensates by explaining each `by` enum value and clarifying that start/end are optional date parameters in YYYY-MM-DD format for the purchase-price mode. This provides essential meaning beyond the bare property names.
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 provides inventory statistics for determining inventory worth, with a specific verb and resource. It distinguishes itself from siblings by focusing on aggregated value and counts rather than item-level operations, and the breakdown of `by` modes further clarifies its purpose.
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 explicitly positions this as the 'cheap way' to answer valuation questions without scanning items, implying use for aggregate analytics rather than item searches. The enumerated `by` modes provide concrete scenarios (totals, locations, tags, purchase-price), but it does not explicitly name alternative tools for item-level queries or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare idempotentHint=true. The description adds valuable behavioral detail: only passed args are set (partial update), clear=True erases all sold fields, and other fields are preserved. This goes beyond the annotation and clarifies side effects, though it does not cover error cases.
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?
The description is concise, with three focused sentences. It is front-loaded with the action, then organizes details logically, and contains no filler or 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?
The description covers core behavior, parameter semantics, and integration with an archival tool, which is sufficient for an agent to select and invoke it. It lacks explicit mention of error handling or return values, but given the idempotency annotation and clear parameter semantics, it is reasonably complete.
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%, but the description compensates by explaining the identifier forms (assetId/alias/exact name), the sold fields (price, buyer, date, notes), the YYYY-MM-DD date format, and the clear parameter. It effectively maps to all six parameters and adds critical semantics about partial updates.
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 tool records an item as sold using an identifier, and lists the updatable fields (price, buyer, date, notes). It also distinguishes itself from siblings by referencing set_item for archiving, making its specific purpose evident.
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 provides explicit pairing guidance with set_item(archived=True) when the item should leave active inventory, and explains when to use clear=True. However, it does not explicitly state when not to use this tool versus alternatives like set_fields, though the specialized purpose is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, and the description adds behavioral context beyond that: identifier null means inventory-wide query, and status values map to scheduled/completed/both. No contradiction.
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 succinct sentences, front-loaded with verb/object, parameter names in backticks, and no filler. Every sentence adds necessary scope or filter context.
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 simple two-parameter read tool with an output schema and readOnlyHint, the description covers selection scope, identifier formats, and status semantics. No critical gaps remain.
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 has zero parameter descriptions, so the description carries full burden. It explains identifier accepts assetId/alias/name or null for all, and status meanings for scheduled/completed/both, covering both parameters.
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 opens with 'List maintenance entries', naming the exact resource and adding scope (one item vs whole inventory). It clearly distinguishes from maintenance mutation tools (log/set/delete_maintenance) and other list tools.
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?
States when to use with an identifier for one item or without for the whole inventory, and explains status filtering options. It doesn't explicitly name alternatives, but the context is clear and no exclusions are needed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
While the readOnlyHint annotation already flags this as a safe read operation, the description adds valuable behavioral context by explaining that default returns only names, while setting detail=True returns full tag objects. This goes beyond the annotation by detailing the tool's behavior in different modes.
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?
The description is two sentences, front-loaded with the primary purpose, and contains no wasted words. It efficiently communicates the core function and the optional detail behavior.
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 tool with a single optional parameter and no output schema, the description is complete. It explains what is returned by default, what detail=True provides, and suggests how to proceed with editing. No critical information is missing.
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 only shows a boolean 'detail' with no meaning, but the description fully explains that setting it to True returns full tag objects. This is significant added meaning beyond the schema, especially since schema description coverage is 0%.
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 tool lists all tag (label) names, using a specific verb and resource. It also distinguishes itself from related tools by explicitly mentioning pairing with set_tag for editing, making its purpose distinct among siblings.
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 provides context for when to use the tool ('for auditing tag setup') and suggests a complementary action (pair with set_tag to edit). It does not explicitly list when not to use it, but the guidance is clear enough for an agent to select it appropriately.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses important behavioral details: it returns direct items plus sub-location names only, recursive mode walks the whole subtree and tags items with full location paths, and location can be a name or /-separated path. This adds meaningful context beyond the readOnlyHint annotation.
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?
The description is efficiently structured: four sentences, each contributing unique information. It front-loads the purpose, then explains return behavior, recursive usage, and location path syntax without redundancy.
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?
The description covers core functionality and recursive behavior well, but since there is no output schema, it only partially details the return format (e.g., what fields of items are returned). The `max_items` parameter behavior is also underexplained, leaving minor gaps.
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 explains the `location` parameter (name or /-separated path) and the `recursive` flag (with usage example), but it does not mention the `max_items` parameter at all, leaving a gap in parameter understanding.
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 tool's function: 'List what is in a location' with concrete examples (tote or shelf). It distinguishes recursive vs non-recursive behavior and differentiates from siblings like list_locations by focusing on contents rather than the list of locations.
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 gives explicit guidance on when to use recursive mode ('use this when a location has sub-locations you also want the contents of, to avoid querying each one by hand'), but does not explicitly mention alternative tools or when not to use the tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses critical behavioral nuance: 'Only the args you pass change; other fields are preserved.' This explains the partial-update semantics, which is not obvious from the schema alone. The idempotentHint annotation is complemented, not contradicted, and the description adds value beyond the structured annotation.
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?
The description is two sentences with no redundancy. The first sentence front-loads the purpose and scope, and the second adds usage context and behavioral detail. Every sentence contributes meaningful 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?
Given the tool's moderate complexity and no output schema, the description covers the main aspects: purpose, identifier types, partial-update behavior, and a typical use case. It does not address edge cases like passing null explicitly to clear a field or what happens if the item is not found, but these are not essential for basic usage.
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 description coverage is 0%, but the description compensates by naming the key fields (manufacturer, model, serial) and clarifying the identifier parameter with its accepted forms. It also explains the update semantics for omitted vs. passed parameters, which aids parameter understanding. However, it does not provide detailed individual parameter descriptions (e.g., formats or constraints), so it doesn't fully cover all semantics.
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 tool's function: 'Set manufacturer/model/serial on an existing item.' It also specifies the identifier types (assetId / alias field / exact name), which makes the action and target unambiguous. This distinguishes it from sibling tools like set_location or set_warranty.
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 provides a clear use case: 'Use when a nameplate/label photo reveals a serial number or a model-number correction after the item was created.' It does not explicitly mention alternatives, but the context effectively implies when this tool is appropriate relative to other set_* tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The idempotentHint annotation is complemented by the description's note that only passed arguments change and other fields are preserved, which is an important partial-update behavior. It also clarifies the date format for expires. No contradiction with the annotation.
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?
The description is compact and front-loaded with the main action. Parameter details are presented in clear, separate lines with no redundant words. Every sentence earns its place.
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 simple update tool, the description covers all necessary context: target item identifier, field meanings, and partial-update behavior. No output schema exists, but return value is not critical for a setter. The level of detail is sufficient.
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%, so the description carries the full burden. It explains all four parameters: identifier forms, expires format (YYYY-MM-DD), lifetime as a boolean flag, and details as a summary string. This fully compensates for the schema's lack of descriptions.
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 opens with 'Set warranty info on an existing item', a specific verb+resource. It also clarifies the identifier formats (assetId / alias field / exact name), which distinguishes it from generic setters like set_fields.
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 clearly implies use when warranty fields need updating, with specific field semantics. It does not explicitly contrast with sibling tools like set_fields or state when not to use, but the context is unmistakable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations only provide destructiveHint: true. The description adds critical behavioral details: 'PERMANENTLY', 'There is no undo', 'including its attachments', and the need for a confirming input equal to the item's exact name. This goes well beyond the annotation and warns about cascade effects and irreversibility.
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?
The description is a single concise sentence that front-loads the action and consequence. Every phrase adds value: the permanence, the scope (attachments), the confirm requirement, and the absence of undo. No filler words.
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 destructive nature, no output schema, and only two parameters, the description covers the essential information: what is deleted, the caveat about attachments, the confirmation requirement, and irreversibility. There is no need for return-value details. It is complete for an agent to safely invoke this tool.
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 `identifier` can be an assetId, alias field, or exact name, and that `confirm` must equal the item's exact name. This adds meaningful context not present in the schema, though it leaves some ambiguity about how the identifier is interpreted.
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 'PERMANENTLY delete an item' which is a specific verb and resource. It clearly distinguishes this tool from sibling delete tools for locations, tags, and attachments by noting 'including its attachments'. This makes the tool's scope 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 implies when to use this tool by stating it deletes an item and its attachments, effectively covering the use case for deleting an entire item. It does not explicitly name alternatives, but the context from sibling tools makes it clear. The confirm requirement is a useful invocation condition.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds significant behavioral detail beyond the destructiveHint annotation: it emphasizes the action is permanent, clarifies that exactly one entry is deleted, and reveals the confirmation safeguard ('confirm must equal the entry's exact name'). This provides the agent with critical safety context beyond what the annotation alone conveys.
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?
The description is exceptionally concise: two sentences with no unnecessary words. The key information is front-loaded ('PERMANENTLY delete'), and every clause earns its place by adding critical details about the deletion process.
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 simplicity (2 parameters, no output schema, destructive), the description covers all essential aspects: the action, the permanence, the prerequisite for finding ids, and the confirmation constraint. It is complete for the agent to select and invoke the tool correctly.
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 the confirm parameter's exact semantics (must match the entry's name) and directing users to list_maintenance for entry_id values. The entry_id parameter's purpose is implied by its name and the reference to list_maintenance, but a bit more detail on its format would improve clarity.
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 ('PERMANENTLY delete') and the resource ('one maintenance entry'), which is specific and unambiguous. It also distinguishes itself from siblings like set_maintenance or log_maintenance by noting that list_maintenance provides the ids, reinforcing its role as the deletion tool.
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 provides explicit context by instructing users to see list_maintenance for ids, establishing a prerequisite for use. It also specifies the confirm requirement, which is a clear conditional for invoking the tool. While it doesn't explicitly mention alternatives, the name and sibling list make it obvious that this is for deleting maintenance entries specifically.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the destructiveHint annotation, the description explains the permanent nature, that the tag is removed from every tagged item, and that items survive. It also discloses the confirmation mechanism, adding valuable behavioral context beyond the annotation.
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?
The description is compact and front-loaded with 'PERMANENTLY delete', immediately conveying severity. Every word adds value, covering side effects and the confirmation requirement in one sentence.
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 simple destructive tool with two parameters, the description covers the action, scope ('removed from every tagged item'), survival of items, and the confirm requirement. No output schema is needed, and the description is sufficient 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.
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 'confirm' must equal the tag's exact name, which clarifies its purpose. The 'name' parameter is implicitly the tag's name from context. The description adequately explains the critical confirm parameter, but 'name' is left to inference.
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 'PERMANENTLY delete a tag itself' with a specific resource (tag). It distinguishes from deleting tagged items by noting 'the items survive', which differentiates it from sibling delete tools like delete_item.
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 implies when to use this tool by clarifying it deletes the tag entity, not the associated items. It also provides a usage requirement (confirm must equal the tag's exact name). However, it does not explicitly name alternative tools or state when not to use it, though the contrast with delete_item is implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full weight and delivers: it discloses auto-creation of location hierarchies, the requirement that tags already exist, location-only row behavior, the need to call finalize_photos after upload, and the return value. This is robust behavioral disclosure for an import tool.
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 longer than average but every sentence carries essential information. It is front-loaded with a clear purpose, then structured into pipeline context, column list, special cases, and follow-up instructions. The density is justified by the tool's complexity, though it could be slightly tighter.
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 one parameter, no output schema, and high complexity (many columns, auto-creation behavior), the description addresses all key aspects: input format, required preconditions (tags), side effects (location creation), post-import steps, and return type. It leaves little ambiguous for an agent.
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 schema provides only a single parameter (csv_text) with zero description coverage. The description completely compensates by enumerating all recognized columns (HB.name, HB.location, etc.), explaining location path semantics, and specifying constraints like tag existence. It turns an opaque text blob into a well-defined input format.
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 opens with a specific verb+resource: 'Bulk-create items and locations from a Homebox CSV'. This clearly distinguishes it from sibling tools like create_item and create_location, and the 'bulk creator' phrasing reinforces its unique role in the photo-intake pipeline.
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 identifies the tool as the 'bulk creator for the photo-intake pipeline' and notes it 'avoids ~4 API calls per item', implying use for multi-item imports. It also references associated tools (list_tags for tag validation, finalize_photos after import) but does not explicitly state when to use single-item alternatives like create_item.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, covering safety. The description adds meaningful behavioral detail: the two modes, the cap at `limit`, and the return shape ({"total", "values"}) for field mode. It omits edge cases like pagination or error responses, but for a read-only list tool this is sufficient context beyond annotations.
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 sentences, front-loaded with the core purpose, and no extraneous text. Every clause adds value: the two modes, the cap, and the use-case hint are all essential and efficient.
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 tool with 2 optional params and no output schema, the description covers the main return shapes (names list, and values object with total/values). It also gives usage context via sibling references. The only gap is the exact return format for the no-arg mode, but that is minor given the simple nature of the output.
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 coverage is 0%, and the description fully compensates by explaining both parameters: `field` toggles between listing names and values, and `limit` caps the result count. It adds semantics beyond the bare schema types and defaults, making parameter behavior unambiguous.
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 tool's purpose: discovering custom-field schema, with two modes (no arg vs field) and a specific verb 'Discover'. It distinguishes from siblings by explicitly mentioning set_fields/field_index as related tools, making its role in the workflow clear.
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?
The description explicitly says 'Useful before set_fields/field_index on an unfamiliar instance', providing direct usage guidance. It also explains when to use each mode: no arg for all field names, with field for distinct values, which helps the agent decide.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the idempotentHint annotation, the description discloses important behavioral traits: partial updates preserve unspecified fields, parent moves the location, clear_parent moves to root, entity_type conversion is rare, and asset_id overrides auto-assignment. These details give the agent a deeper understanding of side effects and edge cases, going well beyond what annotations alone provide.
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?
The description is a compact, well-organized paragraph that front-loads the main purpose and then details each behavior. Every sentence adds valuable information, and there is no redundancy or filler. It manages to cover many nuances without becoming overly long.
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 complex mutation tool with 11 parameters and no output schema, the description is remarkably complete. It explains the core behavior, partial updates, parent handling, rare conversion, and asset_id override. The only minor omission is the tags_mode parameter and return value, but the overall description fully equips an agent to use the tool correctly.
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 the purpose of most parameters: location, new_name, description, notes, tags, fields, parent, clear_parent, entity_type, and asset_id. However, it omits the critical 'tags_mode' parameter (add/remove/replace), which is not self-evident. This gap prevents a perfect score.
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 begins with 'Edit a LOCATION's metadata', clearly identifying the action and resource. It lists specific editable fields and distinguishes itself from create/delete/list operations on locations. The scope is explicit with 'Only the args you pass 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 description provides clear context on when to use: for editing existing location metadata, with details on finding the location by name or path and partial updates. However, it does not explicitly mention alternatives or when not to use, though the purpose is distinct from sibling tools like create_location or set_fields.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Even though annotations already mark destructiveHint=true, the description adds crucial behavioral detail: 'PERMANENTLY', 'There is no undo', that sub-locations are deleted recursively, and that child items are ORPHANED to the top level rather than deleted. This goes well beyond the annotation and fully discloses 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?
The description is three tight sentences: the first states the action, the second explains the confirm requirement, and the third covers non-empty behavior and irreversibility. Every sentence adds necessary information with no fluff or repetition.
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 destructive tool with no output schema, the description covers all important contextual aspects: preconditions (confirm must match), failure modes (non-empty refusal), side effects (sub-locations deleted, items orphaned), and irreversibility (no undo). This is sufficient for an agent to safely invoke the tool.
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%, so the description carries the full burden. It explains location as a name or path, confirm as the location's exact name, and confirm_nonempty as the flag that permits deleting non-empty locations and orphans items. This fully compensates for the missing parameter descriptions in 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 opens with 'PERMANENTLY delete a location', giving a specific verb, resource, and permanence qualifier. It also notes the location can be a name or /-separated path, and the sibling list (delete_item, delete_tag, delete_attachment, etc.) makes the resource distinction clear.
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?
Clear usage context is provided: it explains when deletion is refused (non-empty location without confirm_nonempty=True) and what confirm must satisfy. It does not explicitly name alternatives like delete_item, but the resource-specific scope and conditions are clear enough for an agent to decide when to invoke it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden for behavioral disclosure. It covers defaults for copying custom fields/attachments/maintenance, the prefix behavior, a non-obvious alias-field caveat, and return values (id and assetId). This is rich, useful context beyond the schema.
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?
The description is front-loaded with the main action, then efficiently details defaults, caveats, and return values. Each sentence earns its place with no fluff or repetition of schema field names.
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 5 parameters, no annotations, and no output schema, the description provides all essential context: default behavior, the alias pitfall, how to correct it, and what the tool returns. It is complete for an agent to select and invoke the tool 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?
Schema description coverage is 0%, so the description must explain all params. It explains 'identifier' (assetId / alias / exact name), 'prefix' (prepended to name), and the three boolean copy flags with their defaults. Every parameter's semantics are effectively described.
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 opens with a specific verb-resource pair ('Duplicate an existing item') and clarifies the identifier forms (assetId / alias field / exact name), immediately distinguishing it from sibling tools like create_item or set_item. The example use case ('I bought a second one') further reinforces the intended purpose.
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 gives a clear use case via the example and explains when to use the tool (duplicating an item with copy behavior). It does not explicitly name alternatives or exclusion conditions, but with no annotations and a clear context, the guidance is sufficient for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It discloses the save location (file path or directory), the default filename (homebox-export.csv in the current directory), and the return value (path and row count). However, it does not specify overwrite behavior or how a directory value for save_to is handled (e.g., whether the default filename is used inside the directory), which leaves minor ambiguity.
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?
The description is two sentences, front-loaded with the primary purpose, and includes necessary details without redundancy. Every clause adds value: the complement/backup context, the parameter explanation, and the return value.
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 tool with one optional parameter and no output schema, the description is complete: it explains what is exported, how to specify the output location, what the default is, and what is returned. It also addresses the tool's relationship to import_csv. No critical missing information prevents an agent from invoking it 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?
Schema description coverage is 0%, so the description must compensate. It fully explains the only parameter, save_to: it is a file path or directory, with a default value of homebox-export.csv in the current directory. This adds crucial semantic meaning beyond the bare schema, making the parameter's behavior clear.
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 tool exports the whole inventory as a Homebox CSV (verb+resource+output). It distinguishes itself from siblings by explicitly noting it is the complement of import_csv, making its role unambiguous.
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?
The description provides explicit context on when to use the tool: it is the complement of import_csv and serves as a quick backup. This gives clear usage guidance and implicitly excludes partial-export use cases, as it handles the whole inventory.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds significant behavioral context beyond the readOnlyHint annotation: it explains the fuzzy fallback ('first keyword match') and enumerates the included fields (location path, serial, model, purchase, warranty, custom fields, tags, attachments). This helps the agent understand matching behavior and return contents.
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?
The description is two sentences, front-loaded with the core purpose, followed by identification details and return fields. Every word earns its place; no redundancy or fluff.
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 simple one-parameter schema, readOnlyHint annotation, and no output schema, the description is remarkably complete. It covers identification methods, matching behavior, and return contents, leaving no major gaps for the 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 schema provides only a parameter name 'identifier' with zero description coverage. The description compensates fully by explaining that it can be an assetId (with example), alias custom field, or name with fuzzy fallback. This is essential semantic value 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 the tool's function: 'Get full detail for one item' with specific identifier methods (assetId, alias, name). It distinguishes itself from sibling tools like search_items by focusing on a single item's full detail, making the 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 implies when to use this tool: when full detail for one item is needed, identified by assetId, alias, or name. It does not explicitly mention alternatives or exclusions, but the context of a single-item getter is clear. Sibling tools like search_items are implicitly alternatives for discovery, though not named.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes beyond the idempotentHint annotation by explaining field type mapping (string->text, number->number with integer coercion, boolean) and warning about float values causing API 500s. It also clarifies that untouched fields are preserved, providing valuable behavioral context.
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?
The description is concise, with the purpose stated in the first sentence and implementation details in the second. Every sentence carries useful information without redundancy.
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 two-parameter tool, the description covers the key behaviors: create/update, type selection, coercion caveat, and preservation of existing fields. The output is not described, but given the absence of an output schema and the nature of a mutation tool, the description is sufficiently complete.
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 no descriptions (0% coverage), so the description fully compensates by explaining the `fields` object mapping and the `identifier` parameter's accepted forms ('assetId / alias field / exact name'). This adds critical meaning 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 'Create or update custom fields on an existing item' with a specific verb and resource. It identifies the tool's scope (custom fields) and the target (existing item), distinguishing it from sibling tools like set_tags or set_item.
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 implies usage for updating custom fields via upsert semantics, but it does not explicitly name alternative tools or state when not to use this tool. Clear context is given, but no exclusions or alternatives are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only provide readOnlyHint=true. The description adds substantial behavioral detail: inclusive date range (after <= warrantyExpires <= before), default of after=TODAY, exclusion of expired warranties unless overridden, and lifetime=True ignoring before/after. This goes well beyond the annotation.
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?
Front-loaded with the main purpose. Two paragraphs, every sentence adds value (semantics, defaults, use case). No filler or redundancy.
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?
Output schema exists, so return values are already defined. The description fully explains the tool's core complexity: date window inclusivity, default behavior, and lifetime mode. No missing critical context for a read-only list operation.
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 has 0% description coverage, so the description carries full responsibility. It explains each parameter with ISO date format, boundary comparisons, defaults, and the lifetime flag's behavior, fully compensating for the schema gap.
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 states 'List items whose warranty expires in a date window, or items with a lifetime warranty.' This is a specific verb+resource+scope that clearly distinguishes it from siblings like search_items or get_item, which are more general.
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?
Provides clear context on the date window and lifetime flag, including defaults and ignored parameters. It gives a concrete use case ('which warranties expire this year') but does not explicitly name alternatives or when not to use, so slightly below a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The only annotation is idempotentHint. The description goes far beyond that by disclosing partial-update semantics ('Only the args you pass are changed'), the quantity-only PATCH vs full-body PUT distinction, the '0.26 PUT-clears gotcha', and how custom-field values are typed. This is rich, behavior-relevant context.
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 sentences: purpose, behavior, and sibling pointers. Each sentence earns its place, front-loaded with the primary capability and no filler.
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 11 parameters, no schema descriptions, and no output schema, this description covers purpose, identifier forms, update behavior, custom-field mapping, and sibling tools. The only minor gaps (date format, currency units) are easily inferable and do not hamper correct usage.
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 description coverage is 0%, so the description must compensate. It does clarify identifier resolution (assetId/alias/exact name) and the `fields` map semantics. However, it stops short of detailing formats for purchase_date/purchase_price, leaving some parameters to be inferred purely from their names.
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 opens with 'General item editor' and lists concrete capabilities (rename, edit description/notes/quantity, purchase info, insured/archived flags, custom fields). It also identifies the identifier forms (assetId / alias / exact name) and differentiates from sibling tools by referencing move_item and set_warranty/set_identity/set_tags.
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?
Explicitly states which sibling tool to use for other concerns ('To move an item use move_item; for warranty/identity/tags see set_warranty/set_identity/set_tags'). Also explains when PATCH vs PUT is used, giving clear context for behavior.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the idempotentHint annotation, the description discloses key behaviors: 'Only the args you pass are changed' (partial update semantics), how parent nesting works, and how clear_parent un-nests. This adds substantial context that the annotation alone does not cover, and there is no contradiction.
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?
The description is five sentences, each earning its place. It front-loads the core purpose, then adds critical caveats and usage context without fluff or repetition of schema details.
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 7-parameter tool with no output schema and minimal annotations, this description covers purpose, sibling differentiation, partial update semantics, the create-or-edit behavior, parent nesting, and a recommended preread step. It is complete enough for an agent to select and invoke the tool correctly.
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 carries the burden of explaining parameters. It explicitly explains name matching, parent, and clear_parent, and the 'Only the args you pass are changed' sentence clarifies the update semantics for all optional parameters. However, it does not individually describe icon, color, description, or new_name, even though their purpose is implied.
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 opens with 'Create or edit a tag's own metadata' — a specific verb+resource pair. It explicitly distinguishes itself from the sibling set_tags ('NOT what's tagged on an item'), making the purpose unambiguous and well-differentiated.
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?
The description gives clear when-to-use guidance: it explains the case-insensitive matching against list_tags, the create-if-missing behavior, and points to set_tags as the alternative for item tagging. It also advises using list_tags(detail=True) first, providing a concrete workflow.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes beyond the readOnlyHint annotation by disclosing that the tool scans every entity (performance implication), returns empty assetId for un-asset'd rows, is deliberately uncapped to prevent duplicates, and may return a large result on large inventories. This is rich behavioral context that annotations alone do not provide.
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?
The description is concise yet information-dense. Every sentence serves a purpose: defining output, use case, parameter default, edge case, and size rationale. No wasted words.
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?
Despite being a simple tool, the description covers the return structure, use case, performance caveats, edge cases (empty assetId), and result size expectations. This is fully adequate for an AI agent to safely invoke the tool.
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 description coverage, the description fully compensates by explaining the 'field_name' parameter: it is a custom field name and defaults to $HOMEBOX_ALIAS_FIELD. This adds meaning beyond the bare schema fields.
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 opens with a specific action and resource: 'Return {field_value: assetId} for every entity that has the named custom field'. It clearly defines the tool's purpose as building a custom-field index for deduplication before bulk import, distinguishing it from sibling tools like search_items.
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?
Explicitly states when to use the tool: 'for DEDUPE before a bulk import'. Also explains why it is necessary: 'q does not index custom fields, so this scans every entity'. This gives clear context for choosing this tool over alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that the tool saves a JPEG file, states the output directory default behavior ($HOMEBOX_LABEL_DIR or current directory), and mentions the return value (saved file path). This provides a clear picture of side effects and expected behavior beyond what the schema offers.
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?
The description is three concise sentences, front-loaded with the main purpose. Every sentence adds value—purpose, alternative guidance, and output details—without redundancy or fluff.
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 tool with only 2 parameters and no output schema, the description is complete. It covers the file format, output location, return value, and an important alternative tool. No critical information is missing for the agent to make an informed selection and invocation.
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 coverage is 0%, but the description compensates by explaining both parameters: `data` is described as arbitrary (e.g., a deep link), and `out_dir` is explained with its default resolution logic. This adds significant meaning beyond the raw schema definitions, making the tool easy to invoke correctly.
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 tool's purpose: 'Save a raw QR-code JPEG encoding arbitrary data'. It specifies the action (save), the output format (JPEG), and the content (arbitrary data), and differentiates from the sibling tool generate_label by noting that generate_label adds a readable name for tote labels.
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?
The description provides explicit usage guidance: 'For tote labels prefer generate_label (adds the readable name)'. This tells the agent when not to use this tool and suggests a specific alternative. The phrase 'arbitrary data' implies a general-purpose use case, effectively covering when to use qrcode.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

GitHub Badge

Glama performs regular codebase and documentation scans to:

Confirm that the MCP server is working as expected.
Confirm that there are no obvious security issues.
Evaluate tool definition quality.

Our badge communicates server capabilities, safety, and installation instructions.

Card Badge

Copy to your README.md:

[![homebox-mcp MCP server](https://glama.ai/mcp/servers/dgahagan/homebox-mcp/badges/card.svg)](https://glama.ai/mcp/servers/dgahagan/homebox-mcp)

Score Badge

Copy to your README.md:

[![homebox-mcp MCP server](https://glama.ai/mcp/servers/dgahagan/homebox-mcp/badges/score.svg)](https://glama.ai/mcp/servers/dgahagan/homebox-mcp)

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/dgahagan/homebox-mcp'

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