Megaventory MCP by usefulapi

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

Beyond the annotations, it discloses the insert-only contract ('an existing record is never updated, nothing is deleted') and the concrete non-idempotency consequence ('creating the same name twice creates two records'), which explains the idempotentHint=false flag rather than merely restating it. Note the description's 'nothing is deleted' framing sits in tension with destructiveHint=true, though the mismatch is more a flag-granularity issue than a direct claim reversal.

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?

Three short sentences, front-loaded with the 'WRITE:' operation class, then the dedupe precondition, then the endpoint. Every clause carries information the agent needs; nothing is padding.

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?

For an 11-parameter mutation with no output schema, the description covers the safety-relevant behavior (insert-only, duplicate risk, dedupe workflow) that annotations alone don't explain. It omits auth/permission requirements and what identifier is returned on success, which are the main remaining 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?

Schema description coverage is 55%, so roughly half the parameters (email, phone, comments, contact fields, addresses) are undocumented in both places. The description's 'client, supplier or both' does clarify the semantics of the enum-typed 'type' parameter, but it adds no meaning for the remaining payload fields; baseline 3 is appropriate.

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?

States a precise verb+resource ('create a NEW client, supplier or both in Megaventory') and uses the 'WRITE:' prefix to place it in the mutation family, which cleanly separates it from the many list_* siblings. No ambiguity about what the call produces.

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?

Explicitly routes the agent to megaventory_list_clients_suppliers first and gives the reason (duplicate names create duplicate records), which is a concrete when-to-use-alternative instruction. It does not state any when-not-to-use case beyond that dedupe prerequisite, so it falls short of a full 5.

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

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

Annotations already mark this as non-read-only, destructive and open-world, so the safety profile is covered. The description adds genuinely useful side-effect detail the annotations cannot convey: no stock movement, no invoicing, no payment, nothing received, and it names the underlying endpoint. It stops short of stating auth requirements or what happens on duplicate submissions (idempotentHint=false).

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?

Three short sentences plus the endpoint, front-loaded with the WRITE marker and the resulting state. Every sentence carries information, though the raw POST path is the least valuable element for an agent choosing a tool.

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?

With no output schema, the description must carry the behavior, and it does: it defines the resulting document state and explicitly enumerates what does not happen. Combined with 83% schema coverage on six parameters, an agent has enough to invoke it correctly, though error/validation behavior is unaddressed.

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 83%, so the schema already documents supplier_id, type_id, location_id, unit_price and the row SKU guidance. The description adds only the supplier relationship and the PENDING status, no new parameter-level meaning such as defaults for location or type. Baseline 3 is appropriate when the schema does the heavy lifting.

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?

States a specific verb and resource ('create a NEW purchase order'), names the required relationship ('to an existing supplier'), and pins the resulting state ('PENDING status'). It is distinguishable at a glance from the sibling megaventory_create_sales_order and from the list_purchase_orders read tools.

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?

It gives clear context for use by spelling out that verifying and receiving happen in Megaventory rather than through this server, which tells the agent this tool is for draft creation only. It does not name an explicit alternative tool or exclusion set, so it stops short of a 5.

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

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

Annotations cover the safety profile (destructive/not read-only/not idempotent), and the description adds genuinely useful behavior: the result is an unverified draft, no stock movement, no invoicing/payment. It does not flag the non-idempotency risk (duplicate orders via reference_no) nor what the call returns. The 'stock is not touched' framing sits in mild tension with destructiveHint=true, but it describes real draft semantics rather than 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.

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

Three tight sentences, front-loaded with the write nature and the resulting document state, then the scope boundary, then the endpoint. Every sentence carries distinct information and there is no filler.

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?

For a write tool with no output schema, the description covers what is created and what does not happen downstream, which is the important part. It stops short of saying what the response contains (e.g., created document id) or whether a new order number is returned, which an agent would want before chaining calls.

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 83%, so the schema already documents client_id, rows, type_id, location_id and reference_no with cross-references to list tools. The description adds no parameter-level detail beyond what the schema provides, which is the baseline 3 case.

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?

