SOS Inventory MCP by usefulapi

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, and openWorldHint=true, so the safety profile is covered. The description adds the endpoint and required-field context, but does not explain duplicate handling, response payload, or permission requirements. It adds some value but not rich behavioral 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?

The description is three short sentences with no wasted wording. The write operation, required field, and duplicate-check guidance are all front-loaded and easy to scan.

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 no output schema and annotations that cover safety, the description is nearly complete for invocation: it states the write nature, required field, duplicate-check prerequisite, and endpoint. A minor gap is that it does not clarify what is returned or what happens when a duplicate is found.

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 moderate at 63%, and the schema itself documents the nested terms, billing, and sales_rep objects. The description only notes that name is required, which is redundant with the schema's required field, so it does not add meaningful parameter semantics beyond the structured data.

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 states a specific verb and resource: it creates a new customer record in SOS Inventory. The verb/resource pair distinguishes it from sibling creation tools for items, vendors, and orders.

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 explicitly tells the agent to check sosinventory_list_customers first to avoid duplicates, naming the exact sibling tool and the condition. This is concrete pre-call guidance rather than inferred usage.

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=false, idempotentHint=false and openWorldHint=true; the description adds real behavioral context on top by disclosing the hidden side effect that supplying a quantity causes SOS to create an inventory adjustment at the location. It omits permission/auth requirements and the non-idempotent consequence of retrying (duplicate items), which the annotation only flags without explaining.

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 marker so the agent knows the mutation class immediately, then effect, then precondition. Nothing is padded and the endpoint is a useful trailing detail rather than a lead-in.

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 15-parameter creation tool with no output schema, the description covers the flow and the notable side effect well. What it never addresses is what comes back — whether the new item's id is returned so the agent can chain into sosinventory_get_item or a stock operation — which is the one real 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 coverage is 67% and the description adds only one genuinely new fact — the category-scoped uniqueness constraint on name — plus a soft restatement of the initial_quantity/initial_location dependency already documented in the schema. The remaining 15 parameters, including nested vendor/category objects and the enum-typed 'type', are left to 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?

Opens with a specific verb+resource pair ("WRITE: creates a new inventory item") and immediately names the secondary effect (an inventory adjustment for opening stock). This clearly separates it from the create_* siblings (customer, vendor, purchase order, sales order) and from sosinventory_get_item.

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 a concrete precondition with a named alternative tool: check sosinventory_list_items first because names must be unique per category. It also frames the initial-stock path as optional. It stops short of any when-not-to-use guidance (e.g. don't use for services or for updating existing items — use an update tool instead).

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 readOnly=false, destructive=false, idempotent=false and openWorld=true, so the lower bar applies. The description still adds real behavior: 'WRITE:' labeling, the existing-record constraint (it will not create a vendor or item on the fly), auto-numbering unless a number is supplied, and the underlying POST endpoint.

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?

Four short clauses, front-loaded with the operation type and resource, then the scope constraint, then the confirmation rule. No redundancy and nothing buried.

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 non-idempotent write with nested line items and no output schema, the description never says what comes back (PO id/number) for chaining into sosinventory_get_purchase_order, nor what happens when the vendor/item does not exist or the number collides. Annotations and a fully documented schema cover much of the rest, leaving a moderate 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% and nested objects are fully annotated, so the schema already carries parameter meaning. The description's only extra detail is auto-numbering, which the schema's `number` field already states ('leave out for automatic numbering'); nothing is added about unit_price-as-cost or date defaults 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 ('creates a new purchase order') plus hard scope constraints: the vendor and items must already exist with line items. That scope plus the purchase-vs-sales distinction makes it separable from sosinventory_create_sales_order without opening 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?

Gives an explicit pre-call workflow rule ('Confirm the vendor, items, quantities and costs with the user before calling') and implies prerequisites through 'EXISTING vendor' / 'existing items'. It stops short of naming alternatives or stating when not to use it (e.g. drafts vs confirmed POs).

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 the mutation profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true, idempotentHint=false), so the description's main added value is the auto-numbering behavior and the confirmation requirement, both genuinely useful. However, it says nothing about side effects beyond creation (inventory allocation/reservation, price-floor enforcement is only in the schema), and the non-idempotent, open-world nature is left entirely to 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 tight sentences, front-loaded with the 'WRITE:' marker and the core action, followed by the constraint and the pre-call confirmation rule. The trailing POST endpoint adds integration context without padding; nothing is 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?

