Read Finale Inventory products, stock, orders and shipments; create draft purchase orders.
The last two health checks of this connector failed. If this server requires authentication, missing or expired test credentials may be the cause. A test profile lets Glama authenticate for health checks and discover tools; it is separate from your personal connections.
If you are the author, claim ownership, then add or update a test profile under Admin → Test Profile.
Scored across 13 tools
Most tools split cleanly into list_* (orders, products, shipments, facilities, parties, transfers, stock changes) and get_* (order, product, shipment) patterns, plus one create tool. The only mild overlap is finale_get_product_stock versus finale_list_inventory_items, since both read stock, but the descriptions clearly distinguish per-product totals from raw per-location/lot entries.
Every tool uses the same finale_ prefix plus a consistent verb_noun snake_case pattern: create_draft_purchase_order, get_order, list_orders, etc. Even the long create name follows the convention predictably.
13 tools is well within the sweet spot for an inventory server and each tool maps to a distinct resource or operation (orders, products, stock, shipments, facilities, parties, transfers, stock changes). No tool feels redundant enough to remove.
Read coverage is broad, but the write surface is very thin: only one draft purchase-order creation exists, with no update/delete, no order commit/lock, no shipment creation, no product creation, and no stock adjustment despite listing stock changes. Agents can inspect the domain well but will hit dead ends for most mutations.
WRITE. Creates a purchase order for a supplier in status ORDER_CREATED, i.e. an editable draft. It is NOT locked (committed), received, completed or emailed, no stock changes and no money moves: review and commit it in Finale. Products are looked up first (one single read each; products whose resource URL differs from the SKU cost collection reads, bounded to 3 or one full product-list read), then ONE POST creates the order; the call is never retried, so check finale_list_orders before repeating it after an error. POST /{account}/api/order/.
| Name | Required | Description | Default |
|---|---|---|---|
| items | Yes | Order lines. | |
| order_id | No | Order id (max 20 ASCII characters; must be unique). Omit to let Finale number it. | |
| public_notes | No | Notes to the supplier. | |
| private_notes | No | Internal notes. | |
| reference_number | No | Supplier reference number (max 60 characters). | |
| supplier_party_id | Yes | Supplier partyId (from finale_list_parties). | |
| destination_facility_url | No | Receiving location's facilityUrl (from finale_list_facilities; not a sublocation). Omit for 'Multiple / unspecified'. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the single destructiveHint annotation by disclosing the internal call pattern (one read per product, bounded to 3 or one full product-list read, then ONE POST), the non-idempotent retry policy, and the concrete side-effect boundary (no stock changes, no money moves, order stays unlocked). This is exactly the behavioral detail annotations cannot convey.
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 'WRITE' and the resulting status, which is the most decision-relevant fact, and the rest is dense but information-bearing. The middle sentence is long and packs three distinct behaviors (lookup scope, single POST, no retry) into one clause chain, which costs a little readability.
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 7-parameter write tool with no output schema and only a destructiveHint annotation, the description supplies the state the record lands in, the side effects, the lookup and HTTP behavior, and the error-recovery path. Nothing an agent needs to call this correctly and safely is missing, and return-value detail is unnecessary since no output schema is declared.
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 the baseline is 3, but the description adds runtime semantics not in the schema: per-item product resolution happens before the POST and an unknown SKU aborts the entire request. It does not touch the other five parameters (order_id, notes, reference_number, destination_facility_url), so it only partially extends the schema's meaning.
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 purchase order for a supplier') and pins down the exact resulting state ('status ORDER_CREATED, i.e. an editable draft'). It also explicitly enumerates what it is not (locked, received, completed, emailed), which no sibling write tool would share, so an agent can distinguish it immediately.
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 operational context: products are looked up first, the call is never retried, and 'check finale_list_orders before repeating it after an error' names a concrete sibling for verification. It does not state prerequisites such as needing a supplier_party_id sourced from finale_list_parties (that is only in the schema), so it stops just short of full when/when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One order in full: header, line items (productUrl, quantity, unitPrice), roles (customer or supplier), adjustments, shipment and invoice URLs, notes. GET /{account}/api/order/{orderId}.
| Name | Required | Description | Default |
|---|---|---|---|
| order_id | Yes | The order id as shown by finale_list_orders (orderId). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
readOnlyHint=true already establishes this as a safe read, so the description is free to add payload-level context — and it does, disclosing that customer/supplier roles, adjustments, notes, and invoice/shipment URLs are all returned. It stops short of noting error behavior (e.g. what happens for an unknown orderId) which is the main remaining gap.
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 outcome ('One order in full') followed by a compact inventory of returned fields. The trailing raw endpoint path is largely redundant with the tool name and consumes space without adding decision value, a minor structural inefficiency.
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, enumerating the return payload is exactly the right compensation and it is thorough. What remains missing is failure behavior for invalid or inaccessible orderIds, which is a modest but real gap for a fetch 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% and the single order_id parameter is already documented, including the pointer to finale_list_orders as the source of the id. The description only echoes this implicitly via the GET path template, so it does not add meaning beyond the schema — 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+resource (retrieve one order in full) and enumerates exactly what 'full' contains: header, line items with field names, roles, adjustments, shipment/invoice URLs, notes. The phrase 'One order in full' cleanly distinguishes it from the sibling finale_list_orders, which returns many orders without full detail.
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 the contrast between 'one order in full' and the list sibling, but there is no explicit when-to-use statement, no prerequisite (e.g. you need an orderId from finale_list_orders), and no exclusions. An agent can infer the context but is not guided to it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One product in full: ids, description, UPC/ASIN, dimensions and weight, cost, supplier list, reorder guidelines, price list, custom fields. GET /{account}/api/product/{id} (falls back to a productId filter when the resource URL differs).
| Name | Required | Description | Default |
|---|---|---|---|
| product_id | Yes | The product id (SKU) as shown by finale_list_products. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
readOnlyHint=true already covers the safety profile, so the bar is lower; the description adds genuinely new behavior, namely the endpoint shape and the fallback to a productId filter when the resource URL differs. It also discloses the breadth of the return payload, which matters since no output schema exists. It stops short of noting auth requirements or 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 sentences, front-loaded with the return payload and scoped with the endpoint detail. The dense field enumeration earns its place because it substitutes for a missing output schema, 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 single-parameter read with no output schema, the description usefully enumerates what comes back and explains the fallback resolution of the id. It is nearly complete; error/not-found behavior and auth prerequisites are the remaining omissions, but those are minor for a read-only lookup.
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 one parameter at 100% schema coverage, the schema already documents product_id (including the 'as shown by finale_list_products' hint). The description adds nothing about id format or edge cases 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+resource ('Get a product', 'One product in full') and enumerates the fields returned (ids, UPC/ASIN, dimensions, cost, suppliers, price list, custom fields), which clearly separates it from a bare list tool. However, it never explicitly contrasts with the closest siblings (finale_get_product_stock, finale_list_products), so differentiation is left partly to inference.
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?
'One product in full' implies the use case — fetch complete master data for a single product by id — but there is no explicit when-to-use, when-not-to-use, or named alternative (e.g. use finale_get_product_stock for quantities, finale_list_products to enumerate). 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.
Stock of one product summed over Finale's stock entries: totals for quantityOnHand, quantityOnOrder and quantityReserved, and the same per location/sublocation. Downloads the WHOLE inventoryitem collection (Finale offers no filter; large on big accounts), so it counts as one collection read of the 300 per hour: avoid calling it in a loop. GET /{account}/api/inventoryitem/.
| Name | Required | Description | Default |
|---|---|---|---|
| product_id | Yes | The product id (SKU). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With readOnlyHint=true already covering safety, the description adds the non-obvious behavior: it downloads the WHOLE inventoryitem collection because Finale offers no server-side filter, which is expensive on big accounts and consumes one of 300 hourly collection reads. This is exactly the kind of hidden cost an agent needs before calling it.
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-loads the return shape before the cost warning, and every clause is load-bearing. The long second sentence is dense (payload size, rate limit, loop warning, endpoint) but not 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?
No output schema exists, yet the description enumerates the returned totals and their per-location breakdown, plus the cost implications of the unfiltered fetch. An agent has everything needed to call it correctly and budget for its cost.
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 product_id is already documented as the SKU, so the schema carries the parameter semantics. The description adds no syntax, format, or lookup guidance beyond confirming the scope is one product, matching the baseline for fully-documented schemas.
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 computed resource: per-product stock aggregated over Finale's stock entries, naming the exact metrics (quantityOnHand, quantityOnOrder, quantityReserved) plus per-location/sublocation breakdown. This is distinguishable from the sibling list_inventory_items, since it describes an aggregation rather than a raw listing.
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 real operational guidance ('avoid calling it in a loop', 'counts as one collection read of the 300 per hour'), but never states when to prefer this over finale_list_inventory_items or finale_list_stock_changes. Usage context is implied through the cost warning rather than through an explicit alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One shipment in full, including its shipment items (product, facility, quantity), packages and transfers. GET /{account}/api/shipment/{shipmentId}.
| Name | Required | Description | Default |
|---|---|---|---|
| shipment_id | Yes | The shipmentId as shown by finale_list_shipments. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
readOnlyHint=true already tells the agent this is a safe read, so the description only needs to add context. It does so by disclosing what the payload contains (shipment items with product/facility/quantity, packages, transfers), which is meaningful behavioral detail. No pagination or auth notes, but those are less relevant for a single-resource 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?
Two sentences, front-loaded with the resource and return scope, with the endpoint appended as a terse orientation. Nothing is wasted.
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 it well by naming the included sub-resources. The main gap is the absence of any note on error behavior for an invalid ID, which is minor for a simple read.
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?
Only one parameter, and schema coverage is 100% — the schema documents shipment_id, its length bounds, and even where to find the value. The description adds only the REST path, 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 shipment in full') and enumerates the sub-resources returned (items, packages, transfers), which distinguishes it from the plural list tool finale_list_shipments. 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?
Usage is implied by the singular scope — fetch a single shipment by ID — and the schema points back to finale_list_shipments for discovering IDs. There is no explicit when-to-use statement, no exclusions, and no named alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List Finale locations and sublocations: facilityName, facilityUrl (use it in other tools), parentFacilityUrl (set for sublocations), status. GET /{account}/api/facility/.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum rows to return, 1-1000 (default 100). | |
| fields | No | Fields to return per row (default: a compact useful set). | |
| updated_since | No | Only records last updated on or after this UTC time. Finale allows a range of at most 30 days (updated_until defaults to now). | |
| updated_until | No | Only records last updated on or before this UTC time (needs updated_since). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
readOnlyHint=true already tells the agent this is a safe read, so the description's burden is lighter and it adds real value: it discloses the returned field set, the parent/child relationship semantics (parentFacilityUrl set for sublocations), and the underlying endpoint. It does not mention pagination behavior or that the default field set is compact.
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 dense sentence plus the endpoint, with the resource identified immediately and no filler. Every clause (sub-locations, URL reuse hint, parent linkage, status) 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?
With no output schema, the description usefully enumerates the returned fields and explains the parent/sub-location relationship, which is what an agent needs to use the results. It could go slightly further on result size/pagination expectations, but for a read-only list endpoint it is close to 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, fields, updated_since and updated_until all documented including the 30-day range constraint, so the schema carries the parameter burden. The description's field enumeration loosely maps to the 'fields' parameter but adds no syntax or default detail beyond what the schema already provides; 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) plus the resource (Finale locations and sublocations) and even enumerates the fields returned, so the agent knows exactly what comes back. It does not explicitly contrast itself with any sibling, but the resource is unique among the surrounding list_* tools, so confusion is unlikely.
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 'use it in other tools' for facilityUrl is a useful workflow hint about downstream usage, implying this is a discovery step before other Finale calls. However, there is no explicit when-to-use or when-not-to-use guidance, and no prerequisites or alternatives are named.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Current stock as Finale stores it: one entry per product, location, lot and order with quantityOnHand, quantityOnOrder (committed purchase orders) and quantityReserved (committed sales orders). The inventoryitem collection has no server-side filter, so the WHOLE collection is downloaded (one collection read of the 300 per hour; can be large on big accounts, up to the 50,000 character result cap) and filtered here: pass product_id or facility_url. For per-product totals use finale_get_product_stock. GET /{account}/api/inventoryitem/.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum rows to return, 1-1000 (default 100). | |
| fields | No | Fields to return per row (default: a compact useful set). | |
| product_id | No | Only entries of this product id (SKU). | |
| facility_url | No | Only entries at this facilityUrl (from finale_list_facilities). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only supply readOnlyHint=true, and the description adds substantial non-obvious behavior: the collection has no server-side filter, the whole collection is downloaded and filtered client-side, it consumes one of 300 collection reads per hour, and results can hit the 50,000 character cap on large accounts. These are exactly the operational caveats an agent needs before calling.
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 dense paragraph with the resource definition, the caveat, and the routing advice front-loaded; almost every clause carries information. It is longer than typical and somewhat run-on, but not 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 supplies the row shape and key quantity fields, plus the rate-limit and result-cap constraints that determine whether the call is viable. No blocking gap remains for correct invocation.
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 the baseline is 3, but the description adds real meaning the schema lacks: product_id and facility_url are applied after download (not server-side), and facility_url values come from finale_list_facilities. The remaining parameters (limit, fields) 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?
States a specific verb and resource ('List stock entries' / inventoryitem) and defines exactly what an entry is: product, location, lot and order with quantityOnHand, quantityOnOrder and quantityReserved. It also contrasts itself against finale_get_product_stock, so an agent can distinguish it from the sibling aggregate tool 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?
Explicitly routes the agent: use finale_get_product_stock for per-product totals, use this tool and pass product_id or facility_url to narrow the full-collection download. The condition selecting this tool versus the alternative is stated, not inferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List stock transfers between locations: product, from/to facility, quantity, lot, send and receive dates. GET /{account}/api/inventorytransfer/.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum rows to return, 1-1000 (default 100). | |
| fields | No | Fields to return per row (default: a compact useful set). | |
| updated_since | No | Only records last updated on or after this UTC time. Finale allows a range of at most 30 days (updated_until defaults to now). | |
| updated_until | No | Only records last updated on or before this UTC time (needs updated_since). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already establishes this as a safe read. The description adds value by disclosing the row shape (product, from/to facility, quantity, lot, send/receive dates) and the underlying endpoint, but says nothing about pagination, default ordering, or the compact default field set that the schema mentions.
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 tight sentence front-loads purpose and then the returned fields, with the endpoint appended. Both clauses earn their place; only the raw path adds little for an agent that already knows 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 no output schema, the description usefully compensates by naming the returned columns, but it omits result ordering, default field set behaviour, and the 30-day window semantics of the update filters that an agent must respect to call this correctly. Adequate, not 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 limit, fields, updated_since and updated_until are all fully documented in the schema, giving a baseline of 3. The description contributes nothing to parameter meaning, and the dates it mentions (send and receive) are returned columns rather than query filters, so it cannot be credited with parameter clarification.
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 clear verb+resource (list stock transfers between locations) and enumerates the row fields returned, which pins down what the resource actually contains. It does not, however, distinguish itself from the near neighbours list_stock_changes or list_shipments, so an agent must still infer which listing covers its case.
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 at all: nothing tells the agent how this differs from finale_list_stock_changes, finale_list_shipments, or finale_get_product_stock, nor when to reach for updated_since filtering instead of a full listing. Usage is left entirely to inference from the name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List orders without their line items: orderId, type (SALES_ORDER or PURCHASE_ORDER), status (ORDER_CREATED, ORDER_LOCKED = committed, ORDER_COMPLETED, ORDER_CANCELLED), dates, origin/destination facility, reference number, total. Get the items with finale_get_order. For a large order history always pass updated_since (Finale cuts unfiltered collections at 120,000 rows before applying other filters). GET /{account}/api/order/.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum rows to return, 1-1000 (default 100). | |
| fields | No | Fields to return per row (default: a compact useful set). | |
| status | No | Only orders in this status. | |
| order_type | No | Only sales or only purchase orders. | |
| updated_since | No | Only records last updated on or after this UTC time. Finale allows a range of at most 30 days (updated_until defaults to now). | |
| updated_until | No | Only records last updated on or before this UTC time (needs updated_since). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With readOnlyHint=true already covering the safety profile, the description still adds genuinely behavioral context: results exclude line items, status ORDER_LOCKED means committed, and unfiltered collections are truncated at 120,000 rows before other filters apply. It stops short of describing pagination behavior beyond the limit parameter, so not a full 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?
Three tight sentences, front-loaded with the resource and its scope, then the alternative, then the performance warning. The field enumeration is long but each field is informative; only marginal trimming is possible.
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, and the description compensates by enumerating the returned fields so the agent knows the shape. Combined with the line-items cross-reference and the truncation warning, the definition is nearly complete; the only gap is explicit guidance on how to page beyond the 1,000-row limit.
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 the baseline is 3. The description goes beyond the schema by explaining why updated_since matters (the 120,000-row pre-filter cut) and by decoding an enum value (ORDER_LOCKED = committed), which the schema does not state.
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 orders') and immediately scopes it as 'without their line items', enumerating the returned fields (orderId, type, status, dates, facilities, reference, total). This cleanly separates it from the sibling finale_get_order, which retrieves items.
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: 'Get the items with finale_get_order' names the alternative, and 'For a large order history always pass updated_since' gives a concrete when-to-use condition with the reason (120,000-row cut). Both the alternative and the triggering condition are stated, not inferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List party groups (customers, suppliers, carriers): partyId (derived from partyUrl; use it as supplier_party_id when drafting a purchase order), name (description), type, roles, status. GET /{account}/api/partygroup/.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum rows to return, 1-1000 (default 100). | |
| fields | No | Fields to return per row (default: a compact useful set). | |
| updated_since | No | Only records last updated on or after this UTC time. Finale allows a range of at most 30 days (updated_until defaults to now). | |
| updated_until | No | Only records last updated on or before this UTC time (needs updated_since). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the safety profile is covered, and the description reinforces this by naming the GET endpoint. It adds field-level meaning (how partyId is derived from partyUrl) but says nothing about result volume, pagination beyond the limit parameter, or whether parties are account-scoped or shared.
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: the returned attributes are listed first and the operational hint follows. Nothing needs to be trimmed and nothing is 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?
With no output schema, the description carries the burden of describing returns and does so by listing the key row fields, and it flags the cross-tool id relationship. It is only slightly short of complete because it does not describe pagination or total-count behavior for a list endpoint with a default row cap.
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, and the schema itself documents limit, fields, updated_since and updated_until including the 30-day window rule. The description earns a bump by enumerating the row attributes (partyId, name, type, roles, status), which is directly actionable when choosing values for the fields parameter.
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 (party groups) and enumerates the party subtypes (customers, suppliers, carriers), so an agent knows exactly what entity set this returns. It also names the endpoint. It stops short of explicit sibling differentiation, but no sibling tool touches parties, so the risk of confusion is low.
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 only usage guidance is the embedded workflow hint that partyId should be used as supplier_party_id when drafting a purchase order, which usefully links it to finale_create_draft_purchase_order. There is no explicit when-to-use statement, no exclusions, and no guidance on the update-window filtering.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List products (SKUs): productId, internalName, status, productUrl, manufacturer, UPC, packing. Optional exact filters on productId and status. Collections come back ordered by lastUpdatedDate; for large catalogs narrow with updated_since or page with next_updated_since. GET /{account}/api/product/.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum rows to return, 1-1000 (default 100). | |
| fields | No | Fields to return per row (default: a compact useful set). | |
| status | No | Only active or only inactive products. | |
| product_id | No | Exact product id (SKU). | |
| updated_since | No | Only records last updated on or after this UTC time. Finale allows a range of at most 30 days (updated_until defaults to now). | |
| updated_until | No | Only records last updated on or before this UTC time (needs updated_since). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare readOnlyHint=true, so the description usefully adds that collections come back ordered by lastUpdatedDate and points at the underlying GET endpoint. It does not cover auth requirements or the full response envelope, but ordering and paging behavior are disclosed beyond the annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three dense, front-loaded sentences with no filler: what it lists, what filters exist, and how to handle large result sets. The parenthetical field list is compact and earns its place for a tool with no output schema.
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 compensates by naming the returned fields, ordering, and paging strategy, and the 30-day range cap is covered in the schema. The only gap is the unexplained next_updated_since paging token, which an agent would need more detail on to iterate pages.
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 seven parameters are already documented in the schema; the description's mention of exact productId/status filters only restates that. The reference to a non-existent 'next_updated_since' parameter slightly muddies rather than clarifies the parameter set.
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 products (SKUs)') and immediately enumerates the returned fields, making it unambiguous versus the single-item sibling finale_get_product. The scope (exact filters on productId/status, ordered by lastUpdatedDate) is stated up front.
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 operational guidance: use updated_since to narrow large catalogs, or page with next_updated_since. What's missing is an explicit comparison to siblings like finale_get_product or finale_get_product_stock, and 'next_updated_since' is referenced as a paging token that appears nowhere in the input schema, leaving the paging workflow slightly unclear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List shipments (sales shipments, purchase receipts, transfers): shipmentId, type, status (for example SHIPMENT_INPUT, SHIPMENT_PACKED, SHIPMENT_SHIPPED), order, origin/destination, dates, tracking code. GET /{account}/api/shipment/.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum rows to return, 1-1000 (default 100). | |
| fields | No | Fields to return per row (default: a compact useful set). | |
| status | No | Exact shipment status, e.g. SHIPMENT_SHIPPED. | |
| updated_since | No | Only records last updated on or after this UTC time. Finale allows a range of at most 30 days (updated_until defaults to now). | |
| updated_until | No | Only records last updated on or before this UTC time (needs updated_since). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
readOnlyHint=true is already supplied by annotations, and the description is consistent with it by disclosing the underlying read endpoint (GET /{account}/api/shipment/). Beyond that it adds no behavioral context such as pagination, default row counts, or the 30-day update-window constraint that the schema itself carries.
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 that names the resource first, then the scope, then the fields, then the endpoint. No filler, no repetition of the title, 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?
With no output schema, the description usefully enumerates the returned fields (shipmentId, type, status, order, origin/destination, dates, tracking code), which is exactly the gap it needs to fill for a read-only list tool. Remaining omissions, such as pagination or the update-window limit, are 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 all five parameters (limit, fields, status, updated_since, updated_until) are already documented; baseline 3 applies. The description does add marginally by naming concrete status values (SHIPMENT_INPUT, SHIPMENT_PACKED, SHIPMENT_SHIPPED) beyond the schema's single example.
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 ('List shipments') and immediately qualifies the scope by enumerating shipment kinds (sales shipments, purchase receipts, transfers) and the key returned fields, so an agent can tell what it retrieves. It does not, however, explicitly contrast itself with sibling finale_get_shipment, which returns a single shipment.
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 enumerations of shipment types and fields suggest when a bulk listing is appropriate, but there is no explicit when-to-use clause, no mention of using finale_get_shipment for a single record, and no stated exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List stock changes (physical counts and adjustments already recorded in Finale): id, type, date, status, location, comments. Read-only history. GET /{account}/api/inventoryvariance/.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum rows to return, 1-1000 (default 100). | |
| fields | No | Fields to return per row (default: a compact useful set). | |
| updated_since | No | Only records last updated on or after this UTC time. Finale allows a range of at most 30 days (updated_until defaults to now). | |
| updated_until | No | Only records last updated on or before this UTC time (needs updated_since). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
readOnlyHint=true already declares the safety profile, so the bar is lower; the description reinforces it ('Read-only history') and adds genuine context by naming the underlying endpoint and the fields each record carries. It does not discuss pagination behaviour or the 30-day window constraint (left to the schema), but it discloses enough about record nature and shape for a read tool.
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 clauses, front-loaded with purpose, then scope, then return shape. No filler; the endpoint reference is short and useful for debugging/edge cases. Every sentence earns its place.
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, enumerating the returned fields (id, type, date, status, location, comments) is exactly the compensation needed, and all four parameters are fully documented in the schema. The only real gap is the absence of routing guidance versus sibling listing tools such as finale_list_inventory_transfers.
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%: limit, fields, updated_since and updated_until are all documented in the schema, including the 30-day range rule. The description adds nothing about parameter semantics, 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?
Specific verb ('List') plus a precisely scoped resource: 'physical counts and adjustments already recorded in Finale', which implicitly separates it from siblings like finale_list_inventory_items and finale_list_inventory_transfers. The enumerated return fields (id, type, date, status, location, comments) further pin down what a 'stock change' is. An agent can identify this tool 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?
Usage is implied rather than stated: 'already recorded' and 'Read-only history' signal this is a retrospective audit listing, not a mutation or a live-stock lookup. However, there is no explicit when-to-use / when-not-to-use guidance, and no sibling is named as the alternative (e.g. finale_get_product_stock for current on-hand levels vs this for historical variance records).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read Inventory Planner forecasts, replenishment and purchase orders; create draft purchase orders.
Read SOS Inventory stock and orders; create customers, items and purchase or sales orders.
Read and update live small-business inventory, suppliers, reorder suggestions and purchase orders.
Read Megaventory products, stock, orders and partners; create clients, sales and purchase orders.
Add one secure layer between your agents and this server.