States a specific verb (create), resource (sales order), required precondition (existing client) and resulting state (PENDING). 'WRITE:' plus the endpoint 'POST /SalesOrder/SalesOrderUpdate' makes it unambiguous against siblings like megaventory_list_sales_orders or megaventory_create_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?

Gives clear context for when this applies (draft order creation) and explicitly bounds the scope by saying verifying, shipping and invoicing happen in Megaventory and not through this server. It does not, however, name an alternative tool or state when to prefer a different creation path (quote vs order vs purchase order).

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description still adds real value by disclosing negative behavior — the API key and mobile PIN are never returned — plus the underlying POST /User/UserGet endpoint, which phone books a non-obvious write-verb for a read.

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?

A single front-loaded sentence plus a short security caveat and the endpoint. No filler, and the most decision-relevant information (whose identity, what is returned) leads.

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?

For a zero-parameter tool with no output schema, the description carries the burden of describing the return payload and does so by naming the returned fields and explicitly excluding the sensitive ones. Slightly more on response shape would make it fully self-sufficient, but this is close.

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 tool takes zero parameters, so per the rubric the baseline is 4. The description correctly adds no parameter semantics because none exist.

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?

Names a specific resource (the Megaventory user tied to the current API key) and enumerates the returned fields (user name, administrator flag). It is unambiguously distinguishable from every sibling, which are all list/create operations on domain entities.

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?

Usage is only implied: an agent infers it should call this to identify the key's owner or check admin privileges. There is no explicit when-to-use statement, though no sibling offers a comparable identity lookup, so an exclusion clause would add little.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is fully covered. The description adds the return content shape and the underlying endpoint, but says nothing about auth requirements, whether unassembled products return empty, or error behavior.

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?

Two compact sentences with the return shape front-loaded and no filler. The endpoint reference is minimal and does not bloat the definition.

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?

With no output schema, the description carries the return-value burden and does so by naming the fields returned (id, SKU, description, quantity per unit). Combined with annotations covering safety and a fully documented schema, the only real gap is usage routing, which is scored separately.

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 100%, and the schema itself thoroughly documents all four parameters (including the pagination note on limit). The description adds nothing at the parameter level, so baseline 3 applies.

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?

States a specific resource (the bill of materials of a manufactured product) and its contents (raw materials with id, SKU, description, quantity per unit). An agent can distinguish this from list_product_bundles because it names the distinct BOM concept, though it never explicitly contrasts the two.

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?