For an 8-parameter nested mutation with no output schema, the description covers preconditions and the confirmation workflow well. The one real gap is the return value: the agent isn't told whether the created order (its id or assigned number) comes back, which matters since a follow-up get_sales_order call would need that identifier.

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; the description still adds a bit by explaining that the order number is auto-assigned unless one is passed, which frames the optional 'number' field as a fallback rather than a requirement. The remaining parameters (date, comment, customer_po, location, line-level pricing) are left to the already-verbose 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 ('creates a new sales order') and immediately scopes it to an existing customer with existing line items. The parenthetical exclusion ('a customer or item cannot be created inside an order: use the create tools first') cleanly separates it from the sibling create_customer/create_item 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?

Gives an explicit prerequisite (customer and items must already exist, create them first) plus a workflow rule ('Confirm the customer, items, quantities and prices with the user before calling'). The schema further routes to sosinventory_list_customers and sosinventory_list_items for lookup, so alternatives are named rather than implied.

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=false, openWorldHint=true, and non-idempotent, and the description reinforces the write nature while adding value beyond them: the duplicate risk (no dedup enforcement is implied by the 'check first' advice), the minimal required field, and the underlying endpoint. It does not say what happens when a duplicate name is submitted (error vs. silent duplicate) or whether the created record is returned.

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 with the operation class front-loaded ('WRITE:'), followed by scope, the key constraint, the pre-check, and the endpoint. Nothing is padded or repeated.

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 8-param create with nested objects and no output schema, the description covers the essentials an agent needs to invoke it: minimal required input and duplicate avoidance. The notable omission is the response shape — since there is no output schema, the agent cannot tell whether an ID for the new vendor comes back.

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 63% across 8 params, including nested 'address' and 'terms' objects that the schema already documents. The description adds only the required-field note, which duplicates the schema's 'required: [name]', and says nothing about the optional email/phone/terms/address semantics. Baseline 3 is appropriate since the schema does most of the work.

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 ('creates a new vendor (supplier) record in SOS Inventory'), clarifies the domain synonym 'supplier', and is trivially distinguishable from siblings like sosinventory_create_customer or sosinventory_create_item. 'Only name is required' further pins down the minimal call shape.

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 sosinventory_list_vendors as a pre-check with the reason ('to avoid a duplicate'), which is the main usage decision for this tool. It stops short of stating when-not to use it (e.g. that an existing vendor should be updated instead), so it is clear but not fully exhaustive.

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 by structured data. The description adds value by promising a complete record ("all fields" incl. addresses, terms, price tier) rather than a summary, but says nothing about behavior for a missing/invalid id 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?

Two short sentences, front-loaded with the scope and field coverage; the trailing endpoint path is marginally useful for API mapping and costs little. No filler or repetition of the title.

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 reasonably compensates by enumerating the major field groups returned (addresses, contact, terms, price tier, custom fields). Combined with annotations covering safety, this is nearly complete for a simple single-record getter; only error 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 coverage is 100% and the id parameter already documents its source (from sosinventory_list_customers) plus positivity bound. The description's "by id" adds nothing 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 ("One customer by id") and immediately scopes it as a single-record fetch, which implicitly distinguishes it from sosinventory_list_customers. It does not name the sibling explicitly, so it falls short of full differentiation.

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 phrase "by id" and the parenthetical field list imply the use case (fetch full detail for a known customer), but there is no explicit when-to-use, when-not, or named alternative such as sosinventory_list_customers for discovery.

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 value by enumerating what fields come back (useful since there is no output schema), but says nothing about missing-id behavior, location scoping effects, or response shape beyond the field list.

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 fragments, front-loaded with the core purpose and field list. The trailing endpoint reference ('GET /api/v2/item/{id}') is mildly redundant but cheap and aids API mapping.

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 field enumeration is a meaningful substitute for describing return values, and annotations carry the safety profile. Only minor gaps remain: error behavior for an unknown id and how the optional location parameter changes the response, the latter of which the schema already 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 coverage is 100%, and the schema already explains both the id source and the location-scoping semantics (quantities reflect that location). The description adds no parameter meaning beyond that, 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 ('get') and resource ('one item by id'), then enumerates the returned fields (quantities, prices, accounts, vendor, category, units of measure, price tiers, custom fields). This implicitly distinguishes it from sosinventory_list_items and sosinventory_get_item_bom, though it doesn't name a 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?

Usage is only implied: the schema note 'from sosinventory_list_items' hints at the workflow, but the description itself says nothing about when to call this versus list_items, get_item_bom, or get_transaction. No exclusions or prerequisites are 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 the safety profile is covered. The description adds what the payload contains but says nothing about behavior for non-assembly items, missing items, or error responses.

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 content sentence plus the endpoint reference, front-loaded with the resource name. Nothing redundant or 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 does carry the burden of describing the return, and it names the three main components (items, quantities, costs). Only edge-case behavior for non-assembly or missing items is left unstated.

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?

