Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@inventree-mcp list all parts in category Electronics"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
MCP server for InvenTree inventory management. Provides 12 parameterized tools covering 117 operations for parts, stock, build orders, purchase/sales/return orders, companies, barcodes, labels, reports, attachments, and system administration.
Python 3.11+
uv (recommended) or pip
An InvenTree instance with API access enabled
An API token (generate from InvenTree > Settings > API Tokens)
Related MCP server: MCP Inflow Ingredients
# Clone the repository
git clone https://github.com/puran-water/inventree-mcp.git
cd inventree-mcp
# Copy the example environment file and fill in your values
cp .env.example .env
# Install dependencies
uv syncEdit .env with your InvenTree instance URL and API token:
INVENTREE_URL=https://your-inventree-instance.example.com
INVENTREE_TOKEN=your-api-token-hereuv run python server.pyuv run python server.py sse --port 3074Add to your MCP client config (e.g. ~/.claude/mcp.json):
{
"mcpServers": {
"inventree-mcp": {
"command": "uv",
"args": ["run", "--directory", "/path/to/inventree-mcp", "python", "server.py"],
"env": {
"INVENTREE_URL": "https://your-inventree-instance.example.com",
"INVENTREE_TOKEN": "your-api-token-here"
}
}
}
}Or for SSE transport:
{
"mcpServers": {
"inventree-mcp": {
"url": "http://localhost:3074/sse"
}
}
}Each tool uses a parameterized operation field to select the specific action.
Tool | Operations | Description |
| 21 | Part & category management (list, get, create, update, delete, BOM, suppliers, parameters) |
| 16 | Stock item & location management (list, get, create, transfer, count, add, remove) |
| 9 | Manufacturing build orders (list, get, create, update, allocate, complete, cancel) |
| 12 | Purchase order lifecycle (list, get, create, update, issue, receive, complete) |
| 14 | Sales order lifecycle (list, get, create, shipments, allocations) |
| 8 | Return order management |
| 12 | Suppliers, manufacturers, customers, contacts, addresses |
| 4 | Barcode scan, assign, unassign, lookup |
| 5 | Label template listing and printing |
| 3 | Report template listing and generation |
| 5 | File attachments on any object (upload, download, delete) |
| 8 | Health, version, settings, users, groups, currencies |
server.py — FastMCP server with 12 parameterized tools and dual transport (STDIO/SSE)
client.py — Async adapter wrapping the official inventree-python library via asyncio.to_thread() with a semaphore for concurrency control
The inventree-python library is synchronous (requests-based). All calls are offloaded to threads to maintain async compatibility with the MCP framework.
MIT
File attachment management for any InvenTree object.
Operations: Read: list, download Write: upload, upload_link Delete: delete
Args: operation: One of the operations listed above. model_type: Object type (part, stockitem, build, purchaseorder, salesorder, company). model_id: Object ID for list/upload/upload_link. attachment_id: Attachment ID for download/delete. file_path: Local file path for upload. link: URL for upload_link. comment: Optional comment for uploads. destination: File path to save downloaded attachment to.
Returns: JSON string with attachment data or {"error": "..."}.
| Name | Required | Description | Default |
|---|---|---|---|
| operation | Yes | ||
| model_type | No | ||
| model_id | No | ||
| attachment_id | No | ||
| file_path | No | ||
| link | No | ||
| comment | No | ||
| destination | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true and readOnlyHint=false. The description adds operation breakdown (list, download, upload, delete) and notes return values, but does not detail behavioral aspects like consequences of deletion, authentication requirements, or error handling beyond a simple error string.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with headings and bullet points, but is slightly verbose. It efficiently communicates the tool's purpose and parameters without excessive fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (8 parameters, output schema exists), the description covers operations, parameters, and return values. It lacks detail on delete behavior or file persistence, but overall provides sufficient information for an agent to use the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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 each parameter's purpose (e.g., operation, model_type, model_id, attachment_id, file_path, link, comment, destination), adding significant meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'File attachment management for any InvenTree object' and lists specific operations (read, write, delete), distinguishing it from sibling tools that manage other object types like part, stock, etc.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description lists operations and their purposes but does not explicitly state when to use this tool versus alternatives or provide usage exclusions. It implicitly covers usage context but lacks comparative guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Barcode scanning and assignment in InvenTree.
Operations: Read: scan, lookup Write: assign, unassign
Args: operation: One of the operations listed above. barcode_data: Barcode string for scan/assign/lookup. model_type: Model type for assign/unassign (part, stockitem, stocklocation, build, purchaseorder, salesorder, returnorder). pk: Object ID for assign/unassign.
Returns: JSON string with barcode result or {"error": "..."}.
| Name | Required | Description | Default |
|---|---|---|---|
| operation | Yes | ||
| barcode_data | No | ||
| model_type | No | ||
| pk | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (which indicate read/write but not details), the description discloses that the tool supports both read and write operations, lists the specific operations, and describes the return format (JSON string with result or error). This adds 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is structured with a one-line summary, a bulleted list of operations, and a clear args section. It is appropriately sized with no extraneous text, though it could be slightly more succinct by integrating the operation list inline.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (4 parameters, 1 required) and the presence of an output schema, the description covers the operation types, all parameters, and the return format. It provides sufficient context for an agent to understand and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage on parameters. The description compensates fully by explaining each parameter: operation as 'one of the operations listed above', barcode_data as 'Barcode string for scan/assign/lookup', model_type as the specific model types for assign/unassign, and pk as 'Object ID for assign/unassign'. This adds essential meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Barcode scanning and assignment in InvenTree' and enumerates specific operations (read: scan, lookup; write: assign, unassign). This provides a specific verb and resource, distinguishing it from sibling tools like 'part' or 'stock' which handle other domains.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for barcode operations but does not explicitly guide when to use this tool versus alternatives. No exclusion criteria or comparative guidance is given, relying on the agent to infer context from the tool name and domain.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Manufacturing build order management in InvenTree.
Operations: Read: list, get, get_outputs, get_lines Write: create, update, allocate, complete, cancel
Args: operation: One of the operations listed above. pk: Build order ID. data: Dict of fields for create/update/complete. items: List of allocation dicts for allocate (e.g. [{"stock_item": 1, "quantity": 5, "build_line": 3}]). search: Text search filter for list. limit: Max results (default 25). offset: Pagination offset.
Returns: JSON string with build order data or {"error": "..."}.
| Name | Required | Description | Default |
|---|---|---|---|
| operation | Yes | ||
| pk | No | ||
| data | No | ||
| items | No | ||
| search | No | ||
| limit | No | ||
| offset | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses the supported operations (read/write) and the meaning of arguments like pk, data, items, etc. It explains the return format (JSON string). Annotations indicate readOnlyHint=false and destructiveHint=false, and the description does not contradict them; it adds context about mutation operations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is structured with sections (Operations, Args, Returns) and is front-loaded with the purpose. While it is moderately long, every sentence adds value without being overly verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (7 parameters, nested objects, multiple operations) and that an output schema is implied but not provided, the description covers basic functionality. However, it lacks details on the exact structure of returned data for each operation and potential error conditions beyond a generic error string.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema coverage, the description compensates by explaining each parameter: operation (list of values), pk (build order ID), data (dict for create/update/complete), items (list of allocation dicts with example), search (text filter), limit (default 25), offset (pagination). This adds significant meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it is for 'Manufacturing build order management in InvenTree' and lists specific read and write operations. It distinguishes itself from sibling tools by focusing on build orders, which are separate from parts, stock, purchase orders, etc.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide explicit guidance on when to use this tool versus alternative tools. While it lists the operations it supports, there is no comparison or recommendation relative to sibling tools like 'part' or 'stock'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Supplier, manufacturer, and customer management in InvenTree.
Operations: Read: list, get, list_supplier_parts, get_supplier_part, list_manufacturer_parts, get_manufacturer_part, list_contacts, list_addresses, get_price_breaks Write: create, update Delete: delete
Args: operation: One of the operations listed above. pk: Company, supplier part, or manufacturer part ID. data: Dict of fields for create/update. company_id: Company ID for list_supplier_parts/list_manufacturer_parts/list_contacts/list_addresses. supplier_part_id: Supplier part ID for get_price_breaks. search: Text search filter for list/list_supplier_parts/list_manufacturer_parts. is_supplier/is_manufacturer/is_customer: Boolean filters for list. limit: Max results (default 25). offset: Pagination offset.
Returns: JSON string with company data or {"error": "..."}.
| Name | Required | Description | Default |
|---|---|---|---|
| operation | Yes | ||
| pk | No | ||
| data | No | ||
| company_id | No | ||
| supplier_part_id | No | ||
| search | No | ||
| is_supplier | No | ||
| is_manufacturer | No | ||
| is_customer | No | ||
| limit | No | ||
| offset | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate destructiveHint=true and readOnlyHint=false, and the description confirms by listing delete and write operations. The description adds operational details (e.g., return format) but does not elaborate on side effects beyond what annotations already imply.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with sections (overview, operations, args, returns) and is concise, with no unnecessary words. It front-loads the purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (11 parameters, multiple operations, output schema present), the description covers all essential aspects: operations, parameters, return format, and error handling. No gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description explains each parameter's purpose (e.g., 'pk: Company, supplier part, or manufacturer part ID') and usage, fully compensating for the missing schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it manages suppliers, manufacturers, and customers in InvenTree, with specific operations listed (read, write, delete). This differentiates it from sibling tools like 'part' or 'stock' which handle different domains.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description defines the tool's scope comprehensibly but does not explicitly state when to avoid using it or suggest alternative tools. The context from sibling tools implies distinct purposes, but explicit guidance is missing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Label printing and template management in InvenTree.
Operations: list_templates, print_part, print_stock, print_location, download_template
Args: operation: One of the operations listed above. label_type: Filter for list_templates (part, stock, location). template_id: Label template ID for print/download operations. item_ids: List of item IDs to print labels for. destination: File path to save downloaded template to.
Returns: JSON string with label templates or print result.
| Name | Required | Description | Default |
|---|---|---|---|
| operation | Yes | ||
| label_type | No | part | |
| template_id | No | ||
| item_ids | No | ||
| destination | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false, openWorldHint=true, destructiveHint=false, but the description does not elaborate on side effects, idempotency, or retry safety. It only mentions 'printing' without clarifying if it triggers external actions (e.g., printer).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with purpose. The bullet-style Args and Returns sections are well-structured, though it could be slightly more compact without losing clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers operations and parameters adequately given the presence of an output schema and no nested objects. However, it lacks details on the behavior of each operation (e.g., what happens on failure) and prerequisites.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The 'Args' section adds meaningful explanations for all five parameters beyond the schema titles and types, such as 'label_type: Filter for list_templates (part, stock, location).' This compensates for the 0% schema description coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Label printing and template management in InvenTree.' It lists specific operations (list_templates, print_part, print_stock, print_location, download_template), which distinguishes it from sibling tools like report or barcode.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage through listed operations but does not explicitly state when to use this tool versus alternatives (e.g., report tool for reporting) or provide exclusions. No guidance on 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.
Part & category management in InvenTree.
Operations: Read: list, get, get_stock, get_bom, get_bom_usage, get_suppliers, get_manufacturers, get_parameters, get_parameter_templates, get_test_templates, get_related, get_builds, get_internal_prices, get_sale_prices, list_categories, get_category, get_category_parameters Write: create, update, create_category Delete: delete
Args: operation: One of the operations listed above. pk: Part or category ID (required for get/update/delete and sub-queries). data: Dict of fields for create/update (e.g. {"name": "Seal Kit", "category": 5}). search: Text search filter for list/list_categories. category: Category ID filter for list. limit: Max results for list (default 25). offset: Pagination offset for list.
Returns: JSON string with part/category data or {"error": "..."}.
| Name | Required | Description | Default |
|---|---|---|---|
| operation | Yes | ||
| pk | No | ||
| data | No | ||
| search | No | ||
| category | No | ||
| limit | No | ||
| offset | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true and not read-only. The description adds detail by listing destructive operations ('delete') and explains return format ('JSON string with part/category data or error'), providing extra behavioral 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a leading purpose sentence, followed by operations list, arguments, and returns. It is front-loaded and relatively concise, though could be slightly trimmed without losing clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (7 parameters, multiple operation types), the description covers all aspects: operations, required parameters, data format, pagination, and return type. An output schema exists, so no need to detail return values further.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description adds meaning for each parameter: explains operation values (though not full enum), pk usage, data dict for create/update, search filter, pagination limit/offset. This compensates well for the missing schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool is for 'Part & category management in InvenTree' and enumerates specific operations (read, write, delete), but does not explicitly differentiate from sibling tools like stock or company.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description lists operation types (Read, Write, Delete) and explains when to use each (e.g., 'pk required for get/update/delete'). It gives context for parameters but does not specify when not to use this tool or suggest alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Purchase order lifecycle management in InvenTree.
Operations: Read: list, get, get_line_items Write: create, update, issue, receive, complete, cancel, hold, add_line_item, add_extra_line_item
Args: operation: One of the operations listed above. pk: Purchase order ID. data: Dict of fields for create/update/add_line_item. location_id: Receiving location for receive operation. items: Line items to receive (e.g. [{"line_item": 1, "quantity": 10}]). search: Text search filter for list. limit: Max results (default 25). offset: Pagination offset.
Returns: JSON string with PO data or {"error": "..."}.
| Name | Required | Description | Default |
|---|---|---|---|
| operation | Yes | ||
| pk | No | ||
| data | No | ||
| location_id | No | ||
| items | No | ||
| search | No | ||
| limit | No | ||
| offset | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide basic hints (readOnlyHint=false, destructiveHint=false). The description adds significant behavioral context: which operations are read vs write, and the return format (JSON string with data or error). This goes 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: summary line, operations grouped by read/write, parameter list with clear labels, and return format. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of the tool (multiple operations, 8 parameters), the description covers purpose, operations, all parameters, and return format. The presence of an output schema further supports completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description explains every parameter: operation (list), pk, data, location_id, items with example, search, limit, offset. 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.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Purchase order lifecycle management in InvenTree' and lists all read and write operations. This distinguishes it from sibling tools like sales_order and return_order.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description lists all operations but does not provide explicit guidance on when to use each operation or when to choose this tool over alternatives. Usage is implied through the operation list but lacks explicit when/when-not.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Report generation and template management in InvenTree.
Operations: list_templates, print_report, download_template
Args: operation: One of the operations listed above. template_id: Report template ID for print_report/download_template. item_ids: List of item IDs to include in report. model_type: Model type for print_report. destination: File path to save downloaded template to.
Returns: JSON string with report templates or print result.
| Name | Required | Description | Default |
|---|---|---|---|
| operation | Yes | ||
| template_id | No | ||
| item_ids | No | ||
| model_type | No | ||
| destination | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false (modifications possible) and openWorldHint=true (unexpected side effects possible). The description adds the return format (JSON string) but does not elaborate on behavioral traits like permissions needed, whether print_report sends to a physical printer, or how download_template behaves. No contradictions 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with sections for operations, args, and returns. It is relatively concise at a few lines, though it could be slightly more compact by integrating operation descriptions with the args. No unnecessary sentences.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 5 parameters, multiple operations, and an output schema, the description is somewhat incomplete. It does not explain what each operation returns (though output schema may cover that) or clarify the behavior of operations like 'list_templates' or 'print_report' in detail. The description covers the essentials but leaves gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description provides basic meanings for each parameter (e.g., 'template_id for print_report/download_template'), which adds value beyond the empty schema descriptions (coverage 0%). However, it lacks details like valid model_type values or the format of destination, so it compensates only partially 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.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool handles report generation and template management in InvenTree, listing three operations (list_templates, print_report, download_template). This provides a specific verb-resource pairing and differentiates the tool from siblings like 'label' or 'attachment', though it could be more explicit about the overall single-tool nature.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description lacks guidance on when to use this tool versus alternatives or how to choose between the three operations. No exclusion criteria or context for selecting an operation is provided, leaving the agent to infer usage from operation names alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return order lifecycle management in InvenTree.
Operations: Read: list, get, get_line_items Write: create, update, complete, cancel, add_line_item
Args: operation: One of the operations listed above. pk: Return order ID. data: Dict of fields for create/update/add_line_item. search: Text search filter for list. limit: Max results (default 25). offset: Pagination offset.
Returns: JSON string with RO data or {"error": "..."}.
| Name | Required | Description | Default |
|---|---|---|---|
| operation | Yes | ||
| pk | No | ||
| data | No | ||
| search | No | ||
| limit | No | ||
| offset | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide readOnlyHint=false and destructiveHint=false. The description adds detail on return format and error handling, but does not discuss side effects, auth requirements, or rate limits. The operational list supplements the annotations well.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections for operations, args, and returns. It is concise but covers all necessary information, though a slight reduction in verbosity could improve it.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 6 parameters, nested objects, and an output schema, the description comprehensively covers operations, argument usage, and return format. It is sufficient for an agent to correctly invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema coverage, the description fully explains each parameter: operation, pk, data (dict for write ops), search, limit, offset. This adds critical meaning beyond the schema's type-only definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it is for 'Return order lifecycle management' and lists specific read/write operations (list, get, create, update, complete, cancel, add_line_item). This distinguishes it from sibling order management tools like purchase_order and sales_order.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description enumerates the valid operations and their purposes, guiding the agent on when to use each. While it does not explicitly state exclusions or alternatives, the context of sibling tools implies when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Sales order lifecycle management in InvenTree.
Operations: Read: list, get, get_line_items, get_allocations Write: create, update, complete, cancel, hold, add_line_item, add_extra_line_item, create_shipment, complete_shipment
Args: operation: One of the operations listed above. pk: Sales order ID. data: Dict of fields for create/update/add_line_item. shipment_id: Shipment ID for complete_shipment. reference: Reference string for create_shipment. search: Text search filter for list. limit: Max results (default 25). offset: Pagination offset.
Returns: JSON string with SO data or {"error": "..."}.
| Name | Required | Description | Default |
|---|---|---|---|
| operation | Yes | ||
| pk | No | ||
| data | No | ||
| shipment_id | No | ||
| reference | No | ||
| search | No | ||
| limit | No | ||
| offset | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate the tool is not read-only and not destructive; the description adds the list of write operations but does not disclose further behaviors (e.g., side effects on inventory), providing marginal added value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the purpose but repeats the operation list twice (in the text and as a parameter), making it longer than necessary and slightly redundant.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (multiple operations, 8 parameters, output schema), the description covers the operations and parameters adequately but lacks guidance on when to use specific operations, leaving some gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description compensates by naming all 8 parameters and briefly explaining each (e.g., 'operation: one of the operations'), adding valuable semantic context beyond the schema's bare titles.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Sales order lifecycle management in InvenTree' and lists all specific operations, making the tool's purpose unambiguous and distinct from sibling tools like purchase_order.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description specifies that the tool handles sales order lifecycle operations but does not explicitly compare with alternative tools or state when not to use it, limiting guidance for an agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Stock item & location management in InvenTree.
Operations: Read: list, get, get_by_location, get_by_part, list_locations, get_location, get_tracking, get_test_results Write: create, update, transfer, count, add, remove, create_location, upload_test_result
Args: operation: One of the operations listed above. pk: Stock item or location ID. data: Dict of fields for create/update. part_id: Filter stock by part (for list, get_by_part). location_id: Filter stock by location or transfer destination. quantity: Quantity for transfer/count/add/remove operations. test_name: Name for upload_test_result. test_result: Boolean pass/fail for upload_test_result. search: Text search filter for list/list_locations. limit: Max results (default 25). offset: Pagination offset.
Returns: JSON string with stock/location data or {"error": "..."}.
| Name | Required | Description | Default |
|---|---|---|---|
| operation | Yes | ||
| pk | No | ||
| data | No | ||
| part_id | No | ||
| location_id | No | ||
| quantity | No | ||
| test_name | No | ||
| test_result | No | ||
| search | No | ||
| limit | No | ||
| offset | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false, destructiveHint=false, and idempotentHint=false. The description lists read and write operations, aligning with these hints, but does not disclose additional behavioral details such as authentication needs, error handling specifics, or side effects beyond the basic return description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a brief intro, an operation list, and a parameter list. It is front-loaded with the purpose. However, it is somewhat verbose and could be more concise by grouping operations or using tables.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (11 parameters, 13 operations) and the presence of an output schema, the description covers most aspects but lacks per-operation required parameters or expected outputs. It does not fully leverage the output schema to reduce description burden, leaving some gaps for new users.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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 provides brief explanations for all 11 parameters, including their purpose and usage (e.g., 'pk: Stock item or location ID', 'quantity: Quantity for transfer/count/add/remove operations'). This adds value beyond the schema, though the 'operation' parameter lacks enumerations.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Stock item & location management in InvenTree' and lists distinct operations for read and write, making the tool's purpose specific and distinct from sibling tools like 'part' or 'purchase_order'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description lists operations and parameters but does not explicitly state when to use this tool over alternatives like 'part' or 'build_order'. Usage context is implied through the operation names, but no when-not or comparison guidance is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
InvenTree system administration and health checks.
Operations: health, version, settings, list_users, get_user, list_groups, list_owners, get_project_codes, list_currencies
All operations are read-only.
Args: operation: One of the operations listed above. pk: User ID for get_user.
Returns: JSON string with system data.
| Name | Required | Description | Default |
|---|---|---|---|
| operation | Yes | ||
| pk | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and not destructive. The description adds that all operations are read-only and lists operations, but does not disclose other behavioral traits such as permission requirements or rate limits. Given high annotation coverage, description adds moderate context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is concise with sections for operations, args, and returns. It is front-loaded with the purpose. Minor improvement could be more structured formatting, but it earns its sentences.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given complexity (multiple operations), presence of output schema, and good annotations, the description sufficiently explains the tool's behavior. It lists all operations and parameter usage, though could add details on response structure despite output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Parameter count is 2 and schema has 0% description coverage, so description must compensate. It explains that 'operation' is a choice from listed values and 'pk' is for get_user, providing meaning beyond the raw schema types.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it is for system administration and health checks, listing specific operations and stating they are read-only. It distinguishes itself from sibling tools like 'part' and 'stock' by targeting system-level tasks.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use for system admin tasks but does not explicitly provide when-to-use or when-not-to-use guidance relative to sibling tools. No alternatives or exclusions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.0attachmentbarcodebuild_ordercompanylabelpartpurchase_orderreportreturn_ordersales_orderstocksystemScored across 12 tools
Each tool addresses a distinct domain (e.g., attachment, barcode, build_order), with no overlap in purpose. The operations within each tool are specific to that domain, making it clear which tool to use for a given task.
All tool names are lowercase snake_case single words or compound words (e.g., build_order, purchase_order), following a consistent pattern. Operation names within tools are also uniform and descriptive.
12 tools is well-scoped for an inventory management system, covering all major entities (parts, stock, orders, etc.) without unnecessary granularity or missing core areas.
The tool set provides full lifecycle management for parts, stock, all order types (build, purchase, sales, return), companies, attachments, barcodes, labels, reports, and system administration. No obvious gaps in core functionality.
Manage a Foundry IMS catalog: products, variants, BOMs, plus invoices read from supplier docs.
Query and manage Mercoa AP/AR bill-pay: entities, invoices, transactions and payment methods.
Manage repositories, users, releases, and automate GitHub workflows
Inventory management for small organizations: search, assign, report, order, set up by chat.