Purely definitional. It gives no condition for when to reach for this tool versus get_stock, list_products, or list_product_bundles, and no prerequisites such as the product needing to be manufactured/assembled.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds that the returned figures fold in open sales orders, purchase orders and work orders, which is genuine output semantics, but it says nothing about pagination or rate behavior (that lives only in 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.

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

The resource and returned fields are front-loaded in a single dense sentence, followed by filtering capabilities and the endpoint. Efficient, though the opening sentence is heavily comma-laden and could have been split for scannability.

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?

With no output schema, the description usefully enumerates the fields returned, which is exactly what an agent needs to know what comes back. Filtering options and the location-id cross-reference are covered between description and schema; only paging/limit behavior is left entirely to the 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?

Schema description coverage is 100%, so all 11 parameters — including limit's no-page-offset rule and the filters array semantics — are already documented in the schema. The description only restates the filter categories at a high level and adds no syntax or format detail beyond that, hitting the baseline for full schema 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 names the exact resource (stock per product per inventory location) and enumerates the returned quantities — physical stock, on hand, on hold, not-yet-shipped, not-yet-received and alert level. An agent can distinguish this from sibling list tools such as megaventory_list_products without opening the schema.

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?

It lists the available filtering axes (product ids, SKU, category, location, supplier, below alert level), which implies how the tool is meant to be narrowed, and the schema cross-references megaventory_list_inventory_locations for valid location ids. However, there is no explicit when-to-use vs when-not (e.g. versus list_products or get_product_bom), so usage must be inferred.

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

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

Annotations already declare readOnlyHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds real value by disclosing the returned record shape (id, type, name, addresses, phone, email, tax id, currency, payment terms, contacts) in the absence of an output schema, plus the underlying POST endpoint. It does not, however, mention the newest-first ordering or lack of page offset.

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?

Two compact sentences: resource and scope first, then returned fields, then filtering, then endpoint. Every clause carries information an agent would otherwise have to infer.

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?

For a read-only list tool with fully documented parameters and no output schema, the field enumeration plus filter hint cover most of what an agent needs. The remaining gap is the ordering/limit behavior, which is only documented in the schema rather than surfaced in the description.

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 100%, including the enum choices, filter structure and the explicit note that there is no page offset. The description's 'filter by type or words in the name' only restates what the schema already documents, so the baseline 3 applies.

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?

States a specific verb and resource (list clients and suppliers), clarifies that both are one record type in Megaventory, and enumerates the fields returned. An agent can distinguish it from megaventory_create_client_or_supplier and from the product-oriented list siblings.

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?

'Filter by type or words in the name' implies how to narrow results, but there is no explicit when-to-use/when-not guidance or reference to alternative tools (e.g. list_product_suppliers for supplier-product links). Usage is implied rather than stated.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds genuinely useful non-annotation context: this is a POST to /Currency/CurrencyGet despite being a read, and it lists what comes back (including the exchange rate and default flag). It does not discuss result size, though the schema's limit parameter already covers that.

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?

Two compact clauses: what is listed (with returned fields in parentheses) followed by the endpoint. Front-loaded and free of filler.

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?

No output schema exists, but the description compensates by naming the four returned fields, and the schema fully documents the optional limit/filters behavior. Only minor gaps remain, such as any auth or rate-limit expectations for the POST endpoint.

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 100% and both parameters (limit, filters) are fully documented there, including the no-page-offset quirk. The description adds nothing about the parameters, so the baseline 3 applies.

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?

States a specific verb and resource ('List the currencies of the account') and even enumerates the returned fields (code, description, exchange rate, default flag). The resource is unique among the list_* siblings, so no differentiation ambiguity exists.

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?

There is no when-to-use guidance, no prerequisites, and no mention of alternatives (e.g. when to prefer get_current_user or list_taxes). Usage is only inferable from the name.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the return payload hint ("with totals and status") and the underlying endpoint POST /Document/DocumentGet, which is meaningful because no output schema exists to describe results; it still says nothing about permissions or result volume limits.

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?

Two tight sentences, front-loaded with the purpose and followed by the narrowing options, with the endpoint tucked at the end. Only the trailing "and so on" is mild filler; nothing else could be cut without losing information.

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?

For a zero-required-parameter list tool with an output-schema-free surface, the description covers what it returns (documents with totals and status) and how to narrow broadly enough to invoke it correctly. Pagination and "newest first" behavior are handled by the limit parameter description rather than here, and permission prerequisites remain unaddressed.

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 100%, so the baseline is 3, but the description adds value beyond it by naming three of the five parameters in natural language and explicitly linking document_type_ids to the sibling lookup tool that supplies valid ids. It omits any mention of the limit/filters parameters, which is acceptable since the schema documents them thoroughly.

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?

States a specific verb and resource ("List transaction documents") and immediately bounds the scope with "of any type", enumerating shipments, invoices, receipts, credit notes, returns and adjustments. That scope word is what separates it from the typed siblings list_sales_orders, list_purchase_orders and list_work_orders, which an agent can distinguish without opening either schema.

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?

Gives concrete narrowing paths — document type ids, document number, status — and routes the agent to megaventory_list_document_types to obtain the type ids. It does not state when to prefer this general lister over the order-specific siblings, so there is a small residual ambiguity about which tool to pick for sales orders or purchase orders.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the endpoint (POST /DocumentType/DocumentTypeGet) and states the returned content (ids and abbreviations), but says nothing about rate limits, pagination, or result size.

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?

Two compact sentences, with the resource and returned fields front-loaded. The trailing endpoint string is mildly redundant but does not dilute the message.

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?

For a read-only reference listing with no output schema, the description conveys what is returned (ids and abbreviations) and the examples give a sense of scope. An agent has enough to call it correctly; only usage routing is missing.

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 100%, so limit, filters and show_deleted are fully documented in the schema itself. The description adds no parameter-level detail beyond that, which is the expected baseline when the schema carries the load.

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?

States a specific verb (list) and resource (document types), plus concrete examples of the type values (sales order, purchase order, etc.). It distinguishes itself from sibling list_documents by clearly being about the type taxonomy rather than actual documents, though it does not name that sibling explicitly.

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?

No when-to-use or when-not-to-use guidance is given. The purpose implies a reference/lookup use (e.g. before filtering documents by type), but the description never states this or names alternatives, leaving routing to inference.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds that this is a POST endpoint (POST /InventoryLocation/InventoryLocationGet), which is mildly useful but doesn't disclose pagination, default limits, or deletion-visibility behavior beyond what the schema states.

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?

Two short sentences, front-loaded with the resource and its subtypes, then the downstream use, then the endpoint. Zero filler.

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?

With no output schema, the description helpfully enumerates the returned fields (id, abbreviation, name, address), and the schema carries the filtering and limiting semantics. A note on pagination/newest-first behavior would fully round it out, but it is largely complete.

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 100%, with limit, filters, show_deleted, and include_transit each documented in-schema, so the baseline is 3. The description's mention of "transit" loosely maps to include_transit but adds no syntax or semantics 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?

States a specific verb and resource ("List inventory locations") and immediately disambiguates the term with concrete subtypes (warehouses, shops, transit) plus the returned fields. No sibling tool covers locations, so the scope is unambiguous at a glance.

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?

Tells the agent what to do with the output ("Use the ids for stock filters and order locations"), which makes the tool's role in a workflow clear. It stops short of stating when to prefer an alternative source of location data or any prerequisites.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds only the underlying endpoint (POST /Product/ProductBundleGetAll); it says nothing about pagination, result volume, or default scoping when no filters are supplied.

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?

Two tight sentences with the core purpose front-loaded and no redundancy. The trailing raw endpoint is mildly useful but is the weakest element.

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?

Adequate for a read-only list tool, but with no output schema and no pagination parameter, the description should say what happens when no filters are given and whether the whole catalog is returned — that gap is not filled by the 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?

Schema description coverage is 100%, so the schema already documents all five parameters in detail. The description restates the bundle id/SKU and included-product filters but omits show_deleted entirely, adding little beyond what the schema provides.

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?

States a specific verb (list) and resource (product bundles) and even defines the domain concept — 'a bundle sells several products together'. That distinguishes it from list_products and list_product_suppliers by resource name, though it never explicitly contrasts itself with those siblings.

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 explains how to narrow results (by bundle id/SKU, or by an included product), which implies usage. But it gives no when-to-use/when-not-to-use guidance or routing to a sibling list tool, so an agent must infer the context.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the underlying endpoint (POST /ProductCategory/ProductCategoryGet), which is minor context but does not add return-format or volume/behavior detail beyond the 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?

Three compact fragments with the resource and return fields front-loaded and no wasted wording. Terse to the point of being near-telegraphic, but each clause carries information.

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?

For a read-only list tool with full schema coverage and annotations carrying the safety profile, the description is close to sufficient. Naming the returned fields compensates for the absent output schema, though pagination/newest-first behavior is left entirely to the 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?

Schema description coverage is 100%, so the four parameters (limit, search, filters, show_deleted) are fully documented in the schema. The description adds no syntax or format detail about them, so the baseline 3 applies.

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?

States a specific verb and resource ('List product categories') and lists the returned fields (id, name, description), so the agent knows exactly what this returns. It does not explicitly differentiate itself from the nearby sibling megaventory_list_products, so it falls short of a 5.

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 clause 'Use the ids to filter products' hints at a downstream workflow, implying when this is useful, but there is no explicit when-to-use/when-not guidance and no alternative tool is named for discovering product categories.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds one genuine behavioral detail not in the annotations — 'Empty text fields are omitted' — but says nothing about result ordering, the default limit, or permission requirements (the newest-first / no-page-offset behavior lives only in 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.

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

Two dense, front-loaded sentences with no filler: returned fields first, filtering second. The trailing 'POST /Product/ProductGet' is an endpoint restatement that adds minor value, keeping it just below a 5.

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?

With no output schema published, the description usefully enumerates the result fields, and the schema carries the pagination/limit semantics. The remaining gap is guidance on choosing this endpoint over its siblings, but for a read-only catalog search the definition is otherwise complete.

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 100%, so the schema already documents every parameter, including the limit's 1-100 range and the no-pagination rule. The description's filter summary (id, SKU, category, supplier, description words) mirrors the parameters rather than adding syntax or format detail beyond them, so baseline 3 applies.

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?

States a specific verb ('Search the product catalog') plus the resource, and enumerates what comes back (SKU, description, category, prices, dimensions, supplier, flags). That enumeration cleanly separates it from siblings such as megaventory_list_product_suppliers, megaventory_list_product_categories and megaventory_get_product_bom, which cover adjacent but different resources.

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?

It tells the agent how to narrow results ('Filter by id, exact SKU, category, main supplier or words in the description'), which implies the intended usage pattern, but it never states when this tool should be preferred over alternatives such as megaventory_get_stock or the sibling product list endpoints, and there are no exclusions.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so safety is covered. The description adds one genuinely useful behavioral fact, that this read is performed via a POST to /ProductSupplier/ProductSupplierGet, plus the shape of what comes back. It says nothing about result volume or that the newest records dominate, though the schema carries that.

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?

Two tight clauses with zero filler, and the identifying content (what the pairs represent) is front-loaded before the endpoint metadata. Nothing could be cut without losing information.

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?

With no output schema, the description partially compensates by naming the returned fields, and the read-only annotations plus a fully described schema leave little else an agent needs. It stops short of explaining the return envelope or result volume, which is the only remaining gap.

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?

All three parameters are fully documented in the schema (100% coverage), including the limit range, the no-page-offset caveat, and AND-combined filters. The description adds no parameter-level meaning beyond that, so the baseline of 3 applies.

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 names the exact resource (product-supplier pairs) and enumerates the returned fields (supplier SKU, description, purchase price), which separates it from siblings like list_products and list_clients_suppliers. It does not name those siblings explicitly, so an agent must infer the boundary, but the scope is unambiguous.

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?

There is no when-to-use, when-not-to-use, or alternative-tool guidance. The only orienting detail is the endpoint path. An agent must guess whether this is the right call versus list_products or get_stock when hunting for supplier pricing.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered structurally. The description adds real behavioral value by disclosing the returned payload shape (order header plus row-level SKU/quantity/price detail) and the underlying POST /PurchaseOrder/PurchaseOrderGet call, which tells the agent this is a POST-based read rather than a plain GET.

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?

Three compact sentences: what is returned, how to filter, and which endpoint executes it. No filler, and the returned-field detail is front-loaded before the filtering hint.

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?

With no output schema, the description usefully compensates by describing the return contents at both header and row level, and the schema fully covers limits and filtering. It omits any note on pagination or result ordering in the description, though the limit parameter documents that, leaving only a minor gap.

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 100%, so the schema already documents limit, status, filters, order_no and supplier_id in detail, including the newest-first/no-offset constraint. The description only echoes three of those filters and adds no syntax, format or default information beyond the schema, so the baseline 3 applies.

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?

States a specific verb and resource ('List purchase orders') and goes further by enumerating the payload it returns: supplier, dates, totals, status, and order rows with SKU, quantities and unit price. The name disambiguates it from sibling creators like megaventory_create_purchase_order, but it never explicitly distinguishes itself from list_documents or list_sales_orders, so it stops short of the sibling-aware bar.

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 sentence 'Filter by order number, status or supplier' implies the intended retrieval contexts, but there is no explicit when-to-use, when-not-to-use, or pointer to an alternative (e.g. list_documents when you want documents across types). Usage is inferable rather than stated.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds real value by disclosing the response composition (client, dates, subtotal/tax/discount/grand total, status, and per-row SKU/quantity/shipped/invoiced/unit price) and the backing endpoint POST /SalesOrder/SalesOrderGet, which matters because no output schema exists.

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?

Three compact sentences: result shape first, then filters, then the endpoint. Nothing is padded, though the trailing endpoint path is the least load-bearing element for an agent selecting the tool.

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?

With no output schema the description usefully previews the return shape, and annotations cover the safety profile; the schema itself handles the no-paging/limit nuance. Only the explicit tie-break against sibling list tools is missing for full 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 100%, so the schema already documents limit, status, filters, order_no and client_id with examples and enum meaning. The description only restates two of them ('order number or status') and adds no syntax or format detail beyond the schema, so the baseline of 3 applies.

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?

States a specific verb and resource ('List sales orders') and enumerates the returned content (client, dates, totals, status, order rows). The 'sales' qualifier cleanly separates it from siblings like megaventory_list_purchase_orders and megaventory_list_sales_quotes without needing to open a schema.

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?

'Filter by order number or status' implies how to narrow results, and the schema's limit description pushes toward filtering instead of paging. However, there is no explicit when-to-use guidance, no exclusions, and no routing to alternative tools (e.g. list_sales_quotes) when a different document type is wanted.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds the transport detail (POST /SalesQuote/SalesQuoteGet), which is mildly useful for a read performed via POST, but says nothing beyond annotations about result volume or ordering behavior.

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?

Three short sentences, front-loaded with purpose and return contents before filtering and endpoint. Nothing is padded, though the raw endpoint path adds little value for an agent choosing a tool.

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?

With no output schema, the description helpfully names the main returned fields, and read-only annotations cover safety while the schema fully covers parameters. Only ordering/pagination behavior is left to the schema, which is acceptable since the schema does state it.

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 100%, so all four parameters (limit, status, filters, quote_no) are already documented in the schema, including the no-page-offset behavior. The description's mention of filtering by quote number or status only restates what the schema provides, so the baseline of 3 applies.

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?

States a specific verb and resource ('List sales quotes') and enumerates the salient returned fields (client, totals, status, rows), so the agent knows what it gets back. It does not distinguish itself from siblings like megaventory_list_sales_orders or megaventory_list_documents, leaving that inference to the name.

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?

'Filter by quote number or status' implies when the tool is useful, but there is no explicit when-to-use framing, no prerequisite (e.g. needing a quote number), and no pointer to an alternative listing tool when quotes are not the target.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=true, so the safety profile is covered. The description adds only the returned fields and the underlying POST /Tax/TaxGet endpoint — a little context, but no mention of result limits, ordering, or auth requirements.

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?

One front-loaded sentence carrying purpose, returned fields, and endpoint with zero filler. Nothing could be removed without losing information.

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?

There is no output schema, but the description compensates by naming the returned fields (id, name, rate), and annotations cover the read-only nature. Missing only edge detail like ordering of results, which the schema's limit description partially covers.

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 100%, so limit, filters, and show_deleted are fully documented in the schema itself (including the no-pagination caveat). The description adds nothing about parameters, which is acceptable given the schema does the work — baseline 3.

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?

States a specific verb and resource ('List the tax rates defined in the account') and even names the returned fields (id, name, rate). It is unambiguous, though it offers no explicit differentiation from siblings — unnecessary here since no sibling tool also lists taxes.

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 gives no when-to-use guidance, no prerequisites, and no alternatives. An agent must infer that this is the reference-data lookup for tax rates; nothing in the text routes it there or away from any other list_* tool.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the endpoint detail (POST /WorkOrder/WorkOrderGet) which is mildly useful, but leaves ordering limits and pagination behavior to the schema rather than surfacing them itself.

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?

Two compact sentences with the field list front-loaded and the filter options second; every clause carries information and nothing is padded.

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?

With no output schema, the description usefully enumerates the returned fields, filling that gap, and the schema documents all four parameters. Read-only annotations cover safety; the only shortfall is that pagination/ordering context stays buried in the parameter 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?

Schema coverage is 100%, so each parameter (limit, status, filters, work_order_no) is already fully documented, including the newest-first/no-offset behavior. The description only repeats the two filterable dimensions, adding no syntax or format detail 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?

States a specific verb and resource ('List work (production) orders') and enumerates the returned fields (finished product, quantity, location, status, priority, allocated materials), which no sibling list tool covers. The resource is unique among siblings, so an agent can distinguish it without opening the schema.

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 says it can be filtered by work order number or status, which implies when the tool is useful, but gives no explicit when-to-use/when-not guidance or naming of alternatives. Usage is implied rather than stated.

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