There is a single parameter with 100% schema description coverage ('SOS item id of the assembly'), so the schema fully documents it. The description adds no further semantics such as where to obtain the id or what happens if a non-assembly id is supplied.

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 (bill of materials) and its scope (assembly items), and enumerates the content returned: components, quantities and costs. It is distinguishable from sosinventory_get_item, 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?

Usage is only implied by the name and the 'assembly item' qualifier; there is no explicit when-to-use or when-not-to-use guidance, and no pointer to sosinventory_get_item for the non-BOM case.

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 a useful return-shape hint ('all fields and line items') but says nothing about behavior on a missing/invalid id or the raw endpoint's auth/rate characteristics.

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 with the core payload statement front-loaded; nothing is padded. The raw path 'GET /api/v2/purchaseorder/{id}' is marginally redundant but reinforces the scoping.

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 single-parameter read with no output schema, the description plus annotations cover most of what an agent needs, and 'all fields and line items' hints at the response shape. Only error/not-found 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 coverage is 100% and the schema's own id description is strong (it warns the value is the SOS id from sosinventory_list_purchase_orders, not the PO number). The description contributes only 'by id', 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?

The description names a specific verb (get) and resource (purchase order by id) and adds that the response includes all fields and line items. It is clearly distinguishable from sosinventory_list_purchase_orders by its singular scope, though it never explicitly names that sibling as the alternative.

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 implied rather than stated: 'by id' signals this is the single-record fetch, and the schema note points to sosinventory_list_purchase_orders as the place to obtain the id. There is no explicit when-to-use/when-not sentence or stated prerequisite flow inside the description itself.

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 real value by disclosing return breadth ('all fields and line items'), telling the agent no follow-up call is needed for line items. It says nothing about error behavior (e.g., unknown id) or rate limits, so it is useful but not rich.

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 with zero filler, and the substantive scope statement ('with all fields and line items') is front-loaded ahead of the endpoint path. Every 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 one-parameter read tool with full annotation coverage, the description is nearly sufficient – it states what comes back, which is the main gap when no output schema exists. Minor omissions are failure behavior on a bad id and whether the response is a single object envelope; neither is critical here.

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 a single parameter at 100% schema coverage, the schema already carries the important disambiguation ('not the order number') and points to sosinventory_list_sales_orders as the id source. The description's 'by id' adds nothing beyond that, which is the expected baseline when the schema does the work.

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 pairs a specific verb and resource ('Get' is implied by 'One sales order by id') with a precise scope: a single order retrieved by identifier, plus the endpoint path. 'One ... by id' inherently distinguishes it from sosinventory_list_sales_orders, so an agent can route between single-fetch and list 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?

Usage is implied rather than stated: 'by id' signals this is the lookup path once an id is known, but the description names no alternatives and gives no when-not guidance. Prerequisite knowledge (that the id comes from sosinventory_list_sales_orders) lives only in the input schema, not the description.

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 value beyond that by disclosing the response shape ('all fields and line items'), which matters since there is no output schema, and by giving the concrete endpoint. It stops short of noting any auth scope, rate limits, or whether the payload can be large for certain types.

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 resource and scope, followed by the endpoint path. No filler or redundancy; every 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 2-parameter read tool with full schema coverage and annotations, the definition covers what is returned ('all fields and line items') in the absence of an output schema. The remaining gap is sibling disambiguation against the type-specific getters, which leaves an agent guessing which of several tools to pick for a sales order or purchase order.

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%: both parameters are documented, and the enum of transaction types is fully enumerated in the schema. The description adds only the phrase 'any type', which does not extend the meaning of the type enum or the id beyond what the schema already provides, 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 and resource ('One transaction of any type by id, with all fields and line items') and the underlying route, which is more informative than the bare title 'Get transaction'. The 'any type' phrasing implicitly contrasts with the type-specific siblings (get_sales_order, get_purchase_order), but never names them, so an agent must infer the routing itself.

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: the schema note 'from sosinventory_list_transactions' suggests the listing tool as the source of ids, but the description gives no when-to-use/when-not guidance. Crucially, it never explains when an agent should call this generic getter versus sosinventory_get_sales_order or sosinventory_get_purchase_order for the same record.

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 needs no restating. The description adds real value with "with all fields" (no field projection is applied) and the underlying GET endpoint, but says nothing about auth, rate limits, or error/not-found 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 clipped sentences, front-loaded with the substance (single vendor, all fields) and the endpoint as a trailing technical footnote. No filler, though the endpoint adds little for most agents.

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 one-parameter read tool with full annotation coverage and a fully described schema, this is largely sufficient. The only residual gap is the absence of an output schema combined with no hint of the returned record's shape beyond "all fields".

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% and the schema itself explains that the id comes from sosinventory_list_vendors, so the parameter is fully documented in structured data. The description adds nothing beyond that, which meets the baseline.

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 ("One vendor by id") plus the scope of the return ("all fields"), which distinguishes it from the list_vendors sibling that returns many. It stops short of naming the sibling explicitly, so it is clear but not maximally differentiated.

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: you fetch this when you already have a vendor id, and the id schema note points back to sosinventory_list_vendors as the source of ids. There is no explicit when-to-use/when-not statement or named alternative.

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?

The annotations already declare `readOnlyHint: true`, `openWorldHint: true`, and `destructiveHint: false`, so the safety profile is covered. The description adds useful context about the endpoint and returned customer fields, but does not mention pagination behavior or other operational details beyond what the schema provides.

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 two short sentences plus the endpoint and is front-loaded with the core action and return scope. It contains no redundant or filler text.

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 summarizes the customer fields returned, which is helpful because there is no output schema, and all parameters are covered by the schema. It is nearly complete for a read-only list tool, though it could mention pagination or clarify the distinction from `get_customer`.

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 seven parameters are already documented in the input schema. The description repeats the filtering options at a high level but does not add syntax or behavioral 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?

The description uses a clear verb and resource: 'List or search customers', and specifies the returned data such as contact details, addresses, terms, sales rep and credit-hold flag. It does not explicitly distinguish this tool from the sibling `sosinventory_get_customer`, but the list/search purpose is still clear.

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 by listing filterable fields such as name, email and update time, but it does not state when to choose this tool over `sosinventory_get_customer` or other siblings. The guidance is sufficient to understand filtering, but alternatives are left implicit.

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 readOnly=true, destructive=false, openWorld=true, so the safety profile is covered. The description adds real behavioral detail beyond that: the summary flag defaults to summary records without line items, and the GET /api/v2/item endpoint is named. It omits rate limits or response shape, keeping it below a 5.

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 sentences with no filler, front-loading what the tool does and what it returns before the filtering options and the endpoint. Every 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 an 11-optional-parameter list tool with no output schema, the description covers the returned fields, the summary-vs-full behavior, and location-based quantities. It leaves pagination mechanics (start/max_results) to the schema, which is acceptable, but a fuller note on paging behavior would close the 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 all 11 parameters are already documented, establishing a baseline of 3. The description's parameter enumeration ('filter by free text, SKU, category, type, tags, ids or update time') and the location note mirror the schema rather than adding syntax or semantics beyond it.

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 or search inventory items') and enumerates the fields returned (SKU, type, quantities, prices), which is more than a name restatement. The plural scope makes it distinguishable from sosinventory_get_item in the sibling set.

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 usage context: use filters for free text/SKU/category/type/tags/ids/update time, and 'pass location to see quantities at one location.' It does not explicitly route to alternatives (e.g., use get_item for a single item or list_reference_data for categories), so no exclusions are 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, openWorldHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful behavioral detail by outlining the returned fields and disclosing that summary=true strips line items and long sub-lists, but says nothing about result caps beyond schema or the shape of paging 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?

A single dense sentence that front-loads the verb and resource and then lists returnable facets, with the endpoint appended. Nothing is redundant, though the trailing API path is slightly extraneous for an agent that already has the tool name.

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 eight optional parameters and no output schema, the description earns its keep by sketching the result contents and the summary toggle. Coverage of date-range/query semantics is delegated to the schema, which is complete, so an agent has enough to invoke it 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?

Schema description coverage is 100% and every parameter is documented there, so the schema already carries the semantics. The description only echoes the summary flag's effect, which the schema states more precisely, so it adds little beyond the structured field.

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?

Uses a specific verb pair (list/search) plus resource (purchase orders) and enumerates the returned facets (vendor, dates, receipt date, totals, line items). It implicitly distinguishes itself from the singular sosinventory_get_purchase_order by framing the tool as list/search, though it never names that sibling.

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 parenthetical '(with summary=false) line items' signals when to toggle the detail level, which is genuine usage guidance. However, it gives no explicit direction on when to use this versus sosinventory_get_purchase_order or sosinventory_list_transactions, leaving the choice 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 elsewhere. The description adds the underlying endpoint (GET /api/v2/{type}) and hints at return fields ("users (id, name, email)"), but says nothing about result shape for other tables, page sizing behavior, or what happens with an unsupported query filter.

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?

Front-loaded with the purpose and the usage rule in the first two clauses; the long enumeration duplicates the enum but earns some of its length by translating slugs into human-readable table names. Slightly verbose but no filler 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?

With no output schema, the description should carry return-value expectations; it only partially does (user fields shown, other tables unspecified), though the pagination contract lives in the schema. For a simple read-only list tool this is nearly complete, with the return shape being the one real omission.

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 are already documented in the schema, including the next_start paging convention and the 1-200 max_results range. The description only adds that type values are the API endpoint names and that ids/names are what callers need, which is marginal over 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 a configuration or reference table") and expands the enum slugs into readable table names (terms → payment terms, uom → units of measure), so an agent can map a natural-language entity to a type. It does not explicitly distinguish itself from the entity-specific siblings (list_customers, list_items, list_vendors), which is the remaining gap.

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?

"Use it to find the ids and names that the create tools reference" gives a concrete selection rule tied to the create_* siblings. It stops short of stating exclusions, e.g. whether to use this instead of list_customers/list_items for account-like tables.

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 summary=false unlocks line items with shipped/invoiced quantities, which is real behavioral context, but it says nothing about page size, next_start pagination flow, or result ordering beyond what the schema already 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?

A single dense sentence that front-loads the action and the returned dimensions, followed by the raw endpoint. Nothing is wasted, though the field enumeration is packed tightly enough to read as a list rather than prose.

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 and 11 optional parameters, the description does partly compensate by naming what comes back (customer, totals, line items with shipped/invoiced quantities). However, pagination handling and the shape of a full record versus summary record remain under-described for a tool of this breadth.

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 every one of the 11 parameters is already documented in the schema. The description reinforces the summary flag and hints at order_stage/channel filtering, but adds no syntax, format, or interaction rules beyond the schema. 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 (list/search) and resource (sales orders) and enumerates the dimensions returned: customer, dates, totals, order stage, channel, and optionally line items. Distinguishes itself from sosinventory_get_sales_order by the 'list or search' framing, though it never names the sibling.

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?

'List or search' implies the search-via-query path, and the summary=false note hints at the light-vs-full tradeoff, but there is no explicit guidance on when to use this versus get_sales_order, list_transactions, or which filters to combine. Usage is inferred 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, openWorldHint=true. The description adds behavior the annotations cannot: which types reject the status filter and which types swap location for from/to_location. It does not describe pagination or response shape, but the schema covers the paging contract.

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 sentences, the resource and type enumeration are front-loaded, and the filter caveats follow. The long type list is dense but necessary for an 18-value enum; little waste overall.

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 12 parameters, no output schema, and read-only annotations, the description covers all filter dimensions and the type-specific exceptions. It omits return shape, pagination behavior, and explicit sibling routing, which are modest gaps for an already well-annotated read 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?

Schema coverage is 100%, so baseline is 3. The description earns above baseline because the status enum's schema text defers to the description ('see the tool description') for per-type validity, and the description actually supplies that mapping, plus the location substitution rule, which the schema only half-states.

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 ('any SOS transaction type'), then enumerates all 18 supported types and names the backing endpoint GET /api/v2/{type}. It is clear apart from the more specialized list_sales_orders and list_purchase_orders siblings, though it never explicitly says 'use this for mixed/other types, use the specific list tools for a single document type'.

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?

Explains filter semantics (status allowed values per type, location vs from_location/to_location for transfers/rentals) which is real when-to-use context. However, it gives no guidance on when to prefer this generic lister over the sibling list_sales_orders / list_purchase_orders / list_items tools, leaving that 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, openWorldHint=true and destructiveHint=false, so the safety profile is covered. The description adds the underlying endpoint (GET /api/v2/vendor) and the shape of returned fields, but says nothing about pagination behavior or result ordering 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?

A single front-loaded sentence plus the endpoint reference; no filler, and the most useful information (what you can search on and what you get back) comes first.

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 no output schema and fully documented parameters, the description covers purpose and payload contents adequately. Pagination and result semantics live in the schema, so the remaining gap is minor.

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 every parameter is already documented, including the important note that SOS has no email/phone filter. The description's only added semantic is echoing that search covers name or notes, which is baseline for a fully described 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 specific verbs (list, search) and the resource (vendors/suppliers) plus what each record carries (contacts, address, terms, account number). An agent can distinguish it from sosinventory_get_vendor by the list/search framing, though it never names 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?

Usage is implied by 'List or search ... by name or notes', but there is no explicit when-to-use guidance, no mention of when to prefer sosinventory_get_vendor for a single record, and no note on when search vs enumeration applies.

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